polish “ask” pattern, see #1581

- move package objects into their respective package.scala file in the
  right directories
- make implicit conversion as well as explicit facility available under
  the same name akka.patterns.ask for easy import
- revert the logic to produce the Promise for the PromiseActorRef within
  the ActorRefProvider; supporting wrapping of external Promises does
  not seem to justify doing needless extra allocations in case of
  failure
- add scaladocs
- factor out “def provider” into trait ActorRefWithProvider, as it
  didn’t feel right attaching this information “by exception” to
  MinimalActorRef

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

@@ -8,7 +8,6 @@ import akka.actor.Actor
 import akka.actor.Props
 import akka.event.Logging
 import akka.dispatch.Future
-import akka.Patterns
 
 //#imports1
 
@@ -221,6 +220,8 @@ class ActorDocSpec extends AkkaSpec(Map("akka.loglevel" -> "INFO")) {
 
   "using ask" in {
     //#using-ask
+    import akka.patterns.ask
+
     class MyActor extends Actor {
       def receive = {
         case x: String ⇒ sender ! x.toUpperCase
@@ -230,10 +231,10 @@ class ActorDocSpec extends AkkaSpec(Map("akka.loglevel" -> "INFO")) {
 
     val myActor = system.actorOf(Props(new MyActor), name = "myactor")
     implicit val timeout = system.settings.ActorTimeout
-    val future = Patterns.ask(myActor, "hello")
+    val future = ask(myActor, "hello")
     for (x ← future) println(x) //Prints "hello"
 
-    val result: Future[Int] = for (x ← Patterns.ask(myActor, 3).mapTo[Int]) yield { 2 * x }
+    val result: Future[Int] = for (x ← ask(myActor, 3).mapTo[Int]) yield { 2 * x }
     //#using-ask
 
     system.stop(myActor)

akka-docs/scala/code/akka/docs/future/FutureDocSpec.scala

@@ -13,7 +13,6 @@ import akka.dispatch.Future
 import akka.dispatch.Await
 import akka.util.duration._
 import akka.dispatch.Promise
-import akka.Patterns
 
 object FutureDocSpec {
 
@@ -45,9 +44,10 @@ class FutureDocSpec extends AkkaSpec {
     val msg = "hello"
     //#ask-blocking
     import akka.dispatch.Await
+    import akka.patterns.ask
 
     implicit val timeout = system.settings.ActorTimeout
-    val future = Patterns.ask(actor, msg)
+    val future = actor ? msg // enabled by the “ask” import
     val result = Await.result(future, timeout.duration).asInstanceOf[String]
     //#ask-blocking
     result must be("HELLO")
@@ -59,8 +59,9 @@ class FutureDocSpec extends AkkaSpec {
     implicit val timeout = system.settings.ActorTimeout
     //#map-to
     import akka.dispatch.Future
+    import akka.patterns.ask
 
-    val future: Future[String] = Patterns.ask(actor, msg).mapTo[String]
+    val future: Future[String] = ask(actor, msg).mapTo[String]
     //#map-to
     Await.result(future, timeout.duration) must be("HELLO")
   }
@@ -148,15 +149,16 @@ class FutureDocSpec extends AkkaSpec {
     val msg2 = 2
     implicit val timeout = system.settings.ActorTimeout
     import akka.dispatch.Await
+    import akka.patterns.ask
     //#composing-wrong
 
-    val f1 = Patterns.ask(actor1, msg1)
-    val f2 = Patterns.ask(actor2, msg2)
+    val f1 = ask(actor1, msg1)
+    val f2 = ask(actor2, msg2)
 
     val a = Await.result(f1, 1 second).asInstanceOf[Int]
     val b = Await.result(f2, 1 second).asInstanceOf[Int]
 
-    val f3 = Patterns.ask(actor3, (a + b))
+    val f3 = ask(actor3, (a + b))
 
     val result = Await.result(f3, 1 second).asInstanceOf[Int]
     //#composing-wrong
@@ -171,15 +173,16 @@ class FutureDocSpec extends AkkaSpec {
     val msg2 = 2
     implicit val timeout = system.settings.ActorTimeout
     import akka.dispatch.Await
+    import akka.patterns.ask
     //#composing
 
-    val f1 = Patterns.ask(actor1, msg1)
-    val f2 = Patterns.ask(actor2, msg2)
+    val f1 = ask(actor1, msg1)
+    val f2 = ask(actor2, msg2)
 
     val f3 = for {
       a ← f1.mapTo[Int]
       b ← f2.mapTo[Int]
-      c ← Patterns.ask(actor3, (a + b)).mapTo[Int]
+      c ← ask(actor3, (a + b)).mapTo[Int]
     } yield c
 
     val result = Await.result(f3, 1 second).asInstanceOf[Int]
@@ -192,7 +195,7 @@ class FutureDocSpec extends AkkaSpec {
     val oddActor = system.actorOf(Props[OddActor])
     //#sequence-ask
     // oddActor returns odd numbers sequentially from 1 as a List[Future[Int]]
-    val listOfFutures = List.fill(100)(Patterns.ask(oddActor, GetNext).mapTo[Int])
+    val listOfFutures = List.fill(100)(akka.patterns.ask(oddActor, GetNext).mapTo[Int])
 
     // now we have a Future[List[Int]]
     val futureList = Future.sequence(listOfFutures)
@@ -240,7 +243,7 @@ class FutureDocSpec extends AkkaSpec {
     val actor = system.actorOf(Props[MyActor])
     val msg1 = -1
     //#recover
-    val future = Patterns.ask(actor, msg1) recover {
+    val future = akka.patterns.ask(actor, msg1) recover {
       case e: ArithmeticException ⇒ 0
     }
     //#recover