37 lines
2.4 KiB
Go
37 lines
2.4 KiB
Go
// Package actor provides generic actors with a multi-producer, single-consumer
|
|
// mailbox. By default a sender that acquires consumption ownership runs the
|
|
// handler synchronously until the mailbox is empty, without starting or retaining
|
|
// a goroutine. WithDispatcher can instead send the entire drain task to a custom
|
|
// execution policy, such as an existing worker pool or another goroutine.
|
|
// Concurrent senders only publish messages while a task is queued or running.
|
|
//
|
|
// Dispatcher.Schedule may execute synchronously or asynchronously, but must
|
|
// accept each task and eventually execute it exactly once. It must not reject,
|
|
// silently discard, or panic. Shared dispatchers must support concurrent calls.
|
|
// Ownership is claimed before scheduling, so delayed task execution does not
|
|
// cause duplicate submissions. Dispatchers are configured only at construction;
|
|
// the actor does not provide a fallback for violations of their contract.
|
|
//
|
|
// Successful publication defines FIFO order, including across fixed and dynamic
|
|
// storage. Concurrent calls have no ordering before their publication point. A
|
|
// producer paused before publication does not block other producers. Pending
|
|
// batches are detached atomically and reversed by relinking nodes, without
|
|
// copying their messages. Fixed nodes are retained and reused after the entire
|
|
// reservation round has been consumed; dynamic nodes are cleared and released
|
|
// for garbage collection. The mailbox has no capacity limit.
|
|
//
|
|
// The same handler never runs concurrently or reentrantly. It may send to its own
|
|
// Actor, but must not wait synchronously for a message queued to that Actor.
|
|
// Sending to another idle Actor with the default dispatcher executes that
|
|
// Actor's handler synchronously. A busy mailbox can keep its owning inline Send
|
|
// call active indefinitely. Scheduling yields do not interrupt an individual
|
|
// handler or change the dispatcher's execution policy. Send returning does not
|
|
// guarantee that its message has been handled.
|
|
//
|
|
// Messages are copied as Go values, not deep-copied. Callers must synchronize any
|
|
// subsequent access to referenced data that the handler may also access. Actor
|
|
// state should be accessed only by its handler or with external synchronization.
|
|
// Handler panics, and panics in the optional panic callback, are recovered so
|
|
// processing can continue. There is no cancellation, close, or automatic retry.
|
|
package actor
|