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

various documentation patches, found at the bottom of my inbox

Browse source
This commit is contained in:
Roland 2012-09-17 21:25:41 +02:00
parent cd4927dd04
commit 8a8b32d0eb
8 changed files with 109 additions and 21 deletions
Download patch file Download diff file Expand all files Collapse all files

2
akka-actor/src/main/scala/akka/actor/ActorCell.scala
View file

@ -502,7 +502,7 @@ private[akka] class ActorCell(
if (success) true
else {
val parent: Class[_] = clazz.getSuperclass
if (parent eq null) throw new IllegalActorStateException(toString + " is not an Actor since it have not mixed in the 'Actor' trait")
if (parent eq null) throw new IllegalActorStateException(actorInstance.getClass + " is not an Actor since it have not mixed in the 'Actor' trait")
lookupAndSetField(parent, actor, name, value)
}
}

5
akka-docs/_sphinx/themes/akka/layout.html
View file

@ -48,6 +48,7 @@
</div>
<ul class="nav">
<li><a href="http://akka.io/docs">Documentation</a></li>
<li><a href="http://akka.io/faq">FAQ</a></li>
<li><a href="http://akka.io/downloads">Download</a></li>
<li><a href="http://groups.google.com/group/akka-user">Mailing List</a></li>
<li><a href="http://github.com/akka/akka">Code</a></li>
@ -111,15 +112,17 @@
<ul>
<li><h5>Akka</h5></li>
<li><a href="http://akka.io/docs">Documentation</a></li>
<li><a href="http://akka.io/faq">FAQ</a></li>
<li><a href="http://akka.io/downloads">Downloads</a></li>
<li><a href="http://akka.io/news">News</a></li>
<li><a href="http://letitcrash.com">Blog</a></li>
</ul>
<ul>
<li><h5>Contribute</h5></li>
<li><a href="http://akka.io/community">Community Projects</a></li>
<li><a href="http://github.com/akka/akka">Source Code</a></li>
<li><a href="http://groups.google.com/group/akka-user">Mailing List</a></li>
<li><a href="http://www.assembla.com/spaces/akka/tickets">Report a Bug</a></li>
<li><a href="http://doc.akka.io/docs/akka/current/project/issue-tracking.html">Report a Bug</a></li>
</ul>
<ul>
<li><h5>Company</h5></li>

47
akka-docs/general/message-send-semantics.rst
View file

@ -66,4 +66,51 @@ This means that:
5) ``A2`` can see messages from ``A1`` interleaved with messages from ``A3``
6) Since there is no guaranteed delivery, none, some or all of the messages may arrive to ``A2``
.. _deadletters:
Dead Letters
============
Messages which cannot be delivered (and for which this can be ascertained) will
be delivered to a synthetic actor called ``/deadLetters``. This delivery
happens on a best-effort basis; it may fail even within the local JVM (e.g.
during actor termination). Messages sent via unreliable network transports will
be lost without turning up as dead letters.
How do I Receive Dead Letters?
------------------------------
An actor can subscribe to class :class:`akka.actor.DeadLetter` on the event
stream, see :ref:`event-stream-java` (Java) or :ref:`event-stream-scala`
(Scala) for how to do that. The subscribed actor will then receive all dead
letters published in the (local) system from that point onwards. Dead letters
are not propagated over the network, if you want to collect them in one place
you will have to subscribe one actor per network node and forward them
manually. Also consider that dead letters are generated at that node which can
determine that a send operation is failed, which for a remote send can be the
local system (if no network connection can be established) or the remote one
(if the actor you are sending to does not exist at that point in time).
What Should I Use Dead Letters For?
-----------------------------------
The dead letter service follows the same rules with respect to delivery
guarantees as all other message sends, hence it cannot be used to implement
guaranteed delivery. The main use is for debugging, especially if an actor send
does not arrive consistently (where usually inspecting the dead letters will
tell you that the sender or recipient was set wrong somewhere along the way).
Dead Letters Which are (Usually) not Worrisome
----------------------------------------------
Every time an actor does not terminate by its own decision, there is a chance
that some messages are lost which it sends to itself. There is one which may
happen in complex shutdown scenarios quite easily which is usually benign:
seeing a :class:`akka.dispatch.Terminate` message dropped means that two
termination requests were given, but of course only one can succeed. In the
same vein, you might see :class:`akka.actor.Terminated` messages from children
while stopping a hierarchy of actors turning up in dead letters if the parent
is still watching the child when the parent terminates.
.. _Erlang documentation: http://www.erlang.org/faq/academic.html

22
akka-docs/general/supervision.rst
View file

