The Actor Model

in reviewThis lesson is complete and being validated before release - details may still change.

The actor model

Loading interactive demo…

The chart is the conversation: one lifeline per actor, the program's own thread first, and one row per message in the order it was sent, hollow while it waits in the receiver's mailbox. The strips show every actor's state and how much mail each has waiting. Tap a message to read what it carries and what became of it.Take the tour, or press and explore. Legend:

The panel beside the stage is the real ActorSystem class from the published library executing in your browser, with the current line highlighted.

The message this step concerns, and the actor handling it.
A message that has been handled.
A message dropped because its receiver has no rule for it.
A message still waiting in a mailbox.

sent and delivered count the messages, in flight is their difference, the messages sitting in mailboxes, and dropped counts those no rule matched.

The code panel shows bare executable code by default. The bar above it names the file (hover the name for the full published path); options holds the toggles: comments, the tracer instrumentation that produces this visualization, and verbose names for the terse identifiers (display only: the default is the byte-exact published file). The view switch adds plain-English narration: both interleaves it with the code, pseudo shows only the pseudocode. hide code collapses the panel; the rail it leaves behind brings it back.

Keys: Space play/pause · ←/→ step · Home/End jump · R reset · F fullscreen · G guided tour

Share nothing. The race lesson's threads shared a counter and lost updates; the lock lesson protected it and deadlocked; the event loop gave up parallelism to avoid both. The actor model keeps the parallelism and removes the sharing. An actor has state that only it can read or write, a mailbox, and rules for the messages it receives. To change an actor's state you send it a message and it changes its own state when it gets to the message. There is no variable two actors can both touch, so there is nothing to race on and nothing to lock.

One message at a time. An actor takes the oldest message from its mailbox and handles it to the end before taking the next, like a task on the event loop. Inside one actor there is never any interleaving. Across actors there is as much parallelism as there are actors with mail, because they share nothing and can run on different cores or different machines without changing a line.

The counter again. Two workers each send three increments to a counter actor. The messages queue in the counter's mailbox in whatever order the delivery happens to put them, and the counter handles them one by one: $0, 1, 2, \dots, 6$ . Set the delivery to random and change the seed; the chart fills in a different order and the count is still six, in every order, because a single actor is the only thing that ever adds to it. The race is not fixed; it cannot be expressed.

A send does not wait. The sender puts the message in the mailbox and goes on. That is asynchronous messaging, and it is what makes the model scale: no thread sits blocked holding a stack while another works. It also means a reply is a message back, not a return value, so a conversation that would be one function call becomes a protocol of sends and rules, as the teller's transfer shows.

What it costs. Look at the transfer between the withdrawal and the deposit: account A has given up 50 and account B has not yet received it, and the two balances sum to less than 100. No actor is wrong, but there is no moment at which anyone can see both balances and find them consistent. Shared memory gave a global state and made it dangerous; actors give safety and take the global state away. Systems built on them talk of eventual consistency, which is the in-flight metric on this stage reaching zero.

Messages can be lost or ignored. The teller's report to main is dropped because main has no rule for it, which is the honest model: a message to an actor that does not understand it, or to one that has crashed, goes nowhere, and the sender finds out only if it asked for a reply and none came. Erlang's supervisors and timeouts are the discipline that grew around that fact.

