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
as key because
the unique id of the actor is not taken into account when comparing actor paths.
ActorPath
- Self Type
- InternalActorRef with ActorRefScope
- Annotations
- @nowarn()
- Source
- ActorRef.scala
- Alphabetic
- By Inheritance
- ActorRef
- Serializable
- Comparable
- AnyRef
- Any
- by actorRef2Scala
- by any2stringadd
- by StringFormat
- by Ensuring
- by ArrowAssoc
- Hide All
- Show All
- Public
- Protected
Instance Constructors
- new ActorRef()
Abstract Value Members
- 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
- abstract def path: ActorPath
Returns the path for this actor (from this actor up to the root actor).
Concrete Value Members
- final def !=(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
- final def ##: Int
- Definition Classes
- AnyRef → Any
- def +(other: String): String
- def ->[B](y: B): (ActorRef, B)
- final def ==(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
- final def asInstanceOf[T0]: T0
- Definition Classes
- Any
- def clone(): AnyRef
- Attributes
- protected[lang]
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.CloneNotSupportedException]) @native() @HotSpotIntrinsicCandidate()
- 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
- def ensuring(cond: (ActorRef) => Boolean, msg: => Any): ActorRef
- def ensuring(cond: (ActorRef) => Boolean): ActorRef
- def ensuring(cond: Boolean, msg: => Any): ActorRef
- def ensuring(cond: Boolean): ActorRef
- final def eq(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
- 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
- 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/'?'.
- final def getClass(): Class[_ <: AnyRef]
- Definition Classes
- AnyRef → Any
- Annotations
- @native() @HotSpotIntrinsicCandidate()
- final def hashCode(): Int
- Definition Classes
- ActorRef → AnyRef → Any
- final def isInstanceOf[T0]: Boolean
- Definition Classes
- Any
- final def ne(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
- final def notify(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native() @HotSpotIntrinsicCandidate()
- final def notifyAll(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native() @HotSpotIntrinsicCandidate()
- final def synchronized[T0](arg0: => T0): T0
- Definition Classes
- AnyRef
- 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
ornull
as sender if there is nobody to reply to - def toString(): String
- Definition Classes
- ActorRef → AnyRef → Any
- final def wait(arg0: Long, arg1: Int): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException])
- final def wait(arg0: Long): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException]) @native()
- final def wait(): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException])
Shadowed Implicit Value Members
- 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
- def finalize(): Unit
- Attributes
- protected[lang]
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.Throwable]) @Deprecated @Deprecated
- Deprecated
- 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 ofvalue.formatted(formatString)
, or use thef""
string interpolator. In Java 15 and later,formatted
resolves to the new method in String which has reversed parameters.
- 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.