crashpad::test::Multiprocess Class Reference

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, 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::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,
		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]	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