Actor System

Overview

The GoAkt actor system is the core container for all actor-based operations in a GoAkt application. Without an actor system, no actors can be created. Although the framework does not currently enforce a singleton instance, best practices recommend creating only one actor system per application to centralise management, improve resource utilisation, and simplify supervision.

To instantiate an actor system, use the NewActorSystem method along with the desired configuration Options. These options allow you to tailor the system’s behavior to your application’s needs—for example, by enabling clustering, remoting, passivation, or custom supervision strategies.

Example

package main

import (
	"context"
	"os"
	"os/signal"
	"sync"
	"syscall"
	"time"

	"github.com/tochemey/goakt/v3/actor"
	"github.com/tochemey/goakt/v3/log"
)

func main() {
	ctx := context.Background()
	host := "0.0.0.0"
	port := 4000

	logger := log.New(log.InfoLevel, os.Stdout)

	// create an actor system. Check the reference
	// doc for additional options
	actorSystem, err := actor.NewActorSystem(
		"ChatSystem",
		actor.WithPassivationDisabled(),
		actor.WithRemoting(host, int32(port)),
		actor.WithLogger(logger))

	if err != nil {
		logger.Fatal(err)
		os.Exit(1)
	}

	// start the actor system
	if err := actorSystem.Start(ctx); err != nil {
		logger.Fatal(err)
		os.Exit(1)
	}

	// capture ctrl+c
	interruptSignal := make(chan os.Signal, 1)
	signal.Notify(interruptSignal, os.Interrupt, syscall.SIGINT, syscall.SIGTERM)
	<-interruptSignal

	// stop the actor system
	_ = actorSystem.Stop(ctx)
	os.Exit(0)
}

Characteristics

GoAkt ActorSystem has the following characteristics:

• Actors lifecycle management: The system provides methods such as Spawn, Kill, and ReSpawn to create, terminate, and restart actors. This enables dynamic management of actors during runtime.

• Concurrency and Parallelism:

  • Each actor processes messages from its mailbox independently and concurrently. This design takes full advantage of multicore processors without requiring locks or shared-memory synchronisation.

  • Actors process one message at a time, which helps avoid blocking issues and ensures high throughput even under heavy load.

• Location Transparency - When clustering (or remoting) is enabled, the physical location of actors is abstracted away. You interact with actors solely through their unique addresses, regardless of whether they are local or remote.

• Fault Tolerance and Supervision:

  • Each actor can be configured with a custom supervision strategy that defines how the system should respond to errors (e.g., restart, stop, or resume). One can also set a supervision strategy per actor during the creation of the given actor. See Supervisionfor more information.

  • The framework provides built-in error types and directives to manage actor failures, ensuring that faulty actors are handled gracefully.

• Addressing - Every actor in the system is assigned a unique address, which is used for message routing and, when remoting is enabled, for locating actors across nodes

• Actors Tree - The actor system maintains an actor tree—a hierarchical structure that represents the relationships between actors. This tree structure is central to supervision and coordinated shutdown procedures.

• Message Scheduler - The actor system includes scheduling capabilities, allowing you to send messages after a specified delay or at regular intervals. This feature is useful for implementing time-based events or periodic tasks. See Message Scheduling

• Events Subscription - Clients can subscribe to system events (e.g., actor creation, termination, passivation) to monitor the health and status of the actor system. See Events Stream

• Actor Kinds Registry - The registry holds the mapping of actor kinds (types) and is a critical component when running in cluster mode or when creating remote actors. Using reflection, GoAkt can create actors at runtime based on the registry information.