Packages

abstract class ActorRef extends Comparable[ActorRef] with Serializable

Immutable and serializable handle to an actor, which may or may not reside on the local host or inside the same pekko.actor.ActorSystem. An ActorRef can be obtained from an pekko.actor.ActorRefFactory, an interface which is implemented by ActorSystem and pekko.actor.ActorContext. This means actors can be created top-level in the ActorSystem or as children of an existing actor, but only from within that actor.

ActorRefs can be freely shared among actors by message passing. Message passing conversely is their only purpose, as demonstrated in the following examples:

Scala:

import org.apache.pekko.pattern.ask
import scala.concurrent.Await

class ExampleActor extends Actor {
  val other = context.actorOf(Props[OtherActor], "childName") // will be destroyed and re-created upon restart by default

  def receive {
    case Request1(msg) => other ! refine(msg)     // uses this actor as sender reference, reply goes to us
    case Request2(msg) => other.tell(msg, sender()) // forward sender reference, enabling direct reply
    case Request3(msg) =>
      implicit val timeout = Timeout(5.seconds)
      (other ? msg) pipeTo sender()
      // the ask call will get a future from other's reply
      // when the future is complete, send its value to the original sender
  }
}

Java:

import static org.apache.pekko.pattern.Patterns.ask;
import static org.apache.pekko.pattern.Patterns.pipe;

public class ExampleActor extends AbstractActor {
  // this child will be destroyed and re-created upon restart by default
  final ActorRef other = getContext().actorOf(Props.create(OtherActor.class), "childName");
  @Override
  public Receive createReceive() {
    return receiveBuilder()
      .match(Request1.class, msg ->
        // uses this actor as sender reference, reply goes to us
        other.tell(msg, getSelf()))
      .match(Request2.class, msg ->
        // forward sender reference, enabling direct reply
        other.tell(msg, getSender()))
      .match(Request3.class, msg ->
        // the ask call will get a future from other's reply
        // when the future is complete, send its value to the original sender
        pipe(ask(other, msg, 5000), context().dispatcher()).to(getSender()))
      .build();
  }
}

ActorRef does not have a method for terminating the actor it points to, use pekko.actor.ActorRefFactory.stop(ref), or send a pekko.actor.PoisonPill, for this purpose.

Two actor references are compared equal when they have the same path and point to the same actor incarnation. A reference pointing to a terminated actor doesn't compare equal to a reference pointing to another (re-created) actor with the same path.

If you need to keep track of actor references in a collection and do not care about the exact actor incarnation you can use the ActorPath as key because the unique id of the actor is not taken into account when comparing actor paths.

Self Type
InternalActorRef with ActorRefScope
Annotations
@nowarn()
Source
ActorRef.scala
Type Hierarchy
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. ActorRef
  2. Serializable
  3. Comparable
  4. AnyRef
  5. Any
Implicitly
  1. by actorRef2Scala
  2. by any2stringadd
  3. by StringFormat
  4. by Ensuring
  5. by ArrowAssoc
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. Protected

Instance Constructors

  1. new ActorRef()

Abstract Value Members

  1. abstract def !(message: Any)(implicit sender: ActorRef = Actor.noSender): Unit

    Scala API: Sends a one-way asynchronous message.

    Scala API: Sends a one-way asynchronous message. E.g. fire-and-forget semantics.

    If invoked from within an actor then the actor reference is implicitly passed on as the implicit 'sender' argument.

    This actor 'sender' reference is then available in the receiving actor in the 'sender()' member variable, if invoked from within an Actor. If not then no sender is available.

      actor ! message
    

  2. abstract def path: ActorPath

    Returns the path for this actor (from this actor up to the root actor).

