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.