The purpose of this package is to allow you to create actors in Go.
An introduction and tutorial to using this library is available.
Think of an actor like a little server: it is created, it receives messages and processes them, and it terminates. As part of processing a message, it can reply to the message, it can send messages to other actors that it knows of, it can create new actors, and it can terminate.
Each actor has a mailbox. Clients of the actor call the actor's public API, which will typically post messages into this mailbox. The actor will see that there are messages in the mailbox, retrieve each message, and process them. Whilst posting a message into a mailbox is mainly an asynchronous activity, the message itself may require a reply. The sender can choose to block and wait for the reply at any time. This functionality is provided by the MsgSync and MsgSyncBase types.
Each actor-server is a Go-routine. The mailbox is implemented by chans. It is safe for multiple concurrent Go-routines to post messages to the same actor, and it is always the case that an actor-server itself is single-threaded - a single Go-routine. If you wish for more elaborate setups then that is for you: some sort of sharding or session management across a set of actors of the same type is perfectly possible, but is not currently provided directly by this package.
Use different struct types to implement the client-side and the server-side of each actor. The client-side should embed (probably anonymously) an implementation of the Client type. The server-side should anonymously embed an implementation of the Server type (either BackPressureServerBase or ServerBase).
The server-side of each actor must satisfy the
Server interface,
and so has to provide three methods: Init, HandleMsg, and
Terminated. BackPressureServerBase
and ServerBase
have implementations of all of these, so you need only reimplement the
ones you need. For all methods that you implement yourself on the
server-side, make certain that you also call the embedded version. If
you fail to do this for Init, then various parts of the actor will
not be set up properly. If you fail to do this for HandleMsg then
the actor will not be able to be terminate, and if you fail to do this
for Terminated, then termination subscriptions will not function
correctly.
Init is the first method invoked by the new actor, and is called
synchronously as part of spawning the new actor. I.e. at the point
that Init is invoked (in the new actor's Go-routine), Spawn will
not have returned, and no one will yet know of the existence of this
new actor. So, if the new actor decides to send messages to itself, it
can guarantee that those messages will be the first items in its own
mailbox. This is useful for being able to do deferred asynchronous
initialisation, for example. If Init fails (returns a non-nil
error), then Spawn fails too, and returns the same error.
HandleMsg is invoked for each message that is received from the
actor's mailbox. HandleMsg returns an error; if the error is non-nil
then the actor terminates: the actor's mailbox is closed, Terminated
is invoked, and finally the actor's Go-routine exits. All remaining
messages in the actor's mailbox are discarded, and anyone else waiting
on responses from the actor will be informed that the actor has
terminated and no further responses will be forthcoming.
An introduction and tutorial to using this library is available.