final class ExecFuture
libphutil Technical Documentation (Futures)

Execute system commands in parallel using futures.

ExecFuture is a future, which means it runs asynchronously and represents a value which may not exist yet. See Using Futures for an explanation of futures. When an ExecFuture resolves, it returns the exit code, stdout and stderr of the process it executed.

ExecFuture is the core command execution implementation in libphutil, but is exposed through a number of APIs. See Command Execution for more discussion about executing system commands.

Tasks

Configuring Execution

final public function setEnv($env, $wipe_process_env) — Set environmental variables for the command.
final public function updateEnv($key, $value) — Set the value of a specific environmental variable for this command.
final public function hasEnv() — Returns `true` if this command has a configured environment.
final public function getEnv() — Get the configured environment.
final public function setCWD($cwd) — Set the current working directory for the subprocess (that is, set where the subprocess will execute). If not set, the default value is the parent's current working directory.
final public function getCWD() — Get the command's current working directory.
public function setStdoutSizeLimit($limit) — Set a maximum size for the stdout read buffer. To limit stderr, see @{method:setStderrSizeLimit}. The major use of these methods is to use less memory if you are running a command which sometimes produces huge volumes of output that you don't really care about.
public function setStderrSizeLimit($limit) — Set a maximum size for the stderr read buffer. See @{method:setStdoutSizeLimit} for discussion.
public function setTimeout($seconds) — Set a hard limit on execution time. If the command runs longer, it will be terminated and the future will resolve with an error code. You can test if a future was killed by a timeout with @{method:getWasKilledByTimeout}.

Creating ExecFutures

No methods for this task.

Resolving Execution

public function resolvex(...) — Resolve a command you expect to exit with return code 0. Works like @{method:resolve}, but throws if $err is nonempty. Returns only $stdout and $stderr. See also @{function:execx}.
public function resolveJSON(...) — Resolve a command you expect to return valid JSON. Works like @{method:resolvex}, but also throws if stderr is nonempty, or stdout is not valid JSON. Returns a PHP array, decoded from the JSON command output.
public function resolveKill() — Resolve the process by abruptly terminating it.

Command Information

public function getStderrSizeLimit() — Retrieve the byte limit for the stderr buffer.
public function getStdoutSizeLimit() — Retrieve the byte limit for the stdout buffer.
public function getPID() — Get the process's pid. This only works after execution is initiated, e.g. by a call to start().

Interacting With Commands

public function read() — Read and return output from stdout and stderr, if any is available. This method keeps a read cursor on each stream, but the entire streams are still returned when the future resolves. You can call read() again after resolving the future to retrieve only the parts of the streams you did not previously read:
public function write($data, $keep_pipe) — Write data to stdin of the command.
public function discardBuffers() — Permanently discard the stdout and stderr buffers and reset the read cursors. This is basically useful only if you are streaming a large amount of data from some process.

Internals

public function isReady() — Begin or continue command execution.
public function getReadSockets() — Provides read sockets to the future core.
public function getWriteSockets() — Provides write sockets to the future core.
public function isReadBufferEmpty() — Determine if the read buffer is empty.
public function isWriteBufferEmpty() — Determine if the write buffer is empty.
public function getWriteBufferSize() — Determine the number of bytes in the write buffer.
private function readAndDiscard($stream, $limit, $description, $length) — Reads some bytes from a stream, discarding output once a certain amount has been accumulated.
public function __destruct()
private function closeProcess() — Close and free resources if necessary.
private function procGetStatus() — Execute `proc_get_status()`, but avoid pitfalls.
private function tryToCloseStdin() — Try to close stdin, if we're done using it. This keeps us from hanging if the process on the other end of the pipe is waiting for EOF.

Other Methods

