Clear up blocking _in_ a future vs blocking _on_ a future.

Author: backuitist

overviews/core/_posts/2012-09-20-futures.md

@@ -615,8 +615,30 @@ Invoking the `future` construct uses a global execution context to start an asyn
 Support for extending the Futures API with additional utility methods is planned.
 This will allow external frameworks to provide more specialized utilities.
 
+
 ## Blocking
 
+### in a Future
+
+As seen with the global `ExecutionContext`, it is possible to notify an `ExecutionContext` of a blocking call with the `blocking` construct.
+The implementation is however at the complete discretion of the `ExecutionContext`. While some `ExecutionContext` such as `ExecutionContext.global`
+implement `blocking` by means of `ManagedBlocker`, some just do nothing:
+
+implicit val ec = ExecutionContext.fromExecutor(
+ Executors.newFixedThreadPool(4))
+Future{
+ // here blocking serves only for documentation purpose
+ blocking{blockingStuff() }
+}
+
+Is equivalent to
+
+Future{blockingStuff() }
+
+The blocking code may also throw an exception. In this case, the exception is forwarded to the caller.
+
+### on a Future
+
 As mentioned earlier, blocking on a future is strongly discouraged
 for the sake of performance and for the prevention of deadlocks.
 Callbacks and combinators on futures are a preferred way to use their results.
@@ -656,17 +678,6 @@ The `Future` trait implements the `Awaitable` trait with methods
 method `ready()` and `result()`. These methods cannot be called directly
 by the clients-- they can only be called by the execution context.
 
-To allow clients to call 3rd party code which is potentially blocking
-and avoid implementing the `Awaitable` trait, the same
-`blocking` primitive can also be used in the following form:
-
-blocking{
- potentiallyBlockingCall()
-}
-
-The blocking code may also throw an exception. In this case, the
-exception is forwarded to the caller.
-
 
 
 ## Exceptions