236 lines
4.4 KiB
Markdown
236 lines
4.4 KiB
Markdown
---
|
|
title: "Actors and Modules"
|
|
description: "The ƿit execution model"
|
|
weight: 20
|
|
type: "docs"
|
|
---
|
|
|
|
ƿit organizes code into two types of scripts: **modules** (`.cm`) and **actors** (`.ce`).
|
|
|
|
## The Actor Model
|
|
|
|
ƿit is built on the actor model of computation. Each actor:
|
|
|
|
- Has its own **isolated memory** — actors never share state
|
|
- Runs to completion each **turn** — no preemption
|
|
- Performs its own **garbage collection**
|
|
- Communicates only through **message passing**
|
|
|
|
This isolation makes concurrent programming safer and more predictable.
|
|
|
|
## Modules (.cm)
|
|
|
|
A module is a script that **returns a value**. The returned value is cached and frozen (made stone).
|
|
|
|
```javascript
|
|
// math_utils.cm
|
|
var math = use('math/radians')
|
|
|
|
function distance(x1, y1, x2, y2) {
|
|
var dx = x2 - x1
|
|
var dy = y2 - y1
|
|
return math.sqrt(dx * dx + dy * dy)
|
|
}
|
|
|
|
function midpoint(x1, y1, x2, y2) {
|
|
return {
|
|
x: (x1 + x2) / 2,
|
|
y: (y1 + y2) / 2
|
|
}
|
|
}
|
|
|
|
return {
|
|
distance: distance,
|
|
midpoint: midpoint
|
|
}
|
|
```
|
|
|
|
**Key properties:**
|
|
|
|
- **Must return a value** — it's an error not to
|
|
- **Executed once per actor** — subsequent `use()` calls return the cached value
|
|
- **Return value is stone** — immutable, safe to share
|
|
- Modules can import other modules with `use()`
|
|
|
|
### Using Modules
|
|
|
|
```javascript
|
|
var utils = use('math_utils')
|
|
var d = utils.distance(0, 0, 3, 4) // 5
|
|
```
|
|
|
|
## Actors (.ce)
|
|
|
|
An actor is a script that **does not return a value**. It runs as an independent unit of execution.
|
|
|
|
```javascript
|
|
// worker.ce
|
|
log.console("Worker started")
|
|
|
|
$receiver(function(msg, reply) {
|
|
log.console("Received:", msg)
|
|
// Process message...
|
|
})
|
|
```
|
|
|
|
**Key properties:**
|
|
|
|
- **Must not return a value** — it's an error to return
|
|
- Has access to **actor intrinsics** (functions starting with `$`)
|
|
- Runs until explicitly stopped or crashes
|
|
|
|
## Actor Intrinsics
|
|
|
|
Actors have access to special functions prefixed with `$`:
|
|
|
|
### $me
|
|
|
|
Reference to the current actor.
|
|
|
|
```javascript
|
|
log.console($me) // actor reference
|
|
```
|
|
|
|
### $stop()
|
|
|
|
Stop the current actor.
|
|
|
|
```javascript
|
|
$stop()
|
|
```
|
|
|
|
### $send(actor, message, callback)
|
|
|
|
Send a message to another actor.
|
|
|
|
```javascript
|
|
$send(other_actor, {type: "ping", data: 42}, function(reply) {
|
|
log.console("Got reply:", reply)
|
|
})
|
|
```
|
|
|
|
Messages are automatically **splatted** — flattened to plain data without prototypes.
|
|
|
|
### $start(callback, program)
|
|
|
|
Start a new actor from a script.
|
|
|
|
```javascript
|
|
$start(function(new_actor) {
|
|
log.console("Started:", new_actor)
|
|
}, "worker")
|
|
```
|
|
|
|
### $delay(callback, seconds)
|
|
|
|
Schedule a callback after a delay.
|
|
|
|
```javascript
|
|
$delay(function() {
|
|
log.console("5 seconds later")
|
|
}, 5)
|
|
```
|
|
|
|
### $clock(callback)
|
|
|
|
Get called every frame/tick.
|
|
|
|
```javascript
|
|
$clock(function(dt) {
|
|
// Called each tick with delta time
|
|
})
|
|
```
|
|
|
|
### $receiver(callback)
|
|
|
|
Set up a message receiver.
|
|
|
|
```javascript
|
|
$receiver(function(message, reply) {
|
|
// Handle incoming message
|
|
reply({status: "ok"})
|
|
})
|
|
```
|
|
|
|
### $portal(callback, port)
|
|
|
|
Open a network port.
|
|
|
|
```javascript
|
|
$portal(function(connection) {
|
|
// Handle new connection
|
|
}, 8080)
|
|
```
|
|
|
|
### $contact(callback, record)
|
|
|
|
Connect to a remote address.
|
|
|
|
```javascript
|
|
$contact(function(connection) {
|
|
// Connected
|
|
}, {host: "example.com", port: 80})
|
|
```
|
|
|
|
### $time_limit(requestor, seconds)
|
|
|
|
Wrap a requestor with a timeout.
|
|
|
|
```javascript
|
|
$time_limit(my_requestor, 10) // 10 second timeout
|
|
```
|
|
|
|
## Module Resolution
|
|
|
|
When you call `use('name')`, ƿit searches:
|
|
|
|
1. **Current package** — files relative to package root
|
|
2. **Dependencies** — packages declared in `pit.toml`
|
|
3. **Core** — built-in ƿit modules
|
|
|
|
```javascript
|
|
// From within package 'myapp':
|
|
use('utils') // myapp/utils.cm
|
|
use('helper/math') // myapp/helper/math.cm
|
|
use('json') // core json module
|
|
use('otherlib/foo') // dependency 'otherlib', file foo.cm
|
|
```
|
|
|
|
Files starting with underscore (`_helper.cm`) are private to the package.
|
|
|
|
## Example: Simple Actor System
|
|
|
|
```javascript
|
|
// main.ce - Entry point
|
|
var config = use('config')
|
|
|
|
log.console("Starting application...")
|
|
|
|
$start(function(worker) {
|
|
$send(worker, {task: "process", data: [1, 2, 3]})
|
|
}, "worker")
|
|
|
|
$delay(function() {
|
|
log.console("Shutting down")
|
|
$stop()
|
|
}, 10)
|
|
```
|
|
|
|
```javascript
|
|
// worker.ce - Worker actor
|
|
$receiver(function(msg, reply) {
|
|
if (msg.task == "process") {
|
|
var result = array(msg.data, x => x * 2)
|
|
reply({result: result})
|
|
}
|
|
})
|
|
```
|
|
|
|
```javascript
|
|
// config.cm - Shared configuration
|
|
return {
|
|
debug: true,
|
|
timeout: 30
|
|
}
|
|
```
|