diff options
20 files changed, 109 insertions, 88 deletions
diff --git a/src/actors/scala/actors/AbstractActor.scala b/src/actors/scala/actors/AbstractActor.scala index 63313ee1f6..3817f9cda3 100644 --- a/src/actors/scala/actors/AbstractActor.scala +++ b/src/actors/scala/actors/AbstractActor.scala @@ -10,8 +10,6 @@ package scala.actors /** - * The <code>AbstractActor</code> trait. - * * @author Philipp Haller * * @define actor actor diff --git a/src/actors/scala/actors/Actor.scala b/src/actors/scala/actors/Actor.scala index 3f83a73256..98f5d2287f 100644 --- a/src/actors/scala/actors/Actor.scala +++ b/src/actors/scala/actors/Actor.scala @@ -13,7 +13,7 @@ import scala.util.control.ControlThrowable import java.util.{Timer, TimerTask} /** - * The <code>Actor</code> object provides functions for the definition of + * Provides functions for the definition of * actors, as well as actor operations, such as * <code>receive</code>, <code>react</code>, <code>reply</code>, * etc. @@ -22,22 +22,22 @@ import java.util.{Timer, TimerTask} */ object Actor extends Combinators { - /** An actor state. An actor can be in one of the following states: + /** State of an actor. * <ul> - * <li>New<br> - * An actor that has not yet started is in this state.</li> - * <li>Runnable<br> - * An actor executing is in this state.</li> - * <li>Suspended<br> - * An actor that is suspended waiting in a react is in this state.</li> - * <li>TimedSuspended<br> - * An actor that is suspended waiting in a reactWithin is in this state.</li> - * <li>Blocked<br> - * An actor that is blocked waiting in a receive is in this state.</li> - * <li>TimedBlocked<br> - * An actor that is blocked waiting in a receiveWithin is in this state.</li> - * <li>Terminated<br> - * An actor that has terminated is in this state.</li> + * <li><b>New</b> - + * Not yet started</li> + * <li><b>Runnable</b> - + * Executing</li> + * <li><b>Suspended</b> - + * Suspended, waiting in a `react`</li> + * <li><b>TimedSuspended</b> - + * Suspended, waiting in a `reactWithin` </li> + * <li><b>Blocked</b> - + * Blocked waiting in a `receive` </li> + * <li><b>TimedBlocked</b> - + * Blocked waiting in a `receiveWithin` </li> + * <li><b>Terminated</b> - + * Actor has terminated </li> * </ul> */ object State extends Enumeration { @@ -115,11 +115,9 @@ object Actor extends Combinators { } /** - * This is a factory method for creating actors. + * Factory method for creating and starting an actor. * - * The following example demonstrates its usage: - * - * {{{ + * @example {{{ * import scala.actors.Actor._ * ... * val a = actor { @@ -140,12 +138,10 @@ object Actor extends Combinators { } /** - * This is a factory method for creating actors whose + * Factory method for creating actors whose * body is defined using a `Responder`. * - * The following example demonstrates its usage: - * - * {{{ + * @example {{{ * import scala.actors.Actor._ * import Responder.exec * ... @@ -182,6 +178,14 @@ object Actor extends Combinators { * <code>self</code>. Blocks if no message matching any of the * cases of <code>f</code> can be received. * + * @example {{{ + * receive { + * case "exit" => println("exiting") + * case 42 => println("got the answer") + * case x:Int => println("got an answer") + * } + * }}} + * * @param f a partial function specifying patterns and actions * @return the result of processing the received message */ @@ -210,6 +214,26 @@ object Actor extends Combinators { * computation of <code>self</code>, as this method will never * return. * + * A common method of continuting the computation is to send a message + * to another actor: + * {{{ + * react { + * case Get(from) => + * react { + * case Put(x) => from ! x + * } + * } + * }}} + * + * Another common method is to use `loop` to continuously `react` to messages: + * {{{ + * loop { + * react { + * case Msg(data) => // process data + * } + * } + * }}} + * * @param f a partial function specifying patterns and actions * @return this function never returns */ @@ -250,14 +274,14 @@ object Actor extends Combinators { rawSelf.sender /** - * Send <code>msg</code> to the actor waiting in a call to + * Sends <code>msg</code> to the actor waiting in a call to * <code>!?</code>. */ def reply(msg: Any): Unit = rawSelf.reply(msg) /** - * Send <code>()</code> to the actor waiting in a call to + * Sends <code>()</code> to the actor waiting in a call to * <code>!?</code>. */ def reply(): Unit = @@ -274,9 +298,7 @@ object Actor extends Combinators { * Converts a synchronous event-based operation into * an asynchronous `Responder`. * - * The following example demonstrates its usage: - * - * {{{ + * @example {{{ * val adder = reactor { * for { * _ <- respondOn(react) { case Add(a, b) => reply(a+b) } @@ -357,7 +379,7 @@ object Actor extends Combinators { /** * <p> - * This trait provides lightweight, concurrent actors. Actors are + * Provides lightweight, concurrent actors. Actors are * created by extending the `Actor` trait (alternatively, one of the * factory methods in its companion object can be used). The * behavior of an `Actor` subclass is defined by implementing its @@ -400,13 +422,13 @@ object Actor extends Combinators { * <li> * <a href="http://lampwww.epfl.ch/~odersky/papers/jmlc06.pdf"> * <span style="font-weight:bold; white-space:nowrap;">Event-Based - * Programming without Inversion of Control</span></a>,<br/> + * Programming without Inversion of Control</span></a>, * Philipp Haller and Martin Odersky, <i>Proc. JMLC 2006</i>, and * </li> * <li> * <a href="http://lamp.epfl.ch/~phaller/doc/haller07coord.pdf"> * <span style="font-weight:bold; white-space:nowrap;">Actors that - * Unify Threads and Events</span></a>,<br/> + * Unify Threads and Events</span></a>, * Philipp Haller and Martin Odersky, <i>Proc. COORDINATION 2007</i>. * </li> * </ul> @@ -484,6 +506,7 @@ trait Actor extends AbstractActor with ReplyReactor with ActorCanReply with Inpu private[actors] override def makeReaction(fun: () => Unit, handler: PartialFunction[Any, Any], msg: Any): Runnable = new ActorTask(this, fun, handler, msg) + /** See the companion object's `receive` method. */ def receive[R](f: PartialFunction[Any, R]): R = { assert(Actor.self(scheduler) == this, "receive from channel belonging to other actor") @@ -527,6 +550,7 @@ trait Actor extends AbstractActor with ReplyReactor with ActorCanReply with Inpu result } + /** See the companion object's `receiveWithin` method. */ def receiveWithin[R](msec: Long)(f: PartialFunction[Any, R]): R = { assert(Actor.self(scheduler) == this, "receive from channel belonging to other actor") @@ -599,6 +623,7 @@ trait Actor extends AbstractActor with ReplyReactor with ActorCanReply with Inpu result } + /** See the companion object's `react` method. */ override def react(handler: PartialFunction[Any, Unit]): Nothing = { synchronized { if (shouldExit) exit() @@ -606,6 +631,7 @@ trait Actor extends AbstractActor with ReplyReactor with ActorCanReply with Inpu super.react(handler) } + /** See the companion object's `reactWithin` method. */ override def reactWithin(msec: Long)(handler: PartialFunction[Any, Unit]): Nothing = { synchronized { if (shouldExit) exit() @@ -613,6 +639,7 @@ trait Actor extends AbstractActor with ReplyReactor with ActorCanReply with Inpu super.reactWithin(msec)(handler) } + /** Receives the next message from the mailbox */ def ? : Any = receive { case x => x } @@ -677,6 +704,7 @@ trait Actor extends AbstractActor with ReplyReactor with ActorCanReply with Inpu this } + /** State of this actor */ override def getState: Actor.State.Value = synchronized { if (isSuspended) { if (onTimeout.isEmpty) @@ -850,27 +878,26 @@ trait Actor extends AbstractActor with ReplyReactor with ActorCanReply with Inpu } -/** <p> - * This object is used as the timeout pattern in +/** + * Used as the timeout pattern in * <a href="Actor.html#receiveWithin(Long)" target="contentFrame"> * <code>receiveWithin</code></a> and * <a href="Actor.html#reactWithin(Long)" target="contentFrame"> * <code>reactWithin</code></a>. - * </p> - * <p> - * The following example demonstrates its usage: - * </p><pre> + * + * @example {{{ * receiveWithin(500) { - * <b>case</b> (x, y) <b>=></b> ... - * <b>case</b> TIMEOUT <b>=></b> ... - * }</pre> + * case (x, y) => ... + * case TIMEOUT => ... + * } + * }}} * * @author Philipp Haller */ case object TIMEOUT -/** An `Exit` message (an instance of this class) is sent to an actor +/** Sent to an actor * with `trapExit` set to `true` whenever one of its linked actors * terminates. * @@ -879,10 +906,7 @@ case object TIMEOUT */ case class Exit(from: AbstractActor, reason: AnyRef) -/** <p> - * This class is used to manage control flow of actor - * executions. - * </p> +/** Manages control flow of actor executions. * * @author Philipp Haller */ diff --git a/src/actors/scala/actors/ActorCanReply.scala b/src/actors/scala/actors/ActorCanReply.scala index da53f482fd..b307aafa57 100644 --- a/src/actors/scala/actors/ActorCanReply.scala +++ b/src/actors/scala/actors/ActorCanReply.scala @@ -12,7 +12,7 @@ package scala.actors import scala.concurrent.SyncVar /** - * The `ActorCanReply` trait provides message send operations that + * Provides message send operations that * may result in a response from the receiver. * * @author Philipp Haller diff --git a/src/actors/scala/actors/ActorProxy.scala b/src/actors/scala/actors/ActorProxy.scala index 7c9c5eab73..d4381ab706 100644 --- a/src/actors/scala/actors/ActorProxy.scala +++ b/src/actors/scala/actors/ActorProxy.scala @@ -12,7 +12,7 @@ package scala.actors import java.lang.Thread /** - * The class <code>ActorProxy</code> provides a dynamic actor proxy for normal + * Provides a dynamic actor proxy for normal * Java threads. * * @author Philipp Haller diff --git a/src/actors/scala/actors/ActorTask.scala b/src/actors/scala/actors/ActorTask.scala index 3c7ef4c2dc..8d0379c095 100644 --- a/src/actors/scala/actors/ActorTask.scala +++ b/src/actors/scala/actors/ActorTask.scala @@ -10,10 +10,7 @@ package scala.actors -/** <p> - * The class <code>ActorTask</code>. - * </p> - * +/** * @author Philipp Haller */ private[actors] class ActorTask(actor: Actor, diff --git a/src/actors/scala/actors/CanReply.scala b/src/actors/scala/actors/CanReply.scala index 6d8667be28..a4619a986e 100644 --- a/src/actors/scala/actors/CanReply.scala +++ b/src/actors/scala/actors/CanReply.scala @@ -12,7 +12,7 @@ package scala.actors import scala.annotation.unique.unique /** - * The <code>CanReply</code> trait defines result-bearing message send operations. + * Defines result-bearing message send operations. * * @author Philipp Haller * diff --git a/src/actors/scala/actors/Channel.scala b/src/actors/scala/actors/Channel.scala index 44ec25b7b3..f4898775fc 100644 --- a/src/actors/scala/actors/Channel.scala +++ b/src/actors/scala/actors/Channel.scala @@ -12,15 +12,14 @@ package scala.actors import scala.concurrent.SyncVar /** - * This class is used to pattern match on values that were sent + * Used to pattern match on values that were sent * to some channel <code>Chan<sub>n</sub></code> by the current * actor <code>self</code>. * - * The following example demonstrates its usage: - * {{{ + * @example {{{ * receive { - * <b>case</b> Chan1 ! msg1 => ... - * <b>case</b> Chan2 ! msg2 => ... + * case Chan1 ! msg1 => ... + * case Chan2 ! msg2 => ... * } * }}} * @@ -29,7 +28,7 @@ import scala.concurrent.SyncVar case class ! [a](ch: Channel[a], msg: a) /** - * This class provides a means for typed communication among + * Provides a means for typed communication among * actors. Only the actor creating an instance of a * <code>Channel</code> may receive from it. * diff --git a/src/actors/scala/actors/Future.scala b/src/actors/scala/actors/Future.scala index 7991b9b288..20e2de47a5 100644 --- a/src/actors/scala/actors/Future.scala +++ b/src/actors/scala/actors/Future.scala @@ -12,9 +12,8 @@ package scala.actors import scala.actors.scheduler.DaemonScheduler import scala.concurrent.SyncVar -/** A `Future[T]` is a function of arity 0 that returns - * a value of type `T`. - * Applying a future blocks the current actor (`Actor.self`) +/** A function of arity 0, returing a value of type `T` that, + * when applied, blocks the current actor (`Actor.self`) * until the future's value is available. * * A future can be queried to find out whether its value @@ -110,7 +109,7 @@ private class FutureActor[T](fun: SyncVar[T] => Unit, channel: Channel[T]) exten } } -/** The `Futures` object contains methods that operate on futures. +/** Methods that operate on futures. * * @author Philipp Haller */ diff --git a/src/actors/scala/actors/IScheduler.scala b/src/actors/scala/actors/IScheduler.scala index 5f91448bb8..5e0b6c0d0c 100644 --- a/src/actors/scala/actors/IScheduler.scala +++ b/src/actors/scala/actors/IScheduler.scala @@ -10,7 +10,7 @@ package scala.actors /** - * The <code>IScheduler</code> trait provides a common interface + * A common interface * for all schedulers used to execute actor tasks. * * Subclasses of <code>Actor</code> that override its diff --git a/src/actors/scala/actors/InputChannel.scala b/src/actors/scala/actors/InputChannel.scala index d5eac40f71..51e739b0fb 100644 --- a/src/actors/scala/actors/InputChannel.scala +++ b/src/actors/scala/actors/InputChannel.scala @@ -10,8 +10,7 @@ package scala.actors /** - * The <code>InputChannel</code> trait provides a common interface - * for all channels from which values can be received. + * A common interface for all channels from which values can be received. * * @author Philipp Haller * diff --git a/src/actors/scala/actors/OutputChannel.scala b/src/actors/scala/actors/OutputChannel.scala index 70de12f12f..d68e49a1b1 100644 --- a/src/actors/scala/actors/OutputChannel.scala +++ b/src/actors/scala/actors/OutputChannel.scala @@ -12,8 +12,7 @@ package scala.actors import scala.annotation.unique.unique /** - * The <code>OutputChannel</code> trait provides a common interface - * for all channels to which values can be sent. + * A common interface for all channels to which values can be sent. * * @author Philipp Haller * diff --git a/src/actors/scala/actors/ReactChannel.scala b/src/actors/scala/actors/ReactChannel.scala index f338ccfcd3..9b6c1c5c77 100644 --- a/src/actors/scala/actors/ReactChannel.scala +++ b/src/actors/scala/actors/ReactChannel.scala @@ -10,8 +10,6 @@ package scala.actors /** - * The <code>ReactChannel</code> trait. - * * @author Philipp Haller */ private[actors] class ReactChannel[Msg](receiver: ReplyReactor) extends InputChannel[Msg] { diff --git a/src/actors/scala/actors/Reactor.scala b/src/actors/scala/actors/Reactor.scala index 3853d7d787..507c18d04e 100644 --- a/src/actors/scala/actors/Reactor.scala +++ b/src/actors/scala/actors/Reactor.scala @@ -46,7 +46,7 @@ private[actors] object Reactor { } /** - * The Reactor trait provides lightweight actors. + * Super trait of all actor traits. * * @author Philipp Haller * diff --git a/src/actors/scala/actors/ReactorCanReply.scala b/src/actors/scala/actors/ReactorCanReply.scala index f6df4ed02f..68f9999776 100644 --- a/src/actors/scala/actors/ReactorCanReply.scala +++ b/src/actors/scala/actors/ReactorCanReply.scala @@ -10,7 +10,7 @@ package scala.actors /** - * The ReactorCanReply trait provides message send operations that + * Provides message send operations that * may result in a response from the receiver. * * @author Philipp Haller diff --git a/src/actors/scala/actors/ReactorTask.scala b/src/actors/scala/actors/ReactorTask.scala index 6d87f880d7..98099c4320 100644 --- a/src/actors/scala/actors/ReactorTask.scala +++ b/src/actors/scala/actors/ReactorTask.scala @@ -14,10 +14,7 @@ import java.util.concurrent.Callable import scala.concurrent.forkjoin.RecursiveAction -/** <p> - * The class <code>ReactorTask</code>. - * </p> - * +/** * @author Philipp Haller */ private[actors] class ReactorTask[Msg >: Null](var reactor: Reactor[Msg], diff --git a/src/actors/scala/actors/ReplyReactor.scala b/src/actors/scala/actors/ReplyReactor.scala index 2e567bf697..85ef0d38d3 100644 --- a/src/actors/scala/actors/ReplyReactor.scala +++ b/src/actors/scala/actors/ReplyReactor.scala @@ -11,12 +11,11 @@ package scala.actors import java.util.{Timer, TimerTask} -/** <p> - * The <code>ReplyReactor</code> trait extends the <code>Reactor</code> +/** + * Extends the [[scala.actors.Reactor]] * trait with methods to reply to the sender of a message. * Sending a message to a <code>ReplyReactor</code> implicitly * passes a reference to the sender together with the message. - * </p> * * @author Philipp Haller * diff --git a/src/actors/scala/actors/ReplyReactorTask.scala b/src/actors/scala/actors/ReplyReactorTask.scala index 9e3e7c0700..1db722f89b 100644 --- a/src/actors/scala/actors/ReplyReactorTask.scala +++ b/src/actors/scala/actors/ReplyReactorTask.scala @@ -10,10 +10,7 @@ package scala.actors -/** <p> - * The class <code>ReplyReactorTask</code>. - * </p> - * +/** * @author Philipp Haller */ private[actors] class ReplyReactorTask(reactor: ReplyReactor, diff --git a/src/actors/scala/actors/Scheduler.scala b/src/actors/scala/actors/Scheduler.scala index 112221a469..8d0cac44ea 100644 --- a/src/actors/scala/actors/Scheduler.scala +++ b/src/actors/scala/actors/Scheduler.scala @@ -13,7 +13,7 @@ import java.util.concurrent._ import scheduler.{DelegatingScheduler, ForkJoinScheduler, ResizableThreadPoolScheduler, ThreadPoolConfig} /** - * The <code>Scheduler</code> object is used by <code>Actor</code> to + * Used by [[scala.actors.Actor]] instances to * execute tasks of an actor execution. * * @author Philipp Haller diff --git a/src/actors/scala/actors/SchedulerAdapter.scala b/src/actors/scala/actors/SchedulerAdapter.scala index ebfd5fe42f..110f3582c9 100644 --- a/src/actors/scala/actors/SchedulerAdapter.scala +++ b/src/actors/scala/actors/SchedulerAdapter.scala @@ -9,8 +9,8 @@ package scala.actors -/** The <code>SchedulerAdapter</code> trait is used to adapt - * the behavior of the standard <code>Scheduler</code> object. +/** Adapts + * the behavior of the standard [[scala.actors.Scheduler]] object. * * Providing an implementation for the * <code>execute(f: => Unit)</code> method is sufficient to diff --git a/src/actors/scala/actors/package.scala b/src/actors/scala/actors/package.scala index 66ba05b1dd..55bc8e113f 100644 --- a/src/actors/scala/actors/package.scala +++ b/src/actors/scala/actors/package.scala @@ -1,5 +1,20 @@ package scala +/** + * A library that provides both asynchronous and synchronous messaging to allow + * for concurrent programming without explicit synchronization. + * + * == Guide == + * + * A detailed guide for the actors library is available + * [[http://www.scala-lang.org/docu/files/actors-api/actors_api_guide.html#]]. + * + * == Getting Started == + * + * A starting point for using the actors library would be [[scala.actors.Reactor]], + * [[scala.actors.ReplyReactor]], or [[scala.actors.Actor]] or their companion objects. + * + */ package object actors { // type of Reactors tracked by termination detector |