Page MenuHomePhorge
Diviner Arcanist Tech Docs LinesOfALargeExecFuture

final class LinesOfALargeExecFuture
Arcanist Technical Documentation ()

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

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$keyName of the constant.
int|null$byte_limitMaximum number of bytes permitted in the value.
Return
stringValue 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$characterA 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
stringBytes read from stdout.

public function __construct($future)

To construct, pass an ExecFuture.

Parameters
ExecFuture$futureFuture to wrap.
Return
this//Implicit.//

public function __destruct()

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

Return
void