Class ActorRef
- java.lang.Object
-
- org.apache.pekko.actor.ActorRef
-
- All Implemented Interfaces:
java.io.Serializable
,java.lang.Comparable<ActorRef>
- Direct Known Subclasses:
Nobody$
public abstract class ActorRef extends java.lang.Object implements java.lang.Comparable<ActorRef>, java.io.Serializable
Immutable and serializable handle to an actor, which may or may not reside on the local host or inside the samepekko.actor.ActorSystem
. An ActorRef can be obtained from anpekko.actor.ActorRefFactory
, an interface which is implemented by ActorSystem andpekko.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 apekko.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.
- See Also:
- Serialized Form
-
-
Constructor Summary
Constructors Constructor Description ActorRef()
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description abstract void
$bang(java.lang.Object message, ActorRef sender)
Scala API: Sends a one-way asynchronous message.ActorRef
$bang$default$2(java.lang.Object message)
int
compareTo(ActorRef other)
Comparison takes path and the unique id of the actor cell into account.boolean
equals(java.lang.Object that)
Equals takes path and the unique id of the actor cell into account.void
forward(java.lang.Object message, ActorContext context)
Forwards the message and passes the original sender actor as the sender.int
hashCode()
static ActorRef
noSender()
Use this value as an argument totell(java.lang.Object, org.apache.pekko.actor.ActorRef)
if there is not actor to reply to (e.g.abstract ActorPath
path()
Returns the path for this actor (from this actor up to the root actor).void
tell(java.lang.Object msg, ActorRef sender)
Sends the specified message to this ActorRef, i.e.java.lang.String
toString()
-
-
-
Method Detail
-
noSender
public static final ActorRef noSender()
Use this value as an argument totell(java.lang.Object, org.apache.pekko.actor.ActorRef)
if there is not actor to reply to (e.g. when sending from non-actor code).
-
path
public abstract ActorPath path()
Returns the path for this actor (from this actor up to the root actor).
-
compareTo
public final int compareTo(ActorRef other)
Comparison takes path and the unique id of the actor cell into account.- Specified by:
compareTo
in interfacejava.lang.Comparable<ActorRef>
-
tell
public final void tell(java.lang.Object msg, ActorRef sender)
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
-
$bang
public abstract void $bang(java.lang.Object message, ActorRef sender)
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
-
forward
public void forward(java.lang.Object message, ActorContext context)
Forwards the message and passes the original sender actor as the sender.Works, no matter whether originally sent with tell/'!' or ask/'?'.
-
hashCode
public final int hashCode()
- Overrides:
hashCode
in classjava.lang.Object
-
equals
public final boolean equals(java.lang.Object that)
Equals takes path and the unique id of the actor cell into account.- Overrides:
equals
in classjava.lang.Object
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
$bang$default$2
public ActorRef $bang$default$2(java.lang.Object message)
-
-