CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-io-ray--ray-runtime

Ray runtime implementation for Java - the core distributed runtime component of Ray framework for scaling AI and Python applications

—

Pending
Overview
Eval results
Files

cross-language.mddocs/

Cross-Language Features

Complete Python and C++ integration enabling polyglot distributed computing workflows with seamless interoperability across language boundaries.

Capabilities

Python Integration

Execute Python functions and create Python actors from Java code with full type safety.

// Python function representation
public class PyFunction<R> {
    /**
     * Create Python function reference.
     * @param moduleName Python module name
     * @param functionName Python function name
     * @return PyFunction instance for untyped result
     */
    public static PyFunction<Object> of(String moduleName, String functionName);
    
    /**
     * Create typed Python function reference.
     * @param moduleName Python module name
     * @param functionName Python function name
     * @param returnType Expected return type
     * @return PyFunction instance for typed result
     */
    public static <R> PyFunction<R> of(String moduleName, String functionName, Class<R> returnType);
}

// Python task execution (0-6 Object parameters)
public static <R> PyTaskCaller<R> task(PyFunction<R> pyFunction);
public static <R> PyTaskCaller<R> task(PyFunction<R> pyFunction, Object obj0);
public static <R> PyTaskCaller<R> task(PyFunction<R> pyFunction, Object obj0, Object obj1);
public static <R> PyTaskCaller<R> task(PyFunction<R> pyFunction, Object obj0, Object obj1, Object obj2);
public static <R> PyTaskCaller<R> task(PyFunction<R> pyFunction, Object obj0, Object obj1, Object obj2, Object obj3);
public static <R> PyTaskCaller<R> task(PyFunction<R> pyFunction, Object obj0, Object obj1, Object obj2, Object obj3, Object obj4);
public static <R> PyTaskCaller<R> task(PyFunction<R> pyFunction, Object obj0, Object obj1, Object obj2, Object obj3, Object obj4, Object obj5);

Usage Examples:

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

public class PythonIntegration {
    public static void main(String[] args) {
        Ray.init();
        
        // Call Python function without type specification
        PyFunction<Object> pyFunc = PyFunction.of("math", "sqrt");
        ObjectRef<Object> result1 = Ray.task(pyFunc, 16.0).remote();
        System.out.println("Square root: " + Ray.get(result1)); // 4.0
        
        // Call Python function with type safety
        PyFunction<Double> typedFunc = PyFunction.of("math", "pow", Double.class);
        ObjectRef<Double> result2 = Ray.task(typedFunc, 2.0, 3.0).remote();
        System.out.println("Power: " + Ray.get(result2)); // 8.0
        
        // Call custom Python module
        PyFunction<String> customFunc = PyFunction.of("my_module", "process_data", String.class);
        ObjectRef<String> result3 = Ray.task(customFunc, "input data", 42).remote();
        System.out.println("Processed: " + Ray.get(result3));
        
        Ray.shutdown();
    }
}

Python Actors

Create and interact with Python actors from Java.

// Python actor class representation
public class PyActorClass {
    // Represents a Python actor class
}

// Python actor method representation  
public class PyActorMethod {
    // Represents a Python actor method
}

// Python actor creation (0-6 Object parameters)
public static PyActorCreator actor(PyActorClass pyActorClass);
public static PyActorCreator actor(PyActorClass pyActorClass, Object obj0);
public static PyActorCreator actor(PyActorClass pyActorClass, Object obj0, Object obj1);
public static PyActorCreator actor(PyActorClass pyActorClass, Object obj0, Object obj1, Object obj2);
public static PyActorCreator actor(PyActorClass pyActorClass, Object obj0, Object obj1, Object obj2, Object obj3);
public static PyActorCreator actor(PyActorClass pyActorClass, Object obj0, Object obj1, Object obj2, Object obj3, Object obj4);
public static PyActorCreator actor(PyActorClass pyActorClass, Object obj0, Object obj1, Object obj2, Object obj3, Object obj4, Object obj5);

public interface PyActorHandle extends BaseActorHandle {
    // Python actor handle with method calling capability
}

public interface PyActorCreator {
    /**
     * Create Python actor remotely.
     * @return PyActorHandle for calling Python actor methods
     */
    PyActorHandle remote();
}

public interface PyActorTaskCaller<R> {
    /**
     * Execute Python actor method call.
     * @return ObjectRef to the method result
     */
    ObjectRef<R> remote();
}

Usage Examples:

// Assuming you have a Python actor class like:
// class Counter:
//     def __init__(self, initial_value):
//         self.count = initial_value
//     
//     def increment(self):
//         self.count += 1
//         return self.count
//     
//     def get_value(self):
//         return self.count

