Ray Objects

Share Python objects efficiently across tasks and actors using Ray’s distributed object store.

Every value returned by a task and every value placed with ray.put lives in Ray’s distributed object store. Workers fetch objects on demand: zero-copy from shared memory on the same node, and over the network from remote nodes.

Place values into the object store

import numpy as np
import ray

big = np.zeros((10_000, 10_000))
ref = ray.put(big)

ray.put returns an ObjectRef. Pass it to tasks instead of re-serializing the underlying value.

Retrieve values

ray.get blocks until the object is ready and returns its value.

@ray.remote
def total(arr):
    return arr.sum()

print(ray.get(total.remote(ref)))

Wait for results

ray.wait returns the subset of refs that have already finished.

refs = [task.remote(i) for i in range(100)]
ready, pending = ray.wait(refs, num_returns=10, timeout=5.0)

Pass refs through tasks

A task that takes an ObjectRef argument receives the resolved value automatically — Ray fetches it onto the node where the task runs.

@ray.remote
def shift(arr, n):
    return arr + n

@ray.remote
def stats(arr):
    return arr.mean(), arr.std()

shifted = shift.remote(ref, 5)
print(ray.get(stats.remote(shifted)))

Object lifetimes

Objects are reference-counted. When no Python reference and no in-flight task holds a ref, the object is evicted. To keep an object alive longer than the variable, store the ref somewhere durable (a list, an actor field, a dictionary, etc.).

Spilling

When the object store fills, Ray spills cold objects to local disk and (optionally) external storage like S3.

ray.init(
    object_store_memory=10 * 1024**3,
    _system_config={"object_spilling_config": '{"type":"filesystem","params":{"directory_path":"/tmp/ray_spill"}}'},
)

Out-of-band serialization

The object store uses Ray’s serializer (built on cloudpickle and Arrow). For custom types, register a custom serializer with ray.util.register_serializer.

Best practices

Use ray.put for any large object you’ll pass to multiple tasks. Without it, Ray re-serializes the value into every task argument.

Don’t call ray.get on a list of refs in a loop. Pass the whole list at once to avoid sequencing the work.

Next steps

Tasks

Use refs as arguments and return values.

Patterns

Object store patterns for ML pipelines.