diff --git a/akka-docs/general/addressing.rst b/akka-docs/general/addressing.rst new file mode 100644 index 0000000000..708cc410fc --- /dev/null +++ b/akka-docs/general/addressing.rst @@ -0,0 +1,145 @@ +Actor References, Paths and Addresses +===================================== + +This chapter describes how actors are identified and located within a possibly +distributed actor system. It ties into the central idea that actor systems form +intrinsic supervision hierarchies as well as that communication between actors +is transparent with respect to their placement across multiple network nodes. + +What is an Actor Reference? +--------------------------- + +An actor reference is a subtype of :class:`ActorRef`, whose foremost purpose is +to support sending messages to the actor it represents. Each actor has access +to its canonical (local) reference through the :meth:`self` field; this +reference is also included as sender reference by default for all messages sent +to other actors. Conversely, during message processing the actor has access to +a reference representing the sender of the current message through the +:meth:`sender` field. + +There are several different types of actor references that are supported +depending on the configuration of the actor system: + +- Purely local actor references are used by actor systems which are not + configured to support networking functions. These actor references cannot + ever be sent across a network connection while retaining their functionality. +- Local actor references when remoting is enabled are used by actor systems + which support networking functions for those references which represent + actors within the same JVM. In order to be recognizable also when sent to + other network nodes, these references include protocol and remote addressing + information. +- Remote actor references represent actors which are reachable using remote + communication, i.e. sending messages to them will serialize the messages + transparently and send them to the other JVM. +- **(Future Extension)** Cluster actor references represent clustered actor + services which may be replicated, migrated or load-balanced across multiple + cluster nodes. As such they are virtual names which the cluster service + translates into local or remote actor references as appropriate. +- Unresolved actor references are obtained by querying an actor system and may + potentially represent one or more actors. + +How are Actor References obtained? +---------------------------------- + +An actor system is typically started by creating actors beneath the guardian +actor using the :meth:`ActorSystem.actorOf` method, which returns a reference +to the newly created actor. Each actor has direct access to references for its +parent, itself and its children. These references may be sent within messages +to other actors, enabling those to reply directly. + +Looking up Actors by Absolute Path +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In addition, actor references may be looked up using the +:meth:`ActorSystem.actorFor` method, which returns an unresolved actor +reference. Sending messages to such a reference will traverse the actor +hierarchy of the actor system from top to bottom by passing messages from +supervisor to child until either the target is reached or failure is certain +(i.e. a name in the path does not exist). Since this process takes time, +replies from the found actors—which include their sender reference—should be +used to replace them by direct actor references. + +Looking up Actors by Relative Path +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The third method for obtaining actor references is +:meth:`ActorContext.actorFor`, which is available inside any actor as +``context.actorFor``. This yields an unresolved actor reference much like its +twin on :class:`ActorSystem`, but instead of looking up the path starting from +the root of the actor tree it starts out on the current actor. Path elements +consisting of two dots (``".."``) may be used to access the parent actor and +other names are interpreted as globbing patterns. You can for example send a +message to all your siblings by using a path like ``"../*"`` (this will include +yourself). + +What is an Actor Path? +---------------------- + +Since actors are created in a strictly hierarchical fashion, there exists a +unique sequence of actor names given by following the tree of actors up until +the root of the actor system. This sequence can be seen as enclosing folders in +a file system, hence we adopted the name “path” to refer to it. + +Each actor path has an address component, describing the protocol and location +by which the corresponding actor is reachable, followed by the names of the +actors in the hierarchy from the root up. Examples are:: + + "jvm://my-system/app/service-a/worker1" + "akka://serv.example.com:5678/app/service-b" + +where the first represents a purely local actor reference while the second +stands for a remote actor reference. Each actor has access to its path, and you +may construct paths and pass them to :meth:`ActorSystem.actorFor` in order to +obtain a corresponding actor reference. + +One important aspect is that actor paths never span multiple actor systems or +JVMs. An actor path always represents the physical location of an actor. This +means that the supervision hierarchy and the path hierarchy of an actor may +diverge if one of its ancestors is remotely supervised. + +The Interplay with Remote Deployment +------------------------------------ + +When an actor creates a child, the actor system’s deployer will decide whether +the new actor resides in the same JVM or on another node. In the second case, +creation of the actor will be triggered via a network connection to happen in a +different JVM and consequently within a different actor system. The remote +system will place the new actor below a special path reserved for this purpose +and the supervisor of the new actor will be a remote actor reference +(representing that actor which triggered its creation). In this case, +:meth:`parent` (the supervisor reference) and :meth:`context.path.parent` (the +parent node in the actor’s path) do not represent the same actor. However, +looking up the child’s name within the supervisor will find it on the remote +node, preserving logical structure e.g. when sending to an unresolved actor +reference. + +What is the Address part used for? +---------------------------------- + +When sending an actor reference across the network, it is represented by its +path. Hence, the path must fully encode all information necessary to send +messages to the underlying actor. This is achieved by encoding protocol, host +and port in the address part of the path string. When an actor system receives +an actor path from a remote node, it checks whether that path’s address matches +the address of this actor system, in which case it will be resolved to the +actor’s local reference. Otherwise, it will be represented by a remote actor +reference. + +Special Paths used by Akka +-------------------------- + +At the root of the path hierarchy resides the root guardian above which all +other actors are found. The next level consists of the following: + +- ``"/app"`` is the guardian actor for all user-created top-level actors; + actors created using :meth:`ActorSystem.actorOf` are found at the next level. +- ``"/sys"`` is the guardian actor for all system-created top-level actors, + e.g. logging listeners or actors automatically deployed by configuration at + the start of the actor system. +- ``"/nul"`` is the dead letter actor, which is where all messages sent to + stopped or non-existing actors are re-routed. +- ``"/tmp"`` is the guardian for all short-lived system-created actors, e.g. + those which are used in the implementation of :meth:`ActorRef.ask`. +- ``"/remote"`` is an artificial path below which all actors reside whose + supervisors are remote actor references + diff --git a/akka-docs/general/index.rst b/akka-docs/general/index.rst index 83e9684bb4..687892b177 100644 --- a/akka-docs/general/index.rst +++ b/akka-docs/general/index.rst @@ -8,5 +8,6 @@ General configuration event-handler slf4j + addressing supervision guaranteed-delivery