Page MenuHomePhabricator
Diviner libphutil Tech Docs FutureIterator

final class FutureIterator
libphutil Technical Documentation (Futures)

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

Internals

Other Methods

Methods

public function __construct($futures)

Create a new iterator over a list of futures.

Parameters
list$futuresList 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$intervalMaximum 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$maxMaximum 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

public function rewind()

This method is not documented.
Return
wild

public function next()

This method is not documented.
Return
wild

public function current()

This method is not documented.
Return
wild

public function key()

This method is not documented.
Return
wild

public function valid()

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_listList of sockets expected to become readable.
list$write_listList of sockets expected to become writable.
float$timeoutTimeout, in seconds.
Return
void

public static function handleSIGCHLD($signo)

This method is not documented.
Parameters
$signo
Return
wild
Defined
src/future/FutureIterator.php:31
Phabricator · Built by Phacility