Merge pull request #742 from akka/wip-2411-describe-ActorDSL-∂π

Wip 2411 describe actor dsl ∂π

akka-docs/rst/scala/actors.rst

@@ -153,6 +153,64 @@ When spawning actors for specific sub-tasks from within an actor, it may be conv
   there is not yet a way to detect these illegal accesses at compile time.
   See also: :ref:`jmm-shared-state`
 
+The Actor DSL
+-------------
+
+Simple actors—for example one-off workers or even when trying things out in the
+REPL—can be created more concisely using the :class:`Act` trait. The supporting
+infrastructure is bundled in the following import:
+
+.. includecode:: ../../../akka-actor-tests/src/test/scala/akka/actor/ActorDSLSpec.scala#import
+
+This import is assumed for all code samples throughout this section. To define
+a simple actor, the following is sufficient:
+
+.. includecode:: ../../../akka-actor-tests/src/test/scala/akka/actor/ActorDSLSpec.scala#simple-actor
+
+Here, :meth:`actor` takes the role of either ``system.actorOf`` or
+``context.actorOf``, depending on which context it is called in: it takes an
+implicit :class:`ActorRefFactory`, which within an actor is available in the
+form of the ``implicit val context: ActorContext``. Outside of an actor, you’ll
+have to either declare an implicit :class:`ActorSystem`, or you can give the
+factory explicitly (see further below).
+
+Life-cycle hooks are also exposed as DSL elements (see `Start Hook`_ and `Stop
+Hook`_ below), where later invocations of the methods shown below will replace
+the contents of the respective hooks:
+
+.. includecode:: ../../../akka-actor-tests/src/test/scala/akka/actor/ActorDSLSpec.scala#simple-start-stop
+
+The above is enough if the logical life-cycle of the actor matches the restart
+cycles (i.e. ``whenStopping`` is executed before a restart and ``whenStarting``
+afterwards). If that is not desired, use the following two hooks (see `Restart
+Hooks`_ below):
+
+.. includecode:: ../../../akka-actor-tests/src/test/scala/akka/actor/ActorDSLSpec.scala#failing-actor
+
+It is also possible to create nested actors, i.e. grand-children, like this:
+
+.. includecode:: ../../../akka-actor-tests/src/test/scala/akka/actor/ActorDSLSpec.scala#nested-actor
+
+.. note::
+
+  In some cases it will be necessary to explicitly pass the
+  :class:`ActorRefFactory` to the :meth:`actor()` method (you will notice when
+  the compiler tells you about ambiguous implicits).
+
+The grand-child will be supervised by the child; the supervisor strategy for
+this relationship can also be configured using a DSL element (supervision
+directives are part of the :class:`Act` trait):
+
+.. includecode:: ../../../akka-actor-tests/src/test/scala/akka/actor/ActorDSLSpec.scala#supervise-with
+
+Last but not least there is a little bit of convenience magic built-in, which
+detects if the runtime class of the statically given actor subtype extends the
+:class:`Stash` trait (this is a complicated way of saying that ``new Act with
+Stash`` would not work because its runtime erased type is just an anonymous
+subtype of ``Act``). If you want to use this magic, simply extend
+:class:`ActWithStash`:
+
+.. includecode:: ../../../akka-actor-tests/src/test/scala/akka/actor/ActorDSLSpec.scala#act-with-stash
 
 Actor API
 =========
@@ -246,8 +304,9 @@ Restart Hooks
 -------------
 
 All actors are supervised, i.e. linked to another actor with a fault
-handling strategy. Actors will be restarted in case an exception is thrown while
-processing a message. This restart involves the hooks mentioned above:
+handling strategy. Actors may be restarted in case an exception is thrown while
+processing a message (see :ref:`supervision`). This restart involves the hooks
+mentioned above:
 
 1. The old actor is informed by calling :meth:`preRestart` with the exception
    which caused the restart and the message which triggered that exception; the

akka-docs/rst/scala/code/docs/actor/ActorDocSpec.scala

