From a1309ca93b909f364993dc0c50659792fe744781 Mon Sep 17 00:00:00 2001 From: Aleksandar Pokopec Date: Tue, 15 Feb 2011 09:56:39 +0000 Subject: Applying davetron5000's actors docs patches. Review by phaller. --- src/actors/scala/actors/AbstractActor.scala | 2 - src/actors/scala/actors/Actor.scala | 116 +++++++++++++++---------- src/actors/scala/actors/ActorCanReply.scala | 2 +- src/actors/scala/actors/ActorProxy.scala | 2 +- src/actors/scala/actors/ActorTask.scala | 5 +- src/actors/scala/actors/CanReply.scala | 2 +- src/actors/scala/actors/Channel.scala | 11 ++- src/actors/scala/actors/Future.scala | 7 +- src/actors/scala/actors/IScheduler.scala | 2 +- src/actors/scala/actors/InputChannel.scala | 3 +- src/actors/scala/actors/OutputChannel.scala | 3 +- src/actors/scala/actors/ReactChannel.scala | 2 - src/actors/scala/actors/Reactor.scala | 2 +- src/actors/scala/actors/ReactorCanReply.scala | 2 +- src/actors/scala/actors/ReactorTask.scala | 5 +- src/actors/scala/actors/ReplyReactor.scala | 5 +- src/actors/scala/actors/ReplyReactorTask.scala | 5 +- src/actors/scala/actors/Scheduler.scala | 2 +- src/actors/scala/actors/SchedulerAdapter.scala | 4 +- src/actors/scala/actors/package.scala | 15 ++++ 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 AbstractActor 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 Actor object provides functions for the definition of + * Provides functions for the definition of * actors, as well as actor operations, such as * receive, react, reply, * 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. * */ 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 { * self. Blocks if no message matching any of the * cases of f 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 self, 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 msg to the actor waiting in a call to + * Sends msg to the actor waiting in a call to * !?. */ def reply(msg: Any): Unit = rawSelf.reply(msg) /** - * Send () to the actor waiting in a call to + * Sends () to the actor waiting in a call to * !?. */ 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 { /** *

- * 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 { *

  • * * Event-Based - * Programming without Inversion of Control,
    + * Programming without Inversion of Control, * Philipp Haller and Martin Odersky, Proc. JMLC 2006, and *
    • *
  • * * Actors that - * Unify Threads and Events,
    + * Unify Threads and Events, * Philipp Haller and Martin Odersky, Proc. COORDINATION 2007. *
    • * @@ -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 } -/**

    - * This object is used as the timeout pattern in +/** + * Used as the timeout pattern in * * receiveWithin and * * reactWithin. - *

    - *

    - * The following example demonstrates its usage: - * 

    + *
+ * @example {{{
  *    receiveWithin(500) {
- *      case (x, y) => ...
- *      case TIMEOUT => ...
- *    }
    + * 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) -/**

    - * This class is used to manage control flow of actor - * executions. - *

    +/** 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 ActorProxy 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 -/**

    - * The class ActorTask. - *

    - * +/** * @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 CanReply 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 Chann by the current * actor self. * - * The following example demonstrates its usage: - * {{{ + * @example {{{ * receive { - * case Chan1 ! msg1 => ... - * case 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 * Channel 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 IScheduler trait provides a common interface + * A common interface * for all schedulers used to execute actor tasks. * * Subclasses of Actor 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 InputChannel 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 OutputChannel 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 ReactChannel 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 -/**

    - * The class ReactorTask. - *

    - * +/** * @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} -/**

    - * The ReplyReactor trait extends the Reactor +/** + * Extends the [[scala.actors.Reactor]] * trait with methods to reply to the sender of a message. * Sending a message to a ReplyReactor implicitly * passes a reference to the sender together with the message. - *

    * * @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 -/**

    - * The class ReplyReactorTask. - *

    - * +/** * @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 Scheduler object is used by Actor 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 SchedulerAdapter trait is used to adapt - * the behavior of the standard Scheduler object. +/** Adapts + * the behavior of the standard [[scala.actors.Scheduler]] object. * * Providing an implementation for the * execute(f: => Unit) 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 -- cgit v1.2.3