TheRock/rocm-systems/projects/rocprofiler-systems/examples/fork

Fork

Overview

This example demonstrates profiling across process boundaries by forking child processes from worker threads. Each worker thread creates a child process via fork(), and each child spawns its own thread that sleeps for a variable duration before exiting. The parent process waits for all children using waitpid() with detailed exit status reporting. The entire workflow is annotated with rocprofiler-systems user API regions (launch_child, child_process, child_process_child_thread, wait_for_children) to show how profiling data is captured across fork() boundaries.

Source Files

• fork.cpp - Implements barrier-synchronized thread-to-fork workflow with user API region annotations, child process management with waitpid(), and exit status decoding (WIFEXITED, WIFSIGNALED, etc.).
• hipMallocConcurrencyMproc.cpp - (Optional) HIP GPU memory allocation test across forked processes, built only when hipcc is available.

Prerequisites

• CMake 3.25+
• C++ compiler with pthreads support
• rocprofiler-systems user library
• (Optional) HIP runtime for hipMallocConcurrencyMproc

Building

Standalone build:

cmake -B build -DCMAKE_PREFIX_PATH=/opt/rocm
cmake --build build

As part of the examples suite:

cmake -B build -DCMAKE_PREFIX_PATH=/opt/rocm examples/
cmake --build build --target fork-example

Running

# Default: 4 child processes, 1 cycle
./fork-example

# Custom: 8 children, 3 cycles
./fork-example 8 3

Arguments:

Position	Description	Default
1	Number of child processes to fork	4
2	Number of fork/wait cycles to repeat	1

Profiling with rocprofiler-systems

rocprof-sys-run -- ./fork-example 4 2

Recommended Configuration

Variable	Value	Purpose
ROCPROFSYS_TRACE	true	Generate Perfetto trace with cross-process events
ROCPROFSYS_PROFILE	true	Generate call-stack profile
ROCPROFSYS_USE_SAMPLING	ON	Sample call stacks in parent and child processes
ROCPROFSYS_USE_PROCESS_SAMPLING	ON	Enable process-level resource sampling