Package org.apache.pekko.actor

Class ActorSystem

java.lang.Object
org.apache.pekko.actor.ActorSystem
All Implemented Interfaces:
ActorRefFactory, ClassicActorSystemProvider
Direct Known Subclasses:
ExtendedActorSystem
public abstract class ActorSystem extends Object implements ActorRefFactory, ClassicActorSystemProvider
An actor system is a hierarchical group of actors which share common configuration, e.g. dispatchers, deployments, remote capabilities and addresses. It is also the entry point for creating or looking up actors.

There are several possibilities for creating actors (see pekko.actor.Props for details on props): 


 // Java or Scala
 system.actorOf(props, "name")
 system.actorOf(props)

 // Scala
 system.actorOf(Props[MyActor], "name")
 system.actorOf(Props(classOf[MyActor], arg1, arg2), "name")

 // Java
 system.actorOf(Props.create(MyActor.class), "name");
 system.actorOf(Props.create(MyActor.class, arg1, arg2), "name");

Where no name is given explicitly, one will be automatically generated.

Important Notice:

This class is not meant to be extended by user code. If you want to actually roll your own Pekko, it will probably be better to look into extending pekko.actor.ExtendedActorSystem instead, but beware that you are completely on your own in that case!

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    ActorSystem.Settings
    Settings are the overall ActorSystem Settings which also provides a convenient access to the Config object.
    static class 
    ActorSystem.Settings$
    INTERNAL API

  • Constructor Summary

    Constructors
    Constructor
    Description
    ActorSystem()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    abstract ActorPath
    $div(String name)
    Construct a path below the application guardian to be used with ActorRefFactory.actorSelection(java.lang.String).
    abstract ActorPath
    $div(scala.collection.Iterable<String> name)
    Construct a path below the application guardian to be used with ActorRefFactory.actorSelection(java.lang.String).
    static ActorSystem
    apply()
    Creates a new ActorSystem with the name "default", obtains the current ClassLoader by first inspecting the current threads' getContextClassLoader, then tries to walk the stack to find the callers class loader, then falls back to the ClassLoader associated with the ActorSystem class.
    static ActorSystem
    apply(String name)
    Creates a new ActorSystem with the specified name, obtains the current ClassLoader by first inspecting the current threads' getContextClassLoader, then tries to walk the stack to find the callers class loader, then falls back to the ClassLoader associated with the ActorSystem class.
    static ActorSystem
    apply(String name, com.typesafe.config.Config config)
    Creates a new ActorSystem with the specified name, and the specified Config, then obtains the current ClassLoader by first inspecting the current threads' getContextClassLoader, then tries to walk the stack to find the callers class loader, then falls back to the ClassLoader associated with the ActorSystem class.
    static ActorSystem
    apply(String name, com.typesafe.config.Config config, ClassLoader classLoader)
    Creates a new ActorSystem with the specified name, the specified Config, and specified ClassLoader
    static ActorSystem
    apply(String name, BootstrapSetup bootstrapSetup)
    Scala API: Shortcut for creating an actor system with custom bootstrap settings.
    static ActorSystem
    apply(String name, ActorSystemSetup setup)
    Scala API: Creates a new actor system with the specified name and settings The core actor system settings are defined in BootstrapSetup
    static ActorSystem
    apply(String name, scala.Option<com.typesafe.config.Config> config, scala.Option<ClassLoader> classLoader, scala.Option<scala.concurrent.ExecutionContext> defaultExecutionContext)
    Creates a new ActorSystem with the specified name, the specified ClassLoader if given, otherwise obtains the current ClassLoader by first inspecting the current threads' getContextClassLoader, then tries to walk the stack to find the callers class loader, then falls back to the ClassLoader associated with the ActorSystem class.
    static scala.Option<com.typesafe.config.Config>
    apply$default$2()
     
    static scala.Option<ClassLoader>
    apply$default$3()
     
    static scala.Option<scala.concurrent.ExecutionContext>
    apply$default$4()
     
    ActorPath
    child(String child)
    Java API: Create a new child actor path.
    static ActorSystem
    create()
    Creates a new ActorSystem with the name "default", obtains the current ClassLoader by first inspecting the current threads' getContextClassLoader, then tries to walk the stack to find the callers class loader, then falls back to the ClassLoader associated with the ActorSystem class.
    static ActorSystem
    create(String name)
    Creates a new ActorSystem with the specified name, obtains the current ClassLoader by first inspecting the current threads' getContextClassLoader, then tries to walk the stack to find the callers class loader, then falls back to the ClassLoader associated with the ActorSystem class.
    static ActorSystem
    create(String name, com.typesafe.config.Config config)
    Creates a new ActorSystem with the specified name, and the specified Config, then obtains the current ClassLoader by first inspecting the current threads' getContextClassLoader, then tries to walk the stack to find the callers class loader, then falls back to the ClassLoader associated with the ActorSystem class.
    static ActorSystem
    create(String name, com.typesafe.config.Config config, ClassLoader classLoader)
    Creates a new ActorSystem with the specified name, the specified Config, and specified ClassLoader
    static ActorSystem
    create(String name, com.typesafe.config.Config config, ClassLoader classLoader, scala.concurrent.ExecutionContext defaultExecutionContext)
    Creates a new ActorSystem with the specified name, the specified Config, the specified ClassLoader, and the specified ExecutionContext.
    static ActorSystem
    create(String name, BootstrapSetup bootstrapSetup)
    Java API: Shortcut for creating an actor system with custom bootstrap settings.
    static ActorSystem
    create(String name, ActorSystemSetup setups)
    Java API: Creates a new actor system with the specified name and settings The core actor system settings are defined in BootstrapSetup
    abstract ActorRef
    deadLetters()
    Actor reference where messages are re-routed to which were addressed to stopped or non-existing actors.
    ActorPath
    descendant(Iterable<String> names)
    Java API: Recursively create a descendant&rsquo;s path by appending all child names.
    abstract scala.concurrent.ExecutionContextExecutor
    dispatcher()
    Default dispatcher as configured.
    abstract Dispatchers
    dispatchers()
    Helper object for looking up configured dispatchers.
    abstract EventStream
    eventStream()
    Main event bus of this actor system, used for example for logging.
    abstract <T extends Extension>
    T
    extension(ExtensionId<T> ext)
    Returns the payload that is associated with the provided extension throws an IllegalStateException if it is not registered.
    scala.concurrent.ExecutionContextExecutor
    getDispatcher()
    Java API: Default dispatcher as configured.
    EventStream
    getEventStream()
    Java API: Main event bus of this actor system, used for example for logging.
    Scheduler
    getScheduler()
    Java API: Light-weight scheduler for running asynchronous tasks after some deadline in the future.
    abstract CompletionStage<Terminated>
    getWhenTerminated()
    Returns a CompletionStage which will be completed after the ActorSystem has been terminated and termination hooks have been executed.
    abstract boolean
    hasExtension(ExtensionId<? extends Extension> ext)
    Returns whether the specified extension is already registered, this method can potentially block, waiting for the initialization of the payload, if is in the process of registration from another Thread of execution
    abstract LoggingAdapter
    log()
    Convenient logging adapter for logging to the eventStream().
    abstract void
    logConfiguration()
    Log the configuration.
    abstract org.apache.pekko.dispatch.Mailboxes
    mailboxes()
    Helper object for looking up configured mailbox types.
    abstract String
    name()
    The name of this actor system, used to distinguish multiple ones within the same JVM & class loader.
    abstract <T extends Extension>
    T
    registerExtension(ExtensionId<T> ext)
    Registers the provided extension and creates its payload, if this extension isn't already registered This method has putIfAbsent-semantics, this method can potentially block, waiting for the initialization of the payload, if is in the process of registration from another Thread of execution
    abstract void
    registerOnTermination(Runnable code)
    Java API: Register a block of code (callback) to run after ActorSystem.terminate has been issued and all actors in this actor system have been stopped.
    abstract <T> void
    registerOnTermination(scala.Function0<T> code)
    Register a block of code (callback) to run after ActorSystem.terminate has been issued and all actors in this actor system have been stopped.
    abstract Scheduler
    scheduler()
    Light-weight scheduler for running asynchronous tasks after some deadline in the future.
    abstract ActorSystem.Settings
    settings()
    The core settings extracted from the supplied configuration.
    long
    startTime()
    Start-up time in milliseconds since the epoch.
    abstract scala.concurrent.Future<Terminated>
    terminate()
    Terminates this actor system by running CoordinatedShutdown with reason CoordinatedShutdown.ActorSystemTerminateReason.
    long
    uptime()
    Up-time of this actor system in seconds.
    static String
    Version()
     
    abstract scala.concurrent.Future<Terminated>
    whenTerminated()
    Returns a Future which will be completed after the ActorSystem has been terminated and termination hooks have been executed.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface org.apache.pekko.actor.ActorRefFactory

    actorOf, actorOf, actorSelection, actorSelection, guardian, lookupRoot, provider, stop, systemImpl

    Methods inherited from interface org.apache.pekko.actor.ClassicActorSystemProvider

    classicSystem

  • Constructor Details

    • ActorSystem

      public ActorSystem()

  • Method Details

    • Version

      public static String Version()

    • create

      public static ActorSystem create()
      Creates a new ActorSystem with the name "default", obtains the current ClassLoader by first inspecting the current threads' getContextClassLoader, then tries to walk the stack to find the callers class loader, then falls back to the ClassLoader associated with the ActorSystem class. Then it loads the default reference configuration using the ClassLoader.

    • create

      public static ActorSystem create(String name)
      Creates a new ActorSystem with the specified name, obtains the current ClassLoader by first inspecting the current threads' getContextClassLoader, then tries to walk the stack to find the callers class loader, then falls back to the ClassLoader associated with the ActorSystem class. Then it loads the default reference configuration using the ClassLoader.

    • create

      public static ActorSystem create(String name, ActorSystemSetup setups)
      Java API: Creates a new actor system with the specified name and settings The core actor system settings are defined in BootstrapSetup

    • create

      public static ActorSystem create(String name, BootstrapSetup bootstrapSetup)
      Java API: Shortcut for creating an actor system with custom bootstrap settings. Same behavior as calling ActorSystem.create(name, ActorSystemSetup.create(bootstrapSettings))

    • create

      public static ActorSystem create(String name, com.typesafe.config.Config config)
      Creates a new ActorSystem with the specified name, and the specified Config, then obtains the current ClassLoader by first inspecting the current threads' getContextClassLoader, then tries to walk the stack to find the callers class loader, then falls back to the ClassLoader associated with the ActorSystem class.

      See Also:

    • create

      public static ActorSystem create(String name, com.typesafe.config.Config config, ClassLoader classLoader)
      Creates a new ActorSystem with the specified name, the specified Config, and specified ClassLoader

      See Also:

    • create

      public static ActorSystem create(String name, com.typesafe.config.Config config, ClassLoader classLoader, scala.concurrent.ExecutionContext defaultExecutionContext)
      Creates a new ActorSystem with the specified name, the specified Config, the specified ClassLoader, and the specified ExecutionContext. The ExecutionContext will be used as the default executor inside this ActorSystem. If null is passed in for the Config, ClassLoader and/or ExecutionContext parameters, the respective default value will be used. If no Config is given, the default reference config will be obtained from the ClassLoader. If no ClassLoader is given, it obtains the current ClassLoader by first inspecting the current threads' getContextClassLoader, then tries to walk the stack to find the callers class loader, then falls back to the ClassLoader associated with the ActorSystem class. If no ExecutionContext is given, the system will fallback to the executor configured under "pekko.actor.default-dispatcher.default-executor.fallback". Note that the given ExecutionContext will be used by all dispatchers that have been configured with executor = "default-executor", including those that have not defined the executor setting and thereby fallback to the default of "default-dispatcher.executor".

      See Also:

    • apply

      public static ActorSystem apply()
      Creates a new ActorSystem with the name "default", obtains the current ClassLoader by first inspecting the current threads' getContextClassLoader, then tries to walk the stack to find the callers class loader, then falls back to the ClassLoader associated with the ActorSystem class. Then it loads the default reference configuration using the ClassLoader.

    • apply

      public static ActorSystem apply(String name)
      Creates a new ActorSystem with the specified name, obtains the current ClassLoader by first inspecting the current threads' getContextClassLoader, then tries to walk the stack to find the callers class loader, then falls back to the ClassLoader associated with the ActorSystem class. Then it loads the default reference configuration using the ClassLoader.

    • apply

      public static ActorSystem apply(String name, ActorSystemSetup setup)
      Scala API: Creates a new actor system with the specified name and settings The core actor system settings are defined in BootstrapSetup

    • apply

      public static ActorSystem apply(String name, BootstrapSetup bootstrapSetup)
      Scala API: Shortcut for creating an actor system with custom bootstrap settings. Same behavior as calling ActorSystem(name, ActorSystemSetup(bootstrapSetup))

    • apply

      public static ActorSystem apply(String name, com.typesafe.config.Config config)
      Creates a new ActorSystem with the specified name, and the specified Config, then obtains the current ClassLoader by first inspecting the current threads' getContextClassLoader, then tries to walk the stack to find the callers class loader, then falls back to the ClassLoader associated with the ActorSystem class.

      See Also:

    • apply

      public static ActorSystem apply(String name, com.typesafe.config.Config config, ClassLoader classLoader)
      Creates a new ActorSystem with the specified name, the specified Config, and specified ClassLoader

      See Also:

    • apply

      public static ActorSystem apply(String name, scala.Option<com.typesafe.config.Config> config, scala.Option<ClassLoader> classLoader, scala.Option<scala.concurrent.ExecutionContext> defaultExecutionContext)
      Creates a new ActorSystem with the specified name, the specified ClassLoader if given, otherwise obtains the current ClassLoader by first inspecting the current threads' getContextClassLoader, then tries to walk the stack to find the callers class loader, then falls back to the ClassLoader associated with the ActorSystem class. If an ExecutionContext is given, it will be used as the default executor inside this ActorSystem. If no ExecutionContext is given, the system will fallback to the executor configured under "pekko.actor.default-dispatcher.default-executor.fallback". The system will use the passed in config, or falls back to the default reference configuration using the ClassLoader.

      See Also:

    • apply$default$2

      public static scala.Option<com.typesafe.config.Config> apply$default$2()

    • apply$default$3

      public static scala.Option<ClassLoader> apply$default$3()

    • apply$default$4

      public static scala.Option<scala.concurrent.ExecutionContext> apply$default$4()

    • name

      public abstract String name()
      The name of this actor system, used to distinguish multiple ones within the same JVM & class loader.

    • settings

      public abstract ActorSystem.Settings settings()
      The core settings extracted from the supplied configuration.

    • logConfiguration

      public abstract void logConfiguration()
      Log the configuration.

    • $div

      public abstract ActorPath $div(String name)
      Construct a path below the application guardian to be used with ActorRefFactory.actorSelection(java.lang.String).

    • child

      public ActorPath child(String child)
      Java API: Create a new child actor path.

    • $div

      public abstract ActorPath $div(scala.collection.Iterable<String> name)
      Construct a path below the application guardian to be used with ActorRefFactory.actorSelection(java.lang.String).

    • descendant

      public ActorPath descendant(Iterable<String> names)
      Java API: Recursively create a descendant&rsquo;s path by appending all child names.

    • startTime

      public long startTime()
      Start-up time in milliseconds since the epoch.

    • uptime

      public long uptime()
      Up-time of this actor system in seconds.

    • eventStream

      public abstract EventStream eventStream()
      Main event bus of this actor system, used for example for logging.

    • getEventStream

      public EventStream getEventStream()
      Java API: Main event bus of this actor system, used for example for logging.

    • log

      public abstract LoggingAdapter log()
      Convenient logging adapter for logging to the eventStream().

    • deadLetters

      public abstract ActorRef deadLetters()
      Actor reference where messages are re-routed to which were addressed to stopped or non-existing actors. Delivery to this actor is done on a best effort basis and hence not strictly guaranteed.

    • scheduler

      public abstract Scheduler scheduler()
      Light-weight scheduler for running asynchronous tasks after some deadline in the future. Not terribly precise but cheap.

    • getScheduler

      public Scheduler getScheduler()
      Java API: Light-weight scheduler for running asynchronous tasks after some deadline in the future. Not terribly precise but cheap.

    • dispatchers

      public abstract Dispatchers dispatchers()
      Helper object for looking up configured dispatchers.

    • dispatcher

      public abstract scala.concurrent.ExecutionContextExecutor dispatcher()
      Default dispatcher as configured. This dispatcher is used for all actors in the actor system which do not have a different dispatcher configured explicitly. Importing this member will place the default MessageDispatcher in scope.
      Specified by:
      dispatcher in interface ActorRefFactory

    • getDispatcher

      public scala.concurrent.ExecutionContextExecutor getDispatcher()
      Java API: Default dispatcher as configured. This dispatcher is used for all actors in the actor system which do not have a different dispatcher configured explicitly. Importing this member will place the default MessageDispatcher in scope.

    • mailboxes

      public abstract org.apache.pekko.dispatch.Mailboxes mailboxes()
      Helper object for looking up configured mailbox types.

    • registerOnTermination

      public abstract <T> void registerOnTermination(scala.Function0<T> code)
      Register a block of code (callback) to run after ActorSystem.terminate has been issued and all actors in this actor system have been stopped. Multiple code blocks may be registered by calling this method multiple times. The callbacks will be run sequentially in reverse order of registration, i.e. last registration is run first. Note that ActorSystem will not terminate until all the registered callbacks are finished.

      Throws a RejectedExecutionException if the System has already been terminated or if termination has been initiated.

      Scala API

    • registerOnTermination

      public abstract void registerOnTermination(Runnable code)
      Java API: Register a block of code (callback) to run after ActorSystem.terminate has been issued and all actors in this actor system have been stopped. Multiple code blocks may be registered by calling this method multiple times. The callbacks will be run sequentially in reverse order of registration, i.e. last registration is run first. Note that ActorSystem will not terminate until all the registered callbacks are finished.

      Throws a RejectedExecutionException if the System has already been terminated or if termination has been initiated.

    • terminate

      public abstract scala.concurrent.Future<Terminated> terminate()
      Terminates this actor system by running CoordinatedShutdown with reason CoordinatedShutdown.ActorSystemTerminateReason.

      If pekko.coordinated-shutdown.run-by-actor-system-terminate is configured to off it will not run CoordinatedShutdown, but the ActorSystem and its actors will still be terminated.

      This will stop the guardian actor, which in turn will recursively stop all its child actors, and finally the system guardian (below which the logging actors reside) and then execute all registered termination handlers (see registerOnTermination(scala.Function0<T>)). Be careful to not schedule any operations on completion of the returned future using the dispatcher of this actor system as it will have been shut down before the future completes.

    • whenTerminated

      public abstract scala.concurrent.Future<Terminated> whenTerminated()
      Returns a Future which will be completed after the ActorSystem has been terminated and termination hooks have been executed. If you registered any callback with registerOnTermination(scala.Function0<T>), the returned Future from this method will not complete until all the registered callbacks are finished. Be careful to not schedule any operations, such as onComplete, on the dispatchers (ExecutionContext) of this actor system as they will have been shut down before this future completes.

    • getWhenTerminated

      public abstract CompletionStage<Terminated> getWhenTerminated()
      Returns a CompletionStage which will be completed after the ActorSystem has been terminated and termination hooks have been executed. If you registered any callback with registerOnTermination(scala.Function0<T>), the returned CompletionStage from this method will not complete until all the registered callbacks are finished. Be careful to not schedule any operations, such as thenRunAsync, on the dispatchers (Executor) of this actor system as they will have been shut down before this CompletionStage completes.

    • registerExtension

      public abstract <T extends Extension> T registerExtension(ExtensionId<T> ext)
      Registers the provided extension and creates its payload, if this extension isn't already registered This method has putIfAbsent-semantics, this method can potentially block, waiting for the initialization of the payload, if is in the process of registration from another Thread of execution

    • extension

      public abstract <T extends Extension> T extension(ExtensionId<T> ext)
      Returns the payload that is associated with the provided extension throws an IllegalStateException if it is not registered. This method can potentially block, waiting for the initialization of the payload, if is in the process of registration from another Thread of execution

    • hasExtension

      public abstract boolean hasExtension(ExtensionId<? extends Extension> ext)
      Returns whether the specified extension is already registered, this method can potentially block, waiting for the initialization of the payload, if is in the process of registration from another Thread of execution