Package org.apache.pekko.actor

Interface Actor

All Known Subinterfaces:
AbstractPersistentActorLike, AsyncWriteJournal, AsyncWriteProxy, AtLeastOnceDelivery, AtLeastOnceDeliveryLike, DiagnosticActorLogging, DistributedPubSubMediator.Internal$.TopicLike, Eventsourced, FSM<S,D>, LeveldbCompaction, LeveldbIdMapping, LeveldbStore, LoggingFSM<S,D>, LoggingPersistentFSM<S,D,E>, PersistenceStash, PersistentActor, PersistentFSM<S,D,E>, PersistentFSMBase<S,D,E>, SnapshotStore, Snapshotter, Stash, Timers, UnboundedStash, UnrestrictedStash
All Known Implementing Classes:
AbstractActor, AbstractActorWithStash, AbstractActorWithTimers, AbstractActorWithUnboundedStash, AbstractActorWithUnrestrictedStash, AbstractFSM, AbstractFSMWithStash, AbstractLoggingActor, AbstractLoggingFSM, AbstractPersistentActor, AbstractPersistentActorWithAtLeastOnceDelivery, AbstractPersistentActorWithTimers, AbstractPersistentFSM, AbstractPersistentFSMBase, AbstractPersistentLoggingFSM, ActorTransportAdapterManager, AsyncWriteJournal, AsyncWriteJournal.Resequencer, ClusterClient, ClusterReceptionist, ClusterReceptionist.Internal$.ClientResponseTunnel, ClusterSingletonManager, ClusterSingletonManager.Internal$.OldestChangedBuffer, ClusterSingletonProxy, DeadLetterListener, DefaultOSGiLogger, DistributedPubSubMediator, InetAddressDnsResolver, JournalPerfSpec.BenchActor, LmdbDurableStore, Logging.DefaultLogger, NoSnapshotStore, PersistencePluginProxy, PersistenceTestKitPlugin, PersistenceTestKitSnapshotPlugin, PersistentShardCoordinator, Player.Waiter, RemoveInternalClusterShardingData, ReplayMediator, Replicator, ShardCoordinator, SharedLeveldbStore, SimpleDnsManager, Slf4jLogger, SnapshotStore, TestActor, TestActors.BlackholeActor, TestActors.EchoActor, TestActors.ForwardActor, TestEventListener, UntypedAbstractActor, UntypedAbstractActorWithStash, UntypedAbstractActorWithTimers, UntypedAbstractActorWithUnboundedStash, UntypedAbstractActorWithUnrestrictedStash, UntypedAbstractLoggingActor
public interface Actor
Actor base trait that should be extended by or mixed to create an Actor with the semantics of the 'Actor Model': https://en.wikipedia.org/wiki/Actor_model

An actor has a well-defined (non-cyclic) life-cycle. - ''RUNNING'' (created and started actor) - can receive messages - ''SHUTDOWN'' (when 'stop' is invoked) - can't do anything

The Actor's own pekko.actor.ActorRef is available as self, the current message&rsquo;s sender as sender() and the pekko.actor.ActorContext as context. The only abstract method is receive which shall return the initial behavior of the actor as a partial function (behavior can be changed using context.become and context.unbecome).

This is the Scala API (hence the Scala code below), for the Java API see pekko.actor.AbstractActor. 


 class ExampleActor extends Actor {

   override val supervisorStrategy = OneForOneStrategy(maxNrOfRetries = 10, withinTimeRange = 1 minute) {
     case _: ArithmeticException      => Resume
     case _: NullPointerException     => Restart
     case _: IllegalArgumentException => Stop
     case _: Exception                => Escalate
   }

   def receive = {
                                      // directly calculated reply
     case Request(r)               => sender() ! calculate(r)

                                      // just to demonstrate how to stop yourself
     case Shutdown                 => context.stop(self)

                                      // error kernel with child replying directly to 'sender()'
     case Dangerous(r)             => context.actorOf(Props[ReplyToOriginWorker]).tell(PerformWork(r), sender())

                                      // error kernel with reply going through us
     case OtherJob(r)              => context.actorOf(Props[ReplyToMeWorker]) ! JobRequest(r, sender())
     case JobReply(result, orig_s) => orig_s ! result
   }
 }

The last line demonstrates the essence of the error kernel design: spawn one-off actors which terminate after doing their job, pass on sender() to allow direct reply if that is what makes sense, or round-trip the sender as shown with the fictitious JobRequest/JobReply message pair.

