Scala 2.6.0-final

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

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.