dactor 2.0.0
dactor: ^2.0.0 copied to clipboard
An actor system for Dart
2.0.0 #
Dactor 2.0 brings the actor model closer to Erlang/OTP: a zone per actor,
links and exit reasons, OTP-style supervisors, typed GenServer and
GenStatem behaviours, applications, selective receive and sys. It adds a
deterministic simulator for testing, and actors that run in an isolate of
their own. The README's "Coming from Erlang/OTP" section maps OTP onto
Dactor and lists where the two differ.
Distribution lives in two companion packages in this repository,
dactor_remote and dactor_libp2p. They are experimental and not yet
published; this release carries the hooks they need in core.
Upgrading from 1.x #
Messages and senders. Actors receive exactly what was told, and the runtime records the sender.
| 1.x | 2.0 |
|---|---|
ref.tell(LocalMessage(payload: m)) |
ref.tell(m) |
ref.tell(m, sender: context.self) inside an actor |
ref.tell(m) |
worker.tell(m, sender: context.sender) |
context.forward(worker, m) |
ref.tell(m, sender: probe.ref) in a test |
sendAs(probe.ref, () => ref.tell(m)), from package:dactor/spi.dart |
class M implements Message |
class M |
class R extends AskableResponse |
any class |
an ActorRef implementation: tell(Message, {sender}) |
tell(Object?), reading currentSender if it needs the sender |
watcher.tell(Terminated(...)) from a transport |
tellSystem(watcher, Terminated(...)) |
DeadLetter.sender is an ActorRef |
ActorRef?, null outside any actor |
Terminated.correlationId, timestamp, metadata |
removed |
Behaviour that changed without a compile error. Check code that relies on any of these:
- Each actor runs in its own zone. An error nothing catches (an unawaited future, a timer callback) now fails the actor, and goes to its supervisor.
- Stopping or restarting an actor drops what it left pending: its
timers, and code waiting on an
await.finallyblocks around such anawaitdo not run, so release resources inpostStop. Code afterawait context.system.stop(context.self)does not run. - Restarting an actor stops its children. A supervisor that wants them
back creates them in
preStart. Stopping an actor stops its children first. - Children started with
supervise(id, factory)are permanent: asystem.stop(child)brings one back as a new actor. UseterminateChild, or start the child astransientortemporary. - A restart budget belongs to the supervisor, 10 restarts in 5 seconds
across all its children by default. A supervisor that exceeds it fails
with
RestartLimitExceededand its own supervisor decides. In 1.x each child had a lifetime count and was quietly stopped when it ran out.maxRetriesandwithinare deprecated in favour ofmaxRestartsandperiod. SupervisionDecision.escalateescalates (it used to resume), andspawn(supervision:)is honoured for top-level actors (it used to be ignored).onChildFailureis no longer called while the supervisor'sonMessageis running: decisions go through the supervisor's mailbox.
Code that breaks at compile time, beyond the table above:
- A custom supervision strategy extends
SupervisionStrategyrather than implementing it. - A class that implements
ActorContextorActorRefneeds the new members (receive,forward,link,unlink,unwatch,trapExits;ActorRef.unwatch). MailboxandMessageare no longer exported.- An exhaustive
switchoverExitReason(new in 2.0) needs every case. dactor_test1.0.0 requires dactor 1.x. Usedactor_test2.0.0, released with this version.
Dispatch, escalation and start-up #
Actor.contextis no longer marked@internal. The annotation made the analyzer warn on every use ofcontextin an actor written outside this package, which is every actor a user writes.- The message pump yields to the event loop. Dispatch used to run
entirely in microtasks, so a mailbox backlog kept timers, I/O and
asktimeouts waiting until it drained (a 1 ms timer measured at 1.4 s). The pump now stops after 128 messages or 4 ms in one event-loop turn and resumes on the next. Both limits are configurable throughActorSystemConfig.maxMessagesPerTurnandmaxTurnDuration. Throughput is unchanged. - New metric
actors.blocking_handler, tagged with the actor id, counts handlers that run for longer thanActorSystemConfig.blockingHandlerThreshold(10 ms by default) before their firstawait. SupervisionDecision.escalateworks. The supervisor that escalates is treated as having failed with the same error, and its own parent decides. Escalating past a top-level actor stops it. Previously escalate behaved like resume.spawn(supervision:)is honoured for top-level actors. The strategy now decides whether a failing top-level actor is resumed, restarted or stopped. Previously it was stored and ignored, and the actor was always stopped. Top-level actors spawned without a strategy are still stopped.- Stopping an actor stops its children first, last started first. This includes pool workers, which used to outlive their router.
- Restarting an actor stops its children. The new incarnation starts
with none; a supervisor that wants them back creates them in
preStart, asRouterActordoes. - Failures of two children of one supervisor are handled one after the
other. Under
AllForOneStrategy, two children failing together used to restart every child twice, with the restarts interleaved. - A failed
preStartrolls the spawn back.spawnstill rejects, but the id is free again, refs obtained in the meantime are dead, andpostStopis not called on an actor that never started. Previously the actor stayed registered and processed messages uninitialised. - An actor stopped while its
preStartis still running gets itspostStoponcepreStartcompletes. - A throwing
postStopno longer abortsstop()orshutdown(); it is counted asactors.post_stop_failedand logged. Actor.onErroris now called when a handler throws, before supervision decides. It was documented and never invoked.- Added
SupervisorActor.supervisedChildren.
A zone per actor #
- Each actor incarnation runs in its own zone. An error nothing caught (an unawaited future, a timer or stream callback) now counts as that actor failing and goes to supervision. Previously it reached the enclosing zone, which for most programs means the process-level handler.
- Stopping or restarting an actor drops everything it left pending.
Timers are cancelled and code suspended on an
awaitnever resumes. A restarted actor's old incarnation can no longer act after its replacement has started. stop()is graceful. It waits for the handler in flight (or apreStartstill running) beforepostStop, for at mostActorSystemConfig.stopTimeout(5 seconds by default), then kills the actor. Restarts wait the same way, except for the handler that failed. PreviouslypostStopcould run in the middle of a handler.- Added
ActorSystem.kill(ref): stops an actor and its children at once, without waiting.postStopstill runs. New metricsactors.killedandactors.stop_timed_out. finallyblocks around a pendingawaitdo not run in a killed actor. Release resources inpostStop.- An actor that stops itself is cut off at that call. Code after
await context.system.stop(context.self)no longer runs. - An actor stopped during
preStartno longer haspostStoprun later, on its own; the stop waits forpreStartand then runs it. - While a failed actor waits for its supervisor's decision it receives no messages, also when the failure came from outside a handler.
- Cost: an idle actor takes about 1.7 KB, up from 1.1 KB, and single-actor throughput is 5 to 10 percent lower.
Exit reasons and links #
- Added
ExitReason, a sealed type saying why an actor ended:NormalExit(stopped on request),ShutdownExit(stopped by its parent or by system shutdown),KilledExit(kill, or the stop timeout ran out),ErrorExit(it failed; carries the error and stack trace) andNoProcExit. Terminatednow has areason.- Added links:
context.link(other)andcontext.unlink(other). When one linked actor ends abnormally the other fails withLinkedActorExited, and its supervisor decides what happens to it; with no supervisor it stops, with the same reason. A normal exit does not propagate. - Added
context.trapExits. An actor that sets it receives exits of linked actors, normal ones included, asExitSignalmessages and is not brought down. - A restart counts as the old incarnation ending: linked actors are
signalled and the link is dissolved. Link in
preStartto keep a pairing across restarts. Watchers are different: they are still told only when the actor is gone for good.
Supervisors #
- Restart budgets belong to the supervisor, not to each child. A
supervisor that performs more than
maxRestartsrestarts withinperiod(10 in 5 seconds by default), across all its children, gives up: it fails withRestartLimitExceeded, its children stop with it, and its own supervisor decides. Previously each child had a lifetime count of its own and was quietly stopped when it ran out. maxRetriesandwithinon the strategies are deprecated in favour ofmaxRestartsandperiod. The default period is now 5 seconds; it used to be unlimited.- Strategies are immutable and can be
const. Sharing one instance between supervisors no longer mixes their budgets. Custom strategies should extendSupervisionStrategyrather than implement it. - A top-level actor spawned with
supervision:has its own budget and is stopped withRestartLimitExceededwhen it runs out. - Added
RestForOneStrategy. - Added
ChildSpecandRestartType(permanent,transient,temporary), withSupervisorActor.startChild,startChildrenandterminateChild.supervisetakes optionalrestart:andshutdown:. - A permanent child that stops is started again.
supervise(id, factory)creates permanent children, sosystem.stop(child)on one now brings it back as a new actor under the same id. UseterminateChild, or make the childtransientortemporary. - Supervision decisions go through the supervisor's mailbox, ahead of
its ordinary messages.
onChildFailureno longer runs at the same time as the supervisor'sonMessage. - Added
Supervisor.onChildExited. - A pool router now restarts workers within the default budget and fails when it is exceeded; it used to restart them without limit.
Lints #
- Added
packages/dactor_lints, an analyzer plugin (Dart 3.10 or later) with two rules, both reported bydart analyzeand in the IDE:dactor_mutable_message(an object sent between actors has a field that can be reassigned) anddactor_captured_actor_state(an actor sends a closure, or itself, in a message). This repository's own code has no findings. Seepackages/dactor_lints/README.mdfor how to enable it.
Behaviours and typed protocols #
TypedRef<M>, fromref.typed<M>(): a compile-time view of anActorRefthat only acceptsM.Call<R>marks a message as a request, andtypedRef.call(request)returns aFuture<R>. A handler that throws fails the call withCallExceptioninstead of leaving it to time out.GenServer<S, M>:init,handleCall(Reply,NoReply,StopReply),handleCast,handleInfo,terminate. The state is a value the handlers return.GenStatem<S, D, M>:onEventanswers withnext,keep,postponeorhalt;onEnter; state timeouts withonTimeout; postponed events are replayed in order when the state changes.ApplicationandApplicationController: named supervision trees started in dependency order and stopped in reverse.- Selective receive:
context.receive<T>(where:, timeout:)inside a handler.ActorContextgained this member, which breaks classes that implementActorContextthemselves. LocalActorSystem.sys:getState,replaceState,suspend,resume,trace,statistics, andupgrade, which swaps an actor's code and passes the old state to the new behaviour'scodeChange.- New metric
actors.upgraded.Mailboxgainedlength,dequeueSystemandtakeFirstWhere. - Examples:
example/gen_server_example.dart,example/gen_statem_example.dart. The README's first example is now theGenServercounter.
Deterministic simulation testing #
package:dactor/simulation.dart:simulateruns a test against an actor system on a seeded scheduler with virtual time;exploreruns it under many seeds and reports the failing one with its scheduling trace. The same seed always gives the same run. Timers,Future.delayedand timeouts are virtual, so the runs take no real time.- Fault injection: a
FaultPolicycan drop, delay or crash on any delivery;randomFaultsdoes so at random from the seed. A crash fails the actor withInjectedFault. checkCommands: model-based tests over random command sequences.- Watching a dead actor now delivers
Terminatedat once, withNoProcExit, as linking to one already did. It used to do nothing, so a watcher that registered a moment too late waited forever. Found by the simulator. - Restart budgets measure their period on the simulation's clock when run inside one.
LocalActorSystem.stepped(internal) builds a system that dispatches only when told to; the pump's dispatch step is shared between both modes. Throughput is unchanged.
Actors in their own isolate #
Isolated(factory): an actor that runs the real actor in an isolate of its own and forwards messages to it one at a time. It is spawned, supervised, linked, watched and pooled like any other actor. Messages are copied;context.senderinside the isolate reaches back withtellandask.- Watchdog: the isolate is pinged every
heartbeat; one that stays silent forunresponsiveAfteris killed and the actor fails withIsolateUnresponsive, which its supervisor handles. This stops an actor in an infinite loop, which nothing inside one isolate can do. - New errors
IsolateUnresponsive,IsolateExited,RemoteActorError. LocalActorSystemandLocalActorRefare markedvm:isolate-unsendable. A message or closure that holds one now fails to send to another isolate, where it used to be copied whole.- Probes
tool/probes/p2_isolate_kill.dartandp3_isolate_cost.dart, andtool/probes/isolated_throughput.dart. - Example:
example/isolated_example.dart.
Hooks for distribution, and dactor_remote #
- New exit reason
NoConnectionExit.ExitReasonis sealed, so an exhaustiveswitchover it needs the new case. ForeignActorRef, withLocalActorSystem.linkForeign,unlinkForeignandforeignExit: what a transport needs to link local actors with actors on other nodes.context.linkaccepts aForeignActorRef.Simulation.addSystem()creates further actor systems in one simulation, for tests of several nodes.- New package
packages/dactor_remote(not published):RemoteNode, remotetell,ask,watchandlink, a codec registry over CBOR, capability tokens, remote spawn by behaviour name, an in-memory network that runs under the simulator, and a plain TCP transport.
dactor_libp2p #
- New package
packages/dactor_libp2p(not published):Libp2pTransportover a dart_libp2pHost. Nodes are named by peer id; Noise authenticates them and encrypts traffic, capability tokens included. Nodes behind a NAT are reached through circuit relays.startHostbuilds a host with UDX, Noise and Yamux, with a relay role and keep-alive settings. - The eleven same-as-local scenarios moved to
packages/dactor_remote/test/support/transport_scenarios.dart, so every transport runs the same ones.
Through real NATs #
Libp2pTransportmoves a node's frames off a relay when a direct connection to it appears (after a hole punch), without losing order or reporting the node down. The old stream ends with an empty frame as a marker. NewrouteTo(node).startHostgainedobserversNeeded(how many peers must report the same public address; a hole punch needs one) andannounce(which addresses to advertise).packages/dactor_libp2p/test/nat/run.sh: two dactor nodes behind separate NAT routers in Docker, with a Ricochet server as relay (uses go-ricochet's mailbox Docker setup). Relay, hole punch and lost-node checks; cone and symmetric NATs.
Unwatch, process groups and global names #
- Added
ActorRef.unwatch(watcher)andActorContext.unwatch(actor). The context form also drops aTerminatedfrom that actor still in the mailbox. Works on remote refs. - Fixed: a watcher that unwatched while being told of a stop could crash
stop()with a concurrent modification. RemoteNodedrops the watches a lost node had placed on its actors, instead of keeping them until the actors end. NewwatchedForOthers.- New
ProcessGroups(after Erlang'spg) andGlobalNames(afterglobal) indactor_remote. Seeded simulation of 300 histories each. - New
RemoteNode.serveandsendToService: messages between nodes, with the sending node authenticated by the transport. InMemoryNetworkfixed: a frame lost to a partition could be followed by later frames on the same pair with no node-down in between, if the partition healed before the loss was noticed. That broke the transport's promise ("in order, or nothing, and then a node-down"). Now nothing passes between two nodes from the loss until it is reported.dactor_libp2prequires dart_libp2p 4.12.1, which fixes the socket leak that kept processes from exiting. The examples and tools no longer callexit.- TCP heartbeats are still not done: a silent, still-open TCP connection is not detected (libp2p's keep-alive does detect it).
Discovery, and phones #
- A reference brings its node's addresses. On a transport that is an
AddressBook(new interface;Libp2pTransportis one), a reference sent in a message carries up to eight addresses of its node, anduriOfadds them to the text asaddrparameters. Process groups pass on the addresses of the nodes they know. A node needs an address for one node only. Libp2pTransport:localAddresses(only those this host can dial, oradvertise:), addresses learned through identify, and aresolve:hook asked for a node no one gave an address for (where a DHT would go).- Fixed: idle libp2p links dropped every five minutes. A Yamux read
with no deadline gives up after five minutes without data; the transport
took that for a broken stream and reported the node down. The transport
now sets a far deadline before every read (libp2p clears deadlines on
accepted streams after the handler starts). Found on the phones; new
tool/idle_probe.dart. ProcessGroupsforgets a node that was passed on and has been unreachable forforgetAfter(10 minutes, counted in retries), and no longer passes on a node a retry has missed. Nodes given toconnectare kept. A node that was gone for good used to be retried, and spread to every newcomer, for ever.- New
packages/dactor_libp2p/example/mobile_probe: a Flutter app and a laptop peer that check each other through the Ricochet relay. Run on an iPhone on cellular and an Android phone on Wi-Fi: discovery through a group, every check passing over relay and direct links, background and return, Wi-Fi on and off, 21 idle minutes. Results in thedactor_libp2pREADME ("On phones").
Messages, senders, applications and behaviours #
- An application whose root actor ends is noticed.
Applicationhas arestarttype, as in OTP:temporary(the default),transientorpermanent. When a root ends on its own, its dependents are stopped andstopped()runs; apermanentapplication, or atransientone that ended abnormally, then stops every application. Each case is reported on the newApplicationController.exitsstream as anApplicationExit. Stops made through the controller are not reported. GenStatemevent and generic timeouts.eventTimeout:on a transition callsonEventTimeoutunless any message arrives first.timeouts: {name: duration}sets named timeouts that survive changes of state and callonGenericTimeout(name, state, data); setting a name again restarts it andnullcancels it.haltcancels all of them.- Typed
GenStatemreplies.reply:takesrequest.answer(value), whererequestmixes inCall<R>andvaluemust be anR, so a reply of the wrong type does not compile. GenServer.handleContinue, after OTP'shandle_continue.initor a handler callscontinueWith(arg), andhandleContinue(arg, state)runs before the next message. Frominitit runs afterspawnhas returned; fromhandleCall, after the reply has gone.- Messages are plain values.
ActorRef.tell(Object?)andask<T>(Object?, [timeout]):onMessagereceives exactly what was told. TheMessageinterface is gone.LocalMessage,AskableMessageandAskableResponseare deprecated; aLocalMessagetold is unwrapped to its payload.Mailboxis no longer exported. - Senders cannot be forged.
tellhas nosender:. The runtime stamps the actor whose code is telling, or none outside any actor, and timer messages have none.context.forward(target, message)passes a message on with its original sender, which the router now uses. ATerminatedorExitSignaltold by anyone but the runtime is dropped to the dead letters. Ask correlation ids are made by the runtime. - New library
package:dactor/spi.dart, for transports, bridges and tests:sendAs(sender, () => ref.tell(m)),tellSystem(ref, Terminated(...)), andcurrentSenderfor anActorRefwritten outside dactor.dactor_remoteuses it. dactor_lintschecks what is given totell,ask,forwardand aTypedRef'stellandcall, as well asLocalMessage(payload:).
1.3.0 #
ask()no longer retries by default.AskConfig()now hasenableRetries: false. A retry re-sends the request, so with the old default a slow (not failed) actor executed the same command up to four times, and an ask to a dead actor blocked the caller for about 20 s.AskConfig.development()andAskConfig.production()still enable retries explicitly. Retries keep the samecorrelationIdacross attempts so receivers can deduplicate.- Fixed the Quick Start in the README and
example/dactor_example.dart. Both testedmessage is LocalMessageinsideonMessage, which is never true because actors receive the payload; the counter never incremented and the ask timed out. They now switch on the payload and reply viacontext.sender. - Removed the unused
cbordependency and the "zero dependencies" claim. - Added a
.pubignoresodoc/and repository tooling are not published. - A system built without a config no longer collects metrics or traces.
The previous defaults,
InMemoryMetricsCollectorandInMemoryTraceCollector, kept a timing sample for every message and a trace event (holding the payload) for every send and receive, forever; measured at roughly 485 MB retained per million messages. The defaults are nowNoOpMetricsCollectorandNoOpTraceCollector. Pass an explicit collector to opt in. Also addedNoOpLogCollector. InMemoryMetricsCollectorandInMemoryTraceCollectorare now bounded (maxTimingsper metric andmaxEventsoverall, both 10,000 by default). The tracer evicts whole correlation ids, oldest first, and exposeseventCountandclear();tracesis now a read-only view.dactor.dartnow exports the metrics, tracing, logging and routing libraries (Pool,RoutingLogic, the collectors,LogRecord, ...), which already appeared in public signatures but could only be imported fromsrc/.- Supervision is routed by an explicit parent record, not by parsing
/in the actor id. Previously the system took everything before the last/as the supervisor and cast it withas SupervisorActor; an actor namedplain/evilunder a non-supervisorplaintherefore killed the whole process with an unhandledTypeErroron its first failure, and any actor could attach itself to a foreign supervisor by choosing its name. Children are now created throughSupervisorActor.supervise(internallyLocalActorSystem.spawnChild), which records the parent, requires the parent to be a liveSupervisor, and rejects child ids that are empty or contain/. Actors spawned with a/in their id throughspawnare ordinary unsupervised actors.RouterActorsupervises its workers through the same path. Addedtest/supervision_guard_test.dart. - Restart now happens in place. Previously a restart stopped the actor and
spawned a new one, which created a new
ActorRef; every reference held by other actors (including pool workers) then went to dead letters, pending messages were discarded, watchers receivedTerminated, and event-bus subscriptions were lost. A restart now keeps the ref, mailbox, watchers and subscriptions and only replaces theActorinstance:postStopon the old one, timers cancelled,preStarton the new one.SupervisorActorandRouterActoruse this path. Messages are never dispatched to an actor whosepreStarthas not completed. Addedtest/restart_test.dart. - Errors thrown while handling a child failure (for example a replacement's
preStartthrowing) no longer escape as unhandled zone errors. The child is stopped,actors.supervision_failedis incremented and the error is logged. - Add
dactor_testas a dev dependency. The 1.2.0 release moved the test toolkit out of this package but never declared it, so 9 of the 12 test files could not load from a clean checkout. Added a GitHub Actions workflow that runsdart analyzeand the unit tests on every push and pull request. - README: the testing section now points at the
dactor_testpackage. - Fix
shutdown()not stopping any actor.stop()returned early once the shutdown flag was set, sopostStopnever ran, timers kept firing (keeping the isolate alive), refs stayedisAlive, and late messages were silently queued instead of dead-lettered. Actors are now torn down in reverse spawn order during shutdown. Addedtest/shutdown_test.dart.
1.2.0 #
- Fix actor model correctness, supervision, and messaging issues
- Remove
testfrom regular dependencies (was incorrectly listed as runtime dep) - Extract test utilities into separate
dactor_testpackage
1.1.0 #
- Docs: Added comprehensive documentation for testing actors, including
TestActorSystem,TestProbe, and message tracing.
1.0.0 #
- Initial version.