runact 1.3.3

A Rust-native actor runtime with BEAM-style processes
Documentation
# Hot Code Loading (Pattern 2: Dynamic Supervision)

## Overview

Runact supports **Pattern 2** hot code loading — the ability to load new versions of actor modules at runtime and have **newly spawned child actors automatically use the latest code version** after a hot code upgrade.

This implements Erlang/OTP's "dynamic supervisor" behavior: a supervisor receives work items and spawns a child actor per work unit. New children always use the current module version, so after a hot code upgrade, the next work item automatically gets processed by the new code.

## Feature Flag

All hot code loading functionality is gated behind the `hot_code_loading` cargo feature:

```toml
[dependencies]
runact = { version = "1.3", features = ["hot_code_loading"] }
```

The `hot_code_loading` feature has one optional dependency:
- `libloading` — for loading dynamic libraries at runtime

When the feature is disabled, all hot code loading code is compiled out (zero overhead).

## Architecture

### Core Components

| Component | Module | Description |
|-----------|--------|-------------|
| `CodeManager` | `codemgr.rs` | Version registry — tracks multiple versions of each module, only one is "current" |
| `ActorFactory` | `factory.rs` | Spawns versioned actors using `prepare_dynamic_spawn()` → always gets current vtable |
| `DynamicLibrary` | `loader.rs` | libloading wrapper for loading `.so`/`.dylib`/`.dll` at runtime |
| `DynamicSupervisor` | `dynamic_supervisor.rs` | Pattern 2 supervisor — spawns a child actor per work item |
| `SpawnListener` | `spawn_listener.rs` | Background thread that processes spawn requests from supervisors |
| `HotSwappable` | `mod.rs` | Trait for actors that support state serialization/deserialization |
| `MigrationRegistry` | `migration.rs` | State migration between versions |
| `WorkPayload` | `dynamic_supervisor.rs` | Trait for serializing work items into child actor initial state |

### Automatic Spawning (Pattern 2)

The key mechanism is in `ActorFactory::prepare_dynamic_spawn()`:

```
DynamicSupervisor::handle(SubmitWork)
    -> ctx.spawn_child(module_name, initial_state)        // sends SpawnRequest via channel
    -> SpawnListener thread receives request
    -> CodeManager::get_current_vtable(module_name)       // ALWAYS returns latest version
    -> child actor spawned with current-version vtable
```

The `ActorContext::spawn_child()` method sends a `SpawnRequest` via a crossbeam channel to the `SpawnListener` background thread. The `SpawnListener` looks up the **current** version's vtable from `CodeManager` and spawns the child actor with it.

Since `CodeManager::get_current_vtable()` always returns the latest version, new child actors automatically use the latest code after a hot code upgrade — no explicit coordination needed.

### Key Types

#### `DynamicSupervisor<T, R>`

A supervisor actor generic over:
- `T: WorkPayload` — the work payload type (serialized to bytes for child state)
- `R: Send + 'static` — the result type returned when a child completes

The supervisor implements `Actor` with `WorkerMessage<T, R>` as its message type.

#### `WorkerMessage<T, R>`

```rust
pub enum WorkerMessage<T, R> {
    SubmitWork { work: WorkItem<T>, responder: WorkerResponder<R> },
    ChildCompleted { work_id: u64, result: Result<R, WorkerError> },
    Shutdown,
}
```

#### `WorkPayload`

```rust
pub trait WorkPayload: Send + 'static {
    fn to_bytes(&self) -> Vec<u8>;
}
```

The supervisor calls `to_bytes()` on the payload to produce the initial state for the child actor.

#### `HotSwappable`

```rust
pub trait HotSwappable {
    fn current_version(&self) -> String;
    fn serialize_state(&self) -> Vec<u8>;
    fn deserialize_state(state: Vec<u8>) -> Result<Self, RuntimeError> where Self: Sized;
}
```

## Usage

### Loading a new version

```rust
let mut runtime = Runtime::new().unwrap();
runtime.load_actor_module("MyActor", "/path/to/libmyactor_v2.so")?;
```

### Creating a DynamicSupervisor

`DynamicSupervisor::new` takes the module name and an `Arc<ActorFactory>`:

```rust
pub fn new(module_name: &str, factory: std::sync::Arc<ActorFactory>) -> Self
```

The supervisor already implements `Actor` for `WorkerMessage<T, R>`, so you
do not implement `Actor` yourself — spawn it directly:

```rust
use runact::{DynamicSupervisor, Runtime, WorkPayload, WorkerMessage, WorkItem, WorkerResponder};

struct MyWork(String);
impl WorkPayload for MyWork {
    fn to_bytes(&self) -> Vec<u8> {
        self.0.as_bytes().to_vec()
    }
}

// `factory: Arc<ActorFactory>` — see the status note below.
let supervisor = DynamicSupervisor::<MyWork, String>::new("MyActor", factory);
let sup_id = runtime.spawn(supervisor).unwrap();
```

Submit work with a `WorkerResponder` backed by a channel:

```rust
let (tx, rx) = crossbeam_channel::bounded(1);

runtime.send(sup_id, WorkerMessage::SubmitWork {
    work: WorkItem { id: 1, payload: MyWork("data".into()) },
    responder: WorkerResponder { sender: tx },
}).unwrap();

let result: Result<String, runact::WorkerError> = rx.recv().unwrap();
```

> **Implementation status (v1.3.3):** `Runtime::actor_factory()` returns
> `&ActorFactory`, not the `Arc<ActorFactory>` that `DynamicSupervisor::new`
> requires, and the runtime's `CodeManager` is private. The crate's own tests
> construct the `Arc` directly; there is no public accessor yet. Version
> inspection (`Runtime::module_version`) works through the public API.

## Code Upgrade Flow

1. **Load new code**: `Runtime::load_actor_module("MyActor", "libmyactor_v2.so")`
   - `CodeManager::load_new_version()` loads the library, reads the vtable, marks it as current
   - Old children continue running the old version
   - New spawn requests will use v2.0

2. **New work arrives**: Supervisor receives `SubmitWork`
   - Calls `ctx.spawn_child("MyActor", initial_state)`
   - `SpawnRequest` sent to `SpawnListener`
   - `SpawnListener` calls `CodeManager::get_current_vtable("MyActor")` → gets v2.0 vtable
   - Child actor spawned with v2.0 code

3. **Result**: New child processes use the latest code. No restart of the supervisor needed.