Implementation:Ray project Ray MessagePackSerializer Decode

Knowledge Sources	Ray MessagePack
Domains	Serialization, Cross_Language_Interop
Last Updated	2026-02-13 17:00 GMT

Overview

Concrete tool for decoding MessagePack binary data from cross-language workers into typed Java objects provided by the Ray Java runtime.

Description

MessagePackSerializer.decode() reads the 9-byte length header, unpacks the MessagePack value using registered type unpackers, and returns the Java object. For extension type 101 (Java-specific FST data), it delegates to FstSerializer.decode(). If the foreign worker raised an exception, a CrossLanguageException is thrown (extends RayException, unchecked).

Usage

Used internally by the Ray runtime during object retrieval. Not typically called directly.

Code Reference

Source Location

• Repository: ray-project/ray
• File: java/runtime/src/main/java/io/ray/runtime/serializer/MessagePackSerializer.java (L280-300)
• File: java/api/src/main/java/io/ray/api/exception/CrossLanguageException.java (L3-8)

Signature

public static <T> T decode(byte[] bs, Class<?> type)

CrossLanguageException:

public class CrossLanguageException extends RayException {
    public CrossLanguageException(String message) {
        super(message);
    }
}

Import

import io.ray.runtime.serializer.MessagePackSerializer;
import io.ray.api.exception.CrossLanguageException;

I/O Contract

Inputs

Name	Type	Required	Description
bs	byte[]	Yes	MessagePack-encoded bytes from the object store
type	Class<?>	Yes	Expected Java return type (from function descriptor's returnType)

Outputs

Name	Type	Description
result	T	Deserialized Java object of the specified type
exception	CrossLanguageException	Thrown if the foreign worker raised an error

Usage Examples

Automatic Deserialization on Get

import io.ray.api.Ray;
import io.ray.api.ObjectRef;
import io.ray.api.function.PyFunction;
import io.ray.api.exception.CrossLanguageException;

ObjectRef<Integer> ref = Ray.task(
    PyFunction.of("math_ops", "add", Integer.class), 3, 4
).remote();

try {
    // Automatic MessagePack deserialization to Integer
    Integer result = ref.get();
    System.out.println(result); // 7
} catch (CrossLanguageException e) {
    // Python raised an exception
    System.err.println("Python error: " + e.getMessage());
}

Related Pages

Implements Principle

• Principle:Ray_project_Ray_Cross_Language_Deserialization

Requires Environment

• Environment:Ray_project_Ray_Java_Build_Environment