Function rusty_fork::fork

source ·

pub fn fork<ID, MODIFIER, PARENT, CHILD, R>(
    test_name: &str,
    fork_id: ID,
    process_modifier: MODIFIER,
    in_parent: PARENT,
    in_child: CHILD
) -> Result<R>where
    ID: Hash,
    MODIFIER: FnOnce(&mut Command),
    PARENT: FnOnce(&mut ChildWrapper, &mut File) -> R,
    CHILD: FnOnce(),

Expand description

Simulate a process fork.

The function documentation here only lists information unique to calling it directly; please see the crate documentation for more details on how the forking process works.

Since this is not a true process fork, the calling code must be structured to ensure that the child process, upon starting from the same entry point, also reaches this same fork() call. Recursive forks are supported; the child branch is taken from all child processes of the fork even if it is not directly the child of a particular branch. However, encountering the same fork point more than once in a single execution sequence of a child process is not (e.g., putting this call in a recursive function) and results in unspecified behaviour.

The child’s output is buffered into an anonymous temporary file. Before this call returns, this output is copied to the parent’s standard output (passing through the redirect mechanism Rust test uses).

test_name must exactly match the full path of the test function being run.

fork_id is a unique identifier identifying this particular fork location. This must be stable across processes of the same executable; pointers are not suitable stable, and string constants may not be suitably unique. The rusty_fork_id!() macro is the recommended way to supply this parameter.

If this is the parent process, in_parent is invoked, and the return value becomes the return value from this function. The callback is passed a handle to the file which receives the child’s output. If is the callee’s responsibility to wait for the child to exit. If this is the child process, in_child is invoked, and when the callback returns, the child process exits.

If in_parent returns or panics before the child process has terminated, the child process is killed.

If in_child panics, the child process exits with a failure code immediately rather than let the panic propagate out of the fork() call.

process_modifier is invoked on the std::process::Command immediately before spawning the new process. The callee may modify the process parameters if desired, but should not do anything that would modify or remove any environment variables beginning with RUSTY_FORK_.

§Panics

Panics if the environment indicates that there are already at least 16 levels of fork nesting.

Panics if std::env::current_exe() fails determine the path to the current executable.

Panics if any argument to the current process is not valid UTF-8.