Actor

Overview

The fundamental building blocks of GoAkt are actors.

• Have a unique name across the entire system even in cluster mode. One a name is given to an actor, it is immutable and it is globally unique.

• They are independent, isolated unit of computation with their own state.

• They can be long-lived actors or be passivated after some period of time that is configured during their creation. Use this feature with care when dealing with persistent actors (actors that require their state to be persisted).

• They are automatically thread-safe without having to use locks or any other shared-memory synchronization mechanisms.

• They can be stateful and stateless depending upon the system to build.

• Every actor in GoAkt:

  • has a process id PID. Via the process id any allowable action can be executed by the actor.

  • has a lifecycle via the following methods: PreStart, PostStop.

    • PreStart hook is used to initialise actor state. It is like the actor constructor.

    • PostStop hook is used to clean up resources used by the Actor. It is like the actor destructor. It means it can live and die like any other process.

  • handles and responds to messages via the method Receive. While handling messages it can:

  • create other (child) actors via their process id PID SpawnChild method

  • send messages to other actors locally or remotely via their process id PID Ask, RemoteAsk(request/response fashion) and Tell, RemoteTell(fire-and-forget fashion) methods

  • stop (child) actors via their process id PID

  • watch/unwatch (child) actors via their process id PID Watch and UnWatch methods

  • supervise the failure behavior of (child) actors.

  • remotely lookup for an actor on another node via their process id PID RemoteLookup. This allows it to send messages remotely via RemoteAsk or RemoteTell methods

  • stash/unstash messages. See Stashing

  • can adopt various form using the Behavior feature. See Behaviors

  • can be restarted (respawned)

  • can be gracefully stopped (killed). Every message in the mailbox prior to stoppage will be processed within a configurable time period.

PID

• Acts as a unique, immutable identifier for each actor within the system. See PID for more information.
• Serves as the primary handle for sending messages to the actor, ensuring location transparency.

• Encapsulates the actor’s address and operational semantics (e.g., supervision and lifecycle management).

• Enables message delivery by directing both asynchronous (“tell”) and synchronous (“ask”) interactions.

• Facilitates supervision, where parent actors can monitor, restart, or stop child actors using their PIDs.

• Supports remote messaging by incorporating network location data, making inter-node communication seamless.

• Combines actor reference, mailbox, metrics, and synchronization primitives.

• Provides a rich API with methods like Tell, Ask, RemoteTell, and RemoteAsk to cover different messaging patterns.

• Integrates with the actor’s mailbox and supervision framework, enabling effective lifecycle management and monitoring.

Get Started

To define an actor one needs to implement the Actorinterface:

// Actor defines the interface for an actor in the system.
// Any struct implementing this interface must be immutable, meaning all fields should be private (unexported).
// Use the PreStart hook to initialize any required fields or resources.
type Actor interface {
	// PreStart is called before the actor starts processing messages.
	// It can be used for initialization tasks such as setting up database connections or other dependencies.
	// If this function returns an error, the actor will not start.
	PreStart(ctx context.Context) error
	// Receive handles messages delivered to the actor's mailbox.
	// The actor can respond to messages asynchronously by sending a reply or synchronously by configuring the reply within the message.
	// While synchronous communication is possible, it can impact system performance and should be used with caution.
	Receive(ctx *ReceiveContext)
	// PostStop is called when the actor is shutting down.
	// It ensures that any remaining messages in the mailbox are processed before termination.
	// Use this hook to release resources, close connections, or perform cleanup tasks.
	PostStop(ctx context.Context) error
}

• PreStart this function is used to initialise the given actor and set prerequisites before the actor starts. This function is called before the actor is created. In case of failure the actor is not created after a certain number of attempts that is configurable via the actor system creation option WithActorInitMaxRetries. The default value is 5.

• PostStop this function is used by the Actor implementation to cleanly shutdown the actor.

• Receive is used by the Actor implementation to handle the given message sent to the actor. ReceiveContext represents the message sent context.