Choices worth reading closely in the implementation (the code panel's comments and tracer checkboxes reveal the full published file):

states and mailboxes are maps the system owns, and only deliver writes a state, for the actor whose message it is handling. The rule that only the owner changes a state is a property of the code's shape, not a convention.
send is the one place a message is made, so every message has an id in send order and the chart's rows are that order.
A rule is data: a message type, an effect on the state, and the messages to send, so the stage's three conversations are three tables, and a real actor's behaviour would be code in the same slot.
A bounce is a reply instead of an effect, so an account that cannot cover a withdrawal says so to whoever asked, and the teller has a rule for that reply too. The transfer is a protocol, not a transaction.
run ends when every mailbox is empty, which is the system quiescing; a real system never ends, and the cap on messages is what stops a conversation that keeps itself going.
The delivery policy is the scheduler's, not the actors', and the seeded coin exists to show that the result does not depend on it.

Carl Hewitt, Peter Bishop, and Richard Steiger proposed actors in 1973 as a model of computation for artificial intelligence: all an actor can do is send messages to other actors, make new actors, and decide how to handle its next message. Gul Agha gave the model its theory in 1986, the year a team at Ericsson began Erlang, whose processes are actors and whose telephone switches run for years. The model reached mainstream services through Erlang's open sourcing in 1998, Akka on the JVM in 2009, and Microsoft's Orleans, and sits under chat systems that hold millions of connections.

1973Carl Hewitt, Peter Bishop, and Richard Steiger - A Universal Modular ACTOR Formalism for Artificial Intelligence introduces actors that communicate only by message, inspired by Smalltalk's message sends and physics.source
1986Gul Agha - Actors: A Model of Concurrent Computation in Distributed Systems gives the model its semantics and the name of the field's standard reference.source
1986Joe Armstrong, Robert Virding, and Mike Williams - Erlang begins at Ericsson: lightweight processes with mailboxes, no shared memory, and supervisors that restart what crashes, for switches that must not stop.source
2009Jonas Boner - Akka brings Erlang-style actors to the Java virtual machine, and becomes the model's main form on servers written in Scala and Java.source
2014Microsoft Research - Orleans adds virtual actors that exist whenever addressed and are placed and recovered by the runtime, the design behind the Halo game services.source

Used today

Messaging and chat - A connection, a conversation, or a user session is an actor with a mailbox; WhatsApp's servers ran on Erlang for this reason.
Telephone switches - Erlang's first job was Ericsson's AXD301 switch, where processes isolate faults and a crash restarts one actor, not the system.
Game and cloud services - A player, a match, or a shopping cart as an actor lets a service scale by adding machines and lets a failure take one actor down.

conversation

delivery

seed1

sent: 8
delivered: 8
in flight: 0
dropped: 0

actor-system.ts

import { Mulberry32 } from "../random";import type { Tracer } from "../trace";/** A message an actor sends when a rule fires. */export interface Outgoing {  /** An actor's name, or "sender" for whoever sent the message being handled. */  to: string;  type: string;  /** The handled message's value, the actor's own state after the update, or a constant. */  value: "value" | "state" | number;  /** Send it this many times (default once). */  count?: number;  /** Send only while the state is below this. */  onlyIfStateBelow?: number;}/** What an actor does with one kind of message: change its state, then send. */export interface ActorRule {  on: string;  effect: "add" | "subtract" | "none";  /** For a subtract that would go below zero: reply with this type instead of applying it. */  bounce?: string;  send?: readonly Outgoing[];}export interface ActorSpec {  name: string;  state: number;  rules: readonly ActorRule[];}export interface ActorMessage {  id: number;  from: string;  to: string;  type: string;  value: number;}export const DELIVERY_POLICIES = ["round-robin", "random"] as const;export type DeliveryPolicy = (typeof DELIVERY_POLICIES)[number];export const MAX_ACTORS = 4;export const MAX_MESSAGES = 48;export interface ActorReport {  sent: number;  delivered: number;  dropped: number;  bounced: number;  states: Record<string, number>;}/** * An actor owns its state and nobody else can touch it. The only way * to affect an actor is to send it a message, which waits in its * mailbox until the actor takes it, one at a time, and reacts by * changing its own state and sending messages of its own. Two workers * incrementing a counter cannot race, because the counter is the only * thing that ever changes the count, and it handles one increment * before the next. There are no locks because there is nothing shared * to lock. What the model gives up is a global moment: while a message * is in flight, money withdrawn from one account has not yet arrived at * the other, and no one can see both at once. * * Time: O(messages). Space: O(actors + messages in flight). */export class ActorSystem {  private readonly actors: Map<string, ActorSpec>;  private readonly states = new Map<string, number>();  private readonly mailboxes = new Map<string, ActorMessage[]>();  private readonly random: Mulberry32;  private readonly names: string[];  private last = -1;  private nextId = 0;  private delivered = 0;  private dropped = 0;  private bounced = 0;  constructor(    actors: readonly ActorSpec[],    private readonly policy: DeliveryPolicy,    seed = 1,    private readonly tracer?: Tracer,  ) {    if (actors.length < 1 || actors.length > MAX_ACTORS) throw new RangeError(`actors must be in [1, ${MAX_ACTORS}]`);    if (!DELIVERY_POLICIES.includes(policy)) throw new RangeError(`unknown policy ${String(policy)}`);    this.actors = new Map(actors.map((actor) => [actor.name, actor]));    if (this.actors.size !== actors.length) throw new RangeError("actor names must be unique");    this.names = actors.map((actor) => actor.name);    for (const actor of actors) {      this.states.set(actor.name, actor.state);      this.mailboxes.set(actor.name, []);      for (const rule of actor.rules) for (const out of rule.send ?? []) if (out.to !== "sender" && !this.actors.has(out.to)) throw new RangeError(`${actor.name} sends to unknown ${out.to}`);      for (const matchingRule of actor.rules) for (const outgoingMessage of matchingRule.send ?? []) if (outgoingMessage.to !== "sender" && !this.actors.has(outgoingMessage.to)) throw new RangeError(`${actor.name} sends to unknown ${out.to}`);    }    this.random = new Mulberry32(seed);  }  /** Every actor's state as it stands. */  snapshot(): Record<string, number> {    return Object.fromEntries(this.states);  }  /** The messages waiting for an actor, oldest first. */  mailbox(name: string): readonly ActorMessage[] {    return [...(this.mailboxes.get(name) ?? [])];  }  /** Puts a message in the receiver's mailbox; the one place a message is made. */  send(from: string, to: string, type: string, value: number): ActorMessage {    const mailbox = this.mailboxes.get(to);    if (!mailbox) throw new RangeError(`no actor named ${to}`);    if (this.nextId >= MAX_MESSAGES) throw new RangeError(`more than ${MAX_MESSAGES} messages; the actors are not settling`);    const message: ActorMessage = { id: this.nextId++, from, to, type, value };    mailbox.push(message);    // ▸ a message goes into the receiver's mailbox; the sender does not wait    this.tracer?.emit("send", { id: message.id, from, to, type, value, queued: mailbox.length, inFlight: this.inFlight() });    return message;  }  /** Delivers the opening messages, then one message at a time until every mailbox is empty. */  run(initial: readonly { from: string; to: string; type: string; value: number }[]): ActorReport {    for (const message of initial) this.send(message.from, message.to, message.type, message.value);    while (this.busy().length > 0) this.deliver(this.pick());    return { sent: this.nextId, delivered: this.delivered, dropped: this.dropped, bounced: this.bounced, states: this.snapshot() };  }  /** Takes the oldest message from an actor's mailbox and lets its rule react. */  deliver(name: string): void {    const actor = this.actors.get(name);    const message = this.mailboxes.get(name)?.shift();    if (!actor || !message) throw new RangeError(`${name} has no message to handle`);    this.delivered++;    const state = this.states.get(name)!;    // ▸ an actor takes the oldest message from its mailbox and handles it alone    this.tracer?.emit("receive", { id: message.id, actor: name, from: message.from, type: message.type, value: message.value, state, left: this.mailboxes.get(name)!.length, delivered: this.delivered });    const rule = actor.rules.find((candidate) => candidate.on === message.type);    const matchingRule = actor.rules.find((candidate) => candidate.on === message.type);    if (!rule) {    if (!matchingRule) {      this.dropped++;      // ▸ no rule matches the message, so the actor ignores it      this.tracer?.emit("drop", { id: message.id, actor: name, type: message.type, from: message.from, dropped: this.dropped });      return;    }    if (rule.effect === "subtract" && rule.bounce !== undefined && state < message.value) {    if (matchingRule.effect === "subtract" && matchingRule.bounce !== undefined && state < message.value) {      this.bounced++;      this.send(name, message.from, rule.bounce, message.value);      this.send(name, message.from, matchingRule.bounce, message.value);      return;    }    if (rule.effect !== "none") {    if (matchingRule.effect !== "none") {      const after = rule.effect === "add" ? state + message.value : state - message.value;      const after = matchingRule.effect === "add" ? state + message.value : state - message.value;      this.states.set(name, after);      // ▸ the actor changes its own state; nobody else ever touches it      this.tracer?.emit("update", { actor: name, type: message.type, before: state, after, effect: rule.effect });      this.tracer?.emit("update", { actor: name, type: message.type, before: state, after, effect: matchingRule.effect });    }    for (const out of rule.send ?? []) {    for (const outgoingMessage of matchingRule.send ?? []) {      const current = this.states.get(name)!;      if (out.onlyIfStateBelow !== undefined && current >= out.onlyIfStateBelow) continue;      if (outgoingMessage.onlyIfStateBelow !== undefined && current >= outgoingMessage.onlyIfStateBelow) continue;      const value = out.value === "value" ? message.value : out.value === "state" ? current : out.value;      const value = outgoingMessage.value === "value" ? message.value : outgoingMessage.value === "state" ? current : outgoingMessage.value;      for (let i = 0; i < (out.count ?? 1); i++) this.send(name, out.to === "sender" ? message.from : out.to, out.type, value);      for (let i = 0; i < (outgoingMessage.count ?? 1); i++) this.send(name, outgoingMessage.to === "sender" ? message.from : outgoingMessage.to, outgoingMessage.type, value);    }  }  /** Messages sent and not yet handled. */  private inFlight(): number {    return [...this.mailboxes.values()].reduce((sum, mailbox) => sum + mailbox.length, 0);  }  private busy(): number[] {    return this.names.flatMap((name, i) => ((this.mailboxes.get(name)?.length ?? 0) > 0 ? [i] : []));  }  /** The next actor with mail, by turns or by the seeded coin. */  private pick(): string {    const candidates = this.busy();    const chosen = this.policy === "round-robin" ? (candidates.find((i) => i > this.last) ?? candidates[0]!) : candidates[this.random.index(candidates.length)]!;    this.last = chosen;    return this.names[chosen]!;  }}

sent =: 8
delivered =: 8

Every mailbox is empty: 8 messages sent and 8 handled, 0 dropped. The states settle at main 0, w1 0, w2 0, counter 6.

import { Mulberry32 } from "../random";import type { Tracer } from "../trace";/** A message an actor sends when a rule fires. */export interface Outgoing { /** An actor's name, or "sender" for whoever sent the message being handled. */ to: string; type: string; /** The handled message's value, the actor's own state after the update, or a constant. */ value: "value" | "state" | number; /** Send it this many times (default once). */ count?: number; /** Send only while the state is below this. */ onlyIfStateBelow?: number;}/** What an actor does with one kind of message: change its state, then send. */export interface ActorRule { on: string; effect: "add" | "subtract" | "none"; /** For a subtract that would go below zero: reply with this type instead of applying it. */ bounce?: string; send?: readonly Outgoing[];}export interface ActorSpec { name: string; state: number; rules: readonly ActorRule[];}export interface ActorMessage { id: number; from: string; to: string; type: string; value: number;}export const DELIVERY_POLICIES = ["round-robin", "random"] as const;export type DeliveryPolicy = (typeof DELIVERY_POLICIES)[number];export const MAX_ACTORS = 4;export const MAX_MESSAGES = 48;export interface ActorReport { sent: number; delivered: number; dropped: number; bounced: number; states: Record<string, number>;}/** * An actor owns its state and nobody else can touch it. The only way * to affect an actor is to send it a message, which waits in its * mailbox until the actor takes it, one at a time, and reacts by * changing its own state and sending messages of its own. Two workers * incrementing a counter cannot race, because the counter is the only * thing that ever changes the count, and it handles one increment * before the next. There are no locks because there is nothing shared * to lock. What the model gives up is a global moment: while a message * is in flight, money withdrawn from one account has not yet arrived at * the other, and no one can see both at once. * * Time: O(messages). Space: O(actors + messages in flight). */export class ActorSystem { private readonly actors: Map<string, ActorSpec>; private readonly states = new Map<string, number>(); private readonly mailboxes = new Map<string, ActorMessage[]>(); private readonly random: Mulberry32; private readonly names: string[]; private last = -1; private nextId = 0; private delivered = 0; private dropped = 0; private bounced = 0; constructor( actors: readonly ActorSpec[], private readonly policy: DeliveryPolicy, seed = 1, private readonly tracer?: Tracer, ) { if (actors.length < 1 || actors.length > MAX_ACTORS) throw new RangeError(`actors must be in [1, ${MAX_ACTORS}]`); if (!DELIVERY_POLICIES.includes(policy)) throw new RangeError(`unknown policy ${String(policy)}`); this.actors = new Map(actors.map((actor) => [actor.name, actor])); if (this.actors.size !== actors.length) throw new RangeError("actor names must be unique"); this.names = actors.map((actor) => actor.name); for (const actor of actors) { this.states.set(actor.name, actor.state); this.mailboxes.set(actor.name, []); for (const rule of actor.rules) for (const out of rule.send ?? []) if (out.to !== "sender" && !this.actors.has(out.to)) throw new RangeError(`${actor.name} sends to unknown ${out.to}`); for (const matchingRule of actor.rules) for (const outgoingMessage of matchingRule.send ?? []) if (outgoingMessage.to !== "sender" && !this.actors.has(outgoingMessage.to)) throw new RangeError(`${actor.name} sends to unknown ${out.to}`); } this.random = new Mulberry32(seed); } /** Every actor's state as it stands. */ snapshot(): Record<string, number> { return Object.fromEntries(this.states); } /** The messages waiting for an actor, oldest first. */ mailbox(name: string): readonly ActorMessage[] { return [...(this.mailboxes.get(name) ?? [])]; } /** Puts a message in the receiver's mailbox; the one place a message is made. */ send(from: string, to: string, type: string, value: number): ActorMessage { const mailbox = this.mailboxes.get(to); if (!mailbox) throw new RangeError(`no actor named ${to}`); if (this.nextId >= MAX_MESSAGES) throw new RangeError(`more than ${MAX_MESSAGES} messages; the actors are not settling`); const message: ActorMessage = { id: this.nextId++, from, to, type, value }; mailbox.push(message); // ▸ a message goes into the receiver's mailbox; the sender does not wait this.tracer?.emit("send", { id: message.id, from, to, type, value, queued: mailbox.length, inFlight: this.inFlight() }); return message; } /** Delivers the opening messages, then one message at a time until every mailbox is empty. */ run(initial: readonly { from: string; to: string; type: string; value: number }[]): ActorReport { for (const message of initial) this.send(message.from, message.to, message.type, message.value); while (this.busy().length > 0) this.deliver(this.pick()); return { sent: this.nextId, delivered: this.delivered, dropped: this.dropped, bounced: this.bounced, states: this.snapshot() }; } /** Takes the oldest message from an actor's mailbox and lets its rule react. */ deliver(name: string): void { const actor = this.actors.get(name); const message = this.mailboxes.get(name)?.shift(); if (!actor || !message) throw new RangeError(`${name} has no message to handle`); this.delivered++; const state = this.states.get(name)!; // ▸ an actor takes the oldest message from its mailbox and handles it alone this.tracer?.emit("receive", { id: message.id, actor: name, from: message.from, type: message.type, value: message.value, state, left: this.mailboxes.get(name)!.length, delivered: this.delivered }); const rule = actor.rules.find((candidate) => candidate.on === message.type); const matchingRule = actor.rules.find((candidate) => candidate.on === message.type); if (!rule) { if (!matchingRule) { this.dropped++; // ▸ no rule matches the message, so the actor ignores it this.tracer?.emit("drop", { id: message.id, actor: name, type: message.type, from: message.from, dropped: this.dropped }); return; } if (rule.effect === "subtract" && rule.bounce !== undefined && state < message.value) { if (matchingRule.effect === "subtract" && matchingRule.bounce !== undefined && state < message.value) { this.bounced++; this.send(name, message.from, rule.bounce, message.value); this.send(name, message.from, matchingRule.bounce, message.value); return; } if (rule.effect !== "none") { if (matchingRule.effect !== "none") { const after = rule.effect === "add" ? state + message.value : state - message.value; const after = matchingRule.effect === "add" ? state + message.value : state - message.value; this.states.set(name, after); // ▸ the actor changes its own state; nobody else ever touches it this.tracer?.emit("update", { actor: name, type: message.type, before: state, after, effect: rule.effect }); this.tracer?.emit("update", { actor: name, type: message.type, before: state, after, effect: matchingRule.effect }); } for (const out of rule.send ?? []) { for (const outgoingMessage of matchingRule.send ?? []) { const current = this.states.get(name)!; if (out.onlyIfStateBelow !== undefined && current >= out.onlyIfStateBelow) continue; if (outgoingMessage.onlyIfStateBelow !== undefined && current >= outgoingMessage.onlyIfStateBelow) continue; const value = out.value === "value" ? message.value : out.value === "state" ? current : out.value; const value = outgoingMessage.value === "value" ? message.value : outgoingMessage.value === "state" ? current : outgoingMessage.value; for (let i = 0; i < (out.count ?? 1); i++) this.send(name, out.to === "sender" ? message.from : out.to, out.type, value); for (let i = 0; i < (outgoingMessage.count ?? 1); i++) this.send(name, outgoingMessage.to === "sender" ? message.from : outgoingMessage.to, outgoingMessage.type, value); } } /** Messages sent and not yet handled. */ private inFlight(): number { return [...this.mailboxes.values()].reduce((sum, mailbox) => sum + mailbox.length, 0); } private busy(): number[] { return this.names.flatMap((name, i) => ((this.mailboxes.get(name)?.length ?? 0) > 0 ? [i] : [])); } /** The next actor with mail, by turns or by the seeded coin. */ private pick(): string { const candidates = this.busy(); const chosen = this.policy === "round-robin" ? (candidates.find((i) => i > this.last) ?? candidates[0]!) : candidates[this.random.index(candidates.length)]!; this.last = chosen; return this.names[chosen]!; }}