Scala 2

API Specification

This document is the API specification for Scala 2.

Class Summary
case class ! [a]

class ActorProxy
The class ActorProxyprovides a dynamic actor proxy for normal Java threads.
class Channel [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

case class Exit
Messages of this type are sent to each actor a that is linked to an actor b whenever b terminates and a has trapExit set to true.
class ExitActorException

class JDK5Scheduler

class MessageQueue
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
This class is used by our efficient message queue implementation.
class QuitException
The QuickException class ...
class Reaction
The abstract class Reaction associates an instance of an Actor with a java.lang.Runnable.
class SingleThreadedScheduler
This scheduler executes the tasks of a reactor on a single thread (the current thread).
class SuspendActorException

class TaskRejectedHandler

class TickedScheduler

class WorkerThread

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



Trait Summary
abstract trait Actor

This class provides (together with Channel) an implementation of event-based actors.

The main ideas of our approach are explained in the paper
Event-Based Programming without Inversion of Control, Philipp Haller, Martin Odersky Proc. JMLC 2006


abstract trait IScheduler
This abstract class provides a common interface for all schedulers used to execute reactors.
abstract trait InputChannel [Msg]
The trait InputChannel ...
abstract trait OutputChannel [Msg]
The trait OutputChannel ...

Object Summary
object Actor
The Actor object provides functions for the definition of actors, as well as all actor operations, such as receive, react, reply, etc.
object Debug

object Scheduler
The Scheduler object is used by Actor to execute tasks of an execution of a reactor.
case object TIMEOUT

object TimerThread
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.