public abstract class ActorRef extends java.lang.Object implements java.lang.Comparable<ActorRef>, scala.Serializable
ActorSystem. An ActorRef
can be obtained from an ActorRefFactory, an interface which
is implemented by ActorSystem and 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 akka.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 akka.pattern.Patterns.ask;
import static akka.pattern.Patterns.pipe;
public class ExampleActor extends UntypedActor {
// this child will be destroyed and re-created upon restart by default
final ActorRef other = getContext().actorOf(Props.create(OtherActor.class), "childName");
@Override
public void onReceive(Object o) {
if (o instanceof Request1) {
Msg msg = ((Request1) o).getMsg();
other.tell(msg, getSelf()); // uses this actor as sender reference, reply goes to us
} else if (o instanceof Request2) {
Msg msg = ((Request2) o).getMsg();
other.tell(msg, getSender()); // forward sender reference, enabling direct reply
} else if (o instanceof Request3) {
Msg msg = ((Request3) o).getMsg();
pipe(ask(other, msg, 5000), context().dispatcher()).to(getSender());
// the ask call will get a future from other's reply
// when the future is complete, send its value to the original sender
} else {
unhandled(o);
}
}
}
ActorRef does not have a method for terminating the actor it points to, use
ActorRefFactory.stop(ref), or send a 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.
| Constructor and Description |
|---|
ActorRef() |
| Modifier and Type | Method and Description |
|---|---|
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() |
abstract boolean |
isTerminated()
Deprecated.
Use context.watch(actor) and receive Terminated(actor). Since 2.2.
|
static ActorRef |
noSender()
Use this value as an argument to
tell(java.lang.Object, akka.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() |
public static final ActorRef noSender()
tell(java.lang.Object, akka.actor.ActorRef) if there is not actor to
reply to (e.g. when sending from non-actor code).public abstract ActorPath path()
public final int compareTo(ActorRef other)
compareTo in interface java.lang.Comparable<ActorRef>other - (undocumented)public final void tell(java.lang.Object msg,
ActorRef sender)
Pass ActorRef noSender or null as sender if there is nobody to reply to
msg - (undocumented)sender - (undocumented)public void forward(java.lang.Object message,
ActorContext context)
Works, no matter whether originally sent with tell/'!' or ask/'?'.
message - (undocumented)context - (undocumented)public abstract boolean isTerminated()
public final int hashCode()
hashCode in class java.lang.Objectpublic final boolean equals(java.lang.Object that)
equals in class java.lang.Objectthat - (undocumented)public java.lang.String toString()
toString in class java.lang.Object