ray.util.ActorPool

class ray.util.ActorPool(actors: list)

Bases: object

Utility class to operate on a fixed pool of actors.

Parameters

actors – List of Ray actor handles to use in this pool.

Examples

>>> import ray
>>> from ray.util.actor_pool import ActorPool
>>> @ray.remote 
>>> class Actor: 
...     ... 
>>> a1, a2 = Actor.remote(), Actor.remote() 
>>> pool = ActorPool([a1, a2]) 
>>> print(list(pool.map(lambda a, v: a.double.remote(v), 
...                     [1, 2, 3, 4]))) 
[2, 4, 6, 8]

DeveloperAPI: This API may change across minor Ray releases.

map(fn: Callable[[Any], Any], values: List[Any])

Apply the given function in parallel over the actors and values.

This returns an ordered iterator that will return results of the map as they finish. Note that you must iterate over the iterator to force the computation to finish.

Parameters

• fn – Function that takes (actor, value) as argument and returns an ObjectRef computing the result over the value. The actor will be considered busy until the ObjectRef completes.

• values – List of values that fn(actor, value) should be applied to.

Returns

Iterator over results from applying fn to the actors and values.

Examples

>>> from ray.util.actor_pool import ActorPool
>>> pool = ActorPool(...) 
>>> print(list(pool.map(lambda a, v: a.double.remote(v),
...                     [1, 2, 3, 4]))) 
[2, 4, 6, 8]

map_unordered(fn: Callable[[Any], Any], values: List[Any])

Similar to map(), but returning an unordered iterator.

This returns an unordered iterator that will return results of the map as they finish. This can be more efficient that map() if some results take longer to compute than others.

Parameters

• fn – Function that takes (actor, value) as argument and returns an ObjectRef computing the result over the value. The actor will be considered busy until the ObjectRef completes.

• values – List of values that fn(actor, value) should be applied to.

Returns

Iterator over results from applying fn to the actors and values.

Examples

>>> from ray.util.actor_pool import ActorPool
>>> pool = ActorPool(...) 
>>> print(list(pool.map_unordered(lambda a, v: a.double.remote(v),
...                               [1, 2, 3, 4]))) 
[6, 2, 4, 8]

submit(fn, value)

Schedule a single task to run in the pool.

This has the same argument semantics as map(), but takes on a single value instead of a list of values. The result can be retrieved using get_next() / get_next_unordered().

Parameters

• fn – Function that takes (actor, value) as argument and returns an ObjectRef computing the result over the value. The actor will be considered busy until the ObjectRef completes.

• value – Value to compute a result for.

Examples

>>> from ray.util.actor_pool import ActorPool
>>> pool = ActorPool(...) 
>>> pool.submit(lambda a, v: a.double.remote(v), 1) 
>>> pool.submit(lambda a, v: a.double.remote(v), 2) 
>>> print(pool.get_next(), pool.get_next()) 
2, 4

has_next()

Returns whether there are any pending results to return.

Returns

True if there are any pending results not yet returned.

Examples

>>> from ray.util.actor_pool import ActorPool
>>> pool = ActorPool(...) 
>>> pool.submit(lambda a, v: a.double.remote(v), 1) 
>>> print(pool.has_next()) 
True
>>> print(pool.get_next()) 
2
>>> print(pool.has_next()) 
False

get_next(timeout=None, ignore_if_timedout=False)

Returns the next pending result in order.

This returns the next result produced by submit(), blocking for up to the specified timeout until it is available.

Returns

The next result.

Raises

TimeoutError if the timeout is reached. –

Examples

>>> from ray.util.actor_pool import ActorPool
>>> pool = ActorPool(...) 
>>> pool.submit(lambda a, v: a.double.remote(v), 1) 
>>> print(pool.get_next()) 
2

get_next_unordered(timeout=None, ignore_if_timedout=False)

Returns any of the next pending results.

This returns some result produced by submit(), blocking for up to the specified timeout until it is available. Unlike get_next(), the results are not always returned in same order as submitted, which can improve performance.

Returns

The next result.

Raises

TimeoutError if the timeout is reached. –

Examples

>>> from ray.util.actor_pool import ActorPool
>>> pool = ActorPool(...) 
>>> pool.submit(lambda a, v: a.double.remote(v), 1) 
>>> pool.submit(lambda a, v: a.double.remote(v), 2) 
>>> print(pool.get_next_unordered()) 
4
>>> print(pool.get_next_unordered()) 
2

has_free()

Returns whether there are any idle actors available.

Returns

True if there are any idle actors and no pending submits.

Examples

>>> @ray.remote 
>>> class Actor: 
...     ... 
>>> a1 = Actor.remote() 
>>> pool = ActorPool(a1) 
>>> pool.submit(lambda a, v: a.double.remote(v), 1) 
>>> print(pool.has_free()) 
False
>>> print(pool.get_next()) 
2
>>> print(pool.has_free()) 
True

pop_idle()

Removes an idle actor from the pool.

Returns

An idle actor if one is available. None if no actor was free to be removed.

Examples

>>> @ray.remote 
>>> class Actor: 
...     ... 
>>> a1 = Actor.remote() 
>>> pool = ActorPool([a1]) 
>>> pool.submit(lambda a, v: a.double.remote(v), 1) 
>>> print(pool.pop_idle()) 
None
>>> print(pool.get_next()) 
2
>>> print(pool.pop_idle()) 
<ptr to a1>

push(actor)

Pushes a new actor into the current list of idle actors.

Examples

>>> @ray.remote 
>>> class Actor: 
...     ... 
>>> a1, b1 = Actor.remote(), Actor.remote() 
>>> pool = ActorPool([a1]) 
>>> pool.submit(lambda a, v: a.double.remote(v), 1) 
>>> print(pool.get_next()) 
2
>>> pool2 = ActorPool([b1]) 
>>> pool2.push(pool.pop_idle())