Add missing canonical combinators:

  - `def transform[S](f: Try[T] => Try[S])(implicit executor: ExecutionContext): Future[S]`
  - `def transformWith[S](f: Try[T] => Future[S])(implicit executor: ExecutionContext): Future[S]`
  - `def flatten[S](implicit ev: T <:< Future[S]): Future[S]`
  - `def zipWith[U, R](that: Future[U])(f: (T, U) => R)(implicit executor: ExecutionContext): Future[R]`

Add missing utilities:
  -  `val unit: Future[Unit]` in `object Future`
  -  `object never extends Future[Nothing]` in `object Future`
  -  `def defaultBlockContext: BlockContext` in `object BlockContext`
  -  `def toString: String` on stdlib implementations of `Future`

Refactors:
  - the `scala.concurrent.Future` trait to not explicit create any `Promises`,
    so that implementations can control implementation type,
    this is mainly facilitated through adding of the `transform` and `transformWith` methods.
  - the implementation of `ExecutionContextImpl` has been cleaned up
  - the `scala.concurrent.impl.DefaultPromise` has been reimplemented to not use `sun.misc.Unsafe`

Securing:
  - Add a self-check in `completeWith` and `tryCompleteWith` to avoid cycles in trait Promise
  - Capping the maximum number of threads for the global `ExecutionContext` to the max parallelism
  - Implementing (almost) all `Future` combinators on `transformWith` and `transform` means
     that `DefaultPromise` linking works on both `(flat)map` and `recover(With)`
  - Nested `blocking {}` should not spawn extra threads beyond the first.

Removes:
  - the private `internalExecutor` method in favor of an import in trait `Future`
  - the private `internalExecutor` method in favor of an import in trait `Promise`
  - the `AtomicReferenceFieldUpdater` in `AbstractPromise` since we're using `Unsafe`
  - `scala.concurrent.impl.Future` is no longer needed

Deprecates:
  - `Future.onSuccess` - discourage the use of callbacks
                         (and is also redundant considering `foreach` and `onComplete`)
  - `Future.onFailure` - discourage the use of callbacks
                       (and is also redundant considering `onComplete` and `failed.foreach`)
  - `ExecutionContext.prepare` - it was ill specced and it is too easy to forget to call it
                     (or even know when to call it or call it more times than needed)
  - All classes in scala.concurrent.forkjoin. Scala 2.12 will be Java 8+ and as such the jsr166e
    should be used as included in java.util.concurrent.

Reimplements:
  - `failed` - in terms of `transform`
  - `map` - in terms of `transform`
  - `flatMap` - in terms of `transformWith`
  - `recover` - in terms of `transform`
  - `recoverWith` - in terms of `transformWith`
  - `zip` - in terms of `flatMap` + `map`
  - `fallbackTo` - in terms of `recoverWith` + `recoverWith`
  - `andThen` - in terms of `transform`

Miscellaneous:
  - Giving the threads of `ExecutionContext.global` sensible names
  - Optimizes `object Future.successful` and `object Future.failed` are now separate implementations,
    to optimize for the result, avoiding doing work for the "other branch".
  - Optimizes `compressedRoot()` by avoiding double-calls to volatile get.

Documentation:
  - Almost all methods on `Future` and `Promise` have been revisited and had their ScalaDoc updated

Tests:
  - Yes

Author: viktorklang

src/forkjoin/scala/concurrent/forkjoin/ForkJoinPool.java

@@ -23,6 +23,7 @@
  * @since 1.8
  * @author Doug Lea
  */
