scala.util

# continuations

#### package continuations

Delimited continuations are a feature for modifying the usual control flow of a program. To use continuations, provide the option `-P:continuations:enable` to the Scala compiler or REPL to activate the compiler plugin.

Below is an example of using continuations to suspend execution while awaiting user input. Similar facilities are used in so-called continuation-based web frameworks.

    def go =
    reset {
      println("Welcome!")
      val first = ask("Please give me a number")
      val second = ask("Please enter another number")
      printf("The sum of your numbers is: %d\n", first + second)
    }

The `reset` is provided by this package and delimits the extent of the transformation. The `ask` is a function that will be defined below. Its effect is to issue a prompt and then suspend execution awaiting user input. Once the user provides an input value, execution of the suspended block resumes.

    val sessions = new HashMap[UUID, Int=>Unit]
    def ask(prompt: String): Int @cps[Unit] =
      shift {
        k: (Int => Unit) => {
          val id = uuidGen
          printf("%s\nrespond with: submit(0x%x, ...)\n", prompt, id)
          sessions += id -> k
        }
      }

The type of `ask` includes a `@cps` annotation which drives the transformation. The type signature `Int @cps[Unit]` means that `ask` should be used in a context requiring an `Int`, but actually it will suspend and return `Unit`.

The computation leading up to the first `ask` is executed normally. The remainder of the reset block is wrapped into a closure that is passed as the parameter `k` to the `shift` function, which can then decide whether and how to execute the continuation. In this example, the continuation is stored in a sessions map for later execution. This continuation includes a second call to `ask`, which is treated likewise once the execution resumes.

#### CPS Annotation

The aforementioned `@cps[A]` annotation is an alias for the more general `@cpsParam[B,C]` where `B=C`. The type `A @cpsParam[B,C]` describes a term which yields a value of type `A` within an evaluation context producing a value of type `B`. After the CPS transformation, this return type is modified to `C`.

The `@cpsParam` annotations are introduced by `shift` blocks, and propagate via the return types to the dynamically enclosing context. The propagation stops upon reaching a `reset` block.

Linear Supertypes
AnyRef, Any
Ordering

1. Alphabetic
2. By inheritance

Inherited

1. continuations
2. AnyRef
3. Any

1. Hide All
2. Show all

Learn more about member selection
Visibility

1. Public
2. All

### Type Members

1. #### final class ControlContext[+A, -B, +C] extends Serializable

   This class represent a portion of computation that has a 'hole' in it.

2. #### type cps[A] = cpsParam[A, A]

   An annotation that denotes a type is part of a continuation context.

   An annotation that denotes a type is part of a continuation context. `@cps[A]` is shorthand for `cpsParam[A,A]`.

3. #### class cpsParam[-B, +C] extends Annotation with StaticAnnotation with TypeConstraint

   This annotation is used to mark a parameter as part of a continuation context.

4. #### type suspendable = cpsParam[Unit, Unit]

   An annotation that denotes a type is part of a side effecting continuation context.

   An annotation that denotes a type is part of a side effecting continuation context. `@suspendable` is shorthand notation for `@cpsParam[Unit,Unit]` or `@cps[Unit]`.

### Value Members

1. #### def reify[A, B, C](ctx: ⇒ A @scala.util.continuations.cpsParam[B,C]): ControlContext[A, B, C]

   This method converts from the sugared `A @cpsParam[B,C]` type to the desugared `ControlContext[A,B,C]` type.

   This method converts from the sugared `A @cpsParam[B,C]` type to the desugared `ControlContext[A,B,C]` type. The underlying data is not changed.

2. #### def reifyR[A, B, C](ctx: ⇒ ControlContext[A, B, C]): ControlContext[A, B, C]

3. #### def reset[A, C](ctx: ⇒ A @scala.util.continuations.cpsParam[A,C]): C

   Creates a context for continuations captured within the argument closure of this `reset` call and returns the result of the entire transformed computation.

   Creates a context for continuations captured within the argument closure of this `reset` call and returns the result of the entire transformed computation. Within an expression of the form `reset { block }`, the closure expression (`block`) will be modified such that at each call to `shift` the remainder of the expression is transformed into a function to be passed into the shift.

   returns

     The result of a block of code that uses `shift` to capture continuations.

4. #### def reset0[A](ctx: ⇒ A @scala.util.continuations.cpsParam[A,A]): A

5. #### def run[A](ctx: ⇒ Any @scala.util.continuations.cpsParam[Unit,A]): A

6. #### def shift[A, B, C](fun: ((A) ⇒ B) ⇒ C): A @scala.util.continuations.cpsParam[B,C]

   The `shift` function captures the remaining computation in a `reset` block and passes it to a closure provided by the user.

   The `shift` function captures the remaining computation in a `reset` block and passes it to a closure provided by the user.

   For example:

       reset {
       shift { (k: Int => Int) => k(5) } + 1
       }

   In this example, `shift` is used in the expression `shift ... + 1`. The compiler will alter this expression so that the call to `shift` becomes a parameter to a function, creating something like:

       { (k: Int => Int) => k(5) } apply { _ + 1 }

   The result of this expression is 6.

   There can be more than one `shift` call in a `reset` block. Each call to `shift` can alter the return type of expression within the reset block, but will not change the return type of the entire `reset { block }` expression.

   fun

     A function where

     - The parameter is the remainder of computation within the current `reset` block. This is passed as a function `A => B`.
     - The return is the return value of the `ControlContext` which is generated from this inversion.
   Note

     Must be invoked in the context of a call to `reset` This context may not be far up the stack, but a call to reset is needed to eventually remove the `@cps` annotations from types.

7. #### def shiftR[A, B, C](fun: ((A) ⇒ B) ⇒ C): ControlContext[A, B, C]

   Captures a computation into a `ControlContext`.

   Captures a computation into a `ControlContext`.

   fun

     The function which accepts the inverted computation and returns a final result.

   See also

     shift

8. #### def shiftUnit[A, B, C >: B](x: A): A @scala.util.continuations.cpsParam[B,C]

9. #### def shiftUnit0[A, B](x: A): A @scala.util.continuations.cpsParam[B,B]

10. #### def shiftUnitR[A, B](x: A): ControlContext[A, B, B]

### Inherited from AnyRef

### Inherited from Any

### Ungrouped