@@ -406,4 +406,12 @@ class ActorDocSpec extends AkkaSpec(Map("akka.loglevel" -> "INFO")) {
     lastSender must be === system.actorFor("/user")
   }
 
+  "using ActorDSL outside of akka.actor package" in {
+    import akka.actor.ActorDSL._
+    actor(new Act {
+      superviseWith(OneForOneStrategy() { case _ ⇒ Stop; Restart; Resume; Escalate })
+      superviseWith(AllForOneStrategy() { case _ ⇒ Stop; Restart; Resume; Escalate })
+    })
+  }
+
 }

akka-docs/rst/scala/io.rst

@@ -15,7 +15,7 @@ Components
 ByteString
 ^^^^^^^^^^
 
-A primary goal of Akka's IO module is to only communicate between actors with immutable objects. When dealing with network IO on the jvm ``Array[Byte]`` and ``ByteBuffer`` are commonly used to represent collections of ``Byte``\s, but they are mutable. Scala's collection library also lacks a suitably efficient immutable collection for ``Byte``\s. Being able to safely and efficiently move ``Byte``\s around is very important for this IO module, so ``ByteString`` was developed.
+A primary goal of Akka's IO support is to only communicate between actors with immutable objects. When dealing with network IO on the jvm ``Array[Byte]`` and ``ByteBuffer`` are commonly used to represent collections of ``Byte``\s, but they are mutable. Scala's collection library also lacks a suitably efficient immutable collection for ``Byte``\s. Being able to safely and efficiently move ``Byte``\s around is very important for this IO support, so ``ByteString`` was developed.
 
 ``ByteString`` is a `Rope-like <http://en.wikipedia.org/wiki/Rope_(computer_science)>`_ data structure that is immutable and efficient. When 2 ``ByteString``\s are concatenated together they are both stored within the resulting ``ByteString`` instead of copying both to a new ``Array``. Operations such as ``drop`` and ``take`` return ``ByteString``\s that still reference the original ``Array``, but just change the offset and length that is visible. Great care has also been taken to make sure that the internal ``Array`` cannot be modified. Whenever a potentially unsafe ``Array`` is used to create a new ``ByteString`` a defensive copy is created. If you require a ``ByteString`` that only blocks a much memory as necessary for it's content, use the ``compact`` method to get a ``CompactByteString`` instance. If the ``ByteString`` represented only a slice of the original array, this will result in copying all bytes in that slice.
 
@@ -138,13 +138,13 @@ Receiving messages from the ``IOManager``:
 IO.Iteratee
 ^^^^^^^^^^^
 
-Included with Akka's IO module is a basic implementation of ``Iteratee``\s. ``Iteratee``\s are an effective way of handling a stream of data without needing to wait for all the data to arrive. This is especially useful when dealing with non blocking IO since we will usually receive data in chunks which may not include enough information to process, or it may contain much more data then we currently need.
+Included with Akka's IO support is a basic implementation of ``Iteratee``\s. ``Iteratee``\s are an effective way of handling a stream of data without needing to wait for all the data to arrive. This is especially useful when dealing with non blocking IO since we will usually receive data in chunks which may not include enough information to process, or it may contain much more data then we currently need.
 
 This ``Iteratee`` implementation is much more basic then what is usually found. There is only support for ``ByteString`` input, and enumerators aren't used. The reason for this limited implementation is to reduce the amount of explicit type signatures needed and to keep things simple. It is important to note that Akka's ``Iteratee``\s are completely optional, incoming data can be handled in any way, including other ``Iteratee`` libraries.
 
 ``Iteratee``\s work by processing the data that it is given and returning either the result (with any unused input) or a continuation if more input is needed. They are monadic, so methods like ``flatMap`` can be used to pass the result of an ``Iteratee`` to another.
 
-The basic ``Iteratee``\s included in the IO module can all be found in the ScalaDoc under ``akka.actor.IO``, and some of them are covered in the example below.
+The basic ``Iteratee``\s included in the IO support can all be found in the ScalaDoc under ``akka.actor.IO``, and some of them are covered in the example below.
 
 Examples
 --------