From 97221868047a32d64c4f6a1748fde97d37a16b53 Mon Sep 17 00:00:00 2001 From: Philipp Haller Date: Sun, 11 Apr 2010 16:30:56 +0000 Subject: Completed scaladoc for Reactor and Combinators. --- src/actors/scala/actors/Actor.scala | 5 ++--- src/actors/scala/actors/Combinators.scala | 21 ++++++++++++++------- src/actors/scala/actors/OutputChannel.scala | 14 ++++++-------- src/actors/scala/actors/Reactor.scala | 29 +++++++++++++---------------- 4 files changed, 35 insertions(+), 34 deletions(-) (limited to 'src/actors') diff --git a/src/actors/scala/actors/Actor.scala b/src/actors/scala/actors/Actor.scala index 491c1eb075..c2c967fe69 100644 --- a/src/actors/scala/actors/Actor.scala +++ b/src/actors/scala/actors/Actor.scala @@ -382,6 +382,8 @@ object Actor extends Combinators { * * * @author Philipp Haller + * + * @define actor actor */ @serializable @SerialVersionUID(-781154067877019505L) trait Actor extends AbstractActor with ReplyReactor with ActorCanReply { @@ -605,9 +607,6 @@ trait Actor extends AbstractActor with ReplyReactor with ActorCanReply { _state == Actor.State.Terminated } - /** - * Starts this actor. - */ override def start(): Actor = synchronized { if (_state == Actor.State.New) { _state = Actor.State.Runnable diff --git a/src/actors/scala/actors/Combinators.scala b/src/actors/scala/actors/Combinators.scala index 3c0be7ed15..6082f92323 100644 --- a/src/actors/scala/actors/Combinators.scala +++ b/src/actors/scala/actors/Combinators.scala @@ -12,28 +12,35 @@ package scala.actors private[actors] trait Combinators { + /** + * Enables the composition of suspendable closures using `andThen`, + * `loop`, `loopWhile`, etc. + */ implicit def mkBody[a](body: => a): Actor.Body[a] /** - * Causes self to repeatedly execute - * body. + * Repeatedly executes `body`. * - * @param body the code block to be executed + * @param body the block to be executed */ def loop(body: => Unit): Unit = body andThen loop(body) /** - * Causes self to repeatedly execute - * body while the condition - * cond is true. + * Repeatedly executes `body` while the condition `cond` is `true`. * * @param cond the condition to test - * @param body the code block to be executed + * @param body the block to be executed */ def loopWhile(cond: => Boolean)(body: => Unit): Unit = if (cond) { body andThen loopWhile(cond)(body) } else continue + /** + * Continues with the execution of the closure registered as + * continuation following `andThen`. Continues with the execution + * of the next loop iteration when invoked inside the body of `loop` + * or `loopWhile`. + */ def continue: Unit = throw new KillActorControl } diff --git a/src/actors/scala/actors/OutputChannel.scala b/src/actors/scala/actors/OutputChannel.scala index 514c445944..8bf92b448e 100644 --- a/src/actors/scala/actors/OutputChannel.scala +++ b/src/actors/scala/actors/OutputChannel.scala @@ -15,18 +15,18 @@ package scala.actors * for all channels to which values can be sent. * * @author Philipp Haller + * + * @define actor `OutputChannel` */ trait OutputChannel[-Msg] extends AbstractReactor[Msg] { /** - * Sends msg to this - * OutputChannel (asynchronous). + * Sends msg to this $actor (asynchronous). */ def !(msg: Msg): Unit /** - * Sends msg to this - * OutputChannel (asynchronous) supplying + * Sends msg to this $actor (asynchronous) supplying * explicit reply destination. * * @param msg the message to send @@ -35,14 +35,12 @@ trait OutputChannel[-Msg] extends AbstractReactor[Msg] { def send(msg: Msg, replyTo: OutputChannel[Any]): Unit /** - * Forwards msg to this - * OutputChannel (asynchronous). + * Forwards msg to this $actor (asynchronous). */ def forward(msg: Msg): Unit /** - * Returns the Actor that is - * receiving from this OutputChannel. + * Returns the Actor that is receiving from this $actor. */ def receiver: Actor } diff --git a/src/actors/scala/actors/Reactor.scala b/src/actors/scala/actors/Reactor.scala index db43921056..645b9bc2d3 100644 --- a/src/actors/scala/actors/Reactor.scala +++ b/src/actors/scala/actors/Reactor.scala @@ -50,23 +50,25 @@ private[actors] object Reactor { * The Reactor trait provides lightweight actors. * * @author Philipp Haller + * + * @define actor reactor */ trait Reactor[Msg >: Null] extends OutputChannel[Msg] with Combinators { - /* The actor's mailbox. */ + /* The $actor's mailbox. */ private[actors] val mailbox = new MQueue[Msg]("Reactor") // guarded by this private[actors] val sendBuffer = new MQueue[Msg]("SendBuffer") - /* Whenever this actor executes on some thread, `waitingFor` is + /* Whenever this $actor executes on some thread, `waitingFor` is * guaranteed to be equal to `Reactor.waitingForNone`. * * In other words, whenever `waitingFor` is not equal to - * `Reactor.waitingForNone`, this actor is guaranteed not to execute + * `Reactor.waitingForNone`, this $actor is guaranteed not to execute * on some thread. * - * If the actor waits in a `react`, `waitingFor` holds the + * If the $actor waits in a `react`, `waitingFor` holds the * message handler that `react` was called with. * * guarded by this @@ -78,8 +80,7 @@ trait Reactor[Msg >: Null] extends OutputChannel[Msg] with Combinators { private[actors] var _state: Actor.State.Value = Actor.State.New /** - * The behavior of a Reactor is specified by implementing - * this method. + * The $actor's behavior is specified by implementing this method. */ def act(): Unit @@ -92,13 +93,6 @@ trait Reactor[Msg >: Null] extends OutputChannel[Msg] with Combinators { protected[actors] def mailboxSize: Int = mailbox.size - /** - * Sends msg to this actor (asynchronous) supplying - * explicit reply destination. - * - * @param msg the message to send - * @param replyTo the reply destination - */ def send(msg: Msg, replyTo: OutputChannel[Any]) { val todo = synchronized { if (waitingFor ne Reactor.waitingForNone) { @@ -194,7 +188,7 @@ trait Reactor[Msg >: Null] extends OutputChannel[Msg] with Combinators { } /** - * Receives a message from this actor's mailbox. + * Receives a message from this $actor's mailbox. *

* This method never returns. Therefore, the rest of the computation * has to be contained in the actions of the partial function. @@ -208,7 +202,7 @@ trait Reactor[Msg >: Null] extends OutputChannel[Msg] with Combinators { } /* This method is guaranteed to be executed from inside - * an actors act method. + * an $actor's act method. * * assume handler != null * @@ -218,6 +212,9 @@ trait Reactor[Msg >: Null] extends OutputChannel[Msg] with Combinators { scheduler executeFromActor makeReaction(null, handler, msg) } + /** + * Starts this $actor. + */ def start(): Reactor[Msg] = synchronized { if (_state == Actor.State.New) { _state = Actor.State.Runnable @@ -228,7 +225,7 @@ trait Reactor[Msg >: Null] extends OutputChannel[Msg] with Combinators { this } - /** Returns the execution state of this actor. + /** Returns the execution state of this $actor. * * @return the execution state */ -- cgit v1.2.3