From 8ee1f32478b63286b450a1ac5200ce4da39e69ff Mon Sep 17 00:00:00 2001 From: Philipp Haller Date: Sun, 11 Apr 2010 17:43:54 +0000 Subject: Scaladoc clean-ups for various actor and channe... Scaladoc clean-ups for various actor and channel types. Actor now extends InputChannel. Channel now extends CanReply. Review by plocinic. --- src/actors/scala/actors/AbstractActor.scala | 2 + src/actors/scala/actors/Actor.scala | 20 +------- src/actors/scala/actors/ActorCanReply.scala | 29 +---------- src/actors/scala/actors/CanReply.scala | 10 ++-- src/actors/scala/actors/Channel.scala | 72 ++------------------------- src/actors/scala/actors/InputChannel.scala | 16 +++--- src/actors/scala/actors/Reactor.scala | 2 +- src/actors/scala/actors/ReactorCanReply.scala | 27 ---------- src/actors/scala/actors/ReplyReactor.scala | 14 ++---- 9 files changed, 30 insertions(+), 162 deletions(-) (limited to 'src/actors') diff --git a/src/actors/scala/actors/AbstractActor.scala b/src/actors/scala/actors/AbstractActor.scala index 9cc62a1cde..80b1e76b30 100644 --- a/src/actors/scala/actors/AbstractActor.scala +++ b/src/actors/scala/actors/AbstractActor.scala @@ -14,6 +14,8 @@ package scala.actors * The AbstractActor trait. * * @author Philipp Haller + * + * @define actor actor */ trait AbstractActor extends OutputChannel[Any] with CanReply[Any, Any] { diff --git a/src/actors/scala/actors/Actor.scala b/src/actors/scala/actors/Actor.scala index c2c967fe69..ccd60f666c 100644 --- a/src/actors/scala/actors/Actor.scala +++ b/src/actors/scala/actors/Actor.scala @@ -384,9 +384,10 @@ object Actor extends Combinators { * @author Philipp Haller * * @define actor actor + * @define channel actor's mailbox */ @serializable @SerialVersionUID(-781154067877019505L) -trait Actor extends AbstractActor with ReplyReactor with ActorCanReply { +trait Actor extends AbstractActor with ReplyReactor with ActorCanReply with InputChannel[Any] { /* The following two fields are only used when the actor * suspends by blocking its underlying thread, for example, @@ -415,12 +416,6 @@ trait Actor extends AbstractActor with ReplyReactor with ActorCanReply { private[actors] override def makeReaction(fun: () => Unit, handler: PartialFunction[Any, Any], msg: Any): Runnable = new ActorTask(this, fun, handler, msg) - /** - * Receives a message from this actor's mailbox. - * - * @param f a partial function with message patterns and actions - * @return result of processing the received value - */ def receive[R](f: PartialFunction[Any, R]): R = { assert(Actor.self(scheduler) == this, "receive from channel belonging to other actor") @@ -464,14 +459,6 @@ trait Actor extends AbstractActor with ReplyReactor with ActorCanReply { result } - /** - * Receives a message from this actor's mailbox within a certain - * time span. - * - * @param msec the time span before timeout - * @param f a partial function with message patterns and actions - * @return result of processing the received value - */ def receiveWithin[R](msec: Long)(f: PartialFunction[Any, R]): R = { assert(Actor.self(scheduler) == this, "receive from channel belonging to other actor") @@ -558,9 +545,6 @@ trait Actor extends AbstractActor with ReplyReactor with ActorCanReply { super.reactWithin(msec)(handler) } - /** - * Receives the next message from this actor's mailbox. - */ def ? : Any = receive { case x => x } diff --git a/src/actors/scala/actors/ActorCanReply.scala b/src/actors/scala/actors/ActorCanReply.scala index 8cba425b4c..fdc3833ec4 100644 --- a/src/actors/scala/actors/ActorCanReply.scala +++ b/src/actors/scala/actors/ActorCanReply.scala @@ -13,7 +13,7 @@ package scala.actors import java.util.concurrent.ExecutionException /** - * The ActorCanReply trait provides message send operations that + * The `ActorCanReply` trait provides message send operations that * may result in a response from the receiver. * * @author Philipp Haller @@ -21,13 +21,6 @@ import java.util.concurrent.ExecutionException private[actors] trait ActorCanReply extends ReactorCanReply { thiz: AbstractActor with ReplyReactor => - /** - * Sends msg to this actor and awaits reply - * (synchronous). - * - * @param msg the message to be sent - * @return the reply - */ override def !?(msg: Any): Any = { val replyCh = new Channel[Any](Actor.self(thiz.scheduler)) thiz.send(msg, replyCh) @@ -36,15 +29,6 @@ private[actors] trait ActorCanReply extends ReactorCanReply { } } - /** - * Sends msg to this actor and awaits reply - * (synchronous) within msec milliseconds. - * - * @param msec the time span before timeout - * @param msg the message to be sent - * @return None in case of timeout, otherwise - * Some(x) where x is the reply - */ override def !?(msec: Long, msg: Any): Option[Any] = { val replyCh = new Channel[Any](Actor.self(thiz.scheduler)) thiz.send(msg, replyCh) @@ -54,13 +38,6 @@ private[actors] trait ActorCanReply extends ReactorCanReply { } } - /** - * Sends msg to this actor and immediately - * returns a future representing the reply value. - * The reply is post-processed using the partial function - * handler. This also allows to recover a more - * precise type for the reply value. - */ override def !![A](msg: Any, handler: PartialFunction[Any, A]): Future[A] = { val ftch = new Channel[A](Actor.self(thiz.scheduler)) thiz.send(msg, new OutputChannel[Any] { @@ -76,10 +53,6 @@ private[actors] trait ActorCanReply extends ReactorCanReply { Futures.fromInputChannel(ftch) } - /** - * Sends msg to this actor and immediately - * returns a future representing the reply value. - */ override def !!(msg: Any): Future[Any] = { val ftch = new Channel[Any](Actor.self(thiz.scheduler)) val linkedChannel = new AbstractActor { diff --git a/src/actors/scala/actors/CanReply.scala b/src/actors/scala/actors/CanReply.scala index 23f0a5319b..99e1169900 100644 --- a/src/actors/scala/actors/CanReply.scala +++ b/src/actors/scala/actors/CanReply.scala @@ -14,11 +14,13 @@ package scala.actors * The CanReply trait defines result-bearing message send operations. * * @author Philipp Haller + * + * @define actor `CanReply` */ trait CanReply[-T, +R] { /** - * Sends msg to this CanReply and + * Sends msg to this $actor and * awaits reply (synchronous). * * @param msg the message to be sent @@ -27,7 +29,7 @@ trait CanReply[-T, +R] { def !?(msg: T): R /** - * Sends msg to this CanReply and + * Sends msg to this $actor and * awaits reply (synchronous) within msec * milliseconds. * @@ -39,7 +41,7 @@ trait CanReply[-T, +R] { def !?(msec: Long, msg: T): Option[R] /** - * Sends msg to this CanReply and + * Sends msg to this $actor and * immediately returns a future representing the reply value. * * @param msg the message to be sent @@ -49,7 +51,7 @@ trait CanReply[-T, +R] { () => this !? msg /** - * Sends msg to this CanReply and + * Sends msg to this $actor and * immediately returns a future representing the reply value. * The reply is post-processed using the partial function * handler. This also allows to recover a more diff --git a/src/actors/scala/actors/Channel.scala b/src/actors/scala/actors/Channel.scala index 4c37de7665..e40a804e4a 100644 --- a/src/actors/scala/actors/Channel.scala +++ b/src/actors/scala/actors/Channel.scala @@ -35,45 +35,26 @@ case class ! [a](ch: Channel[a], msg: a) * Channel may receive from it. * * @author Philipp Haller + * + * @define actor channel + * @define channel channel */ -class Channel[Msg](val receiver: Actor) extends InputChannel[Msg] with OutputChannel[Msg] { +class Channel[Msg](val receiver: Actor) extends InputChannel[Msg] with OutputChannel[Msg] with CanReply[Msg, Any] { def this() = this(Actor.self) - /** - * Sends a message to this Channel. - * - * @param msg the message to be sent - */ def !(msg: Msg) { receiver ! scala.actors.!(this, msg) } - /** - * Sends a message to this Channel - * (asynchronous) supplying explicit reply destination. - * - * @param msg the message to send - * @param replyTo the reply destination - */ def send(msg: Msg, replyTo: OutputChannel[Any]) { receiver.send(scala.actors.!(this, msg), replyTo) } - /** - * Forwards msg to this keeping the - * last sender as sender instead of self. - */ def forward(msg: Msg) { receiver forward scala.actors.!(this, msg) } - /** - * Receives a message from this Channel. - * - * @param f a partial function with message patterns and actions - * @return result of processing the received value - */ def receive[R](f: PartialFunction[Msg, R]): R = { val C = this.asInstanceOf[Channel[Any]] val recvActor = receiver.asInstanceOf[Actor] @@ -82,21 +63,10 @@ class Channel[Msg](val receiver: Actor) extends InputChannel[Msg] with OutputCha } } - /** - * Receives the next message from this Channel. - */ def ? : Msg = receive { case x => x } - /** - * Receives a message from this Channel within a certain - * time span. - * - * @param msec the time span before timeout - * @param f a partial function with message patterns and actions - * @return result of processing the received value - */ def receiveWithin[R](msec: Long)(f: PartialFunction[Any, R]): R = { val C = this.asInstanceOf[Channel[Any]] val recvActor = receiver.asInstanceOf[Actor] @@ -106,14 +76,6 @@ class Channel[Msg](val receiver: Actor) extends InputChannel[Msg] with OutputCha } } - /** - * Receives a message from this Channel. - *

- * This method never returns. Therefore, the rest of the computation - * has to be contained in the actions of the partial function. - * - * @param f a partial function with message patterns and actions - */ def react(f: PartialFunction[Msg, Unit]): Nothing = { val C = this.asInstanceOf[Channel[Any]] receiver.react { @@ -121,16 +83,6 @@ class Channel[Msg](val receiver: Actor) extends InputChannel[Msg] with OutputCha } } - /** - * Receives a message from this Channel within a certain - * time span. - *

- * This method never returns. Therefore, the rest of the computation - * has to be contained in the actions of the partial function. - * - * @param msec the time span before timeout - * @param f a partial function with message patterns and actions - */ def reactWithin(msec: Long)(f: PartialFunction[Any, Unit]): Nothing = { val C = this.asInstanceOf[Channel[Any]] val recvActor = receiver.asInstanceOf[Actor] @@ -140,13 +92,6 @@ class Channel[Msg](val receiver: Actor) extends InputChannel[Msg] with OutputCha } } - /** - * Sends a message to this Channel and - * awaits reply. - * - * @param msg the message to be sent - * @return the reply - */ def !?(msg: Msg): Any = { val replyCh = new Channel[Any](Actor.self(receiver.scheduler)) receiver.send(scala.actors.!(this, msg), replyCh) @@ -155,15 +100,6 @@ class Channel[Msg](val receiver: Actor) extends InputChannel[Msg] with OutputCha } } - /** - * Sends a message to this Channel and - * awaits reply within a certain time span. - * - * @param msec the time span before timeout - * @param msg the message to be sent - * @return None in case of timeout, otherwise - * Some(x) where x is the reply - */ def !?(msec: Long, msg: Msg): Option[Any] = { val replyCh = new Channel[Any](Actor.self(receiver.scheduler)) receiver.send(scala.actors.!(this, msg), replyCh) diff --git a/src/actors/scala/actors/InputChannel.scala b/src/actors/scala/actors/InputChannel.scala index fa2fad43c6..dfe26b3462 100644 --- a/src/actors/scala/actors/InputChannel.scala +++ b/src/actors/scala/actors/InputChannel.scala @@ -15,11 +15,13 @@ package scala.actors * for all channels from which values can be received. * * @author Philipp Haller + * + * @define channel `InputChannel` */ trait InputChannel[+Msg] { /** - * Receives a message from this InputChannel. + * Receives a message from this $channel. * * @param f a partial function with message patterns and actions * @return result of processing the received value @@ -27,7 +29,7 @@ trait InputChannel[+Msg] { def receive[R](f: PartialFunction[Msg, R]): R /** - * Receives a message from this InputChannel within + * Receives a message from this $channel within * a certain time span. * * @param msec the time span before timeout @@ -37,8 +39,8 @@ trait InputChannel[+Msg] { def receiveWithin[R](msec: Long)(f: PartialFunction[Any, R]): R /** - * Receives a message from this InputChannel. - *

+ * Receives a message from this $channel. + * * This method never returns. Therefore, the rest of the computation * has to be contained in the actions of the partial function. * @@ -47,9 +49,9 @@ trait InputChannel[+Msg] { def react(f: PartialFunction[Msg, Unit]): Nothing /** - * Receives a message from this InputChannel within + * Receives a message from this $channel within * a certain time span. - *

+ * * This method never returns. Therefore, the rest of the computation * has to be contained in the actions of the partial function. * @@ -59,7 +61,7 @@ trait InputChannel[+Msg] { def reactWithin(msec: Long)(f: PartialFunction[Any, Unit]): Nothing /** - * Receives the next message from this Channel. + * Receives the next message from this $channel. */ def ? : Msg } diff --git a/src/actors/scala/actors/Reactor.scala b/src/actors/scala/actors/Reactor.scala index 645b9bc2d3..a5bdcf1dd9 100644 --- a/src/actors/scala/actors/Reactor.scala +++ b/src/actors/scala/actors/Reactor.scala @@ -189,7 +189,7 @@ trait Reactor[Msg >: Null] extends OutputChannel[Msg] with Combinators { /** * 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. * diff --git a/src/actors/scala/actors/ReactorCanReply.scala b/src/actors/scala/actors/ReactorCanReply.scala index c53e3a78e1..9002a55b87 100644 --- a/src/actors/scala/actors/ReactorCanReply.scala +++ b/src/actors/scala/actors/ReactorCanReply.scala @@ -19,25 +19,9 @@ package scala.actors private[actors] trait ReactorCanReply extends CanReply[Any, Any] { _: ReplyReactor => - /** - * Sends msg to this actor and awaits reply - * (synchronous). - * - * @param msg the message to be sent - * @return the reply - */ def !?(msg: Any): Any = (this !! msg)() - /** - * Sends msg to this actor and awaits reply - * (synchronous) within msec milliseconds. - * - * @param msec the time span before timeout - * @param msg the message to be sent - * @return None in case of timeout, otherwise - * Some(x) where x is the reply - */ def !?(msec: Long, msg: Any): Option[Any] = { val myself = Actor.rawSelf(this.scheduler) val res = new scala.concurrent.SyncVar[Any] @@ -55,20 +39,9 @@ private[actors] trait ReactorCanReply extends CanReply[Any, Any] { res.get(msec) } - /** - * Sends msg to this actor and immediately - * returns a future representing the reply value. - */ override def !!(msg: Any): Future[Any] = this !! (msg, { case x => x }) - /** - * Sends msg to this actor and immediately - * returns a future representing the reply value. - * The reply is post-processed using the partial function - * handler. This also allows to recover a more - * precise type for the reply value. - */ override def !![A](msg: Any, handler: PartialFunction[Any, A]): Future[A] = { val myself = Actor.rawSelf(this.scheduler) val ftch = new ReactChannel[A](myself) diff --git a/src/actors/scala/actors/ReplyReactor.scala b/src/actors/scala/actors/ReplyReactor.scala index 26057ab9cb..665ed3091f 100644 --- a/src/actors/scala/actors/ReplyReactor.scala +++ b/src/actors/scala/actors/ReplyReactor.scala @@ -20,6 +20,8 @@ import java.util.{Timer, TimerTask} *

* * @author Philipp Haller + * + * @define actor `ReplyReactor` */ trait ReplyReactor extends Reactor[Any] with ReactorCanReply { @@ -38,7 +40,7 @@ trait ReplyReactor extends Reactor[Any] with ReactorCanReply { private[actors] var onTimeout: Option[TimerTask] = None /** - * Returns the actor which sent the last received message. + * Returns the $actor which sent the last received message. */ protected[actors] def sender: OutputChannel[Any] = senders.head @@ -49,16 +51,10 @@ trait ReplyReactor extends Reactor[Any] with ReactorCanReply { sender ! msg } - /** - * Sends msg to this actor (asynchronous). - */ override def !(msg: Any) { send(msg, Actor.rawSelf(scheduler)) } - /** - * Forwards msg to this actor (asynchronous). - */ override def forward(msg: Any) { send(msg, Actor.sender) } @@ -115,9 +111,9 @@ trait ReplyReactor extends Reactor[Any] with ReactorCanReply { } /** - * Receives a message from this actor's mailbox within a certain + * Receives a message from this $actor's mailbox within a certain * time span. - *

+ * * This method never returns. Therefore, the rest of the computation * has to be contained in the actions of the partial function. * -- cgit v1.2.3