Minimize the public API

 - Remove the CPS fallback version of async. That was not intended
   to be part of 1.0.
 - Lookup the await method beside the macro, rather than requiring
   all calls to go to AsyncBase.await.
 - Create a minimal version of Async that just contains await/async
   and delegates to the macro implementation in internal._
 - Add scaladoc.

Author: retronym

build.sbt

@@ -28,27 +28,6 @@ testOptions += Tests.Argument(TestFrameworks.JUnit, "-q", "-v", "-s")
 
 parallelExecution in Global := false
 
-autoCompilerPlugins := true
-
-scalacOptions ++= (scalaHome.value match {
-  case Some(sh) =>
-    // Use continuations plugin from the local scala instance
-    val continuationsJar = sh / "misc" / "scala-devel" / "plugins" / "continuations.jar"
-    ("-Xplugin:" + continuationsJar.getAbsolutePath) :: Nil
-  case None =>
-    Nil
-})
-
-libraryDependencies ++= (scalaHome.value match {
-  case Some(sh) =>
-    Nil
-  case None =>
-    // Use continuations plugin from the published artifact.
-    compilerPlugin("org.scala-lang.plugins" % "continuations" % scalaVersion.value) :: Nil
-})
-
-scalacOptions += "-P:continuations:enable"
-
 scalacOptions in compile ++= Seq("-optimize", "-deprecation", "-unchecked", "-Xlint", "-feature")
 
 scalacOptions in Test ++= Seq("-Yrangepos")
@@ -133,4 +112,4 @@ packageOptions in packageSrc := Seq(Package.ManifestAttributes(
                       ("Bundle-Name", s"${name.value} sources"),
                       ("Bundle-Version", osgiVersion.value),
                       ("Eclipse-SourceBundle", s"""${organization.value}.${name.value};version="${osgiVersion.value}";roots:="."""")
-                  ))
+                  ))

pending/run/fallback0/fallback0-manual.scala

@@ -0,0 +1,55 @@
+/*
+ * Copyright (C) 2012 Typesafe Inc. <http://www.typesafe.com>
+ */
+
+package scala.async
+
+import scala.language.experimental.macros
+import scala.concurrent.{Future, ExecutionContext}
+import scala.reflect.internal.annotations.compileTimeOnly
+
+/**
+ * Async blocks provide a direct means to work with [[scala.concurrent.Future]].
+ *
+ * For example, to use an API to that fetches as web page to fetch
+ * two pages and add their lengths:
+ *
+ * {{{
+ *  import ExecutionContext.Implicits.global
+ *  import scala.async.Async.{async, await}
+ *
+ *  def fetchURL(url: URL): Future[String] = ...
+ *
+ *  val sumLengths: Future[Int] = async {
+ *    val body1 = fetchURL("http://scala-lang.org")
+ *    val body2 = fetchURL("http://docs.scala-lang.org")
+ *    await(body1).length + await(body2).length
+ *  }
+ * }}}
+ *
+ * Note that the in the following program, the second fetch does *not* start
+ * until after the first. If you need to start tasks in parallel, you must do
+ * so before `await`-ing a result.
+ *
+ * {{{
+ *  val sumLengths: Future[Int] = async {
+ *    await(fetchURL("http://scala-lang.org")).length + await(fetchURL("http://docs.scala-lang.org")).length
+ *  }
+ * }}}
+ */
+object Async {
+  /**
+   * Run the block of code `body` asynchronously. `body` may contain calls to `await` when the results of
+   * a `Future` are needed; this is translated into non-blocking code.
+   */
+  def async[T](body: T)(implicit execContext: ExecutionContext): Future[T] = macro internal.ScalaConcurrentAsync.asyncImpl[T]
+
+  /**
+   * Non-blocking await the on result of `awaitable`. This may only be used directly within an enclosing `await` block.
+   *
+   * Internally, this will register the remainder of the code in enclosing `async` block as a callback
+   * in the `onComplete` handler of `awaitable`, and will *not* block a thread.
+   */
+  @compileTimeOnly("`await` must be enclosed in an `async` block")
+  def await[T](awaitable: Future[T]): T = ??? // No implementation here, as calls to this are translated to `onComplete` by the macro.
+}

pending/run/fallback0/fallback0.scala

@@ -5,6 +5,8 @@
 package scala.async
 
 /** Internal class used by the `async` macro; should not be manually extended by client code */
+// NOTE: this is not in the `internal` package as we must keep this binary compatible as it extended
+// by the translated code.
 abstract class StateMachine[Result, EC] extends (scala.util.Try[Any] => Unit) with (() => Unit) {
   def result: Result