Concrete Value Members

  1. final def !=(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  2. final def ##: Int
    Definition Classes
    AnyRef → Any
  3. def +(other: String): String
    Implicit
    This member is added by an implicit conversion from ActorRef toany2stringadd[ActorRef] performed by method any2stringadd in scala.Predef.
    Definition Classes
    any2stringadd
  4. def ->[B](y: B): (ActorRef, B)
    Implicit
    This member is added by an implicit conversion from ActorRef toArrowAssoc[ActorRef] performed by method ArrowAssoc in scala.Predef.
    Definition Classes
    ArrowAssoc
    Annotations
    @inline()
  5. final def ==(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  6. final def asInstanceOf[T0]: T0
    Definition Classes
    Any
  7. def clone(): AnyRef
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.CloneNotSupportedException]) @native() @HotSpotIntrinsicCandidate()
  8. final def compareTo(other: ActorRef): Int

    Comparison takes path and the unique id of the actor cell into account.

    Comparison takes path and the unique id of the actor cell into account.

    Definition Classes
    ActorRef → Comparable
  9. def ensuring(cond: (ActorRef) => Boolean, msg: => Any): ActorRef
    Implicit
    This member is added by an implicit conversion from ActorRef toEnsuring[ActorRef] performed by method Ensuring in scala.Predef.
    Definition Classes
    Ensuring
  10. def ensuring(cond: (ActorRef) => Boolean): ActorRef
    Implicit
    This member is added by an implicit conversion from ActorRef toEnsuring[ActorRef] performed by method Ensuring in scala.Predef.
    Definition Classes
    Ensuring
  11. def ensuring(cond: Boolean, msg: => Any): ActorRef
    Implicit
    This member is added by an implicit conversion from ActorRef toEnsuring[ActorRef] performed by method Ensuring in scala.Predef.
    Definition Classes
    Ensuring
  12. def ensuring(cond: Boolean): ActorRef
    Implicit
    This member is added by an implicit conversion from ActorRef toEnsuring[ActorRef] performed by method Ensuring in scala.Predef.
    Definition Classes
    Ensuring
  13. final def eq(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  14. final def equals(that: Any): Boolean

    Equals takes path and the unique id of the actor cell into account.

    Equals takes path and the unique id of the actor cell into account.

    Definition Classes
    ActorRef → AnyRef → Any
  15. def forward(message: Any)(implicit context: ActorContext): Unit

    Forwards the message and passes the original sender actor as the sender.

    Forwards the message and passes the original sender actor as the sender.

    Works, no matter whether originally sent with tell/'!' or ask/'?'.

  16. final def getClass(): Class[_ <: AnyRef]
    Definition Classes
    AnyRef → Any
    Annotations
    @native() @HotSpotIntrinsicCandidate()
  17. final def hashCode(): Int
    Definition Classes
    ActorRef → AnyRef → Any
  18. final def isInstanceOf[T0]: Boolean
    Definition Classes
    Any
  19. final def ne(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  20. final def notify(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native() @HotSpotIntrinsicCandidate()
  21. final def notifyAll(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native() @HotSpotIntrinsicCandidate()
  22. final def synchronized[T0](arg0: => T0): T0
    Definition Classes
    AnyRef
  23. final def tell(msg: Any, sender: ActorRef): Unit

    Sends the specified message to this ActorRef, i.e.

    Sends the specified message to this ActorRef, i.e. fire-and-forget semantics, including the sender reference if possible.

    Pass pekko.actor.ActorRef noSender or null as sender if there is nobody to reply to

  24. def toString(): String
    Definition Classes
    ActorRef → AnyRef → Any
  25. final def wait(arg0: Long, arg1: Int): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException])
  26. final def wait(arg0: Long): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException]) @native()
  27. final def wait(): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException])

Shadowed Implicit Value Members

  1. def !(message: Any)(implicit sender: ActorRef = Actor.noSender): Unit

    Sends a one-way asynchronous message.

    Sends a one-way asynchronous message. E.g. fire-and-forget semantics.

    If invoked from within an actor then the actor reference is implicitly passed on as the implicit 'sender' argument.

    This actor 'sender' reference is then available in the receiving actor in the 'sender()' member variable, if invoked from within an Actor. If not then no sender is available.

      actor ! message
    

    Implicit
    This member is added by an implicit conversion from ActorRef toScalaActorRef performed by method actorRef2Scala in org.apache.pekko.actor.
    Shadowing
    This implicitly inherited member is shadowed by one or more members in this class.
    To access this member you can use a type ascription:
    (actorRef: ScalaActorRef).!(message)(sender)
    Definition Classes
    ScalaActorRef

Deprecated Value Members

  1. def finalize(): Unit
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.Throwable]) @Deprecated @Deprecated
    Deprecated
  2. def formatted(fmtstr: String): String
    Implicit
    This member is added by an implicit conversion from ActorRef toStringFormat[ActorRef] performed by method StringFormat in scala.Predef.
    Definition Classes
    StringFormat
    Annotations
    @deprecated @inline()
    Deprecated

    (Since version 2.12.16) Use formatString.format(value) instead of value.formatted(formatString), or use the f"" string interpolator. In Java 15 and later, formatted resolves to the new method in String which has reversed parameters.

  3. def [B](y: B): (ActorRef, B)
    Implicit
    This member is added by an implicit conversion from ActorRef toArrowAssoc[ActorRef] performed by method ArrowAssoc in scala.Predef.
    Definition Classes
    ArrowAssoc
    Annotations
    @deprecated
    Deprecated

    (Since version 2.13.0) Use -> instead. If you still wish to display it as one character, consider using a font with programming ligatures such as Fira Code.

Inherited from Serializable

Inherited from Comparable[ActorRef]

Inherited from AnyRef

Inherited from Any

Inherited by implicit conversion actorRef2Scala fromActorRef to ScalaActorRef

Inherited by implicit conversion any2stringadd fromActorRef to any2stringadd[ActorRef]

Inherited by implicit conversion StringFormat fromActorRef to StringFormat[ActorRef]

Inherited by implicit conversion Ensuring fromActorRef to Ensuring[ActorRef]

Inherited by implicit conversion ArrowAssoc fromActorRef to ArrowAssoc[ActorRef]

Ungrouped