# "Process Model"
_Path: en/concepts/process-model_
> "How Wippy processes execute, communicate, isolate capabilities, and recover through supervision."
## Table of Contents
- Process Model
## Content
# Process Model
Wippy executes code in isolated processes: lightweight state machines that communicate through messages rather than shared memory. This actor model gives each process its own state and lifecycle.
This page explains the lifecycle and isolation model. Use the [Process Management reference](../lua/core/process.md) for spawn, messaging, monitoring, registry, and upgrade APIs. See [Process Host and Services](../system/process-host.md) for runtime-managed service fields.
## State Machine Execution
Each process initializes, advances through execution, yields on blocking operations, and closes when complete. The scheduler multiplexes processes across a worker pool and runs other work while a process waits for I/O.
Processes support multiple concurrent yields, allowing code to start several asynchronous operations and wait for any or all of them without spawning additional processes.
```mermaid
flowchart LR
Ready --> Running
Running --> Blocked
Running --> Idle
Blocked --> Running
Idle --> Running
Running --> Complete
```
Processes are not limited to Lua. The runtime also supports WebAssembly modules through the `process.wasm` kind, and its process architecture can support other state-machine implementations.
Processes are lightweight but not free. Each process carries a small baseline cost for its state, inbox, and scheduler bookkeeping, and dynamic allocations grow that footprint during execution.
## Process Hosts
Wippy can run multiple process hosts within one runtime, each with its own capabilities and security boundaries. Privileged system processes can run in a host separate from hosts that execute user sessions.
Some hosts are specialized. The Terminal host, for example, uses one scheduler
worker and supplies terminal I/O context to accepted processes; it does not
enforce a one-process lifetime limit. Separate hosts allow one deployment to
run processes with different trust levels.
## Security Model
Each process executes under an actor identity and security policy. This is typically the user who initiated the call, while system processes use a system actor with different privileges.
Access control applies at multiple levels. Security policy can restrict individual process operations and message delivery between hosts. The policy attached to the current actor determines which operations are permitted.
For the security implications of process isolation, see the [Security Model](concepts/security-model.md).
## Spawning Processes
Create background processes with `process.spawn()`:
```lua
local pid, err = process.spawn("app.workers:handler", "app:processes", arg1, arg2)
if err then return nil, err end
return pid
```
The first argument is the registry entry, the second is the process host, and remaining arguments pass to the process.
Spawn variants control lifecycle relationships:
| Function | Behavior |
|----------|----------|
| `spawn` | Start an independent process |
| `spawn_monitored` | Receive EXIT events when child exits |
| `spawn_linked` | Abnormal exit propagates in either direction; with `trap_links: true`, the peer receives `LINK_DOWN` instead of failing |
## Message Passing
Processes communicate through messages rather than shared memory:
```lua
local ok, err = process.send(target_pid, "topic", payload)
if err then return nil, err end
return ok
```
Messages from the same sender arrive in order. Messages from different senders may interleave. Delivery is fire-and-forget—use request-response patterns when you need confirmation.
Processes can register in a local name registry and be addressed by name instead of PID (e.g., `session_manager`). Names can also be registered cluster-wide for cross-node addressing via `process.registry` using EVENTUAL (gossip-based), CONSISTENT, or STRONG (both Raft-backed) scopes.
## Supervision
Any process can supervise other processes by monitoring them. A supervisor starts monitored children, watches for EXIT events, and decides whether to restart them after failure.
```lua
local worker, spawn_err = process.spawn_monitored("app.workers:handler", "app:processes")
if spawn_err then return nil, spawn_err end
local event, open = process.events():receive()
if not open then return nil, errors.new("process event channel closed") end
if event.kind == process.event.EXIT and event.result.error then
local replacement, restart_err = process.spawn_monitored("app.workers:handler", "app:processes")
if restart_err then return nil, restart_err end
worker = replacement
end
```
At the runtime level, services can start and supervise long-running processes. Define a `process.service` entry to have the runtime manage a process:
```yaml
- name: worker.service
kind: process.service
process: app.workers:handler
host: app:processes
lifecycle:
auto_start: true
restart:
max_attempts: 5
initial_delay: 1s
```
The service starts automatically and integrates with the runtime's lifecycle management. At the pinned runtime, the initial failed start counts toward `max_attempts`, so `5` permits at most four follow-up starts. Each retry waits for `initial_delay` with jitter; the delay does not increase between attempts.
## Process Upgrading
Running processes can upgrade their code without losing identity. Call `process.upgrade()` to swap to a new definition while preserving PID, mailbox, and supervision relationships:
```lua
process.upgrade("app.workers:v2", current_state)
```
The first argument is the new registry entry (or nil to reload the current definition). Additional arguments pass to the new version, letting you carry state across the upgrade. The process resumes execution with the new code immediately.
Unread inbox and listener messages, unread lifecycle events, and process-owned context values survive the handoff. The new execution recreates listeners, timers, sockets, and application channels; consumed messages and old coroutine state are not replayed.
The runtime caches compiled prototypes to avoid repeated compilation. If an upgrade fails, the process crashes and normal supervision behavior applies; a monitoring parent can restart it or escalate the failure.
## Scheduling
The actor scheduler uses work-stealing across CPU cores. Each worker has a local queue for cache locality, plus a global queue for distributing work. Processes yield on blocking operations so other processes can run on the worker pool.
## Navigation
Previous: Security Model - Process Isolation, Capability Control, and Data Boundaries (concepts/security-model)
Next: "Cluster" (concepts/cluster)