public class PythonActors {
    public static void main(String[] args) {
        Ray.init();
        
        // Create Python actor class reference
        PyActorClass counterClass = new PyActorClass(); // Implementation details abstracted
        
        // Create Python actor with constructor arguments
        PyActorHandle counter = Ray.actor(counterClass, 10).remote();
        
        // Call Python actor methods
        // Note: Actual method calling syntax may vary in implementation
        // This shows the conceptual approach
        
        Ray.shutdown();
    }
}

C++ Integration

Execute C++ functions and create C++ actors from Java code.

// C++ function representation
public class CppFunction<R> {
    // Represents a C++ function
}

// C++ actor class representation
public class CppActorClass {
    // Represents a C++ actor class
}

// C++ actor method representation
public class CppActorMethod {
    // Represents a C++ actor method
}

// C++ task execution (0-6 Object parameters)
public static <R> CppTaskCaller<R> task(CppFunction<R> cppFunction);
public static <R> CppTaskCaller<R> task(CppFunction<R> cppFunction, Object obj0);
public static <R> CppTaskCaller<R> task(CppFunction<R> cppFunction, Object obj0, Object obj1);
public static <R> CppTaskCaller<R> task(CppFunction<R> cppFunction, Object obj0, Object obj1, Object obj2);
public static <R> CppTaskCaller<R> task(CppFunction<R> cppFunction, Object obj0, Object obj1, Object obj2, Object obj3);
public static <R> CppTaskCaller<R> task(CppFunction<R> cppFunction, Object obj0, Object obj1, Object obj2, Object obj3, Object obj4);
public static <R> CppTaskCaller<R> task(CppFunction<R> cppFunction, Object obj0, Object obj1, Object obj2, Object obj3, Object obj4, Object obj5);

// C++ actor creation (0-6 Object parameters)
public static CppActorCreator actor(CppActorClass cppActorClass);
public static CppActorCreator actor(CppActorClass cppActorClass, Object obj0);
public static CppActorCreator actor(CppActorClass cppActorClass, Object obj0, Object obj1);
public static CppActorCreator actor(CppActorClass cppActorClass, Object obj0, Object obj1, Object obj2);
public static CppActorCreator actor(CppActorClass cppActorClass, Object obj0, Object obj1, Object obj2, Object obj3);
public static CppActorCreator actor(CppActorClass cppActorClass, Object obj0, Object obj1, Object obj2, Object obj3, Object obj4);
public static CppActorCreator actor(CppActorClass cppActorClass, Object obj0, Object obj1, Object obj2, Object obj3, Object obj4, Object obj5);

Usage Examples:

import io.ray.api.Ray;
import io.ray.api.ObjectRef;
import io.ray.api.function.CppFunction;

public class CppIntegration {
    public static void main(String[] args) {
        Ray.init();
        
        // Create C++ function reference
        CppFunction<Double> cppMathFunc = new CppFunction<>(); // Implementation details abstracted
        
        // Call C++ function
        ObjectRef<Double> result = Ray.task(cppMathFunc, 5.0, 3.0).remote();
        System.out.println("C++ result: " + Ray.get(result));
        
        Ray.shutdown();
    }
}

Cross-Language Handle Types

Handle different types of actors from different languages.

// Base actor handle (language-agnostic)
public interface BaseActorHandle {
    ActorId getId();
    void kill();
    void kill(boolean noRestart);
}

// Java actor handle (typed)
public interface ActorHandle<A> extends BaseActorHandle {
    // Type-safe method calling for Java actors
}

// Python actor handle
public interface PyActorHandle extends BaseActorHandle {
    // Python-specific actor operations
}

// C++ actor handle
public interface CppActorHandle extends BaseActorHandle {
    // C++-specific actor operations
}

Cross-Language Task Callers

Task Caller Interfaces

// Java task caller
public interface TaskCaller<R> {
    ObjectRef<R> remote();
}

// Python task caller
public interface PyTaskCaller<R> {
    ObjectRef<R> remote();
}

// C++ task caller
public interface CppTaskCaller<R> {
    ObjectRef<R> remote();
}

// Actor task callers
public interface ActorTaskCaller<R> {
    ObjectRef<R> remote();
}

public interface PyActorTaskCaller<R> {
    ObjectRef<R> remote();
}

public interface CppActorTaskCaller<R> {
    ObjectRef<R> remote();
}

Practical Cross-Language Workflows

Polyglot Data Pipeline

