Scala 2.6.0-RC2
API Specification

This document is the API specification for Scala Library Documentation

Class Summary
`case class` | ! [a](`val` ch : Channel[a], `val` msg : a)`extends` Product This class is used to pattern match on values that were sent to some channel `Chann` by the current actor `self`. The following example demonstrates its usage:
      receive {
        case Chan1 ! msg1 => ...
        case Chan2 ! msg2 => ...
      }
`trait` | Actor `extends` OutputChannel[Any] This class provides (together with `Channel`) an implementation of event-based actors. The main ideas of our approach are explained in the two papers Event-Based Programming without Inversion of Control, Philipp Haller and Martin Odersky, Proc. JMLC 2006, and Actors that Unify Threads and Events, Philipp Haller and Martin Odersky, LAMP-REPORT-2007-001, EPFL.
`class` | ActorProxy (t : Thread)`extends` Actor The class `ActorProxy` provides a dynamic actor proxy for normal Java threads.
`class` | Channel [Msg]`extends` InputChannel[Msg]`with` OutputChannel[Msg] This class provides a means for typed communication among actors. Only the actor creating an instance of a `Channel` may receive from it.
`class` | Debug (tag : String)`extends` AnyRef
`case class` | Exit (`val` from : Actor, `val` reason : AnyRef)`extends` Product
`class` | ExitActorException `extends` Throwable `with` AnyRef This exception is thrown whenever an actor exits. Its purpose is to let `exit` have return type `Nothing`.
`class` | FJTaskScheduler2 `extends` Thread `with` IScheduler FJTaskScheduler2
`abstract class` | Future [T](`val` ch : InputChannel[Any])`extends` () => T A Future is a function of arity 0 that returns a value of type Any. Applying a future blocks the current actor until its value is available. A future can be queried to find out whether its value is already available.
`trait` | IScheduler `extends` AnyRef This abstract class provides a common interface for all schedulers used to execute actor tasks.
`trait` | InputChannel [+Msg]`extends` AnyRef The `InputChannel` trait provides a common interface for all channels from which values can be received.
`class` | MessageQueue `extends` AnyRef The class `MessageQueue` provides an efficient implementation of a message queue specialized for this actor library. Classes in this package are supposed to be the only clients of this class.
`class` | MessageQueueElement `extends` AnyRef This class is used by our efficient message queue implementation.
`trait` | OutputChannel [Msg]`extends` AnyRef The `OutputChannel` trait provides a common interface for all channels to which values can be sent.
`class` | QuitException `extends` Throwable `with` AnyRef The `QuickException` class is used to manage control flow of certain schedulers and worker threads.
`class` | Reaction (a : Actor, f : PartialFunction[Any, Unit], msg : Any)`extends` Runnable `with` AnyRef
`class` | SingleThreadedScheduler `extends` IScheduler This scheduler executes the tasks of an actor on a single thread (the current thread).
`class` | SuspendActorException `extends` Throwable `with` AnyRef This class is used to manage control flow of actor executions.
`class` | TickedScheduler `extends` Thread `with` IScheduler This scheduler uses a thread pool to execute tasks that are generated by the execution of actors.
`class` | WorkerThread (sched : IScheduler)`extends` Thread `with` AnyRef The class `WorkerThread` is used by schedulers to execute actor tasks on multiple threads. !!ACHTUNG: If you change this, make sure you understand the following proof of deadlock-freedom!! We proof that there is no deadlock between the scheduler and any worker thread possible. For this, note that the scheduler only acquires the lock of a worker thread by calling `execute`. This method is only called when the worker thread is in the idle queue of the scheduler. On the other hand, a worker thread only acquires the lock of the scheduler when it calls `getTask`. At the only callsite of `getTask`, the worker thread holds its own lock. Thus, deadlock can only occur when a worker thread calls `getTask` while it is in the idle queue of the scheduler, because then the scheduler might call (at any time!) `execute` which tries to acquire the lock of the worker thread. In such a situation the worker thread would be waiting to acquire the lock of the scheduler and vice versa. Therefore, to prove deadlock-freedom, it suffices to ensure that a worker thread will never call `getTask` when it is in the idle queue of the scheduler. A worker thread enters the idle queue of the scheduler when `getTask` returns `null`. Then it will also stay in the while-loop W (`while (task eq null)`) until `task` becomes non-null. The only way this can happen is through a call of `execute` by the scheduler. Before every call of `execute` the worker thread is removed from the idle queue of the scheduler. Only then--after executing its task-- the worker thread may call `getTask`. However, the scheduler is unable to call `execute` as the worker thread is not in the idle queue any more. In fact, the scheduler made sure that this is the case even _before_ calling `execute` and thus releasing the worker thread from the while-loop W. Thus, the property holds for every possible interleaving of thread execution. QED

Object Summary
`object` | Actor `extends` AnyRef The `Actor` object provides functions for the definition of actors, as well as all actor operations, such as `receive`, `react`, `reply`, etc.
`object` | Debug `extends` AnyRef
`object` | Futures `extends` AnyRef The `Futures` object contains methods that operate on Futures.
`object` | Scheduler `extends` AnyRef The `Scheduler` object is used by `Actor` to execute tasks of an execution of an actor.
`case object` | TIMEOUT `extends` Product This object is used as the timeout pattern in `receiveWithin` and `reactWithin`. The following example demonstrates its usage:
        receiveWithin(500) {
          case (x, y) => ...
          case TIMEOUT => ...
        }
`object` | TimerThread `extends` AnyRef This class allows the (local) sending of a message to an actor after a timeout. Used by the library to build `receiveWithin(time: long)`. Note that the library deletes non-received `TIMEOUT` message if a message is received before the time-out occurs.