From 7ef5ace8d8643e769a2e5294c61db49f36cad163 Mon Sep 17 00:00:00 2001
From: Roland <rk@rkuhn.info>
Date: Thu, 31 Jan 2013 11:40:39 +0100
Subject: [PATCH] add docs on how to create child actors with channels

---
 .../code/docs/channels/ChannelDocSpec.scala   | 57 +++++++++++++++++--
 akka-docs/rst/scala/typed-channels.rst        | 12 ++++
 2 files changed, 65 insertions(+), 4 deletions(-)

diff --git a/akka-docs/rst/scala/code/docs/channels/ChannelDocSpec.scala b/akka-docs/rst/scala/code/docs/channels/ChannelDocSpec.scala
index 0806e6aad1..ef74019446 100644
--- a/akka-docs/rst/scala/code/docs/channels/ChannelDocSpec.scala
+++ b/akka-docs/rst/scala/code/docs/channels/ChannelDocSpec.scala
@@ -13,7 +13,7 @@ import scala.concurrent.duration._
 import akka.util.Timeout
 import akka.testkit.TestProbe
 
-class ChannelDocSpec extends AkkaSpec {
+object ChannelDocSpec {
 
   //#motivation0
   trait Request
@@ -24,6 +24,39 @@ class ChannelDocSpec extends AkkaSpec {
   case class CommandFailure(msg: String) extends Reply
   //#motivation0
 
+  //#child
+  case class Stats(b: Request)
+  case object GetChild
+  case class ChildRef(child: ChannelRef[(Request, Reply) :+: TNil])
+
+  class Child extends Actor
+    with Channels[(Stats, Nothing) :+: TNil, (Request, Reply) :+: TNil] {
+
+    channel[Request] { (x, snd) ⇒
+      parentChannel <-!- Stats(x)
+      snd <-!- CommandSuccess
+    }
+  }
+
+  class Parent extends Actor
+    with Channels[TNil, (Stats, Nothing) :+: (GetChild.type, ChildRef) :+: TNil] {
+    
+    val child = createChild(new Child)
+
+    channel[GetChild.type] { (_, snd) ⇒ ChildRef(child) -!-> snd }
+
+    channel[Stats] { (x, _) ⇒
+      // collect some stats
+    }
+  }
+
+  //#child
+}
+
+class ChannelDocSpec extends AkkaSpec {
+
+  import ChannelDocSpec._
+
   class A
   class B
   class C
@@ -116,14 +149,14 @@ class ChannelDocSpec extends AkkaSpec {
       extends Actor with Channels[TNil, (Request, Reply) :+: (T1, T2) :+: TNil] {
 
       implicit val timeout = Timeout(5.seconds)
-      
+
       //#become
       channel[Request] {
-        
+
         case (Command("close"), snd) ⇒
           channel[T1] { (t, s) ⇒ t -?-> target -!-> s }
           snd <-!- CommandSuccess
-          
+
         case (Command("open"), snd) ⇒
           channel[T1] { (_, _) ⇒ }
           snd <-!- CommandSuccess
@@ -163,4 +196,20 @@ class ChannelDocSpec extends AkkaSpec {
     //#usage
   }
 
+  "demonstrate child creation" in {
+    implicit val selfChannel = new ChannelRef[(Any, Nothing) :+: TNil](testActor)
+    //#child
+    // 
+    // then it is used somewhat like this:
+    // 
+    
+    val parent = ChannelExt(system).actorOf(new Parent)
+    parent <-!- GetChild
+    val child = expectMsgType[ChildRef].child // this assumes TestKit context
+
+    child <-!- Command("hey there")
+    expectMsg(CommandSuccess)
+    //#child
+  }
+
 }
\ No newline at end of file
diff --git a/akka-docs/rst/scala/typed-channels.rst b/akka-docs/rst/scala/typed-channels.rst
index d998c216ca..a0b2574443 100644
--- a/akka-docs/rst/scala/typed-channels.rst
+++ b/akka-docs/rst/scala/typed-channels.rst
@@ -449,6 +449,18 @@ Creating top-level actors with channels is done using the ``ChannelExt`` extensi
    :include: usage
    :exclude: processing
 
+Inside an actor with channels children are created using the ``createChild`` method:
+
+.. includecode:: code/docs/channels/ChannelDocSpec.scala#child
+
+In this example we create a simple child actor which responds to requests, but
+also keeps its parent informed about what it is doing. The parent channel
+within the child is thus declared to accept :class:`Stats` messages, and the
+parent must consequently declare such a channel in order to be able to create
+such a child. The parent’s job then is to create the child, make it available
+to the outside via properly typed messages and collect the statistics coming in
+from the child.
+
 Implementation Restrictions
 ---------------------------