Diviner libphutil Tech Docs LinesOfALargeExecFuture

final class LinesOfALargeExecFuture
libphutil Technical Documentation (Filesystem)

Read the output stream of an ExecFuture one line at a time. This abstraction allows you to process large inputs without holding them in memory. If you know your inputs fit in memory, it is generally more efficient (and certainly simpler) to read the entire input and explode() it. For more information, see LinesOfALarge. See also LinesOfALargeFile for a similar abstraction that works on files.

$future = new ExecFuture('hg log ...');
foreach (new LinesOfALargeExecFuture($future) as $line) {
  // ...
}

If the subprocess exits with an error, a CommandException will be thrown.

On destruction, this class terminates the subprocess if it has not already exited.

Tasks

Configuration

final public function setDelimiter($character) — Change the "line" delimiter character, which defaults to "\n". This is used to determine where each line ends.

Internals

protected function willRewind() — The PHP `foreach()` construct calls rewind() once, so we allow the first `rewind()`, without effect. Subsequent rewinds mean misuse.
protected function readMore() — Read more data from the subprocess.
public function __destruct() — On destruction, we terminate the subprocess if it hasn't exited already.

Iterator Interface

final public function current()
final public function key()
final public function next()
final public function rewind()
final public function valid()

Construction

public function __construct($future) — To construct, pass an @{class:ExecFuture}.

Other Methods

public function __get($name)
public function __set($name, $value)
private function throwOnAttemptedIteration()
public function getPhobjectClassConstant($key, $byte_limit) — Read the value of a class constant.

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

final public function current()
Inherited

This method is not documented.

Return

wild

final public function key()
Inherited

This method is not documented.

Return

wild

final public function next()
Inherited

This method is not documented.

Return

wild

final public function rewind()
Inherited

This method is not documented.

Return

wild

final 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.

final public function setDelimiter($character)
Inherited

LinesOfALarge

Change the "line" delimiter character, which defaults to "\n". This is used to determine where each line ends.

If you pass null, data will be read from source as it becomes available, without looking for delimiters. You can use this to stream a large file or the output of a command which returns a large amount of data.

Parameters

string|null

$character

A one-byte delimiter character.

Return

this

protected function willRewind()

LinesOfALarge

Hook, called before rewind()(). Allows a concrete implementation to open resources or reset state.

LinesOfALargeExecFuture

The PHP foreach() construct calls rewind() once, so we allow the first rewind(), without effect. Subsequent rewinds mean misuse.

Return

void

protected function readMore()

LinesOfALarge

Called when the iterator needs more data. The subclass should return more data, or empty string to indicate end-of-stream.

LinesOfALargeExecFuture

Read more data from the subprocess.

Return

string

Bytes read from stdout.

public function __construct($future)

To construct, pass an ExecFuture.

Parameters

ExecFuture

$future

Future to wrap.

Return

this	//Implicit.//

public function __destruct()

On destruction, we terminate the subprocess if it hasn't exited already.

Return

void

Defined: src/filesystem/linesofalarge/LinesOfALargeExecFuture.php:25
Extends: PhobjectLinesOfALarge