public function __get($name)
public function __set($name, $value)
public function current()
public function key()
public function next()
public function rewind()
public function valid()
private function throwOnAttemptedIteration()
public function getPhobjectClassConstant($key, $byte_limit) — Read the value of a class constant.
public function resolve() — Resolve a future and return its result, blocking until the result is ready if necessary.
final public function updateFuture()
private function startServiceProfiler()
private function endServiceProfiler()
protected function getServiceProfilerStartParameters()
protected function getServiceProfilerResultParameters()
public function getDefaultWait()
public function start()
final protected function getResult() — Retrieve the final result of the future.
final protected function setResult($result)
final public function hasResult()
private function setException($exception)
private function getException()
final public function hasException()
final public function setFutureKey($key)
final public function getFutureKey()
final public function setRaiseExceptionOnStart($raise)
final public function getHasFutureStarted()
final public function canResolve()
private function endFuture()
final public function __construct($pattern)
protected function didConstruct()
final public function setResolveOnError($resolve_on_error)
final public function getResolveOnError()
final public function getCommand()
public function hasPID()
public function setReadBufferSize($read_buffer_size) — Set the maximum internal read buffer size this future. The future will block reads once the internal stdout or stderr buffer exceeds this size.
public function readStdout()
public function discardStdoutBuffer()
public function getWasKilledByTimeout() — Returns true if this future was killed by a timeout configured with @{method:setTimeout}.
private function recordResult($result)
private function raiseResultError($result)
private function getNextTimeout()
private function sendTerminateSignal()
private function waitForExit($duration)
private function getStdoutBufferLength()
private function getStderrBufferLength()

Methods

public function __get($name)
Inherited

This method is not documented.

Parameters

$name

Return

wild

public function __set($name, $value)
Inherited

This method is not documented.

Parameters

	$name
	$value

Return

wild

public function current()
Inherited

This method is not documented.

Return

wild

public function key()
Inherited

This method is not documented.

Return

wild

public function next()
Inherited

This method is not documented.

Return

wild

public function rewind()
Inherited

This method is not documented.

Return

wild

public function valid()
Inherited

This method is not documented.

Return

wild

private function throwOnAttemptedIteration()
Inherited

This method is not documented.

Return

wild

public function getPhobjectClassConstant($key, $byte_limit)
Inherited

Phobject

Read the value of a class constant.

This is the same as just typing self::CONSTANTNAME, but throws a more useful message if the constant is not defined and allows the constant to be limited to a maximum length.

Parameters

string	$key	Name of the constant.
int\|null	$byte_limit	Maximum number of bytes permitted in the value.

Return

string

Value of the constant.

public function isReady()

Future

Is this future's process complete? Specifically, can this future be resolved without blocking?

ExecFuture

Begin or continue command execution.

Return

bool	True if future has resolved.

public function resolve()
Inherited

Future

Resolve a future and return its result, blocking until the result is ready if necessary.

Return

wild	Future result.

final public function updateFuture()
Inherited

This method is not documented.

Return

wild

private function startServiceProfiler()
Inherited

This method is not documented.

Return

wild

private function endServiceProfiler()
Inherited

This method is not documented.

Return

wild

protected function getServiceProfilerStartParameters()

This method is not documented.

Return

wild

protected function getServiceProfilerResultParameters()

This method is not documented.

Return

wild

public function getReadSockets()

Future

Retrieve a list of sockets which we can wait to become readable while a future is resolving. If your future has sockets which can be select()ed, return them here (or in getWriteSockets()) to make the resolve loop do a select(). If you do not return sockets in either case, you'll get a busy wait.

ExecFuture

Provides read sockets to the future core.

Return

list	List of read sockets.

public function getWriteSockets()

Future

Retrieve a list of sockets which we can wait to become writable while a future is resolving. See getReadSockets().

ExecFuture

Provides write sockets to the future core.

Return

list	List of write sockets.

public function getDefaultWait()

Future

Default amount of time to wait on stream select for this future. Normally 1 second is fine, but if the future has a timeout sooner than that it should return the amount of time left before the timeout.

ExecFuture

This method is not documented.

Return

wild

public function start()
Inherited

This method is not documented.

Return

wild

final protected function getResult()
Inherited

Future

Retrieve the final result of the future.

Return

wild	Final resolution of this future.

final protected function setResult($result)
Inherited

This method is not documented.

Parameters

$result

Return

wild

final public function hasResult()
Inherited

This method is not documented.

Return

wild

private function setException($exception)
Inherited

This method is not documented.

Parameters

$exception

Return

wild

private function getException()
Inherited

This method is not documented.

Return

wild

final public function hasException()
Inherited

This method is not documented.

Return

wild

final public function setFutureKey($key)
Inherited

This method is not documented.

Parameters

$key

Return

wild

final public function getFutureKey()
Inherited

This method is not documented.

Return

