diff options
author | Philipp Haller <hallerp@gmail.com> | 2007-02-01 17:01:57 +0000 |
---|---|---|
committer | Philipp Haller <hallerp@gmail.com> | 2007-02-01 17:01:57 +0000 |
commit | 039e9821820695dc90ea712126a4de22e3a23341 (patch) | |
tree | c9632949056ba74941c42e55e037be35d091e5db /src/actors | |
parent | 1a605eefa6cbbca331e1e299cd74ce287c00d5d1 (diff) | |
download | scala-039e9821820695dc90ea712126a4de22e3a23341.tar.gz scala-039e9821820695dc90ea712126a4de22e3a23341.tar.bz2 scala-039e9821820695dc90ea712126a4de22e3a23341.zip |
scala.actors: added some more ScalaDoc comments.
Diffstat (limited to 'src/actors')
-rw-r--r-- | src/actors/scala/actors/Actor.scala | 85 | ||||
-rw-r--r-- | src/actors/scala/actors/Channel.scala | 30 | ||||
-rw-r--r-- | src/actors/scala/actors/InputChannel.scala | 4 | ||||
-rw-r--r-- | src/actors/scala/actors/OutputChannel.scala | 4 | ||||
-rw-r--r-- | src/actors/scala/actors/Reaction.scala | 11 | ||||
-rw-r--r-- | src/actors/scala/actors/Scheduler.scala | 19 | ||||
-rw-r--r-- | src/actors/scala/actors/ThreadPoolScheduler.scala | 16 | ||||
-rw-r--r-- | src/actors/scala/actors/TickedScheduler.scala | 3 |
8 files changed, 128 insertions, 44 deletions
diff --git a/src/actors/scala/actors/Actor.scala b/src/actors/scala/actors/Actor.scala index 79ae0e1f83..1da3c683f7 100644 --- a/src/actors/scala/actors/Actor.scala +++ b/src/actors/scala/actors/Actor.scala @@ -51,6 +51,19 @@ object Actor { a*/ } + /** + * <p>This function is used for the definition of actors.</p> + * <p>The following example demonstrates its usage:</p><pre> + * import scala.actors.Actor._ + * ... + * val a = actor { + * ... + * } + * </pre> + * + * @param body the code block to be executed by the newly created actor + * @return the newly created actor. Note that it is automatically started. + */ def actor(body: => Unit): Actor = synchronized { val actor = new Actor { def act() = body @@ -75,6 +88,10 @@ object Actor { } */ + /** + * Receives the next message from the mailbox of the current actor + * <code>self</code>. + */ def ? : Any = self.? /** @@ -82,8 +99,8 @@ object Actor { * <code>self</code>. Blocks if no message matching any of the * cases of <code>f</code> can be received. * - * @param f ... - * @return ... + * @param f a partial function specifying patterns and actions + * @return the result of processing the received message */ def receive[a](f: PartialFunction[Any, a]): a = self.receive(f) @@ -96,36 +113,36 @@ object Actor { * received the <code>TIMEOUT</code> action is executed if * specified. * - * @param msec ... - * @param f ... - * @return ... + * @param msec the time span before timeout + * @param f a partial function specifying patterns and actions + * @return the result of processing the received message */ def receiveWithin[R](msec: long)(f: PartialFunction[Any, R]): R = self.receiveWithin(msec)(f) /** - * <code>receive</code> for event-based reactors. + * Lightweight variant of <code>receive</code>. * * Actions in <code>f</code> have to contain the rest of the * computation of <code>self</code>, as this method will never * return. * - * @param f ... - * @return ... + * @param f a partial function specifying patterns and actions + * @return this function never returns */ def react(f: PartialFunction[Any, Unit]): Nothing = self.react(f) /** - * <code>receiveWithin</code> for event-based reactors. + * Lightweight variant of <code>receiveWithin</code>. * * Actions in <code>f</code> have to contain the rest of the * computation of <code>self</code>, as this method will never * return. * - * @param msec ... - * @param f ... - * @return ... + * @param msec the time span before timeout + * @param f a partial function specifying patterns and actions + * @return this function never returns */ def reactWithin(msec: long)(f: PartialFunction[Any, Unit]): Nothing = self.reactWithin(msec)(f) @@ -172,7 +189,7 @@ object Actor { * Causes <code>self</code> to repeatedly execute * <code>body</code>. * - * @param body ... + * @param body the code block to be executed */ def loop(body: => Unit): Unit = { val s = self @@ -185,8 +202,8 @@ object Actor { * Causes <code>self</code> to execute <code>first</code> * followed by <code>next</code>. * - * @param first ... - * @param next ... + * @param first the first code block to be executed + * @param next the second code block to be executed */ def seq[a, b](first: => a, next: => b): Nothing = { val s = self @@ -199,8 +216,8 @@ object Actor { /** * Links <code>self</code> to actor <code>to</code>. * - * @param to ... - * @return ... + * @param to the actor to link to + * @return */ def link(to: Actor): Actor = self.link(to) @@ -215,7 +232,7 @@ object Actor { /** * Unlinks <code>self</code> from actor <code>from</code>. * - * @param from ... + * @param from the actor to unlink from */ def unlink(from: Actor): Unit = self.unlink(from) @@ -639,3 +656,35 @@ trait Actor extends OutputChannel[Any] { */ case class Exit(from: Actor, reason: String) + +/** + * <p>This object is used as the timeout pattern in + * <code>receiveWithin</code> and <code>reactWithin</code>. + * </p> + * <p>The following example demonstrates its usage:</p><pre> + * receiveWithin(500) { + * case {x, y} => ... + * case TIMEOUT => ... + * } + * </pre> + * + * @version 0.9.2 + * @author Philipp Haller + */ +case object TIMEOUT + + +/** + * <p>This class is used to manage control flow of actor + * executions.</p> + * + * @version 0.9.2 + * @author Philipp Haller + */ +private[actors] class SuspendActorException extends Throwable { + /* + * For efficiency reasons we do not fill in + * the execution stack trace. + */ + override def fillInStackTrace(): Throwable = this +} diff --git a/src/actors/scala/actors/Channel.scala b/src/actors/scala/actors/Channel.scala index 7449f9a4eb..cee8ab5642 100644 --- a/src/actors/scala/actors/Channel.scala +++ b/src/actors/scala/actors/Channel.scala @@ -10,20 +10,24 @@ package scala.actors -import Actor._ - -case object TIMEOUT - -class SuspendActorException extends Throwable { - /* - * For efficiency reasons we do not fill in - * the execution stack trace. - */ - override def fillInStackTrace(): Throwable = { - this - } -} +/** <p> + * This class is 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>. + * </p> + * <p> + * The following example demonstrates its usage: + * </p><pre> + * receive { + * case Chan1 ! msg1 => ... + * case Chan2 ! msg2 => ... + * } + * </pre> + * + * @version 0.9.2 + * @author Philipp Haller + */ case class ! [a](ch: Channel[a], msg: a) /** diff --git a/src/actors/scala/actors/InputChannel.scala b/src/actors/scala/actors/InputChannel.scala index c22671fc93..80f334b30d 100644 --- a/src/actors/scala/actors/InputChannel.scala +++ b/src/actors/scala/actors/InputChannel.scala @@ -11,8 +11,10 @@ package scala.actors /** - * The trait <code>InputChannel</code> ... + * The <code>InputChannel</code> trait provides a common interface + * for all channels from which values can be received. * + * @version 0.9.2 * @author Philipp Haller */ trait InputChannel[Msg] { diff --git a/src/actors/scala/actors/OutputChannel.scala b/src/actors/scala/actors/OutputChannel.scala index 964c9dada1..50cde1a4fa 100644 --- a/src/actors/scala/actors/OutputChannel.scala +++ b/src/actors/scala/actors/OutputChannel.scala @@ -11,8 +11,10 @@ package scala.actors /** - * The trait <code>OutputChannel</code> ... + * The <code>OutputChannel</code> trait provides a common interface + * for all channels to which values can be sent. * + * @version 0.9.2 * @author Philipp Haller */ trait OutputChannel[Msg] { diff --git a/src/actors/scala/actors/Reaction.scala b/src/actors/scala/actors/Reaction.scala index 13e2ed7d5e..fd3f8df0e9 100644 --- a/src/actors/scala/actors/Reaction.scala +++ b/src/actors/scala/actors/Reaction.scala @@ -13,7 +13,16 @@ package scala.actors import java.lang.{InterruptedException, Runnable} -class ExitActorException extends Throwable +/** <p> + * This exception is thrown whenever an actor exits. + * Its purpose is to let <code>exit</code> have + * return type <code>Nothing</code>. + * </p> + * + * @version 0.9.2 + * @author Philipp Haller + */ +private[actors] class ExitActorException extends Throwable /** * The abstract class <code>Reaction</code> associates diff --git a/src/actors/scala/actors/Scheduler.scala b/src/actors/scala/actors/Scheduler.scala index 15852fa7cb..947ad9947d 100644 --- a/src/actors/scala/actors/Scheduler.scala +++ b/src/actors/scala/actors/Scheduler.scala @@ -20,8 +20,7 @@ import scala.collection.mutable.{ArrayBuffer, Buffer, HashMap, Queue, Stack, Has /** * The <code>Scheduler</code> object is used by - * <code>Actor</code> to execute tasks of an execution of a - * reactor. + * <code>Actor</code> to execute tasks of an execution of an actor. * * @version 0.9.2 * @author Philipp Haller @@ -70,7 +69,7 @@ object Scheduler { /** * This abstract class provides a common interface for all - * schedulers used to execute reactors. + * schedulers used to execute actor tasks. * * @version 0.9.2 * @author Philipp Haller @@ -99,7 +98,7 @@ trait IScheduler { /** - * This scheduler executes the tasks of a reactor on a single + * This scheduler executes the tasks of an actor on a single * thread (the current thread). * * @version 0.9.2 @@ -133,16 +132,18 @@ class SingleThreadedScheduler extends IScheduler { /** - * The <code>QuickException</code> class ... + * The <code>QuickException</code> class is used to manage control flow + * of certain schedulers and worker threads. + * + * @version 0.9.2 + * @author Philipp Haller */ -class QuitException extends Throwable { +private[actors] class QuitException extends Throwable { /* For efficiency reasons we do not fill in the execution stack trace. */ - override def fillInStackTrace(): Throwable = { - this - } + override def fillInStackTrace(): Throwable = this } /** diff --git a/src/actors/scala/actors/ThreadPoolScheduler.scala b/src/actors/scala/actors/ThreadPoolScheduler.scala index 2174d90497..eefd9bcbe9 100644 --- a/src/actors/scala/actors/ThreadPoolScheduler.scala +++ b/src/actors/scala/actors/ThreadPoolScheduler.scala @@ -13,7 +13,18 @@ import java.util.concurrent.{ThreadPoolExecutor, TimeUnit, RejectedExecutionHandler} -class TaskRejectedHandler(sched: ThreadPoolScheduler) extends RejectedExecutionHandler { +/** + * This handler is called whenever the thread pool of its + * associated <code>ThreadPoolScheduler</code> is unable + * to serve a request to execute some task. + * + * This handler executes rejected tasks on the thread of + * the scheduler. + * + * @version 0.9.2 + * @author Philipp Haller + */ +private class TaskRejectedHandler(sched: ThreadPoolScheduler) extends RejectedExecutionHandler { def rejectedExecution(r: Runnable, executor: ThreadPoolExecutor) { sched.pendReaction r.run() @@ -22,6 +33,9 @@ class TaskRejectedHandler(sched: ThreadPoolScheduler) extends RejectedExecutionH } /** + * <p>This scheduler uses a thread pool to execute tasks that are generated + * by the execution of actors. This scheduler is only available on Java >= 1.5 + * since it uses <code>java.util.concurrent.ThreadPoolExecutor</code>.</p> * * @version 0.9.2 * @author Philipp Haller diff --git a/src/actors/scala/actors/TickedScheduler.scala b/src/actors/scala/actors/TickedScheduler.scala index 333c1aaa63..2d85263b6d 100644 --- a/src/actors/scala/actors/TickedScheduler.scala +++ b/src/actors/scala/actors/TickedScheduler.scala @@ -9,6 +9,9 @@ import scala.collection.Set import scala.collection.mutable.{ArrayBuffer, Buffer, HashMap, Queue, Stack, HashSet} /** + * <p>This scheduler uses a thread pool to execute tasks that are generated + * by the execution of actors. Unlike <code>ThreadPoolScheduler</code>, this + * scheduler is available on all Java versions >= 1.4.</p> * * @version 0.9.2 * @author Philipp Haller |