Diviner Arcanist Tech Docs FutureIterator

final class FutureIterator
Arcanist Technical Documentation ()

FutureIterator aggregates Futures and allows you to respond to them in the order they resolve. This is useful because it minimizes the amount of time your program spends waiting on parallel processes.

$futures = array(
  'a.txt' => new ExecFuture('wc -c a.txt'),
  'b.txt' => new ExecFuture('wc -c b.txt'),
  'c.txt' => new ExecFuture('wc -c c.txt'),
);

foreach (new FutureIterator($futures) as $key => $future) {
  // IMPORTANT: keys are preserved but the order of elements is not. This
  // construct iterates over the futures in the order they resolve, so the
  // fastest future is the one you'll get first. This allows you to start
  // doing followup processing as soon as possible.

  list($err, $stdout) = $future->resolve();
  do_some_processing($stdout);
}

For a general overview of futures, see Using Futures.

Tasks

Basics

public function __construct($futures) — Create a new iterator over a list of futures.
public function resolveAll() — Block until all futures resolve.
public function addFuture($future) — Add another future to the set of futures. This is useful if you have a set of futures to run mostly in parallel, but some futures depend on others.

Configuring Iteration

public function setUpdateInterval($interval) — Set a maximum amount of time you want to wait before the iterator will yield a result. If no future has resolved yet, the iterator will yield null for key and value. Among other potential uses, you can use this to show some busy indicator:
public function limit($max) — Limit the number of simultaneously executing futures.

Iterator Interface

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

Internals

protected function updateWorkingSet()

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.
public function setMaximumWorkingSetSize($limit)
public function getMaximumWorkingSetSize()
private function canMoveFutureToWait($future_key)
private function moveFutureToWait($future_key)
private function moveFutureToWork($future_key)
private function moveFutureToDone($future_key)
private function waitForSockets($read_list, $write_list, $timeout) — Wait for activity on one of several sockets.
public static function handleSIGCHLD($signo)

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()

This method is not documented.

Return

wild

public function key()

This method is not documented.

Return

wild

public function next()

This method is not documented.

Return

wild

public function rewind()

This method is not documented.

Return

wild

public function valid()

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 __construct($futures)

Create a new iterator over a list of futures.

Parameters

list

$futures

List of @{class:Future}s to resolve.

Return

this	//Implicit.//

public function resolveAll()

Block until all futures resolve.

Return

void

public function addFuture($future)

Add another future to the set of futures. This is useful if you have a set of futures to run mostly in parallel, but some futures depend on others.

Parameters

Future

$future

@{class:Future} to add to iterator

Return

wild

public function setUpdateInterval($interval)

Set a maximum amount of time you want to wait before the iterator will yield a result. If no future has resolved yet, the iterator will yield null for key and value. Among other potential uses, you can use this to show some busy indicator:

$futures = id(new FutureIterator($futures))
  ->setUpdateInterval(1);
foreach ($futures as $future) {
  if ($future === null) {
    echo "Still working...\n";
  } else {
    // ...
  }
}

This will echo "Still working..." once per second as long as futures are resolving. By default, FutureIterator never yields null.

Parameters

float

$interval

Maximum number of seconds to block waiting on futures before yielding null.

Return

this

public function limit($max)

Limit the number of simultaneously executing futures.

$futures = id(new FutureIterator($futures))

->limit(4);

foreach ($futures as $future) {

// Run no more than 4 futures simultaneously.

}

Parameters

int

$max

Maximum number of simultaneous jobs allowed.

Return

this

public function setMaximumWorkingSetSize($limit)

This method is not documented.

Parameters

$limit

Return

wild

public function getMaximumWorkingSetSize()

This method is not documented.

Return

wild

protected function updateWorkingSet()

This method is not documented.

Return

wild

private function canMoveFutureToWait($future_key)

This method is not documented.

Parameters

$future_key

Return

wild

private function moveFutureToWait($future_key)

This method is not documented.

Parameters

$future_key

Return

wild

private function moveFutureToWork($future_key)

This method is not documented.

Parameters

$future_key

Return

wild

private function moveFutureToDone($future_key)

This method is not documented.

Parameters

$future_key

Return

wild

private function waitForSockets($read_list, $write_list, $timeout)

Wait for activity on one of several sockets.

Parameters

list	$read_list	List of sockets expected to become readable.
list	$write_list	List of sockets expected to become writable.
float	$timeout	Timeout, in seconds.

Return

void

public static function handleSIGCHLD($signo)

This method is not documented.

Parameters

$signo

Return

wild

Defined: src/future/FutureIterator.php:31
Extends: Phobject

final class FutureIteratorArcanist Technical Documentation ()

Tasks

Basics

Configuring Iteration

Iterator Interface

Internals

Other Methods

Methods

public function __get($name)Inherited

public function __set($name, $value)Inherited

public function current()

public function key()

public function next()

public function rewind()

public function valid()

private function throwOnAttemptedIteration()Inherited

public function getPhobjectClassConstant($key, $byte_limit)Inherited

public function __construct($futures)

public function resolveAll()

public function addFuture($future)

public function setUpdateInterval($interval)

public function limit($max)

public function setMaximumWorkingSetSize($limit)

public function getMaximumWorkingSetSize()

protected function updateWorkingSet()

private function canMoveFutureToWait($future_key)

private function moveFutureToWait($future_key)

private function moveFutureToWork($future_key)

private function moveFutureToDone($future_key)

private function waitForSockets($read_list, $write_list, $timeout)

public static function handleSIGCHLD($signo)

final class FutureIterator
Arcanist Technical Documentation ()

public function __get($name)
Inherited

public function __set($name, $value)
Inherited

private function throwOnAttemptedIteration()
Inherited

public function getPhobjectClassConstant($key, $byte_limit)
Inherited