wild

final public function setRaiseExceptionOnStart($raise)
Inherited

This method is not documented.

Parameters

$raise

Return

wild

final public function getHasFutureStarted()
Inherited

This method is not documented.

Return

wild

final public function canResolve()
Inherited

This method is not documented.

Return

wild

private function endFuture()
Inherited

This method is not documented.

Return

wild

final public function __construct($pattern)
Inherited

This method is not documented.

Parameters

$pattern

Return

this	//Implicit.//

protected function didConstruct()

This method is not documented.

Return

wild

final public function setResolveOnError($resolve_on_error)
Inherited

This method is not documented.

Parameters

$resolve_on_error

Return

wild

final public function getResolveOnError()
Inherited

This method is not documented.

Return

wild

final public function getCommand()
Inherited

This method is not documented.

Return

wild

final public function setEnv($env, $wipe_process_env)
Inherited

PhutilExecutableFuture

Set environmental variables for the command.

By default, variables are added to the environment of this process. You can optionally wipe the environment and pass only the specified values.

// Env will have "X" and current env ("PATH", etc.)
$exec->setEnv(array('X' => 'y'));

// Env will have ONLY "X".
$exec->setEnv(array('X' => 'y'), $wipe_process_env = true);

Parameters

map<string,	$env	string> Dictionary of environmental variables.
bool	$wipe_process_env	Optionally, pass `true` to replace the existing environment.

Return

this

final public function updateEnv($key, $value)
Inherited

PhutilExecutableFuture

Set the value of a specific environmental variable for this command.

Parameters

string	$key	Environmental variable name.
string\|null	$value	New value, or null to remove this variable.

Return

this

final public function hasEnv()
Inherited

PhutilExecutableFuture

Returns true if this command has a configured environment.

Return

bool	True if this command has an environment.

final public function getEnv()
Inherited

PhutilExecutableFuture

Get the configured environment.

Return

map<string, string>

Effective environment for this command.

final public function setCWD($cwd)
Inherited

PhutilExecutableFuture

Set the current working directory for the subprocess (that is, set where the subprocess will execute). If not set, the default value is the parent's current working directory.

Parameters

string

$cwd

Directory to execute the subprocess in.

Return

this

final public function getCWD()
Inherited

PhutilExecutableFuture

Get the command's current working directory.

Return

string

Working directory.

public function getStderrSizeLimit()

Retrieve the byte limit for the stderr buffer.

Return

int	Maximum buffer size, in bytes.

public function getStdoutSizeLimit()

Retrieve the byte limit for the stdout buffer.

Return

int	Maximum buffer size, in bytes.

public function getPID()

Get the process's pid. This only works after execution is initiated, e.g. by a call to start().

Return

int	Process ID of the executing process.

public function hasPID()

This method is not documented.

Return

wild

public function setStdoutSizeLimit($limit)

Set a maximum size for the stdout read buffer. To limit stderr, see setStderrSizeLimit(). The major use of these methods is to use less memory if you are running a command which sometimes produces huge volumes of output that you don't really care about.

NOTE: Setting this to 0 means "no buffer", not "unlimited buffer".

Parameters

int

$limit

Maximum size of the stdout read buffer.

Return

this

public function setStderrSizeLimit($limit)

Set a maximum size for the stderr read buffer. See setStdoutSizeLimit() for discussion.

Parameters

int

$limit

Maximum size of the stderr read buffer.

Return

this

public function setReadBufferSize($read_buffer_size)

Set the maximum internal read buffer size this future. The future will block reads once the internal stdout or stderr buffer exceeds this size.

NOTE: If you resolve() a future with a read buffer limit, you may block forever!

TODO: We should probably release the read buffer limit during resolve(), or otherwise detect this. For now, be careful.

Parameters

int|null

$read_buffer_size

Maximum buffer size, or `null` for unlimited.

Return

this

public function read()

Read and return output from stdout and stderr, if any is available. This method keeps a read cursor on each stream, but the entire streams are still returned when the future resolves. You can call read() again after resolving the future to retrieve only the parts of the streams you did not previously read:

$future = new ExecFuture('...');
// ...
list($stdout) = $future->read(); // Returns output so far
list($stdout) = $future->read(); // Returns new output since first call
// ...
list($stdout) = $future->resolvex(); // Returns ALL output
list($stdout) = $future->read(); // Returns unread output

