Struct ActrRef 

pub struct ActrRef<W: Workload> { /* private fields */ }

ActrRef - Lightweight reference to a running Actor

This is the primary handle returned by ActrNode::start().

Code Generation Pattern

actr-cli code generator will generate type-safe RPC methods for ActrRef.

Proto Definition

service EchoService {
  rpc Echo(EchoRequest) returns (EchoResponse);
  rpc Ping(PingRequest) returns (PingResponse);
}

Generated Code (in generated/echo_service_actr_ref.rs)

use actr_runtime::ActrRef;
use super::echo_service_actor::{EchoServiceWorkload, EchoServiceHandler};
use super::echo::{EchoRequest, EchoResponse, PingRequest, PingResponse};

impl<T: EchoServiceHandler> ActrRef<EchoServiceWorkload<T>> {
    /// Call Echo RPC method
    pub async fn echo(&self, request: EchoRequest) -> ActorResult<EchoResponse> {
        self.call(request).await
    }

    /// Call Ping RPC method
    pub async fn ping(&self, request: PingRequest) -> ActorResult<PingResponse> {
        self.call(request).await
    }
}

Usage in Shell

use generated::echo_service_actr_ref::*;  // Import ActrRef extensions

let actr = node.start().await?;

// Type-safe RPC calls (generated methods)
let response = actr.echo(EchoRequest {
    message: "Hello".to_string(),
}).await?;

// Or use generic call() method
let response: EchoResponse = actr.call(EchoRequest { ... }).await?;

Design Rationale

Why bind RPC methods to ActrRef?

1. Type Safety: Compiler checks request/response types
2. Auto-completion: IDE shows available RPC methods
3. No target needed: ActrRef already knows its target Actor
4. Symmetric to Context: Similar to Context extension pattern

Comparison with Context pattern:

Aspect	Context (in Workload)	ActrRef (in Shell)
Caller	Workload	Shell
Target	Any Actor (needs target param)	This Workload (fixed)
Method	ctx.call(target, req)	actr.echo(req)
Generation	Extension trait	Concrete impl

Implementations

impl<W: Workload> ActrRef<W>

pub fn actor_id(&self) -> &ActrId

Get Actor ID

pub async fn call<R>(&self, request: R) -> ActorResult<R::Response>

where R: RpcRequest + ProstMessage,

Call Actor method (Shell → Workload RPC)

This is a generic method used by code-generated RPC methods. Most users should use the generated methods instead.

Example

// Generic call
let response: EchoResponse = actr.call(EchoRequest {
    message: "Hello".to_string(),
}).await?;

// Generated method (preferred)
let response = actr.echo(EchoRequest {
    message: "Hello".to_string(),
}).await?;

pub async fn tell<R>(&self, message: R) -> ActorResult<()>

where R: RpcRequest + ProstMessage,

Send one-way message to Actor (Shell → Workload, fire-and-forget)

Unlike call(), this method does not wait for a response. Use this for notifications or commands that don’t need acknowledgment.

Example

// Send notification without waiting for response
actr.tell(LogEvent {
    level: "INFO".to_string(),
    message: "User logged in".to_string(),
}).await?;

// Generated method (if codegen supports tell)
actr.log_event(LogEvent { ... }).await?;

Performance

• Latency: ~10μs (in-process, zero serialization)
• No blocking: Returns immediately after sending
• No response: Caller won’t know if message was processed

pub fn shutdown(&self)

Trigger Actor shutdown

This signals the Actor to stop, but does not wait for completion. Use wait_for_shutdown() to wait for cleanup to finish.

pub async fn wait_for_shutdown(&self)

Wait for Actor to fully shutdown

This waits for the shutdown signal to be triggered. All background tasks will be aborted when the last ActrRef is dropped.

pub fn is_shutting_down(&self) -> bool

Check if Actor is shutting down

pub async fn wait_for_ctrl_c_and_shutdown(self) -> ActorResult<()>

Convenience: wait for Ctrl+C and shutdown

This consumes the ActrRef and waits for Ctrl+C, then triggers shutdown.

Example

let actr = node.start().await?;
actr.wait_for_ctrl_c_and_shutdown().await?;

Trait Implementations

impl<W: Workload> Clone for ActrRef<W>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.