Implementation:Ray project Ray ObjectRefImpl

Knowledge Sources	Ray
Domains	Distributed_Computing, Java_Runtime
Last Updated	2026-02-13 16:00 GMT

Overview

Implementation of the ObjectRef<T> interface representing a reference to a Ray object in the object store, with automatic GC-based reference counting.

Description

ObjectRefImpl wraps an ObjectId and type class, managing local reference counts via the object store's addLocalReference/removeLocalReference methods. It uses FinalizableWeakReference with a FinalizableReferenceQueue to automatically decrement references when the Java object is garbage collected. A global ConcurrentHashMap of weak references supports memory store callback handling. The class implements Externalizable to serialize ownership information alongside the object ID for cross-worker object transfer.

Usage

Use ObjectRefImpl as the core user-facing handle to Ray objects. Every Ray.put() and task return value produces an ObjectRefImpl. Call get() to retrieve the underlying object value, or pass the reference to other tasks. The GC-aware reference counting ensures distributed garbage collection correctness without requiring manual cleanup.

Code Reference

Source Location

• Repository: Ray
• File: java/runtime/src/main/java/io/ray/runtime/object/ObjectRefImpl.java

Signature

public final class ObjectRefImpl<T> implements ObjectRef<T>, Externalizable {

  private ObjectId id;
  private Class<T> type;
  private byte[] rawData;

  public ObjectRefImpl(ObjectId id, Class<T> type, boolean skipAddingLocalRef) { ... }
  public ObjectRefImpl(ObjectId id, Class<T> type) { ... }
  public ObjectRefImpl() { ... }

  public void init(ObjectId id, Class<?> type, boolean skipAddingLocalRef) { ... }
  public synchronized T get() { ... }
  public synchronized T get(long timeoutMs) { ... }
  public ObjectId getId() { ... }
  public Class<T> getType() { ... }
  public void writeExternal(ObjectOutput out) throws IOException { ... }
  public void readExternal(ObjectInput in) throws IOException, ClassNotFoundException { ... }

  public static <T> void registerObjectRefImpl(ObjectId objectId, ObjectRefImpl<T> obj) { ... }
}

Import

import io.ray.runtime.object.ObjectRefImpl;

I/O Contract

Input (Constructor)

Parameter	Type	Description
id	ObjectId	The unique identifier for the Ray object
type	Class<T>	The Java class of the referenced object
skipAddingLocalRef	boolean	If true, skip adding a local reference (used for special internal cases)

Output

Method	Return Type	Description
get()	T	Blocks until the object is available and returns its value
get(long)	T	Blocks up to the specified timeout in milliseconds
getId()	ObjectId	The underlying object identifier
getType()	Class<T>	The Java type of the referenced object
toString()	String	String representation in the form ObjectRef(id)

Usage Examples

// ObjectRefImpl is typically created by the runtime, not directly by users.
// User code interacts with it through the ObjectRef<T> interface.

// Put an object and get a reference
ObjectRef<String> ref = Ray.put("hello world");

// Retrieve the value (blocks until available)
String value = ref.get();

// Retrieve with timeout
String valueWithTimeout = ref.get(5000); // 5 second timeout

// Pass references to remote tasks
ObjectRef<Integer> resultRef = Ray.task(MyClass::processData, ref).remote();

// The reference is automatically cleaned up when garbage collected,
// decrementing the distributed reference count.

Related Pages

• Environment:Ray_project_Ray_Java_Build_Environment