NOTE: If you set a limit with setStdoutSizeLimit() or setStderrSizeLimit(), this method will not be able to read data past the limit.

NOTE: If you call discardBuffers(), all the stdout/stderr data will be thrown away and the cursors will be reset.

Return

pair	<$stdout, $stderr> pair with new output since the last call to this method.

public function readStdout()

This method is not documented.

Return

wild

public function write($data, $keep_pipe)

Write data to stdin of the command.

Parameters

string	$data	Data to write.
bool	$keep_pipe	If true, keep the pipe open for writing. By default, the pipe will be closed as soon as possible so that commands which listen for EOF will execute. If you want to keep the pipe open past the start of command execution, do an empty write with `$keep_pipe = true` first.

Return

this

public function discardBuffers()

Permanently discard the stdout and stderr buffers and reset the read cursors. This is basically useful only if you are streaming a large amount of data from some process.

Conceivably you might also need to do this if you're writing a client using ExecFuture and netcat, but you probably should not do that.

NOTE: This completely discards the data. It won't be available when the future resolves. This is almost certainly only useful if you need the buffer memory for some reason.

Return

this

public function discardStdoutBuffer()

This method is not documented.

Return

wild

public function getWasKilledByTimeout()

Returns true if this future was killed by a timeout configured with setTimeout().

Return

bool	True if the future was killed for exceeding its time limit.

public function setTimeout($seconds)

Set a hard limit on execution time. If the command runs longer, it will be terminated and the future will resolve with an error code. You can test if a future was killed by a timeout with getWasKilledByTimeout().

The subprocess will be sent a TERM signal, and then a KILL signal a short while later if it fails to exit.

Parameters

int

$seconds

Maximum number of seconds this command may execute for before it is signaled.

Return

this

public function resolvex(...)

Resolve a command you expect to exit with return code 0. Works like resolve(), but throws if $err is nonempty. Returns only $stdout and $stderr. See also execx().

list($stdout, $stderr) = $future->resolvex();

Parameters

float

Optional timeout after which resolution will pause and execution will return to the caller.

Return

pair	<$stdout, $stderr> pair.

public function resolveJSON(...)

Resolve a command you expect to return valid JSON. Works like resolvex(), but also throws if stderr is nonempty, or stdout is not valid JSON. Returns a PHP array, decoded from the JSON command output.

Parameters

float

Optional timeout after which resolution will pause and execution will return to the caller.

Return

array

PHP array, decoded from JSON command output.

public function resolveKill()

Resolve the process by abruptly terminating it.

Return

list	List of <err, stdout, stderr> results.

private function recordResult($result)

This method is not documented.

Parameters

array

$result

Return

wild

private function raiseResultError($result)

This method is not documented.

Parameters

$result

Return

wild

public function isReadBufferEmpty()

Determine if the read buffer is empty.

Return

bool	True if the read buffer is empty.

public function isWriteBufferEmpty()

Determine if the write buffer is empty.

Return

bool	True if the write buffer is empty.

public function getWriteBufferSize()

Determine the number of bytes in the write buffer.

Return

int	Number of bytes in the write buffer.

private function readAndDiscard($stream, $limit, $description, $length)

Reads some bytes from a stream, discarding output once a certain amount has been accumulated.

Parameters

resource	$stream	Stream to read from.
int	$limit	Maximum number of bytes to return from $stream. If additional bytes are available, they will be read and discarded.
string	$description	Human-readable description of stream, for exception message.
int	$length	Maximum number of bytes to read.

Return

string

The data read from the stream.

public function __destruct()

This method is not documented.

Return

void

private function closeProcess()

Close and free resources if necessary.

Return

void

private function procGetStatus()

Execute proc_get_status(), but avoid pitfalls.

Return

dict	Process status.

private function tryToCloseStdin()

Try to close stdin, if we're done using it. This keeps us from hanging if the process on the other end of the pipe is waiting for EOF.

Return

void

private function getNextTimeout()

This method is not documented.

Return

wild

private function sendTerminateSignal()

This method is not documented.

Return

wild

private function waitForExit($duration)

This method is not documented.

Parameters

$duration

Return

wild

private function getStdoutBufferLength()

This method is not documented.

Return

wild

private function getStderrBufferLength()