If you don&rsquo;t like writing context you can always import context._ to get direct access to actorOf, stop etc. This is not default in order to keep the name-space clean.

  • Method Details

    • org$apache$pekko$actor$Actor$_setter_$context_$eq

      void org$apache$pekko$actor$Actor$_setter_$context_$eq(ActorContext x$1)
      Scala API: Stores the context for this actor, including self, and sender. It is implicit to support operations such as forward.

      WARNING: Only valid within the Actor itself, so do not close over it and publish it to other threads!

      pekko.actor.ActorContext is the Scala API. getContext returns a pekko.actor.AbstractActor.ActorContext, which is the Java API of the actor context.

    • org$apache$pekko$actor$Actor$_setter_$self_$eq

      void org$apache$pekko$actor$Actor$_setter_$self_$eq(ActorRef x$1)
      The 'self' field holds the ActorRef for this actor.

      Can be used to send messages to itself: 
       self ! message

    • context

      ActorContext context()
      Scala API: Stores the context for this actor, including self, and sender. It is implicit to support operations such as forward.

      WARNING: Only valid within the Actor itself, so do not close over it and publish it to other threads!

      pekko.actor.ActorContext is the Scala API. getContext returns a pekko.actor.AbstractActor.ActorContext, which is the Java API of the actor context.

    • self

      ActorRef self()
      The 'self' field holds the ActorRef for this actor.

      Can be used to send messages to itself: 
       self ! message

    • sender

      ActorRef sender()
      The reference sender Actor of the last received message. Is defined if the message was sent from another Actor, else deadLetters in pekko.actor.ActorSystem.

      WARNING: Only valid within the Actor itself, so do not close over it and publish it to other threads!

    • receive

      scala.PartialFunction<Object,scala.runtime.BoxedUnit> receive()
      Scala API: This defines the initial actor behavior, it must return a partial function with the actor logic.

    • aroundReceive

      void aroundReceive(scala.PartialFunction<Object,scala.runtime.BoxedUnit> receive, Object msg)
      INTERNAL API.

      Can be overridden to intercept calls to this actor's current behavior.

      Parameters:
      receive - current behavior.
      msg - current message.

    • aroundPreStart

      void aroundPreStart()
      INTERNAL API.

      Can be overridden to intercept calls to preStart. Calls preStart by default.

    • aroundPostStop

      void aroundPostStop()
      INTERNAL API.

      Can be overridden to intercept calls to postStop. Calls postStop by default.

    • aroundPreRestart

      void aroundPreRestart(Throwable reason, scala.Option<Object> message)
      INTERNAL API.

      Can be overridden to intercept calls to preRestart. Calls preRestart by default.

    • aroundPostRestart

      void aroundPostRestart(Throwable reason)
      INTERNAL API.

      Can be overridden to intercept calls to postRestart. Calls postRestart by default.

    • supervisorStrategy

      SupervisorStrategy supervisorStrategy()
      User overridable definition the strategy to use for supervising child actors.

    • preStart

      void preStart() throws Exception
      User overridable callback.

      Is called when an Actor is started. Actors are automatically started asynchronously when created. Empty default implementation.
      Throws:
      Exception

    • postStop

      void postStop() throws Exception
      User overridable callback.

      Is called asynchronously after 'actor.stop()' is invoked. Empty default implementation.
      Throws:
      Exception

    • preRestart

      void preRestart(Throwable reason, scala.Option<Object> message) throws Exception
      Scala API: User overridable callback: '''By default it disposes of all children and then calls postStop().'''
      Parameters:
      reason - the Throwable that caused the restart to happen
      message - optionally the current message the actor processed when failing, if applicable

      Is called on a crashed Actor right BEFORE it is restarted to allow clean up of resources before Actor is terminated.
      Throws:
      Exception

    • postRestart

      void postRestart(Throwable reason) throws Exception
      User overridable callback: By default it calls preStart().
      Parameters:
      reason - the Throwable that caused the restart to happen

      Is called right AFTER restart on the newly created Actor to allow reinitialization after an Actor crash.
      Throws:
      Exception

    • unhandled

      void unhandled(Object message)
      User overridable callback.

      Is called when a message isn't handled by the current behavior of the actor by default it fails with either a pekko.actor.DeathPactException (in case of an unhandled pekko.actor.Terminated message) or publishes an pekko.actor.UnhandledMessage to the actor's system's pekko.event.EventStream