crashpad::test::Multiprocess Class Referenceabstract

Manages a multiprocess test. More...

`#include "test/multiprocess.h"`

Inheritance diagram for crashpad::test::Multiprocess:

## Public Types

enum | TerminationReason : bool
| The termination type for a child process. More...

## Public Member Functions

void | Run ()
| Runs the test. More...
void | SetExpectedChildTermination (TerminationReason reason, int code)
| Sets the expected termination reason and code. More...
void | SetExpectedChildTerminationBuiltinTrap ()
| Sets termination reason and code appropriately for a child that terminates via `__builtin_trap()`.

## Protected Member Functions

virtual void | PreFork ()
| Establishes the proper testing environment prior to forking. More...
pid_t | ChildPID () const
| Returns the child process’ process ID. More...
FileHandle | ReadPipeHandle () const
| Returns the read pipe’s file handle. More...
FileHandle | WritePipeHandle () const
| Returns the write pipe’s file handle. More...
void | CloseReadPipe ()
| Closes the read pipe. More...
void | CloseWritePipe ()
| Closes the write pipe. More...
void | set_info (internal::MultiprocessInfo *info)
internal::MultiprocessInfo * | info ()

## Detailed Description

Manages a multiprocess test.

These tests are `fork()`-based. The parent and child processes are able to communicate via a pair of POSIX pipes.

Subclasses are expected to implement the parent and child by overriding the appropriate methods.

On Windows and Fuchsia, this class is only an internal implementation detail of MultiprocessExec and all tests must use that class.

## Member Enumeration Documentation

## TerminationReason

enum crashpad::test::Multiprocess::TerminationReason : bool

The termination type for a child process.

Enumerator
kTerminationNormal | The child terminated normally. A normal return happens when a test returns from RunChild(), or for tests that `exec()`, returns from `main()`. This also happens for tests that call `exit()` or `_exit()`.
kTerminationSignal | The child terminated by signal. Signal termination happens as a result of a crash, a call to `abort()`, assertion failure (including gtest assertions), etc.

## Member Function Documentation

## ChildPID()

pid_t crashpad::test::Multiprocess::ChildPID | ( |  | ) | const

protected

Returns the child process’ process ID.

This method may only be called by the parent process.

## CloseReadPipe()

void crashpad::test::Multiprocess::CloseReadPipe | ( |  | ) |

protected

Closes the read pipe.

This method may be called by either the parent or the child process. An attempt to write to the write pipe in the partner process will fail with `EPIPE` or `SIGPIPE`. ReadPipeHandle() must not be called after this.

## CloseWritePipe()

void crashpad::test::Multiprocess::CloseWritePipe | ( |  | ) |

protected

Closes the write pipe.

This method may be called by either the parent or the child process. An attempt to read from the read pipe in the partner process will indicate end-of-file. WritePipeHandle() must not be called after this.

## PreFork()

void crashpad::test::Multiprocess::PreFork | ( |  | ) |

protectedvirtual

Establishes the proper testing environment prior to forking.

Subclasses that solely implement a test should not need to override this method. Subclasses that do not implement tests but instead implement additional testing features on top of this class may override this method provided that they call the superclass’ implementation first as follows:

void PreFork() override {
ASSERT_NO_FATAL_FAILURE(Multiprocess::PreFork());
// Place subclass-specific pre-fork code here.
}

Subclass implementations may signal failure by raising their own fatal gtest assertions.

Reimplemented in crashpad::test::MultiprocessExec, and crashpad::test::MachMultiprocess.

## ReadPipeHandle()

FileHandle crashpad::test::Multiprocess::ReadPipeHandle | ( |  | ) | const

protected

Returns the read pipe’s file handle.

This method may be called by either the parent or the child process. Anything written to the write pipe in the partner process will appear on this file handle in this process.

It is an error to call this after CloseReadPipe() has been called.

Returns
  The read pipe’s file handle.

## Run()

void crashpad::test::Multiprocess::Run | ( |  | ) |

Runs the test.

This method establishes the proper testing environment by calling PreFork(), then calls `fork()`. In the parent process, it calls RunParent(), and in the child process, it calls RunChild().

This method uses gtest assertions to validate the testing environment. If the testing environment cannot be set up properly, it is possible that MultiprocessParent() or MultiprocessChild() will not be called. In the parent process, this method also waits for the child process to exit after MultiprocessParent() returns, and verifies that it exited in accordance with the expectations set by SetExpectedChildTermination().

## SetExpectedChildTermination()

void crashpad::test::Multiprocess::SetExpectedChildTermination | ( | TerminationReason | reason,
|  | int | code
| ) |  |

Sets the expected termination reason and code.

The default expected termination reasaon is TerminationReason::kTerminationNormal, and the default expected termination code is `EXIT_SUCCESS` (`0`).

This method does not need to be called if the default termination expectation is appropriate, but if this method is called, it must be called before Run().

Parameters

  [in] | reason | Whether to expect the child to terminate normally or as a result of a signal.
  [in] | code | If reason is TerminationReason::kTerminationNormal, this is the expected exit status of the child. If reason is TerminationReason::kTerminationSignal, this is the signal that is expected to kill the child. On Linux platforms, SIG_DFL will be installed for code in the child process.

## WritePipeHandle()

FileHandle crashpad::test::Multiprocess::WritePipeHandle | ( |  | ) | const

protected

Returns the write pipe’s file handle.

This method may be called by either the parent or the child process. Anything written to this file handle in this process will appear on the read pipe in the partner process.

It is an error to call this after CloseWritePipe() has been called.

Returns
  The write pipe’s file handle.

The documentation for this class was generated from the following files:

- test/multiprocess.h
- test/multiprocess_exec_fuchsia.cc
- test/multiprocess_exec_win.cc
- test/multiprocess_posix.cc