This method is not documented.

Return

wild

Defined: src/future/exec/ExecFuture.php:22
Extends: PhobjectFuturePhutilExecutableFuture

final class ExecFuturelibphutil Technical Documentation (Futures)

Tasks

Configuring Execution

Creating ExecFutures

Resolving Execution

Command Information

Interacting With Commands

Internals

Other Methods

Methods

public function __get($name)Inherited

public function __set($name, $value)Inherited

public function current()Inherited

public function key()Inherited

public function next()Inherited

public function rewind()Inherited

public function valid()Inherited

private function throwOnAttemptedIteration()Inherited

public function getPhobjectClassConstant($key, $byte_limit)Inherited

public function isReady()

public function resolve()Inherited

final public function updateFuture()Inherited

private function startServiceProfiler()Inherited

private function endServiceProfiler()Inherited

protected function getServiceProfilerStartParameters()

protected function getServiceProfilerResultParameters()

public function getReadSockets()

public function getWriteSockets()

public function getDefaultWait()

public function start()Inherited

final protected function getResult()Inherited

final protected function setResult($result)Inherited

final public function hasResult()Inherited

private function setException($exception)Inherited

private function getException()Inherited

final public function hasException()Inherited

final public function setFutureKey($key)Inherited

final public function getFutureKey()Inherited

final public function setRaiseExceptionOnStart($raise)Inherited

final public function getHasFutureStarted()Inherited

final public function canResolve()Inherited

private function endFuture()Inherited

final public function __construct($pattern)Inherited

protected function didConstruct()

final public function setResolveOnError($resolve_on_error)Inherited

final public function getResolveOnError()Inherited

final public function getCommand()Inherited

final public function setEnv($env, $wipe_process_env)Inherited

final public function updateEnv($key, $value)Inherited

final public function hasEnv()Inherited

final public function getEnv()Inherited

final public function setCWD($cwd)Inherited

final public function getCWD()Inherited

public function getStderrSizeLimit()

public function getStdoutSizeLimit()

public function getPID()

public function hasPID()

public function setStdoutSizeLimit($limit)

public function setStderrSizeLimit($limit)

public function setReadBufferSize($read_buffer_size)

public function read()

public function readStdout()

public function write($data, $keep_pipe)

public function discardBuffers()

public function discardStdoutBuffer()

public function getWasKilledByTimeout()

public function setTimeout($seconds)

public function resolvex(...)

public function resolveJSON(...)

public function resolveKill()

private function recordResult($result)

private function raiseResultError($result)

public function isReadBufferEmpty()

public function isWriteBufferEmpty()

public function getWriteBufferSize()

private function readAndDiscard($stream, $limit, $description, $length)

public function __destruct()

private function closeProcess()

private function procGetStatus()

private function tryToCloseStdin()

final class ExecFuture
libphutil Technical Documentation (Futures)

public function __get($name)
Inherited

public function __set($name, $value)
Inherited

public function current()
Inherited

public function key()
Inherited

public function next()
Inherited

public function rewind()
Inherited

public function valid()
Inherited

private function throwOnAttemptedIteration()
Inherited

public function getPhobjectClassConstant($key, $byte_limit)
Inherited

public function resolve()
Inherited

final public function updateFuture()
Inherited

private function startServiceProfiler()
Inherited

private function endServiceProfiler()
Inherited

public function start()
Inherited

final protected function getResult()
Inherited

final protected function setResult($result)
Inherited

final public function hasResult()
Inherited

private function setException($exception)
Inherited

private function getException()
Inherited

final public function hasException()
Inherited

final public function setFutureKey($key)
Inherited

final public function getFutureKey()
Inherited

final public function setRaiseExceptionOnStart($raise)
Inherited

final public function getHasFutureStarted()
Inherited

final public function canResolve()
Inherited

private function endFuture()
Inherited

final public function __construct($pattern)
Inherited

final public function setResolveOnError($resolve_on_error)
Inherited

final public function getResolveOnError()
Inherited

final public function getCommand()
Inherited

final public function setEnv($env, $wipe_process_env)
Inherited

final public function updateEnv($key, $value)
Inherited

final public function hasEnv()
Inherited

final public function getEnv()
Inherited

final public function setCWD($cwd)
Inherited

final public function getCWD()
Inherited