ray.remote#

ray.remote(__t: Type[T]) → ActorClass[T][source]#
ray.remote(__function: Callable[[], R]) → RemoteFunctionNoArgs[R]
ray.remote(__function: Callable[[T0], R]) → RemoteFunction0[R, T0]
ray.remote(__function: Callable[[T0, T1], R]) → RemoteFunction1[R, T0, T1]
ray.remote(__function: Callable[[T0, T1, T2], R]) → RemoteFunction2[R, T0, T1, T2]
ray.remote(__function: Callable[[T0, T1, T2, T3], R]) → RemoteFunction3[R, T0, T1, T2, T3]
ray.remote(__function: Callable[[T0, T1, T2, T3, T4], R]) → RemoteFunction4[R, T0, T1, T2, T3, T4]
ray.remote(__function: Callable[[T0, T1, T2, T3, T4, T5], R]) → RemoteFunction5[R, T0, T1, T2, T3, T4, T5]
ray.remote(__function: Callable[[T0, T1, T2, T3, T4, T5, T6], R]) → RemoteFunction6[R, T0, T1, T2, T3, T4, T5, T6]
ray.remote(__function: Callable[[T0, T1, T2, T3, T4, T5, T6, T7], R]) → RemoteFunction7[R, T0, T1, T2, T3, T4, T5, T6, T7]
ray.remote(__function: Callable[[T0, T1, T2, T3, T4, T5, T6, T7, T8], R]) → RemoteFunction8[R, T0, T1, T2, T3, T4, T5, T6, T7, T8]
ray.remote(__function: Callable[[T0, T1, T2, T3, T4, T5, T6, T7, T8, T9], R]) → RemoteFunction9[R, T0, T1, T2, T3, T4, T5, T6, T7, T8, T9]
ray.remote(*, num_returns: int | Literal['streaming'] = Undefined, num_cpus: int | float = Undefined, num_gpus: int | float = Undefined, resources: Dict[str, float] = Undefined, accelerator_type: str = Undefined, memory: int | float = Undefined, max_calls: int = Undefined, max_restarts: int = Undefined, max_task_retries: int = Undefined, max_retries: int = Undefined, runtime_env: Dict[str, Any] = Undefined, retry_exceptions: bool = Undefined, scheduling_strategy: None | Literal['DEFAULT'] | Literal['SPREAD'] | PlacementGroupSchedulingStrategy = Undefined, label_selector: Dict[str, str] = Undefined, fallback_strategy: List[Dict[str, Any]] = Undefined) → RemoteDecorator

Defines a remote function or an actor class.

This function can be used as a decorator with no arguments to define a remote function or actor as follows:

import ray

@ray.remote
def f(a, b, c):
    return a + b + c

object_ref = f.remote(1, 2, 3)
result = ray.get(object_ref)
assert result == (1 + 2 + 3)

@ray.remote
class Foo:
    def __init__(self, arg):
        self.x = arg

    def method(self, a):
        return self.x + a

actor_handle = Foo.remote(123)
object_ref = actor_handle.method.remote(321)
result = ray.get(object_ref)
assert result == (123 + 321)

Equivalently, use a function call to create a remote function or actor.

def g(a, b, c):
    return a + b + c

remote_g = ray.remote(g)
object_ref = remote_g.remote(1, 2, 3)
assert ray.get(object_ref) == (1 + 2 + 3)

class Bar:
    def __init__(self, arg):
        self.x = arg

    def method(self, a):
        return self.x + a

RemoteBar = ray.remote(Bar)
actor_handle = RemoteBar.remote(123)
object_ref = actor_handle.method.remote(321)
result = ray.get(object_ref)
assert result == (123 + 321)

It can also be used with specific keyword arguments as follows:

@ray.remote(num_gpus=1, max_calls=1, num_returns=2)
def f():
    return 1, 2

@ray.remote(num_cpus=2, resources={"CustomResource": 1})
class Foo:
    def method(self):
        return 1

Remote task and actor objects returned by @ray.remote can also be dynamically modified with the same arguments as above using .options() as follows:

@ray.remote(num_gpus=1, max_calls=1, num_returns=2)
def f():
    return 1, 2

f_with_2_gpus = f.options(num_gpus=2)
object_refs = f_with_2_gpus.remote()
assert ray.get(object_refs) == [1, 2]

@ray.remote(num_cpus=2, resources={"CustomResource": 1})
class Foo:
    def method(self):
        return 1

Foo_with_no_resources = Foo.options(num_cpus=1, resources=None)
foo_actor = Foo_with_no_resources.remote()
assert ray.get(foo_actor.method.remote()) == 1

A remote actor will be terminated when all actor handle to it in Python is deleted, which will cause them to complete any outstanding work and then shut down. If you only have 1 reference to an actor handle, calling del actor could trigger actor deletion. Note that your program may have multiple references to the same ActorHandle, and actor termination will not occur until the reference count goes to 0. See the Python documentation for more context about object deletion. https://docs.python.org/3.9/reference/datamodel.html#object.__del__

If you want to kill actors immediately, you can also call ray.kill(actor).

Tip

Avoid repeatedly passing in large arguments to remote task or method calls.

Instead, use ray.put to create a copy of the object in the object store.

See more info here.

Parameters:

  • *args – When used as a bare decorator (@ray.remote), the single positional argument is the function or class being decorated.

  • **kwargs –

    When used with options (@ray.remote(...) or ray.remote(...)), the decorator options. Accepted keys:

    • num_returns: remote functions only. Number of object refs returned by the remote function invocation. The default is 1. Pass "dynamic" to allow the task to decide at runtime; callers receive an ObjectRef[DynamicObjectRefGenerator]. See dynamic generators for details.

    • num_cpus: CPU resources to reserve for the task or actor. By default, tasks use 1 CPU resource and actors use 1 CPU for scheduling and 0 CPU for running. See specifying resource requirements.

    • num_gpus: GPU resources to reserve. Default is 0. See Ray GPU support.

    • resources: Dict of custom resources mapping resource names to float quantities.

    • label_selector: [Experimental] Labels required for the node this actor can be scheduled on (key-value expressions).

    • fallback_strategy: [Experimental] Soft scheduling constraints expressed as a list of decorator-option dicts. Currently only label_selector is supported.

    • accelerator_type: Require a node with the specified accelerator type. See accelerator types.

    • memory: Heap memory request in bytes for this task/actor.

    • max_calls: remote functions only. Maximum number of times a worker can execute this function before it must exit. By default infinite for CPU tasks and 1 for GPU tasks.

    • max_restarts: actors only. Maximum number of times the actor should be restarted when it dies unexpectedly. -1 means restart indefinitely.

    • max_task_retries: actors only. How many times to retry an actor task if it fails due to a system error.

    • max_retries: remote functions only. Maximum number of times to rerun the function when the worker crashes unexpectedly. Default is 3; -1 means infinite retries.

    • allow_out_of_order_execution: actors only. Whether Ray may execute actor tasks out of order.

    • runtime_env: Runtime environment for this actor or task and its children. See Runtime environments.

    • retry_exceptions: remote functions only. Whether application-level errors should be retried up to max_retries times, or a list of allow-listed exceptions to retry.

    • scheduling_strategy: How to schedule the remote function or actor. See Ray scheduling strategies.

    • _labels: Key-value labels for the task or actor.

Returns:

The decorated remote function or actor class, or a decorator that applies the supplied options when used as @ray.remote(...).

On this page