+@Deprecated
 /*public*/ abstract class CountedCompleter<T> extends ForkJoinTask<T> {
     private static final long serialVersionUID = 5232453752276485070L;
 
@@ -471,6 +472,7 @@ private static sun.misc.Unsafe getUnsafe() {
  * @since 1.7
  * @author Doug Lea
  */
+@Deprecated
 public class ForkJoinPool extends AbstractExecutorService {
 
     /*
@@ -3578,6 +3580,7 @@ static void quiesceCommonPool() {
      *   }
      * }}</pre>
      */
+    @Deprecated
     public static interface ManagedBlocker {
         /**
          * Possibly blocks the current thread, for example waiting for

src/forkjoin/scala/concurrent/forkjoin/ForkJoinTask.java

@@ -180,6 +180,7 @@
  * @since 1.7
  * @author Doug Lea
  */
+@Deprecated
 public abstract class ForkJoinTask<V> implements Future<V>, Serializable {
 
     /*
@@ -391,6 +392,7 @@ private int doInvoke() {
      * any ForkJoinPool will call helpExpungeStaleExceptions when its
      * pool becomes isQuiescent.
      */
+    @Deprecated
     static final class ExceptionNode extends WeakReference<ForkJoinTask<?>> {
         final Throwable ex;
         ExceptionNode next;
@@ -1330,6 +1332,7 @@ public final boolean compareAndSetForkJoinTaskTag(short e, short tag) {
      * to be compliant with AbstractExecutorService constraints
      * when used in ForkJoinPool.
      */
+    @Deprecated
     static final class AdaptedRunnable<T> extends ForkJoinTask<T>
         implements RunnableFuture<T> {
         final Runnable runnable;
@@ -1349,6 +1352,7 @@ static final class AdaptedRunnable<T> extends ForkJoinTask<T>
     /**
      * Adaptor for Runnables without results
      */
+    @Deprecated
     static final class AdaptedRunnableAction extends ForkJoinTask<Void>
         implements RunnableFuture<Void> {
         final Runnable runnable;
@@ -1366,6 +1370,7 @@ public final void setRawResult(Void v) { }
     /**
      * Adaptor for Callables
      */
+    @Deprecated
     static final class AdaptedCallable<T> extends ForkJoinTask<T>
         implements RunnableFuture<T> {
         final Callable<? extends T> callable;

src/forkjoin/scala/concurrent/forkjoin/ForkJoinWorkerThread.java

@@ -20,6 +20,7 @@
  * @since 1.7
  * @author Doug Lea
  */
+@Deprecated
 public class ForkJoinWorkerThread extends Thread {
     /*
      * ForkJoinWorkerThreads are managed by ForkJoinPools and perform

src/forkjoin/scala/concurrent/forkjoin/LinkedTransferQueue.java

@@ -53,6 +53,7 @@
  * @author Doug Lea
  * @param <E> the type of elements held in this collection
  */
+@Deprecated
 public class LinkedTransferQueue<E> extends AbstractQueue<E>
     implements TransferQueue<E>, java.io.Serializable {
     private static final long serialVersionUID = -3223113410248163686L;
@@ -416,6 +417,7 @@ public class LinkedTransferQueue<E> extends AbstractQueue<E>
      * unnecessary ordering constraints: Writes that are intrinsically
      * ordered wrt other accesses or CASes use simple relaxed forms.
      */
+    @Deprecated
     static final class Node {
         final boolean isData;   // false if this is a request node
         volatile Object item;   // initially non-null if isData; CASed to match
@@ -789,6 +791,7 @@ private int countOfMode(boolean data) {
         return count;
     }
 
+    @Deprecated
     final class Itr implements Iterator<E> {
         private Node nextNode;   // next node to return item for
         private E nextItem;      // the corresponding item

src/forkjoin/scala/concurrent/forkjoin/RecursiveAction.java

@@ -133,6 +133,7 @@
  * @since 1.7
  * @author Doug Lea
  */
+@Deprecated
 public abstract class RecursiveAction extends ForkJoinTask<Void> {
     private static final long serialVersionUID = 5232453952276485070L;
 

src/forkjoin/scala/concurrent/forkjoin/RecursiveTask.java

@@ -36,6 +36,7 @@
  * @since 1.7
  * @author Doug Lea
  */
+@Deprecated
 public abstract class RecursiveTask<V> extends ForkJoinTask<V> {
     private static final long serialVersionUID = 5232453952276485270L;
 

src/forkjoin/scala/concurrent/forkjoin/ThreadLocalRandom.java

@@ -32,6 +32,7 @@
  * @since 1.7
  * @author Doug Lea
  */
+@Deprecated
 public class ThreadLocalRandom extends Random {
     // same constants as Random, but must be redeclared because private
     private static final long multiplier = 0x5DEECE66DL;
@@ -80,6 +81,7 @@ protected ThreadLocalRandom initialValue() {
      *
      * @return the current thread's {@code ThreadLocalRandom}
      */
+    @Deprecated
     public static ThreadLocalRandom current() {
         return localRandom.get();
     }

src/forkjoin/scala/concurrent/forkjoin/TransferQueue.java

@@ -37,6 +37,7 @@
  * @author Doug Lea
  * @param <E> the type of elements held in this collection
  */
+@Deprecated
 public interface TransferQueue<E> extends BlockingQueue<E> {
     /**
      * Transfers the element to a waiting consumer immediately, if possible.

src/forkjoin/scala/concurrent/util/Unsafe.java

@@ -7,14 +7,12 @@
 \*                                                                      */
 
 package scala.concurrent.util;
-
-
-
 import java.lang.reflect.Field;
 
 
-
+@Deprecated
 public final class Unsafe {
+    @Deprecated
     public final static sun.misc.Unsafe instance;
     static {
         try {

src/library/scala/concurrent/BlockContext.scala

@@ -41,7 +41,7 @@ package scala.concurrent
 trait BlockContext {
 
   /** Used internally by the framework;
-   * Designates (and eventually executes) a thunk which potentially blocks the calling `Thread`.
+   * Designates (and eventually executes) a thunk which potentially blocks the calling `java.lang.Thread`.
    *
    * Clients must use `scala.concurrent.blocking` or `scala.concurrent.Await` instead.
    */
@@ -53,9 +53,16 @@ object BlockContext {
     override def blockOn[T](thunk: =>T)(implicit permission: CanAwait): T = thunk
   }
 
+  /**
+   * @return the `BlockContext` that will be used if no other is found.
+   **/
+  def defaultBlockContext: BlockContext = DefaultBlockContext
+
   private val contextLocal = new ThreadLocal[BlockContext]()
 
-  /** Obtain the current thread's current `BlockContext`. */
+  /**
+    @return the `BlockContext` that would be used for the current `java.lang.Thread` at this point
+   **/
   def current: BlockContext = contextLocal.get match {
     case null => Thread.currentThread match {
       case ctx: BlockContext => ctx
@@ -64,7 +71,9 @@ object BlockContext {
     case some => some
   }
 
-  /** Pushes a current `BlockContext` while executing `body`. */
+  /**
+   * Installs a current `BlockContext` around executing `body`.
+   **/
   def withBlockContext[T](blockContext: BlockContext)(body: => T): T = {
     val old = contextLocal.get // can be null
     try {

src/library/scala/concurrent/ExecutionContext.scala

@@ -72,22 +72,24 @@ trait ExecutionContext {
    */
   def reportFailure(@deprecatedName('t) cause: Throwable): Unit
 
-  /** Prepares for the execution of a task. Returns the prepared execution context.
-   *
-   *  `prepare` should be called at the site where an `ExecutionContext` is received (for
-   *  example, through an implicit method parameter). The returned execution context may
-   *  then be used to execute tasks. The role of `prepare` is to save any context relevant
-   *  to an execution's ''call site'', so that this context may be restored at the
-   *  ''execution site''. (These are often different: for example, execution may be
-   *  suspended through a `Promise`'s future until the `Promise` is completed, which may
-   *  be done in another thread, on another stack.)
-   *
-   *  Note: a valid implementation of `prepare` is one that simply returns `this`.
-   *
-   *  @return the prepared execution context
-   */
+  /** Prepares for the execution of a task. Returns the prepared
+     *  execution context. The recommended implementation of
+     *  `prepare` is to return `this`.
+     * 
+     *  This method should no longer be overridden or called. It was
+     *  originally expected that `prepare` would be called by
+     *  all libraries that consume ExecutionContexts, in order to
+     *  capture thread local context. However, this usage has proven
+     *  difficult to implement in practice and instead it is
+     *  now better to avoid using `prepare` entirely.
+     *
+     *  Instead, if an `ExecutionContext` needs to capture thread
+     *  local context, it should capture that context when it is
+     *  constructed, so that it doesn't need any additional
+     *  preparation later.
+     */
+  @deprecated("Preparation of ExecutionContexts will be removed.", "2.12")
   def prepare(): ExecutionContext = this
-
 }
 
 /**