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

1 files changed, 54 insertions, 62 deletions

diff --git a/src/library/scala/util/Try.scala b/src/library/scala/util/Try.scala
index b0cf122f2a..f08cc18f7d 100644
--- a/src/library/scala/util/Try.scala
+++ b/src/library/scala/util/Try.scala
@@ -74,16 +74,11 @@ sealed abstract class Try[+T] {
    *
    * ''Note:'': This will throw an exception if it is not a success and default throws an exception.
    */
-  def getOrElse[U >: T](default: => U): U =
-    if (isSuccess) get else default
+  def getOrElse[U >: T](default: => U): U
 
   /** Returns this `Try` if it's a `Success` or the given `default` argument if this is a `Failure`.
    */
-  def orElse[U >: T](default: => Try[U]): Try[U] =
-    try if (isSuccess) this else default
-    catch {
-      case NonFatal(e) => Failure(e)
-    }
+  def orElse[U >: T](default: => Try[U]): Try[U]
 
   /** Returns the value from this `Success` or throws the exception if this is a `Failure`.
    */
@@ -107,6 +102,11 @@ sealed abstract class Try[+T] {
   def map[U](f: T => U): Try[U]
 
   /**
+   * Applies the given partial function to the value from this `Success` or returns this if this is a `Failure`.
+   */
+  def collect[U](pf: PartialFunction[T, U]): Try[U]
+
+  /**
    * Converts this to a `Failure` if the predicate is not satisfied.
    */
   def filter(p: T => Boolean): Try[T]
@@ -133,6 +133,7 @@ sealed abstract class Try[+T] {
    *  collection" contract even though it seems unlikely to matter much in a
    *  collection with max size 1.
    */
+  @deprecatedInheritance("You were never supposed to be able to extend this class.", "2.12")
   class WithFilter(p: T => Boolean) {
     def map[U](f:     T => U): Try[U]           = Try.this filter p map f
     def flatMap[U](f: T => Try[U]): Try[U]      = Try.this filter p flatMap f
@@ -144,18 +145,18 @@ sealed abstract class Try[+T] {
    * Applies the given function `f` if this is a `Failure`, otherwise returns this if this is a `Success`.
    * This is like `flatMap` for the exception.
    */
-  def recoverWith[U >: T](f: PartialFunction[Throwable, Try[U]]): Try[U]
+  def recoverWith[U >: T](@deprecatedName('f) pf: PartialFunction[Throwable, Try[U]]): Try[U]
 
   /**
    * Applies the given function `f` if this is a `Failure`, otherwise returns this if this is a `Success`.
    * This is like map for the exception.
    */
-  def recover[U >: T](f: PartialFunction[Throwable, U]): Try[U]
+  def recover[U >: T](@deprecatedName('f) pf: PartialFunction[Throwable, U]): Try[U]
 
   /**
    * Returns `None` if this is a `Failure` or a `Some` containing the value if this is a `Success`.
    */
-  def toOption: Option[T] = if (isSuccess) Some(get) else None
+  def toOption: Option[T]
 
   /**
    * Transforms a nested `Try`, ie, a `Try` of type `Try[Try[T]]`,
@@ -172,14 +173,7 @@ sealed abstract class Try[+T] {
   /** Completes this `Try` by applying the function `f` to this if this is of type `Failure`, or conversely, by applying
    *  `s` if this is a `Success`.
    */
-  def transform[U](s: T => Try[U], f: Throwable => Try[U]): Try[U] =
-    try this match {
-      case Success(v) => s(v)
-      case Failure(e) => f(e)
-    } catch {
-      case NonFatal(e) => Failure(e)
-    }
-
+  def transform[U](s: T => Try[U], f: Throwable => Try[U]): Try[U]
 }
 
 object Try {
@@ -191,57 +185,55 @@ object Try {
     try Success(r) catch {
       case NonFatal(e) => Failure(e)
     }
-
 }
 
 final case class Failure[+T](exception: Throwable) extends Try[T] {
-  def isFailure: Boolean = true
-  def isSuccess: Boolean = false
-  def recoverWith[U >: T](f: PartialFunction[Throwable, Try[U]]): Try[U] =
-    try {
-      if (f isDefinedAt exception) f(exception) else this
-    } catch {
-      case NonFatal(e) => Failure(e)
-    }
-  def get: T = throw exception
-  def flatMap[U](f: T => Try[U]): Try[U] = this.asInstanceOf[Try[U]]
-  def flatten[U](implicit ev: T <:< Try[U]): Try[U] = this.asInstanceOf[Try[U]]
-  def foreach[U](f: T => U): Unit = ()
-  def map[U](f: T => U): Try[U] = this.asInstanceOf[Try[U]]
-  def filter(p: T => Boolean): Try[T] = this
-  def recover[U >: T](rescueException: PartialFunction[Throwable, U]): Try[U] =
-    try {
-      if (rescueException isDefinedAt exception) {
-        Try(rescueException(exception))
-      } else this
-    } catch {
-      case NonFatal(e) => Failure(e)
-    }
-  def failed: Try[Throwable] = Success(exception)
+  override def isFailure: Boolean = true
+  override def isSuccess: Boolean = false
+  override def get: T = throw exception
+  override def getOrElse[U >: T](default: => U): U = default
+  override def orElse[U >: T](default: => Try[U]): Try[U] = 
+    try default catch { case NonFatal(e) => Failure(e) }
+  override def flatMap[U](f: T => Try[U]): Try[U] = this.asInstanceOf[Try[U]]
+  override def flatten[U](implicit ev: T <:< Try[U]): Try[U] = this.asInstanceOf[Try[U]]
+  override def foreach[U](f: T => U): Unit = ()
+  override def transform[U](s: T => Try[U], f: Throwable => Try[U]): Try[U] = 
+    try f(exception) catch { case NonFatal(e) => Failure(e) }
+  override def map[U](f: T => U): Try[U] = this.asInstanceOf[Try[U]]
+  override def collect[U](pf: PartialFunction[T, U]): Try[U] = this.asInstanceOf[Try[U]]
+  override def filter(p: T => Boolean): Try[T] = this
+  override def recover[U >: T](@deprecatedName('rescueException) pf: PartialFunction[Throwable, U]): Try[U] =
+    try { if (pf isDefinedAt exception) Success(pf(exception)) else this } catch { case NonFatal(e) => Failure(e) }
+  override def recoverWith[U >: T](@deprecatedName('f) pf: PartialFunction[Throwable, Try[U]]): Try[U] =
+    try { if (pf isDefinedAt exception) pf(exception) else this } catch { case NonFatal(e) => Failure(e) }
+  override def failed: Try[Throwable] = Success(exception)
+  override def toOption: Option[T] = None
 }
 
 
 final case class Success[+T](value: T) extends Try[T] {
-  def isFailure: Boolean = false
-  def isSuccess: Boolean = true
-  def recoverWith[U >: T](f: PartialFunction[Throwable, Try[U]]): Try[U] = this
-  def get = value
-  def flatMap[U](f: T => Try[U]): Try[U] =
-    try f(value)
-    catch {
-      case NonFatal(e) => Failure(e)
-    }
-  def flatten[U](implicit ev: T <:< Try[U]): Try[U] = value
-  def foreach[U](f: T => U): Unit = f(value)
-  def map[U](f: T => U): Try[U] = Try[U](f(value))
-  def filter(p: T => Boolean): Try[T] = {
+  override def isFailure: Boolean = false
+  override def isSuccess: Boolean = true
+  override def get = value
+  override def getOrElse[U >: T](default: => U): U = get
+  override def orElse[U >: T](default: => Try[U]): Try[U] = this
+  override def flatMap[U](f: T => Try[U]): Try[U] =
+    try f(value) catch { case NonFatal(e) => Failure(e) }
+  override def flatten[U](implicit ev: T <:< Try[U]): Try[U] = value
+  override def foreach[U](f: T => U): Unit = f(value)
+  override def transform[U](s: T => Try[U], f: Throwable => Try[U]): Try[U] = this flatMap s
+  override def map[U](f: T => U): Try[U] = Try[U](f(value))
+  override def collect[U](pf: PartialFunction[T, U]): Try[U] =
     try {
-      if (p(value)) this
+      if (pf isDefinedAt value) Success(pf(value))
       else Failure(new NoSuchElementException("Predicate does not hold for " + value))
-    } catch {
-      case NonFatal(e) => Failure(e)
-    }
-  }
-  def recover[U >: T](rescueException: PartialFunction[Throwable, U]): Try[U] = this
-  def failed: Try[Throwable] = Failure(new UnsupportedOperationException("Success.failed"))
+    } catch { case NonFatal(e) => Failure(e) }
+  override def filter(p: T => Boolean): Try[T] =
+    try {
+      if (p(value)) this else Failure(new NoSuchElementException("Predicate does not hold for " + value))
+    } catch { case NonFatal(e) => Failure(e) }
+  override def recover[U >: T](@deprecatedName('rescueException) pf: PartialFunction[Throwable, U]): Try[U] = this
+  override def recoverWith[U >: T](@deprecatedName('f) pf: PartialFunction[Throwable, Try[U]]): Try[U] = this
+  override def failed: Try[Throwable] = Failure(new UnsupportedOperationException("Success.failed"))
+  override def toOption: Option[T] = Some(value)
 }