Ray Actors

Use Ray actors to build long-lived, stateful workers that persist across method calls.

An actor is a Python class annotated with @ray.remote. Each actor instance runs in its own worker process and keeps state in memory across calls.

Define an actor

import ray

@ray.remote
class Counter:
    def __init__(self, start: int = 0):
        self.value = start

    def increment(self) -> int:
        self.value += 1
        return self.value

    def get(self) -> int:
        return self.value

Create instances and call methods

counter = Counter.remote(10)
ray.get([counter.increment.remote() for _ in range(5)])
print(ray.get(counter.get.remote()))  # 15

Method calls return ObjectRefs, just like tasks. Calls to the same actor instance execute serially, in the order they were submitted.

Resource requirements

@ray.remote(num_cpus=2, num_gpus=1)
class ModelServer:
    def __init__(self):
        import torch
        self.model = torch.load("model.pt").cuda()

    def predict(self, x):
        with torch.no_grad():
            return self.model(x).cpu()

Named actors

Give an actor a name so other tasks can fetch a handle to it from anywhere in the cluster.

counter = Counter.options(name="global_counter", lifetime="detached").remote()

# elsewhere — even in a different job
counter = ray.get_actor("global_counter")

lifetime="detached" keeps the actor alive after the creating job exits.

Async actors

Actors with async methods can interleave concurrent calls.

import asyncio

@ray.remote
class AsyncFetcher:
    async def fetch(self, url):
        await asyncio.sleep(0.1)
        return url

Concurrency groups

Use max_concurrency to allow multiple methods to run on the same actor concurrently (within thread or asyncio scheduling limits).

@ray.remote(max_concurrency=4)
class Service:
    ...

Killing actors

ray.kill(counter)

This terminates the actor immediately. Add no_restart=False to re-create the actor automatically after a crash.

Best practices

Actors are heavyweight compared to tasks. Use them when you need state — model weights, caches, accumulators — and use tasks when you don’t.

Avoid making actor methods CPU-bound and long-running. A long call blocks all other calls to that actor. Split work into smaller methods or use multiple actors.

Next steps

Tasks

Stateless parallel work.

Patterns

Effective use of actors for parameter servers, caches, and pipelines.