Merge pull request #337 from jboner/wip-1828-document-ec-√

Adding example on how to roll your own ExecutionContext

akka-docs/java/code/akka/docs/future/FutureDocTestBase.java

@@ -5,8 +5,6 @@ package akka.docs.future;
 
 //#imports1
 import akka.dispatch.*;
-import akka.japi.Procedure;
-import akka.japi.Procedure2;
 import akka.util.Timeout;
 
 //#imports1
@@ -41,9 +39,17 @@ import static akka.dispatch.Futures.reduce;
 
 //#imports6
 
+//#imports7
+import akka.dispatch.ExecutionContexts;
+import akka.dispatch.ExecutionContextExecutorService;
+
+//#imports7
+
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.List;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
 
 import org.junit.After;
 import org.junit.Before;
@@ -73,6 +79,20 @@ public class FutureDocTestBase {
     system.shutdown();
   }
 
+  @Test public void useCustomExecutionContext() throws Exception {
+      ExecutorService yourExecutorServiceGoesHere = Executors.newSingleThreadExecutor();
+      //#diy-execution-context
+      ExecutionContextExecutorService ec =
+        ExecutionContexts.fromExecutorService(yourExecutorServiceGoesHere);
+
+      //Use ec with your Futures
+      Future<String> f1 = Futures.successful("foo", ec);
+
+      // Then you shut the ec down somewhere at the end of your program/application.
+      ec.shutdown();
+      //#diy-execution-context
+  }
+
   @Test
   public void useBlockingFromActor() throws Exception {
     ActorRef actor = system.actorOf(new Props(MyActor.class));
@@ -324,10 +344,10 @@ public class FutureDocTestBase {
   public void useAndThen() {
     //#and-then
     Future<String> future1 = Futures.successful("value", system.dispatcher()).andThen(new OnComplete<String>() {
-      public void onComplete(Throwable failure, String result) {
+        public void onComplete(Throwable failure, String result) {
-        if (failure != null)
+            if (failure != null)
-          sendToIssueTracker(failure);
+                sendToIssueTracker(failure);
-      }
+        }
     }).andThen(new OnComplete<String>() {
       public void onComplete(Throwable failure, String result) {
         if (result != null)
@@ -416,13 +436,13 @@ public class FutureDocTestBase {
       Future<String> future = Futures.successful("foo", system.dispatcher());
       //#onComplete
       future.onComplete(new OnComplete<String>() {
-        public void onComplete(Throwable failure, String result) {
+          public void onComplete(Throwable failure, String result) {
-          if (failure != null) {
+              if (failure != null) {
-            //We got a failure, handle it here
+                  //We got a failure, handle it here
-          } else {
+              } else {
-            // We got a result, do something with it
+                  // We got a result, do something with it
+              }
           }
-        }
       });
       //#onComplete
     }

akka-docs/java/futures.rst

@@ -22,6 +22,9 @@ which is very similar to a ``java.util.concurrent.Executor``. if you have an ``A
 it will use its default dispatcher as the ``ExecutionContext``, or you can use the factory methods provided
 by the ``ExecutionContexts`` class to wrap ``Executors`` and ``ExecutorServices``, or even create your own.
 
+.. includecode:: code/akka/docs/future/FutureDocTestBase.java
+   :include: imports1,imports7,diy-execution-context
+
 Use with Actors
 ---------------
 

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

@@ -9,12 +9,10 @@ import akka.testkit._
 import akka.actor.Actor
 import akka.actor.Props
 import akka.actor.Status.Failure
-import akka.dispatch.Future
-import akka.dispatch.Await
 import akka.util.Timeout
 import akka.util.duration._
-import akka.dispatch.Promise
 import java.lang.IllegalStateException
+import akka.dispatch.{ ExecutionContext, Future, Await, Promise }
 
 object FutureDocSpec {
 
@@ -41,6 +39,22 @@ object FutureDocSpec {
 class FutureDocSpec extends AkkaSpec {
   import FutureDocSpec._
 
+  "demonstrate usage custom ExecutionContext" in {
+    val yourExecutorServiceGoesHere = java.util.concurrent.Executors.newSingleThreadExecutor()
+    //#diy-execution-context
+    import akka.dispatch.{ ExecutionContext, Promise }
+
+    implicit val ec = ExecutionContext.fromExecutorService(yourExecutorServiceGoesHere)
+
+    // Do stuff with your brand new shiny ExecutionContext
+    val f = Promise.successful("foo")
+
+    // Then shut your ExecutionContext down at some
+    // appropriate place in your program/application
+    ec.shutdown()
+    //#diy-execution-context
+  }
+
   "demonstrate usage of blocking from actor" in {
     val actor = system.actorOf(Props[MyActor])
     val msg = "hello"

akka-docs/scala/futures.rst

@@ -22,6 +22,9 @@ which is very similar to a ``java.util.concurrent.Executor``. if you have an ``A
 it will use its default dispatcher as the ``ExecutionContext``, or you can use the factory methods provided
 by the ``ExecutionContext`` companion object to wrap ``Executors`` and ``ExecutorServices``, or even create your own.
 
+.. includecode:: code/akka/docs/future/FutureDocSpec.scala
+   :include: diy-execution-context
+
 Use With Actors
 ---------------