raboof/pekko
1
0
Fork 0
Code Issues Pull requests Projects Releases 6 Packages Wiki Activity Actions 11

DOC: fixed minor path err

Browse source
This commit is contained in:
Patrik Nordwall 2012-01-18 10:10:42 +01:00
parent a1e42f659c
commit 1b4983f865
1 changed files with 122 additions and 122 deletions
Download patch file Download diff file Expand all files Collapse all files

244
akka-docs/general/addressing.rst
View file

@ -21,68 +21,68 @@ within an actor system, please read on for the details.
What is an Actor Reference? What is an Actor Reference?
--------------------------- ---------------------------
An actor reference is a subtype of :class:`ActorRef`, whose foremost purpose is 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 support sending messages to the actor it represents. Each actor has access
to its canonical (local) reference through the :meth:`self` field; this to its canonical (local) reference through the :meth:`self` field; this
reference is also included as sender reference by default for all messages sent 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 to other actors. Conversely, during message processing the actor has access to
a reference representing the sender of the current message through the a reference representing the sender of the current message through the
:meth:`sender` field. :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: depending on the configuration of the actor system:
- Purely local actor references are used by actor systems which are not - Purely local actor references are used by actor systems which are not
configured to support networking functions. These actor references cannot configured to support networking functions. These actor references cannot
ever be sent across a network connection while retaining their functionality. ever be sent across a network connection while retaining their functionality.
- Local actor references when remoting is enabled are used by actor systems - Local actor references when remoting is enabled are used by actor systems
which support networking functions for those references which represent which support networking functions for those references which represent
actors within the same JVM. In order to be recognizable also when sent to actors within the same JVM. In order to be recognizable also when sent to
other network nodes, these references include protocol and remote addressing other network nodes, these references include protocol and remote addressing
information. information.
- There is a subtype of local actor references which is used for routers (i.e. - 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 actors mixing in the :class:`Router` trait). Its logical structure is the
same as for the aforementioned local references, but sending a message to same as for the aforementioned local references, but sending a message to
them dispatches to one of their children directly instead. them dispatches to one of their children directly instead.
- Remote actor references represent actors which are reachable using remote - Remote actor references represent actors which are reachable using remote
communication, i.e. sending messages to them will serialize the messages communication, i.e. sending messages to them will serialize the messages
transparently and send them to the other JVM. 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: actor references for all practical purposes:
- :class:`AskActorRef` is the special representation of a :meth:`Promise` for - :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 the purpose of being completed by the response from an actor; it is created
by the :meth:`ActorRef.ask` invocation. 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 letters service, where all messages are re-routed whose routees are shut
down or non-existent. 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: never really see:
- There is an actor reference which does not represent an actor but acts only - 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 as a pseudo-supervisor for the root guardian, we call it “the one who walks
the bubbles of space-time”. the bubbles of space-time”.
- The first logging service started before actually firing up actor creation - The first logging service started before actually firing up actor creation
facilities is a fake actor reference which accepts log events and prints facilities is a fake actor reference which accepts log events and prints
them directly to standard output; it is :class:`Logging.StandardOutLogger`. them directly to standard output; it is :class:`Logging.StandardOutLogger`.
- **(Future Extension)** Cluster actor references represent clustered actor - **(Future Extension)** Cluster actor references represent clustered actor
services which may be replicated, migrated or load-balanced across multiple services which may be replicated, migrated or load-balanced across multiple
cluster nodes. As such they are virtual names which the cluster service cluster nodes. As such they are virtual names which the cluster service
translates into local or remote actor references as appropriate. translates into local or remote actor references as appropriate.
What is an Actor Path? What is an Actor Path?
---------------------- ----------------------
Since actors are created in a strictly hierarchical fashion, there exists a Since actors are created in a strictly hierarchical fashion, there exists a
unique sequence of actor names given by recursively following the supervision 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 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 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 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, “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 where all but one involve some translation which decouples part of the path
from the actor’s actual supervision ancestor line; these specialities are from the actor’s actual supervision ancestor line; these specialities are
described in the sub-sections to follow. described in the sub-sections to follow.
An actor path consists of an anchor, which identifies the actor system, An actor path consists of an anchor, which identifies the actor system,
@ -93,80 +93,80 @@ are separated by slashes.
Actor Path Anchors Actor Path Anchors
^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^
Each actor path has an address component, describing the protocol and location 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 by which the corresponding actor is reachable, followed by the names of the
actors in the hierarchy from the root up. Examples are:: actors in the hierarchy from the root up. Examples are::
"akka://my-system/app/service-a/worker1" // purely local "akka://my-system/user/service-a/worker1" // purely local
"akka://my-system@serv.example.com:5678/app/service-b" // local or remote "akka://my-system@serv.example.com:5678/user/service-b" // local or remote
"cluster://my-cluster/service-c" // clustered (Future Extension) "cluster://my-cluster/service-c" // clustered (Future Extension)
Here, ``akka`` is the default remote protocol for the 2.0 release, and others 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. are pluggable. The interpretation of the host & port part (i.e.
``serv.example.com:5678`` in the example) depends on the transport mechanism ``serv.example.com:5678`` in the example) depends on the transport mechanism
used, but it must abide by the URI structural rules. used, but it must abide by the URI structural rules.
Logical Actor Paths Logical Actor Paths
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
The unique path obtained by following the parental supervision links towards 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 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 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 actor system’s remoting configuration (and with it the address component of
the path) is set. the path) is set.
Physical Actor Paths Physical Actor Paths
^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^
While the logical actor path describes the functional location within one actor While the logical actor path describes the functional location within one actor
system, configuration-based remote deployment means that an actor may be 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 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 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 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 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 system where the actual actor object resides. Using this path as sender
reference when querying other actors will let them reply directly to this reference when querying other actors will let them reply directly to this
actor, minimizing delays incurred by routing. actor, minimizing delays incurred by routing.
One important aspect is that a physical actor path never spans multiple actor 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 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 the physical path (actor deployment) of an actor may diverge if one of its
ancestors is remotely supervised. ancestors is remotely supervised.
Virtual Actor Paths **(Future Extension)** Virtual Actor Paths **(Future Extension)**
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In order to be able to replicate and migrate actors across a cluster of Akka 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 nodes, another level of indirection has to be introduced. The cluster component
therefore provides a translation from virtual paths to physical paths which may therefore provides a translation from virtual paths to physical paths which may
change in reaction to node failures, cluster rebalancing, etc. 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.* for the 2.1 release.*
How are Actor References obtained? How are Actor References obtained?
---------------------------------- ----------------------------------
There are two general categories to how actor references may be obtained: by 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 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 the two flavours of creating actor references from concrete actor paths and
querying the logical actor hierarchy. querying the logical actor hierarchy.
*While local and remote actor references and their paths work in the same way *While local and remote actor references and their paths work in the same way
concerning the facilities mentioned below, the exact semantics of clustered concerning the facilities mentioned below, the exact semantics of clustered
actor references and their paths—while certainly as similar as possible—may 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 differ in certain aspects, owing to the virtual nature of those paths. Expect
updates for the 2.1 release.* updates for the 2.1 release.*
Creating Actors Creating Actors
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
An actor system is typically started by creating actors above the guardian An actor system is typically started by creating actors above the guardian
actor using the :meth:`ActorSystem.actorOf` method and then using actor using the :meth:`ActorSystem.actorOf` method and then using
:meth:`ActorContext.actorOf` from within the created actors to spawn the actor :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 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 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 references may be sent within messages to other actors, enabling those to reply
directly. directly.
Looking up Actors by Concrete Path Looking up Actors by Concrete Path
@ -187,12 +187,12 @@ is not visible to client code.
Absolute vs. Relative Paths Absolute vs. Relative Paths
``````````````````````````` ```````````````````````````
In addition to :meth:`ActorSystem.actorFor` there is also In addition to :meth:`ActorSystem.actorFor` there is also
:meth:`ActorContext.actorFor`, which is available inside any actor as :meth:`ActorContext.actorFor`, which is available inside any actor as
``context.actorFor``. This yields an actor reference much like its twin on ``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 :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 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 of two dots (``".."``) may be used to access the parent actor. You can for
example send a message to a specific sibling:: example send a message to a specific sibling::
context.actorFor("../brother") ! msg context.actorFor("../brother") ! msg
@ -208,25 +208,25 @@ will work as expected.
Querying the Logical Actor Hierarchy Querying the Logical Actor Hierarchy
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Since the actor system forms a file-system like hierarchy, matching on paths is 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 possible in the same was as supported by Unix shells: you may replace (parts
of) path element names with wildcards (`«*»` and `«?»`) to formulate a of) path element names with wildcards (`«*»` and `«?»`) to formulate a
selection which may match zero or more actual actors. Because the result is not 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 a single actor reference, it has a different type :class:`ActorSelection` and
does not support the full set of operations an :class:`ActorRef` does. does not support the full set of operations an :class:`ActorRef` does.
Selections may be formulated using the :meth:`ActorSystem.actorSelection` and Selections may be formulated using the :meth:`ActorSystem.actorSelection` and
:meth:`ActorContext.actorSelection` methods and do support sending messages:: :meth:`ActorContext.actorSelection` methods and do support sending messages::
context.actorSelection("../*") ! msg context.actorSelection("../*") ! msg
will send `msg` to all siblings including the current actor. As for references 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 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 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, 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 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, that, resolve the uncertainty by sending a request and gathering all answers,
extracting the sender references, and then watch all discovered concrete extracting the sender references, and then watch all discovered concrete
actors. This scheme of resolving a selection may be improved upon in a future actors. This scheme of resolving a selection may be improved upon in a future
release. release.
.. _actorOf-vs-actorFor: .. _actorOf-vs-actorFor:
@ -269,50 +269,50 @@ The Interplay with Clustering **(Future Extension)**
*This section is subject to change!* *This section is subject to change!*
When creating a scaled-out actor subtree, a cluster name is created for a 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 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 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 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 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 paths will be used as ``self`` references for these instances. In the case
of replication for achieving fault-tolerance the opposite is required: the of replication for achieving fault-tolerance the opposite is required: the
``self`` reference will be a virtual (cluster) path so that in case of ``self`` reference will be a virtual (cluster) path so that in case of
migration or fail-over communication is resumed with the fresh instance. migration or fail-over communication is resumed with the fresh instance.
What is the Address part used for? What is the Address part used for?
---------------------------------- ----------------------------------
When sending an actor reference across the network, it is represented by its 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 path. Hence, the path must fully encode all information necessary to send
messages to the underlying actor. This is achieved by encoding protocol, host 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 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 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 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 actor’s local reference. Otherwise, it will be represented by a remote actor
reference. reference.
Special Paths used by Akka 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: 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. actors created using :meth:`ActorSystem.actorOf` are found at the next level.
- ``"/system"`` is the guardian actor for all system-created top-level actors, - ``"/system"`` is the guardian actor for all system-created top-level actors,
e.g. logging listeners or actors automatically deployed by configuration at e.g. logging listeners or actors automatically deployed by configuration at
the start of the actor system. 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. 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`. 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 supervisors are remote actor references
Future extensions: Future extensions:
- ``"/service"`` is an artificial path below which actors can be presented by - ``"/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 means of configuration, i.e. deployed at system start-up or just-in-time
(triggered by look-up) (triggered by look-up)
- ``"/alias"`` is an artificial path below which other actors may be “mounted” - ``"/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 (as in the Unix file-system sense) by path—local or remote—to give them