Workflow:Ray project Ray Cross Language Invocation
| Knowledge Sources | |
|---|---|
| Domains | Distributed_Computing, Cross_Language, Interoperability |
| Last Updated | 2026-02-13 16:00 GMT |
Overview
End-to-end process for invoking remote functions and actors across language boundaries (Java, Python, C++) within a Ray cluster using MessagePack-based cross-language serialization.
Description
This workflow covers the mechanism for calling functions and actors defined in one programming language from another within the same Ray cluster. It supports Java-to-Python, Python-to-Java, Java-to-C++, and Python-to-C++ invocations. The cross-language bridge uses typed function descriptors (PyFunction, CppFunction, PyActorClass, CppActorClass) to reference foreign-language callables, MessagePack serialization for argument and result transfer, and the standard Ray task/actor submission infrastructure for execution. Named actors provide cross-language service discovery, and exception chains propagate faithfully across language boundaries.
Usage
Execute this workflow when you need to combine components written in different languages within a single Ray application. Typical scenarios include calling Python ML inference from a Java web service, invoking high-performance C++ routines from Python data pipelines, or building polyglot microservices where each component uses the most appropriate language for its task.
Execution Steps
Step 1: Initialize Multi-Language Ray Cluster
Start a Ray cluster with support for multiple worker languages. The cluster must have workers for each language that will participate in cross-language calls. Java workers, Python workers, and optionally C++ workers are started with the appropriate code search paths configured so that each worker can locate the remote code modules.
Key considerations:
- Code search paths must include locations of all cross-language modules
- C++ workers require shared object (.so) library paths
- Python modules must be importable from the configured paths
- Java classpath must include all relevant class files
Step 2: Create Cross-Language Function Descriptors
Construct typed descriptors that reference functions or classes in the target language. Java uses PyFunction.of(moduleName, functionName, returnType) for Python functions and CppFunction.of(functionName, returnType) for C++ functions. Python uses ray.cross_language.java_function(className, methodName) for Java functions. Each descriptor captures the module path, function name, and expected return type for proper deserialization.
Key considerations:
- Module names must match the actual importable Python module paths
- Java class names must be fully qualified (e.g., io.ray.test.MyClass)
- C++ function names correspond to exported symbols in shared libraries
- Return type must be specified for correct deserialization on the caller side
Step 3: Serialize Arguments with MessagePack
Prepare function arguments for cross-language transfer using the MessagePack serialization protocol. The serializer converts Java/Python/C++ objects into a language-neutral binary format. Supported cross-language types include primitives (boolean, integers, floats, strings), byte arrays, and nested arrays. Language-specific types (Java Lists, Maps, custom objects) are wrapped in a MessagePack extension type (ID 101) and fall back to language-specific serialization, making them inaccessible from other languages.
Key considerations:
- Cross-language compatible types: Boolean, Byte, Short, Integer, Long, BigInteger, Float, Double, String, byte[], arrays
- Java Lists and Maps are NOT directly transferable; use Object[] instead
- BigInteger is limited to 2^64-1 due to MessagePack constraints
- Float values may be promoted to Double across language boundaries
- The serialized format includes a 9-byte length header followed by MessagePack data
Step 4: Submit Cross-Language Task
Submit the cross-language function call as a standard Ray task using the descriptor and serialized arguments. The runtime routes the task to a worker of the target language, which deserializes the arguments, executes the function, serializes the result, and stores it in the object store. The caller receives an ObjectRef pointing to the result. For actor invocations, actor creation and method calls follow the same pattern using PyActorClass/CppActorClass descriptors and PyActorMethod/CppActorMethod for method specification.
Key considerations:
- Cross-language tasks are scheduled on workers matching the target language
- Actor handles (PyActorHandle, CppActorHandle) can be passed between languages
- Named actors enable cross-language actor discovery without handle passing
- Async and sync actor concurrency modes are supported for Python actors
Step 5: Deserialize Results and Handle Exceptions
Retrieve the result from the object store and deserialize it back to the caller's language type. If the remote function raised an exception, a CrossLanguageException is thrown on the caller side, preserving the original error message and stack trace from the target language. Exception chains are faithfully propagated, allowing callers to diagnose failures that occurred in foreign-language code.
Key considerations:
- Return type specified in the descriptor guides deserialization
- CrossLanguageException wraps errors from foreign-language execution
- Nested exception chains (e.g., Java exception caused by Python error) are preserved
- Integer return values undergo automatic range detection (byte, short, int, long, BigInteger)