diff --git a/akka-docs/general/addressing.rst b/akka-docs/general/addressing.rst index cc87da61f3..86c22fdaea 100644 --- a/akka-docs/general/addressing.rst +++ b/akka-docs/general/addressing.rst @@ -21,68 +21,68 @@ within an actor system, please read on for the details. 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 +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 +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 +- 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 +- 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. -- There is a subtype of local actor references which is used for routers (i.e. - actors mixing in the :class:`Router` trait). Its logical structure is the - same as for the aforementioned local references, but sending a message to +- There is a subtype of local actor references which is used for routers (i.e. + actors mixing in the :class:`Router` trait). Its logical structure is the + same as for the aforementioned local references, but sending a message to them dispatches to one of their children directly instead. -- Remote actor references represent actors which are reachable using remote - communication, i.e. sending messages to them will serialize the messages +- 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. -- There are several special types of actor references which behave like local +- There are several special types of actor references which behave like local actor references for all practical purposes: - - :class:`AskActorRef` is the special representation of a :meth:`Promise` for - the purpose of being completed by the response from an actor; it is created + - :class:`AskActorRef` is the special representation of a :meth:`Promise` for + the purpose of being completed by the response from an actor; it is created by the :meth:`ActorRef.ask` invocation. - - :class:`DeadLetterActorRef` is the default implementation of the dead + - :class:`DeadLetterActorRef` is the default implementation of the dead letters service, where all messages are re-routed whose routees are shut down or non-existent. -- And then there are some one-off internal implementations which you should +- And then there are some one-off internal implementations which you should never really see: - - There is an actor reference which does not represent an actor but acts only - as a pseudo-supervisor for the root guardian, we call it “the one who walks + - There is an actor reference which does not represent an actor but acts only + as a pseudo-supervisor for the root guardian, we call it “the one who walks the bubbles of space-time”. - - The first logging service started before actually firing up actor creation - facilities is a fake actor reference which accepts log events and prints + - The first logging service started before actually firing up actor creation + facilities is a fake actor reference which accepts log events and prints them directly to standard output; it is :class:`Logging.StandardOutLogger`. -- **(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 +- **(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. What is an Actor Path? ---------------------- -Since actors are created in a strictly hierarchical fashion, there exists a -unique sequence of actor names given by recursively following the supervision -links between child and parent down towards 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. As in some real file-systems there also are -“symbolic links”, i.e. one actor may be reachable using more than one path, -where all but one involve some translation which decouples part of the path -from the actor’s actual supervision ancestor line; these specialities are +Since actors are created in a strictly hierarchical fashion, there exists a +unique sequence of actor names given by recursively following the supervision +links between child and parent down towards 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. As in some real file-systems there also are +“symbolic links”, i.e. one actor may be reachable using more than one path, +where all but one involve some translation which decouples part of the path +from the actor’s actual supervision ancestor line; these specialities are described in the sub-sections to follow. An actor path consists of an anchor, which identifies the actor system, @@ -93,80 +93,80 @@ are separated by slashes. Actor Path Anchors ^^^^^^^^^^^^^^^^^^ -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 +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:: - "akka://my-system/app/service-a/worker1" // purely local - "akka://my-system@serv.example.com:5678/app/service-b" // local or remote + "akka://my-system/user/service-a/worker1" // purely local + "akka://my-system@serv.example.com:5678/user/service-b" // local or remote "cluster://my-cluster/service-c" // clustered (Future Extension) -Here, ``akka`` is the default remote protocol for the 2.0 release, and others -are pluggable. The interpretation of the host & port part (i.e. -``serv.example.com:5678`` in the example) depends on the transport mechanism +Here, ``akka`` is the default remote protocol for the 2.0 release, and others +are pluggable. The interpretation of the host & port part (i.e. +``serv.example.com:5678`` in the example) depends on the transport mechanism used, but it must abide by the URI structural rules. Logical Actor Paths ^^^^^^^^^^^^^^^^^^^ -The unique path obtained by following the parental supervision links towards -the root guardian is called the logical actor path. This path matches exactly -the creation ancestry of an actor, so it is completely deterministic as soon as -the actor system’s remoting configuration (and with it the address component of +The unique path obtained by following the parental supervision links towards +the root guardian is called the logical actor path. This path matches exactly +the creation ancestry of an actor, so it is completely deterministic as soon as +the actor system’s remoting configuration (and with it the address component of the path) is set. Physical Actor Paths ^^^^^^^^^^^^^^^^^^^^ -While the logical actor path describes the functional location within one actor -system, configuration-based remote deployment means that an actor may be -created on a different network host as its parent, i.e. within a different -actor system. In this case, following the actor path from the root guardian up -entails traversing the network, which is a costly operation. Therefore, each -actor also has a physical path, starting at the root guardian of the actor -system where the actual actor object resides. Using this path as sender -reference when querying other actors will let them reply directly to this +While the logical actor path describes the functional location within one actor +system, configuration-based remote deployment means that an actor may be +created on a different network host as its parent, i.e. within a different +actor system. In this case, following the actor path from the root guardian up +entails traversing the network, which is a costly operation. Therefore, each +actor also has a physical path, starting at the root guardian of the actor +system where the actual actor object resides. Using this path as sender +reference when querying other actors will let them reply directly to this actor, minimizing delays incurred by routing. -One important aspect is that a physical actor path never spans multiple actor -systems or JVMs. This means that the logical path (supervision hierarchy) and -the physical path (actor deployment) of an actor may diverge if one of its +One important aspect is that a physical actor path never spans multiple actor +systems or JVMs. This means that the logical path (supervision hierarchy) and +the physical path (actor deployment) of an actor may diverge if one of its ancestors is remotely supervised. Virtual Actor Paths **(Future Extension)** ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -In order to be able to replicate and migrate actors across a cluster of Akka -nodes, another level of indirection has to be introduced. The cluster component -therefore provides a translation from virtual paths to physical paths which may +In order to be able to replicate and migrate actors across a cluster of Akka +nodes, another level of indirection has to be introduced. The cluster component +therefore provides a translation from virtual paths to physical paths which may change in reaction to node failures, cluster rebalancing, etc. -*This area is still under active development, expect updates in this section +*This area is still under active development, expect updates in this section for the 2.1 release.* How are Actor References obtained? ---------------------------------- -There are two general categories to how actor references may be obtained: by -creating actors or by looking them up, where the latter functionality comes in -the two flavours of creating actor references from concrete actor paths and +There are two general categories to how actor references may be obtained: by +creating actors or by looking them up, where the latter functionality comes in +the two flavours of creating actor references from concrete actor paths and querying the logical actor hierarchy. -*While local and remote actor references and their paths work in the same way -concerning the facilities mentioned below, the exact semantics of clustered -actor references and their paths—while certainly as similar as possible—may -differ in certain aspects, owing to the virtual nature of those paths. Expect +*While local and remote actor references and their paths work in the same way +concerning the facilities mentioned below, the exact semantics of clustered +actor references and their paths—while certainly as similar as possible—may +differ in certain aspects, owing to the virtual nature of those paths. Expect updates for the 2.1 release.* Creating Actors ^^^^^^^^^^^^^^^ -An actor system is typically started by creating actors above the guardian -actor using the :meth:`ActorSystem.actorOf` method and then using -:meth:`ActorContext.actorOf` from within the created actors to spawn the actor -tree. These methods return 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 +An actor system is typically started by creating actors above the guardian +actor using the :meth:`ActorSystem.actorOf` method and then using +:meth:`ActorContext.actorOf` from within the created actors to spawn the actor +tree. These methods return 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 Concrete Path @@ -187,12 +187,12 @@ is not visible to client code. Absolute vs. Relative Paths ``````````````````````````` -In addition to :meth:`ActorSystem.actorFor` there is also -:meth:`ActorContext.actorFor`, which is available inside any actor as -``context.actorFor``. This yields an 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. You can for +In addition to :meth:`ActorSystem.actorFor` there is also +:meth:`ActorContext.actorFor`, which is available inside any actor as +``context.actorFor``. This yields an 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. You can for example send a message to a specific sibling:: context.actorFor("../brother") ! msg @@ -208,25 +208,25 @@ will work as expected. Querying the Logical Actor Hierarchy ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Since the actor system forms a file-system like hierarchy, matching on paths is -possible in the same was as supported by Unix shells: you may replace (parts -of) path element names with wildcards (`«*»` and `«?»`) to formulate a -selection which may match zero or more actual actors. Because the result is not -a single actor reference, it has a different type :class:`ActorSelection` and -does not support the full set of operations an :class:`ActorRef` does. -Selections may be formulated using the :meth:`ActorSystem.actorSelection` and +Since the actor system forms a file-system like hierarchy, matching on paths is +possible in the same was as supported by Unix shells: you may replace (parts +of) path element names with wildcards (`«*»` and `«?»`) to formulate a +selection which may match zero or more actual actors. Because the result is not +a single actor reference, it has a different type :class:`ActorSelection` and +does not support the full set of operations an :class:`ActorRef` does. +Selections may be formulated using the :meth:`ActorSystem.actorSelection` and :meth:`ActorContext.actorSelection` methods and do support sending messages:: context.actorSelection("../*") ! msg -will send `msg` to all siblings including the current actor. As for references -obtained using `actorFor`, a traversal of the supervision hierarchy is done in -order to perform the message send. As the exact set of actors which match a -selection may change even while a message is making its way to the recipients, -it is not possible to watch a selection for liveliness changes. In order to do -that, resolve the uncertainty by sending a request and gathering all answers, -extracting the sender references, and then watch all discovered concrete -actors. This scheme of resolving a selection may be improved upon in a future +will send `msg` to all siblings including the current actor. As for references +obtained using `actorFor`, a traversal of the supervision hierarchy is done in +order to perform the message send. As the exact set of actors which match a +selection may change even while a message is making its way to the recipients, +it is not possible to watch a selection for liveliness changes. In order to do +that, resolve the uncertainty by sending a request and gathering all answers, +extracting the sender references, and then watch all discovered concrete +actors. This scheme of resolving a selection may be improved upon in a future release. .. _actorOf-vs-actorFor: @@ -269,50 +269,50 @@ The Interplay with Clustering **(Future Extension)** *This section is subject to change!* -When creating a scaled-out actor subtree, a cluster name is created for a -routed actor reference, where sending to this reference will send to one (or -more) of the actual actors created in the cluster. In order for those actors to -be able to query other actors while processing their messages, their sender -reference must be unique for each of the replicas, which means that physical -paths will be used as ``self`` references for these instances. In the case -of replication for achieving fault-tolerance the opposite is required: the -``self`` reference will be a virtual (cluster) path so that in case of +When creating a scaled-out actor subtree, a cluster name is created for a +routed actor reference, where sending to this reference will send to one (or +more) of the actual actors created in the cluster. In order for those actors to +be able to query other actors while processing their messages, their sender +reference must be unique for each of the replicas, which means that physical +paths will be used as ``self`` references for these instances. In the case +of replication for achieving fault-tolerance the opposite is required: the +``self`` reference will be a virtual (cluster) path so that in case of migration or fail-over communication is resumed with the fresh instance. 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 +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 +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: -- ``"/user"`` is the guardian actor for all user-created top-level actors; +- ``"/user"`` is the guardian actor for all user-created top-level actors; actors created using :meth:`ActorSystem.actorOf` are found at the next level. -- ``"/system"`` is the guardian actor for all system-created top-level actors, - e.g. logging listeners or actors automatically deployed by configuration at +- ``"/system"`` 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. -- ``"/deadLetters"`` is the dead letter actor, which is where all messages sent to +- ``"/deadLetters"`` is the dead letter actor, which is where all messages sent to stopped or non-existing actors are re-routed. -- ``"/temp"`` is the guardian for all short-lived system-created actors, e.g. +- ``"/temp"`` 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 +- ``"/remote"`` is an artificial path below which all actors reside whose supervisors are remote actor references Future extensions: -- ``"/service"`` is an artificial path below which actors can be presented by - means of configuration, i.e. deployed at system start-up or just-in-time +- ``"/service"`` is an artificial path below which actors can be presented by + means of configuration, i.e. deployed at system start-up or just-in-time (triggered by look-up) - ``"/alias"`` is an artificial path below which other actors may be “mounted” (as in the Unix file-system sense) by path—local or remote—to give them