From 1869e569aadb27023b5a1abc8e07b3dd663b8944 Mon Sep 17 00:00:00 2001
From: Gaju Bhat <gajukbhat@gmail.com>
Date: Sat, 9 May 2015 22:29:24 -0700
Subject: [PATCH] =doc #17438 Refine documentation

It doesn't make sense to send a message composed of a future to another
actor. Futures aren't serializable.
---
 akka-actor/src/main/scala/akka/actor/ActorRef.scala | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/akka-actor/src/main/scala/akka/actor/ActorRef.scala b/akka-actor/src/main/scala/akka/actor/ActorRef.scala
index d71a95ed65..9e26fe0c64 100644
--- a/akka-actor/src/main/scala/akka/actor/ActorRef.scala
+++ b/akka-actor/src/main/scala/akka/actor/ActorRef.scala
@@ -39,6 +39,7 @@ object ActorRef {
  * Scala:
  * {{{
  * import akka.pattern.ask
+ * import scala.concurrent.Await
  *
  * class ExampleActor extends Actor {
  *   val other = context.actorOf(Props[OtherActor], "childName") // will be destroyed and re-created upon restart by default
@@ -48,7 +49,9 @@ object ActorRef {
  *     case Request2(msg) => other.tell(msg, sender()) // forward sender reference, enabling direct reply
  *     case Request3(msg) =>
  *       implicit val timeout = Timeout(5.seconds)
- *       sender() ! (other ? msg)  // will reply with a Future for holding other's reply
+ *       (other ? msg) pipeTo sender()
+ *       // the ask call will get a future from other's reply
+ *       // when the future is complete, send its value to the original sender
  *   }
  * }
  * }}}
@@ -56,6 +59,7 @@ object ActorRef {
  * Java:
  * {{{
  * import static akka.pattern.Patterns.ask;
+ * import static akka.pattern.Patterns.pipe;
  *
  * public class ExampleActor extends UntypedActor {
  *   // this child will be destroyed and re-created upon restart by default
@@ -73,7 +77,9 @@ object ActorRef {
  *
  *     } else if (o instanceof Request3) {
  *       Msg msg = ((Request3) o).getMsg();
- *       getSender().tell(ask(other, msg, 5000)); // reply with Future for holding the other's reply (timeout 5 seconds)
+ *       pipe(ask(other, msg, 5000)).to(getSender());
+ *       // the ask call will get a future from other's reply
+ *       // when the future is complete, send its value to the original sender
  *
  *     } else {
  *       unhandled(o);