# actors

`include actor;` loads `src/lib/actor.zc` from the project library directory. the compiler contains generic module loading, syntax registration and statement hooks. it does not embed or recognize actor syntax until the library registers its parser.

actors run asynchronously in separate operating-system processes on the native and portable micro interpreters on posix hosts. each worker has its own vm stack, heap, globals and captured handler state. workers can execute in parallel. these are isolated worker processes, rather than shared-memory threads.

```zc
namespace;
include rt, actor;
typecheck on;

actor Counter {
    int total;
    int handle(int value) {
        this.total += value;
        return this.total;
    }
}

fn main() {
    Counter* counter = rt.new(Counter);
    counter.spawn();
    counter.recv(fn(int value) {
        rt.put_n(value);
        rt.put_c(10);
        return 0;
    });
    counter.send(2);
    counter.send(3);
    counter.await();
    counter.close();
    return 0;
}
```

the example prints `2` and `5`. the worker's `total` changes independently of the caller's `counter.total`. `this` is implicit in actor methods; declaring it as an explicit first parameter is rejected.

a declared actor requires a `handle(input)` method with one input parameter and a typed result. the library adds `spawn`, `send`, `recv`, `poll`, `await` and `close`. allocate actor instances with `rt.new` to initialize their storage.

for a handler function or closure without a declared actor, allocate `actor.Actor<I,O>` and call `spawn(handler)`. for example, `actor.Actor<char*,int>` accepts character strings and returns integers. `typecheck on;` checks the handler, message and receiver types. receive callbacks currently return `int`.

`send` snapshots a message and queues it for the worker. it does not run the handler on the caller's stack. `recv(callback)` registers a callback without waiting. ordinary caller statements poll for completed results; `poll()` requests delivery explicitly and `await()` waits for all submitted messages to reach the registered receiver. callbacks execute on the caller's vm at statement boundaries and retain fifo order. a long blocking host call or an optimized `o3` region delays automatic delivery until the caller reaches another boundary.

messages copy their typed object graphs into the receiving context. supported values include scalars, enums, strings, packed fields, byte strings, growable arrays, pointers to structs, and function values with typed captures. repeated references and cycles preserve identity within a copied graph. integer payloads that happen to equal heap addresses remain integers. changes to a received graph do not modify the sender's graph. ordinary language rules for aggregate parameters still apply.

`await()` requires a registered receiver when messages are pending. `close()` cancels remaining work, closes the channel and joins the worker; repeated closes succeed. later sends and receives return `-1`. an actor struct that declares no `drop` of its own gets one: when its owner's block ends, or it is freed or collected, it waits for the replies a registered receiver is still owed (as `await()` does), then closes. so an actor owned by a block needs no explicit `close()`; one moved out of the block lives on with its new owner. a struct that declares its own `drop` should close the actor there. the worker's snapshot of the struct never closes anything. sends may wait for channel space under backpressure, and polling a large result can wait for its remaining bytes.

## current limits

- custom generic actor declarations are rejected. use `actor.Actor<I,O>` with a typed handler instead.
- javascript, wasm, bare-metal and windows hosts do not provide the required context primitives.
- compiler-free emitted images cannot import this source parser: a syntax handler must already reside in the compiling host. the actor library reports this limitation through the generic syntax-registration interface.
- statement hooks run outside included library code and `o3` regions. automatic callbacks therefore require the caller to return to an ordinary statement; explicit `poll` and `await` remain available.
- channels stay within the spawning vm process family. function messages require code and type descriptors already present when the worker was spawned; code compiled dynamically afterward is not transferred.
- raw pointers lack bounds. a pointer to a non-heap object copies its declared pointee; it does not infer the extent of an arbitrary interior pointer or external native allocation.

## checks

`python3 tests/drivers/actor_test.py build/bin/zy` and `python3 tests/drivers/actor_test.py build/bin/zym` exercise library-only syntax installation, declared actors, independent captures, two-instance parallelism, callback registration before send, statement delivery, fifo ordering, typed graph copies, closure messages, lifecycle behavior and rejection fixtures. the parallel fixture measures worker time inside the vm: two 300 ms tasks must complete in less than 580 ms.