@ -141,17 +141,17 @@ re-processed.
The precise sequence of events during a restart is the following:
* suspend the actor
* call the old instance’s :meth:`supervisionStrategy.handleSupervisorFailing`
method (defaults to suspending all children)
* call the old instance’s :meth:`preRestart` hook (defaults to sending
termination requests to all children and calling :meth:`postStop`)
* wait for all children stopped during :meth:`preRestart` to actually terminate
* call the old instance’s :meth:`supervisionStrategy.handleSupervisorRestarted`
method (defaults to sending restart request to all remaining children)
* create new actor instance by invoking the originally provided factory again
* invoke :meth:`postRestart` on the new instance
* resume the actor
#. suspend the actor (which means that it will not process normal messages until
resumed), and recursively suspend all children
#. call the old instance’s :meth:`preRestart` hook (defaults to sending
termination requests to all children and calling :meth:`postStop`)
#. wait for all children which were requested to terminate (using
``context.stop()``) during :meth:`preRestart` to actually terminate
#. create new actor instance by invoking the originally provided factory again
#. invoke :meth:`postRestart` on the new instance
#. send restart request to all children (they will follow the same process
recursively, from step 2)
#. resume the actor
What Lifecycle Monitoring Means
-------------------------------

10
akka-docs/java/remoting.rst
View file

@ -116,6 +116,16 @@ As you can see from the example above the following pattern is used to find an `
object, which in most cases is not serializable. It is best to make a static
inner class which implements :class:`UntypedActorFactory`.
.. warning::
*Caveat:* Remote deployment ties both systems together in a tight fashion,
where it may become impossible to shut down one system after the other has
become unreachable. This is due to a missing feature—which will be part of
the clustering support—that hooks up network failure detection with
DeathWatch. If you want to avoid this strong coupling, do not remote-deploy
but send ``Props`` to a remotely looked-up actor and have that create a
child, returning the resulting actor reference.
Programmatic Remote Deployment
------------------------------

17
akka-docs/java/testing.rst
View file

@ -46,8 +46,8 @@ The tools offered are described in detail in the following sections.
Be sure to add the module :mod:`akka-testkit` to your dependencies.
Unit Testing with :class:`TestActorRef`
=======================================
Synchronous Unit Testing with :class:`TestActorRef`
===================================================
Testing the business logic inside :class:`Actor` classes can be divided into
two parts: first, each atomic operation must work in isolation, then sequences
@ -141,8 +141,8 @@ Feel free to experiment with the possibilities, and if you find useful
patterns, don't hesitate to let the Akka forums know about them! Who knows,
common operations might even be worked into nice DSLs.
Integration Testing with :class:`JavaTestKit`
=============================================
Asynchronous Integration Testing with :class:`JavaTestKit`
==========================================================
When you are reasonably sure that your actor's business logic is correct, the
next step is verifying that it works correctly within its intended environment.
@ -489,6 +489,15 @@ queued invocations from all threads into its own queue and process them.
Limitations
-----------
.. warning::
In case the CallingThreadDispatcher is used for top-level actors, but
without going through TestActorRef, then there is a time window during which
the actor is awaiting construction by the user guardian actor. Sending
messages to the actor during this time period will result in them being
enqueued and then executed on the guardian’s thread instead of the caller’s
thread. To avoid this, use TestActorRef.
If an actor's behavior blocks on a something which would normally be affected
by the calling actor after having sent the message, this will obviously
dead-lock when using this dispatcher. This is a common scenario in actor tests

10
akka-docs/scala/remoting.rst
View file

@ -125,6 +125,16 @@ actor systems has to have a JAR containing the class.
most cases is not serializable. It is best to create a factory method in the
companion object of the actor’s class.
.. warning::
*Caveat:* Remote deployment ties both systems together in a tight fashion,
where it may become impossible to shut down one system after the other has
become unreachable. This is due to a missing feature—which will be part of
the clustering support—that hooks up network failure detection with
DeathWatch. If you want to avoid this strong coupling, do not remote-deploy
but send ``Props`` to a remotely looked-up actor and have that create a
child, returning the resulting actor reference.
Programmatic Remote Deployment
------------------------------

17
akka-docs/scala/testing.rst
View file

@ -35,8 +35,8 @@ The tools offered are described in detail in the following sections.
Be sure to add the module :mod:`akka-testkit` to your dependencies.
Unit Testing with :class:`TestActorRef`
=======================================
Synchronous Unit Testing with :class:`TestActorRef`
===================================================
Testing the business logic inside :class:`Actor` classes can be divided into
two parts: first, each atomic operation must work in isolation, then sequences
@ -151,8 +151,8 @@ Feel free to experiment with the possibilities, and if you find useful
patterns, don't hesitate to let the Akka forums know about them! Who knows,
common operations might even be worked into nice DSLs.
Integration Testing with :class:`TestKit`
=========================================
Asynchronous Integration Testing with :class:`TestKit`
======================================================
When you are reasonably sure that your actor's business logic is correct, the
next step is verifying that it works correctly within its intended environment
@ -548,6 +548,15 @@ queued invocations from all threads into its own queue and process them.
Limitations
-----------
.. warning::
In case the CallingThreadDispatcher is used for top-level actors, but
without going through TestActorRef, then there is a time window during which
the actor is awaiting construction by the user guardian actor. Sending
messages to the actor during this time period will result in them being
enqueued and then executed on the guardian’s thread instead of the caller’s
thread. To avoid this, use TestActorRef.
If an actor's behavior blocks on a something which would normally be affected
by the calling actor after having sent the message, this will obviously
dead-lock when using this dispatcher. This is a common scenario in actor tests