public class PolyglotPipeline {
    public static void main(String[] args) {
        Ray.init();
        
        // Step 1: Load data with Java
        ObjectRef<List<String>> rawData = Ray.task(JavaDataLoader::loadData, "source.csv").remote();
        
        // Step 2: Process with Python (using pandas, numpy, etc.)
        PyFunction<Object> pythonProcessor = PyFunction.of("data_processing", "clean_and_transform");
        ObjectRef<Object> cleanedData = Ray.task(pythonProcessor, rawData).remote();
        
        // Step 3: Analyze with C++ (high-performance algorithms)
        CppFunction<Double> cppAnalyzer = new CppFunction<>(); // Implementation abstracted
        ObjectRef<Double> analysisResult = Ray.task(cppAnalyzer, cleanedData).remote();
        
        // Step 4: Generate report with Java
        ObjectRef<String> report = Ray.task(JavaReportGenerator::generateReport, analysisResult).remote();
        
        System.out.println("Final report: " + Ray.get(report));
        
        Ray.shutdown();
    }
}

class JavaDataLoader {
    public static List<String> loadData(String source) {
        // Java data loading logic
        return Arrays.asList("data1", "data2", "data3");
    }
}

class JavaReportGenerator {
    public static String generateReport(Double result) {
        return "Analysis Result: " + result;
    }
}

Mixed-Language Actor System

public class MixedActorSystem {
    public static void main(String[] args) {
        Ray.init();
        
        // Create Java coordinator actor
        ActorHandle<Coordinator> coordinator = Ray.actor(Coordinator::new).remote();
        
        // Create Python worker actors
        PyActorClass pythonWorkerClass = new PyActorClass(); // Implementation abstracted
        PyActorHandle pythonWorker1 = Ray.actor(pythonWorkerClass, "worker1").remote();
        PyActorHandle pythonWorker2 = Ray.actor(pythonWorkerClass, "worker2").remote();
        
        // Create C++ compute actor
        CppActorClass cppComputeClass = new CppActorClass(); // Implementation abstracted
        CppActorHandle cppCompute = Ray.actor(cppComputeClass).remote();
        
        // Coordinate work across languages
        ObjectRef<String> result = coordinator.task(Coordinator::orchestrateWork, 
            Arrays.asList(pythonWorker1, pythonWorker2), cppCompute).remote();
        
        System.out.println("Orchestration result: " + Ray.get(result));
        
        Ray.shutdown();
    }
}

class Coordinator {
    public String orchestrateWork(List<PyActorHandle> pythonWorkers, CppActorHandle cppCompute) {
        // Coordinate work between different language actors
        // Implementation would involve calling methods on the different actor types
        return "Work orchestrated successfully";
    }
}

Exception Handling

Cross-Language Exceptions

/**
 * Exception thrown when cross-language operations fail.
 */
public class CrossLanguageException extends RayException {
    // Cross-language integration specific exceptions
}

Usage Example:

try {
    PyFunction<String> pyFunc = PyFunction.of("invalid_module", "invalid_function", String.class);
    ObjectRef<String> result = Ray.task(pyFunc, "data").remote();
    String value = Ray.get(result);
} catch (CrossLanguageException e) {
    System.out.println("Cross-language call failed: " + e.getMessage());
} catch (RayTaskException e) {
    System.out.println("Python task failed: " + e.getMessage());
}

Best Practices

Type Safety

// Use typed function references when possible
PyFunction<Double> mathFunc = PyFunction.of("math", "sqrt", Double.class);
ObjectRef<Double> result = Ray.task(mathFunc, 25.0).remote();
Double value = Ray.get(result); // Type-safe result

// Handle untyped results carefully
PyFunction<Object> untypedFunc = PyFunction.of("my_module", "complex_function");
ObjectRef<Object> untypedResult = Ray.task(untypedFunc, "input").remote();
Object value = Ray.get(untypedResult);
// Cast carefully based on expected Python return type

Data Serialization

// Ray handles serialization across languages automatically
// Complex Java objects are serialized and can be used in Python/C++
List<CustomData> javaData = createComplexData();
ObjectRef<List<CustomData>> dataRef = Ray.put(javaData);

// Pass to Python function
PyFunction<Object> processor = PyFunction.of("processor", "handle_java_data");
ObjectRef<Object> result = Ray.task(processor, dataRef).remote();

Error Handling

// Always wrap cross-language calls in appropriate try-catch blocks
try {
    PyFunction<String> pyFunc = PyFunction.of("data_module", "process", String.class);
    ObjectRef<String> result = Ray.task(pyFunc, inputData).remote();
    String processedData = Ray.get(result);
    // Handle successful result
} catch (CrossLanguageException e) {
    // Handle cross-language integration errors
    System.err.println("Cross-language error: " + e.getMessage());
} catch (RayTaskException e) {
    // Handle Python/C++ task execution errors
    System.err.println("Task execution error: " + e.getMessage());
} catch (RayException e) {
    // Handle other Ray-related errors
    System.err.println("Ray error: " + e.getMessage());
}

Install with Tessl CLI

npx tessl i tessl/maven-io-ray--ray-runtime

docs

actors.md

advanced-actors.md

cross-language.md

index.md

object-store.md

placement-groups.md

runtime.md

tasks.md

tile.json