Crashpad
Public Types | Public Member Functions | Protected Member Functions | List of all members
crashpad::test::Multiprocess Class Referenceabstract

Manages a multiprocess test. More...

#include "test/multiprocess.h"

Inheritance diagram for crashpad::test::Multiprocess:
crashpad::test::MachMultiprocess crashpad::test::MultiprocessExec

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, ReturnCodeType 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::MultiprocessInfoinfo ()
 

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

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,
ReturnCodeType  code 
)

Sets the expected termination reason and code.

The default expected termination reason 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]reasonWhether to expect the child to terminate normally or as a result of a signal.
[in]codeIf 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:
crashpad::test::Multiprocess::PreFork
virtual void PreFork()
Establishes the proper testing environment prior to forking.
Definition: multiprocess_posix.cc:175