raboof/pekko
1
0
Fork 0
Code Issues Pull requests Projects Releases 6 Packages Wiki Activity Actions 10

Merge pull request #1602 from akka/wip-3152-scaladoc-patriknw

Browse source 
Improve ScalaDoc/JavaDoc, see #3152
This commit is contained in:
Roland Kuhn 2013-07-08 02:49:08 -07:00
commit 5f8a7ded76
25 changed files with 246 additions and 286 deletions
Download patch file Download diff file Expand all files Collapse all files

8
akka-actor/src/main/scala/akka/Main.scala
View file

@ -13,8 +13,16 @@ import akka.actor.Props
import akka.actor.ActorRef
import scala.util.control.NonFatal
/**
* Main class to start an [[akka.actor.ActorSystem]] with one
* top level application supervisor actor. It will shutdown
* the actor system when the top level actor is terminated.
*/
object Main {
/**
* @params args one argument: the class of the application supervisor actor
*/
def main(args: Array[String]): Unit = {
if (args.length != 1) {
println("you need to provide exactly one argument: the class of the application supervisor actor")

21
akka-actor/src/main/scala/akka/actor/Actor.scala
View file

@ -185,7 +185,7 @@ private[akka] case class SelectParent(next: Any) extends SelectionPath
case class IllegalActorStateException private[akka] (message: String) extends AkkaException(message)
/**
* ActorKilledException is thrown when an Actor receives the akka.actor.Kill message
* ActorKilledException is thrown when an Actor receives the [[akka.actor.Kill]] message
*/
@SerialVersionUID(1L)
case class ActorKilledException private[akka] (message: String) extends AkkaException(message) with NoStackTrace
@ -320,7 +320,8 @@ object Status {
}
/**
* Mix in ActorLogging into your Actor to easily obtain a reference to a logger, which is available under the name "log".
* Scala API: Mix in ActorLogging into your Actor to easily obtain a reference to a logger,
* which is available under the name "log".
*
* {{{
* class MyActor extends Actor with ActorLogging {
@ -365,7 +366,7 @@ object Actor {
*
* An actor has a well-defined (non-cyclic) life-cycle.
* - ''RUNNING'' (created and started actor) - can receive messages
* - ''SHUTDOWN'' (when 'stop' or 'exit' is invoked) - can't do anything
* - ''SHUTDOWN'' (when 'stop' is invoked) - can't do anything
*
* The Actor's own [[akka.actor.ActorRef]] is available as `self`, the current
* message’s sender as `sender` and the [[akka.actor.ActorContext]] as
@ -379,10 +380,10 @@ object Actor {
* class ExampleActor extends Actor {
*
* override val supervisorStrategy = OneForOneStrategy(maxNrOfRetries = 10, withinTimeRange = 1 minute) {
* case _: ArithmeticException ⇒ Resume
* case _: NullPointerException ⇒ Restart
* case _: IllegalArgumentException ⇒ Stop
* case _: Exception ⇒ Escalate
* case _: ArithmeticException => Resume
* case _: NullPointerException => Restart
* case _: IllegalArgumentException => Stop
* case _: Exception => Escalate
* }
*
* def receive = {
@ -392,7 +393,7 @@ object Actor {
* // just to demonstrate how to stop yourself
* case Shutdown => context.stop(self)
*
* // error kernel with child replying directly to “customer”
* // error kernel with child replying directly to 'sender'
* case Dangerous(r) => context.actorOf(Props[ReplyToOriginWorker]).tell(PerformWork(r), sender)
*
* // error kernel with reply going through us
@ -429,7 +430,7 @@ trait Actor {
* [[akka.actor.UntypedActorContext]], which is the Java API of the actor
* context.
*/
protected[akka] implicit val context: ActorContext = {
implicit val context: ActorContext = {
val contextStack = ActorCell.contextStack.get
if ((contextStack.isEmpty) || (contextStack.head eq null))
throw ActorInitializationException(
@ -540,7 +541,7 @@ trait Actor {
* case of an unhandled [[akka.actor.Terminated]] message) or publishes an [[akka.actor.UnhandledMessage]]
* to the actor's system's [[akka.event.EventStream]]
*/
def unhandled(message: Any) {
def unhandled(message: Any): Unit = {
message match {
case Terminated(dead) ⇒ throw new DeathPactException(dead)
case _ ⇒ context.system.eventStream.publish(UnhandledMessage(message, sender, self))

14
akka-actor/src/main/scala/akka/actor/ActorCell.scala
View file

@ -52,13 +52,13 @@ trait ActorContext extends ActorRefFactory {
/**
* Gets the current receive timeout.
* When specified, the receive method should be able to handle a 'ReceiveTimeout' message.
* When specified, the receive method should be able to handle a [[akka.actor.ReceiveTimeout]] message.
*/
def receiveTimeout: Duration
/**
* Defines the inactivity timeout after which the sending of a `ReceiveTimeout` message is triggered.
* When specified, the receive function should be able to handle a 'ReceiveTimeout' message.
* Defines the inactivity timeout after which the sending of a [[akka.actor.ReceiveTimeout]] message is triggered.
* When specified, the receive function should be able to handle a [[akka.actor.ReceiveTimeout]] message.
* 1 millisecond is the minimum supported timeout.
*
* Please note that the receive timeout might fire and enqueue the `ReceiveTimeout` message right after
@ -113,13 +113,13 @@ trait ActorContext extends ActorRefFactory {
/**
* Returns the dispatcher (MessageDispatcher) that is used for this Actor.
* Importing this member will place a implicit MessageDispatcher in scope.
* Importing this member will place a implicit ExecutionContext in scope.
*/
implicit def dispatcher: ExecutionContext
/**
* The system that the actor belongs to.
* Importing this member will place a implicit MessageDispatcher in scope.
* Importing this member will place a implicit ExecutionContext in scope.
*/
implicit def system: ActorSystem
@ -130,8 +130,8 @@ trait ActorContext extends ActorRefFactory {
/**
* Registers this actor as a Monitor for the provided ActorRef.
* This actor will receive a Terminated(watched) message when watched
* is terminated.
* This actor will receive a Terminated(subject) message when watched
* actor is terminated.
* @return the provided ActorRef
*/
def watch(subject: ActorRef): ActorRef

2
akka-actor/src/main/scala/akka/actor/ActorDSL.scala
View file

@ -118,7 +118,7 @@ abstract class Inbox {
* Receive the next message from this Inbox. This call will return immediately
* if the internal actor previously received a message, or it will block for
* up to the specified duration to await reception of a message. If no message
* is received a [[TimeoutException]] will be raised.
* is received a [[java.util.concurrent.TimeoutException]] will be raised.
*/
def receive(max: FiniteDuration): Any

19
akka-actor/src/main/scala/akka/actor/ActorRef.scala
View file

@ -16,7 +16,7 @@ import akka.event.LoggingAdapter
object ActorRef {
/**
* Use this value as an argument to [[#tell]] if there is not actor to
* Use this value as an argument to [[ActorRef#tell]] if there is not actor to
* reply to (e.g. when sending from non-actor code).
*/
final val noSender: ActorRef = Actor.noSender
@ -45,7 +45,9 @@ object ActorRef {
* def receive {
* case Request1(msg) => other ! refine(msg) // uses this actor as sender reference, reply goes to us
* case Request2(msg) => other.tell(msg, sender) // forward sender reference, enabling direct reply
* case Request3(msg) => sender ! (other ? msg) // will reply with a Future for holding other’s reply (implicit timeout from "akka.actor.timeout")
* case Request3(msg) =>
* implicit val timeout = Timeout(5.seconds)
* sender ! (other ? msg) // will reply with a Future for holding other's reply
* }
* }
* }}}
@ -61,16 +63,16 @@ object ActorRef {
* @Override
* public void onReceive(Object o) {
* if (o instanceof Request1) {
* val msg = ((Request1) o).getMsg();
* other.tell(msg); // uses this actor as sender reference, reply goes to us
* Msg msg = ((Request1) o).getMsg();
* other.tell(msg, getSelf()); // uses this actor as sender reference, reply goes to us
*
* } else if (o instanceof Request2) {
* val msg = ((Request2) o).getMsg();
* Msg msg = ((Request2) o).getMsg();
* other.tell(msg, getSender()); // forward sender reference, enabling direct reply
*
* } else if (o instanceof Request3) {
* val msg = ((Request3) o).getMsg();
* getSender().tell(ask(other, msg, 5000)); // reply with Future for holding the other’s reply (timeout 5 seconds)
* Msg msg = ((Request3) o).getMsg();
* getSender().tell(ask(other, msg, 5000)); // reply with Future for holding the other's reply (timeout 5 seconds)
*
* } else {
* unhandled(o);
@ -80,7 +82,8 @@ object ActorRef {
* }}}
*
* ActorRef does not have a method for terminating the actor it points to, use
* [[akka.actor.ActorRefFactory]]`.stop(child)` for this purpose.
* [[akka.actor.ActorRefFactory]]`.stop(ref)`, or send a [[akka.actor.PoisonPill]],
* for this purpose.
*
* Two actor references are compared equal when they have the same path and point to
* the same actor incarnation. A reference pointing to a terminated actor doesn't compare

13
akka-actor/src/main/scala/akka/actor/ActorRefProvider.scala
View file

@ -211,6 +211,9 @@ trait ActorRefFactory {
* reversed and with “$” prepended, may change in the future).
*
* See [[akka.actor.Props]] for details on how to obtain a `Props` object.
*
* @throws akka.ConfigurationException if deployment, dispatcher
* or mailbox configuration is wrong
*/
def actorOf(props: Props): ActorRef
@ -220,6 +223,10 @@ trait ActorRefFactory {
* and `InvalidActorNameException` is thrown.
*
* See [[akka.actor.Props]] for details on how to obtain a `Props` object.
* @throws akka.actor.InvalidActorNameException if the given name is
* invalid or already in use
* @throws akka.ConfigurationException if deployment, dispatcher
* or mailbox configuration is wrong
*/
def actorOf(props: Props, name: String): ActorRef
@ -263,7 +270,7 @@ trait ActorRefFactory {
* ...
* val target = context.actorFor(Seq("..", "myBrother", "myNephew"))
* ...
* }
* }
* }
* }}}
*
@ -285,9 +292,9 @@ trait ActorRefFactory {
* path.add("..");
* path.add("myBrother");
* path.add("myNephew");
* final ActorRef target = context().actorFor(path);
* final ActorRef target = getContext().actorFor(path);
* ...
* }
* }
* }
* }}}
*

5
akka-actor/src/main/scala/akka/actor/DynamicAccess.scala
View file

@ -55,11 +55,10 @@ abstract class DynamicAccess {
}
/**
* This is the default [[akka.actor.DynamicAccess]] implementation used by [[akka.actor.ActorSystemImpl]]
* This is the default [[akka.actor.DynamicAccess]] implementation used by [[akka.actor.ExtendedActorSystem]]
* unless overridden. It uses reflection to turn fully-qualified class names into `Class[_]` objects
* and creates instances from there using `getDeclaredConstructor()` and invoking that. The class loader
* to be used for all this is determined by the [[akka.actor.ActorSystemImpl]]’s `findClassLoader` method
* by default.
* to be used for all this is determined by the actor system’s class loader by default.
*/
class ReflectiveDynamicAccess(val classLoader: ClassLoader) extends DynamicAccess {

14
akka-actor/src/main/scala/akka/actor/FSM.scala
View file

@ -27,27 +27,27 @@ object FSM {
/**
* Message type which is sent directly to the subscribed actor in
* [[akka.actor.FSM.SubscribeTransitionCallback]] before sending any
* [[akka.actor.FSM.SubscribeTransitionCallBack]] before sending any
* [[akka.actor.FSM.Transition]] messages.
*/
case class CurrentState[S](fsmRef: ActorRef, state: S)
/**
* Message type which is used to communicate transitions between states to
* all subscribed listeners (use [[akka.actor.FSM.SubscribeTransitionCallback]]).
* all subscribed listeners (use [[akka.actor.FSM.SubscribeTransitionCallBack]]).
*/
case class Transition[S](fsmRef: ActorRef, from: S, to: S)
/**
* Send this to an [[akka.actor.FSM]] to request first the [[akka.actor.CurrentState]]
* and then a series of [[akka.actor.Transition]] updates. Cancel the subscription
* using [[akka.actor.FSM.UnsubscribeTransitionCallback]].
* Send this to an [[akka.actor.FSM]] to request first the [[FSM.CurrentState]]
* and then a series of [[FSM.Transition]] updates. Cancel the subscription
* using [[FSM.UnsubscribeTransitionCallBack]].
*/
case class SubscribeTransitionCallBack(actorRef: ActorRef)
/**
* Unsubscribe from [[akka.actor.FSM.Transition]] notifications which was
* effected by sending the corresponding [[akka.actor.FSM.SubscribeTransitionCallback]].
* effected by sending the corresponding [[akka.actor.FSM.SubscribeTransitionCallBack]].
*/
case class UnsubscribeTransitionCallBack(actorRef: ActorRef)
@ -663,7 +663,7 @@ trait FSM[S, D] extends Actor with Listeners with ActorLogging {
}
/**
* By default [[Failure]] is logged at error level and other reason
* By default [[FSM.Failure]] is logged at error level and other reason
* types are not logged. It is possible to override this behavior.
*/
protected def logTermination(reason: Reason): Unit = reason match {

2
akka-actor/src/main/scala/akka/actor/FaultHandling.scala
View file

@ -156,7 +156,7 @@ object SupervisorStrategy extends SupervisorStrategyLowPriorityImplicits {
* When supervisorStrategy is not specified for an actor this
* [[Decider]] is used by default in the supervisor strategy.
* The child will be stopped when [[akka.actor.ActorInitializationException]],
* [[akka.ActorKilledException]], or [[akka.actor.DeathPactException]] is
* [[akka.actor.ActorKilledException]], or [[akka.actor.DeathPactException]] is
* thrown. It will be restarted for other `Exception` types.
* The error is escalated if it's a `Throwable`, i.e. `Error`.
*/

6
akka-actor/src/main/scala/akka/actor/Props.scala
View file

@ -120,7 +120,7 @@ object Props {
def create(clazz: Class[_], args: AnyRef*): Props = apply(defaultDeploy, clazz, args.toVector)
/**
* Create new Props from the given [[Creator]].
* Create new Props from the given [[akka.japi.Creator]].
*/
def create[T <: Actor](creator: Creator[T]): Props = {
if ((creator.getClass.getEnclosingClass ne null) && (creator.getClass.getModifiers & Modifier.STATIC) == 0)
@ -216,7 +216,7 @@ final case class Props(deploy: Deploy, clazz: Class[_], args: immutable.Seq[Any]
def this(factory: UntypedActorFactory) = this(Props.defaultDeploy, classOf[UntypedActorFactoryConsumer], Vector(factory))
/**
* Java API: create Props from a given [[Class]]
* Java API: create Props from a given [[java.lang.Class]]
*
* @deprecated use Props.create(clazz) instead; deprecated since it duplicates
* another API
@ -303,7 +303,7 @@ final case class Props(deploy: Deploy, clazz: Class[_], args: immutable.Seq[Any]
/**
* Obtain an upper-bound approximation of the actor class which is going to
* be created by these Props. In other words, the [[#newActor]] method will
* be created by these Props. In other words, the actor factory method will
* produce an instance of this class or a subclass thereof. This is used by
* the actor system to select special dispatchers or mailboxes in case
* dependencies are encoded in the actor type.

13
akka-actor/src/main/scala/akka/actor/Stash.scala
View file

@ -30,18 +30,7 @@ import akka.AkkaException
* </pre>
*
* Note that the `Stash` trait can only be used together with actors that have a deque-based
* mailbox. Actors can be configured to use a deque-based mailbox using a configuration like
* the following (see the documentation on dispatchers on how to configure a custom
* dispatcher):
* <pre>
* akka {
* actor {
* my-custom-dispatcher {
* mailbox-type = "akka.dispatch.UnboundedDequeBasedMailbox"
* }
* }
* }
* </pre>
* mailbox.
*
* Note that the `Stash` trait must be mixed into (a subclass of) the `Actor` trait before
* any trait/class that overrides the `preRestart` callback. This means it's not possible to write

24
akka-actor/src/main/scala/akka/actor/UntypedActor.scala
View file

@ -27,7 +27,7 @@ import akka.japi.{ Creator }
* {{{
* public class SampleUntypedActor extends UntypedActor {
*
* public class Reply {
* public static class Reply implements java.io.Serializable {
* final public ActorRef sender;
* final public Result result;
* Reply(ActorRef sender, Result result) {
@ -59,7 +59,7 @@ import akka.japi.{ Creator }
*
* public void onReceive(Object message) throws Exception {
* if (message instanceof String) {
* String msg = (String)message;
* String msg = (String) message;
*
* if (msg.equals("UseSender")) {
* // Reply to original sender of message
@ -77,7 +77,9 @@ import akka.japi.{ Creator }
* // Send work to one-off child and collect the answer, reply handled further down
* getContext().actorOf(Props.create(Worker.class)).tell("DoWorkAndReplyToMe", getSelf());
*
* } else throw new IllegalArgumentException("Unknown message: " + message);
* } else {
* unhandled(message);
* }
*
* } else if (message instanceof Reply) {
*
@ -85,7 +87,9 @@ import akka.japi.{ Creator }
* // might want to do some processing/book-keeping here
* reply.sender.tell(reply.result, getSelf());
*
* } else throw new IllegalArgumentException("Unknown message: " + message);
* } else {
* unhandled(message);
* }
* }
* }
* }}}
@ -107,7 +111,7 @@ abstract class UntypedActor extends Actor {
def getContext(): UntypedActorContext = context.asInstanceOf[UntypedActorContext]
/**
* Returns the 'self' reference.
* Returns the ActorRef for this actor.
*/
def getSelf(): ActorRef = self
@ -161,6 +165,16 @@ abstract class UntypedActor extends Actor {
override def postRestart(reason: Throwable): Unit = super.postRestart(reason)
final def receive = { case msg ⇒ onReceive(msg) }
/**
* Recommended convention is to call this method if the message
* isn't handled in [[#onReceive]] (e.g. unknown message type).
* By default it fails with either a [[akka.actor.DeathPactException]] (in
* case of an unhandled [[akka.actor.Terminated]] message) or publishes an [[akka.actor.UnhandledMessage]]
* to the actor's system's [[akka.event.EventStream]].
*/
override def unhandled(message: Any): Unit = super.unhandled(message)
}
/**

14
akka-actor/src/main/scala/akka/dispatch/sysmsg/SystemMessage.scala
View file

@ -12,7 +12,7 @@ import akka.actor.{ ActorInitializationException, InternalActorRef, ActorRef, Po
* Helper companion object for [[akka.dispatch.sysmsg.LatestFirstSystemMessageList]] and
* [[akka.dispatch.sysmsg.EarliestFirstSystemMessageList]]
*/
object SystemMessageList {
private[akka] object SystemMessageList {
final val LNil: LatestFirstSystemMessageList = new LatestFirstSystemMessageList(null)
final val ENil: EarliestFirstSystemMessageList = new EarliestFirstSystemMessageList(null)
@ -33,7 +33,7 @@ object SystemMessageList {
*
* INTERNAL API
*
* Value class supporting list operations on system messages. The `next` field of [[akka.dispatch.sysmsg.SystemMessage]]
* Value class supporting list operations on system messages. The `next` field of [[SystemMessage]]
* is hidden, and can only accessed through the value classes [[akka.dispatch.sysmsg.LatestFirstSystemMessageList]] and
* [[akka.dispatch.sysmsg.EarliestFirstSystemMessageList]], abstracting over the fact that system messages are the
* list nodes themselves. If used properly, this stays a compile time construct without any allocation overhead.
@ -44,7 +44,7 @@ object SystemMessageList {
* latest appended element.
*
*/
class LatestFirstSystemMessageList(val head: SystemMessage) extends AnyVal {
private[akka] class LatestFirstSystemMessageList(val head: SystemMessage) extends AnyVal {
import SystemMessageList._
/**
@ -65,7 +65,7 @@ class LatestFirstSystemMessageList(val head: SystemMessage) extends AnyVal {
/**
* Gives back the list containing all the elements except the first. This operation has constant cost.
*
* *Warning:* as the underlying list nodes (the [[akka.dispatch.sysmsg.SystemMessage]] instances) are mutable, care
* *Warning:* as the underlying list nodes (the [[SystemMessage]] instances) are mutable, care
* should be taken when passing the tail to other methods. [[akka.dispatch.sysmsg.SystemMessage#unlink]] should be
* called on the head if one wants to detach the tail permanently.
*/
@ -94,7 +94,7 @@ class LatestFirstSystemMessageList(val head: SystemMessage) extends AnyVal {
*
* INTERNAL API
*
* Value class supporting list operations on system messages. The `next` field of [[akka.dispatch.sysmsg.SystemMessage]]
* Value class supporting list operations on system messages. The `next` field of [[SystemMessage]]
* is hidden, and can only accessed through the value classes [[akka.dispatch.sysmsg.LatestFirstSystemMessageList]] and
* [[akka.dispatch.sysmsg.EarliestFirstSystemMessageList]], abstracting over the fact that system messages are the
* list nodes themselves. If used properly, this stays a compile time construct without any allocation overhead.
@ -105,7 +105,7 @@ class LatestFirstSystemMessageList(val head: SystemMessage) extends AnyVal {
* latest appended element.
*
*/
class EarliestFirstSystemMessageList(val head: SystemMessage) extends AnyVal {
private[akka] class EarliestFirstSystemMessageList(val head: SystemMessage) extends AnyVal {
import SystemMessageList._
/**
@ -126,7 +126,7 @@ class EarliestFirstSystemMessageList(val head: SystemMessage) extends AnyVal {
/**
* Gives back the list containing all the elements except the first. This operation has constant cost.
*
* *Warning:* as the underlying list nodes (the [[akka.dispatch.sysmsg.SystemMessage]] instances) are mutable, care
* *Warning:* as the underlying list nodes (the [[SystemMessage]] instances) are mutable, care
* should be taken when passing the tail to other methods. [[akka.dispatch.sysmsg.SystemMessage#unlink]] should be
* called on the head if one wants to detach the tail permanently.
*/

6
akka-actor/src/main/scala/akka/event/Logging.scala
View file

@ -366,7 +366,7 @@ object LogSource {
* your own, make sure to handle these four event types plus the <code>InitializeLogger</code>
* message which is sent before actually attaching it to the logging bus.
*
* Logging is configured in <code>akka.conf</code> by setting (some of) the following:
* Logging is configured by setting (some of) the following:
*
* <pre><code>
* akka {
@ -737,8 +737,8 @@ object Logging {
* Actor-less logging implementation for synchronous logging to standard
* output. This logger is always attached first in order to be able to log
* failures during application start-up, even before normal logging is
* started. Its log level can be configured by setting
* <code>akka.stdout-loglevel</code> in <code>akka.conf</code>.
* started. Its log level can be defined by configuration setting
* <code>akka.stdout-loglevel</code>.
*/
class StandardOutLogger extends MinimalActorRef with StdOutLogger {
val path: ActorPath = new RootActorPath(Address("akka", "all-systems"), "/StandardOutLogger")

2
akka-actor/src/main/scala/akka/event/LoggingReceive.scala
View file

@ -24,7 +24,7 @@ object LoggingReceive {
* </code></pre>
*
* This method does NOT modify the given Receive unless
* akka.actor.debug.receive is set within akka.conf.
* `akka.actor.debug.receive` is set in configuration.
*/
def apply(r: Receive)(implicit context: ActorContext): Receive = r match {
case _: LoggingReceive ⇒ r

24
akka-actor/src/main/scala/akka/io/Inet.scala
View file

@ -31,7 +31,7 @@ object Inet {
object SO {
/**
* [[akka.io.Tcp.SocketOption]] to set the SO_RCVBUF option
* [[akka.io.Inet.SocketOption]] to set the SO_RCVBUF option
*
* For more information see [[java.net.Socket.setReceiveBufferSize]]
*/
@ -45,7 +45,7 @@ object Inet {
// server socket options
/**
* [[akka.io.Tcp.SocketOption]] to enable or disable SO_REUSEADDR
* [[akka.io.Inet.SocketOption]] to enable or disable SO_REUSEADDR
*
* For more information see [[java.net.Socket.setReuseAddress]]
*/
@ -56,7 +56,7 @@ object Inet {
}
/**
* [[akka.io.Tcp.SocketOption]] to set the SO_SNDBUF option.
* [[akka.io.Inet.SocketOption]] to set the SO_SNDBUF option.
*
* For more information see [[java.net.Socket.setSendBufferSize]]
*/
@ -66,7 +66,7 @@ object Inet {
}
/**
* [[akka.io.Tcp.SocketOption]] to set the traffic class or
* [[akka.io.Inet.SocketOption]] to set the traffic class or
* type-of-service octet in the IP header for packets sent from this
* socket.
*
@ -81,28 +81,28 @@ object Inet {
trait SoForwarders {
/**
* [[akka.io.Tcp.SocketOption]] to set the SO_RCVBUF option
* [[akka.io.Inet.SocketOption]] to set the SO_RCVBUF option
*
* For more information see [[java.net.Socket.setReceiveBufferSize]]
*/
val ReceiveBufferSize = SO.ReceiveBufferSize
/**
* [[akka.io.Tcp.SocketOption]] to enable or disable SO_REUSEADDR
* [[akka.io.Inet.SocketOption]] to enable or disable SO_REUSEADDR
*
* For more information see [[java.net.Socket.setReuseAddress]]
*/
val ReuseAddress = SO.ReuseAddress
/**
* [[akka.io.Tcp.SocketOption]] to set the SO_SNDBUF option.
* [[akka.io.Inet.SocketOption]] to set the SO_SNDBUF option.
*
* For more information see [[java.net.Socket.setSendBufferSize]]
*/
val SendBufferSize = SO.SendBufferSize
/**
* [[akka.io.Tcp.SocketOption]] to set the traffic class or
* [[akka.io.Inet.SocketOption]] to set the traffic class or
* type-of-service octet in the IP header for packets sent from this
* socket.
*
@ -114,28 +114,28 @@ object Inet {
trait SoJavaFactories {
import SO._
/**
* [[akka.io.Tcp.SocketOption]] to set the SO_RCVBUF option
* [[akka.io.Inet.SocketOption]] to set the SO_RCVBUF option
*
* For more information see [[java.net.Socket.setReceiveBufferSize]]
*/
def receiveBufferSize(size: Int) = ReceiveBufferSize(size)
/**
* [[akka.io.Tcp.SocketOption]] to enable or disable SO_REUSEADDR
* [[akka.io.Inet.SocketOption]] to enable or disable SO_REUSEADDR
*
* For more information see [[java.net.Socket.setReuseAddress]]
*/
def reuseAddress(on: Boolean) = ReuseAddress(on)
/**
* [[akka.io.Tcp.SocketOption]] to set the SO_SNDBUF option.
* [[akka.io.Inet.SocketOption]] to set the SO_SNDBUF option.
*
* For more information see [[java.net.Socket.setSendBufferSize]]
*/
def sendBufferSize(size: Int) = SendBufferSize(size)
/**
* [[akka.io.Tcp.SocketOption]] to set the traffic class or
* [[akka.io.Inet.SocketOption]] to set the traffic class or
* type-of-service octet in the IP header for packets sent from this
* socket.
*

20
akka-actor/src/main/scala/akka/io/Pipelines.scala
View file

@ -148,7 +148,7 @@ abstract class AbstractPipePair[CmdAbove, CmdBelow, EvtAbove, EvtBelow] {
/**
* Wrap a single command for efficient return to the pipeline’s machinery.
* This method avoids allocating a [[Right]] and an [[java.lang.Iterable]] by reusing
* This method avoids allocating a [[scala.util.Right]] and an [[java.lang.Iterable]] by reusing
* one such instance within the AbstractPipePair, hence it can be used ONLY ONCE by
* each pipeline stage. Prototypic and safe usage looks like this:
*
@ -166,7 +166,7 @@ abstract class AbstractPipePair[CmdAbove, CmdBelow, EvtAbove, EvtBelow] {
/**
* Wrap a single event for efficient return to the pipeline’s machinery.
* This method avoids allocating a [[Left]] and an [[Iterable]] by reusing
* This method avoids allocating a [[scala.util.Left]] and an [[java.lang.Iterable]] by reusing
* one such instance within the AbstractPipePair, hence it can be used ONLY ONCE by
* each pipeline stage. Prototypic and safe usage looks like this:
*
@ -490,7 +490,7 @@ trait PipelineContext {
/**
* Scala API: Wrap a single command for efficient return to the pipeline’s machinery.
* This method avoids allocating a [[Right]] and an [[Iterable]] by reusing
* This method avoids allocating a [[scala.util.Right]] and an [[scala.collection.Iterable]] by reusing
* one such instance within the PipelineContext, hence it can be used ONLY ONCE by
* each pipeline stage. Prototypic and safe usage looks like this:
*
@ -510,7 +510,7 @@ trait PipelineContext {
/**
* Scala API: Wrap a single event for efficient return to the pipeline’s machinery.
* This method avoids allocating a [[Left]] and an [[Iterable]] by reusing
* This method avoids allocating a [[scala.util.Left]] and an [[scala.collection.Iterable]] by reusing
* one such instance within the context, hence it can be used ONLY ONCE by
* each pipeline stage. Prototypic and safe usage looks like this:
*
@ -742,15 +742,15 @@ object BackpressureBuffer {
* This pipeline stage implements a configurable buffer for transforming the
* per-write ACK/NACK-based backpressure model of a TCP connection actor into
* an edge-triggered back-pressure model: the upper stages will receive
* notification when the buffer runs full ([[HighWatermarkReached]]) and when
* it subsequently empties ([[LowWatermarkReached]]). The upper layers should
* notification when the buffer runs full ([[BackpressureBuffer.HighWatermarkReached]]) and when
* it subsequently empties ([[BackpressureBuffer.LowWatermarkReached]]). The upper layers should
* respond by not generating more writes when the buffer is full. There is also
* a hard limit upon which this buffer will abort the connection.
*
* All limits are configurable and are given in number of bytes.
* The `highWatermark` should be set such that the
* amount of data generated before reception of the asynchronous
* [[HighWatermarkReached]] notification does not lead to exceeding the
* [[BackpressureBuffer.HighWatermarkReached]] notification does not lead to exceeding the
* `maxCapacity` hard limit; if the writes may arrive in bursts then the
* difference between these two should allow for at least one burst to be sent
* after the high watermark has been reached. The `lowWatermark` must be less
@ -758,7 +758,7 @@ object BackpressureBuffer {
* defines the hysteresis, i.e. how often these notifications are sent out (i.e.
* if the difference is rather large then it will take some time for the buffer
* to empty below the low watermark, and that room is then available for data
* sent in response to the [[LowWatermarkReached]] notification; if the
* sent in response to the [[BackpressureBuffer.LowWatermarkReached]] notification; if the
* difference was small then the buffer would more quickly oscillate between
* these two limits).
*/
@ -1152,7 +1152,7 @@ class StringByteStringAdapter(charset: String = "utf-8")
*/
trait HasLogging extends PipelineContext {
/**
* Retrieve the [[LoggingAdapter]] for this pipeline’s context.
* Retrieve the [[akka.event.LoggingAdapter]] for this pipeline’s context.
*/
def getLogger: LoggingAdapter
}
@ -1164,7 +1164,7 @@ trait HasLogging extends PipelineContext {
*/
trait HasActorContext extends PipelineContext {
/**
* Retrieve the [[ActorContext]] for this pipeline’s context.
* Retrieve the [[akka.actor.ActorContext]] for this pipeline’s context.
*/
def getContext: ActorContext
}

2
akka-actor/src/main/scala/akka/io/SslTlsSupport.scala
View file

@ -45,7 +45,7 @@ object SslTlsSupport {
/**
* This pipeline stage implements SSL / TLS support, using an externally
* configured [[SSLEngine]]. It operates on the level of [[Tcp.Event]] and
* configured [[javax.net.ssl.SSLEngine]]. It operates on the level of [[Tcp.Event]] and
* [[Tcp.Command]] messages, which means that it will typically be one of
* the lowest stages in a protocol stack. Since SSLEngine relies on contiguous
* transmission of a data stream you will need to handle backpressure from

64
akka-actor/src/main/scala/akka/io/Tcp.scala
View file

@ -25,7 +25,7 @@ import java.lang.{ Iterable ⇒ JIterable }
* stable and ready for production use.
*
* For a full description of the design and philosophy behind this IO
* implementation please refer to {@see <a href="http://doc.akka.io/">the Akka online documentation</a>}.
* implementation please refer to <a href="http://doc.akka.io/">the Akka online documentation</a>.
*
* In order to open an outbound connection send a [[Tcp.Connect]] message
* to the [[TcpExt#manager]].
@ -526,8 +526,8 @@ object TcpMessage {
/**
* The Connect message is sent to the TCP manager actor, which is obtained via
* [[TcpExt#getManager]]. Either the manager replies with a [[CommandFailed]]
* or the actor handling the new connection replies with a [[Connected]]
* [[TcpExt#getManager]]. Either the manager replies with a [[Tcp.CommandFailed]]
* or the actor handling the new connection replies with a [[Tcp.Connected]]
* message.
*
* @param remoteAddress is the address to connect to
@ -567,13 +567,13 @@ object TcpMessage {
/**
* The Bind message is send to the TCP manager actor, which is obtained via
* [[TcpExt#getManager]] in order to bind to a listening socket. The manager
* replies either with a [[CommandFailed]] or the actor handling the listen
* socket replies with a [[Bound]] message. If the local port is set to 0 in
* the Bind message, then the [[Bound]] message should be inspected to find
* replies either with a [[Tcp.CommandFailed]] or the actor handling the listen
* socket replies with a [[Tcp.Bound]] message. If the local port is set to 0 in
* the Bind message, then the [[Tcp.Bound]] message should be inspected to find
* the actual port which was bound to.
*
* @param handler The actor which will receive all incoming connection requests
* in the form of [[Connected]] messages.
* in the form of [[Tcp.Connected]] messages.
*
* @param localAddress The socket address to bind to; use port zero for
* automatic assignment (i.e. an ephemeral port, see [[Bound]])
@ -596,7 +596,7 @@ object TcpMessage {
/**
* This message must be sent to a TCP connection actor after receiving the
* [[Connected]] message. The connection will not read any data from the
* [[Tcp.Connected]] message. The connection will not read any data from the
* socket until this message is received, because this message defines the
* actor which will receive all inbound data.
*
@ -605,11 +605,11 @@ object TcpMessage {
*
* @param keepOpenOnPeerClosed If this is set to true then the connection
* is not automatically closed when the peer closes its half,
* requiring an explicit [[Closed]] from our side when finished.
* requiring an explicit [[Tcp.Closed]] from our side when finished.
*
* @param useResumeWriting If this is set to true then the connection actor
* will refuse all further writes after issuing a [[CommandFailed]]
* notification until [[ResumeWriting]] is received. This can
* will refuse all further writes after issuing a [[Tcp.CommandFailed]]
* notification until [[Tcp.ResumeWriting]] is received. This can
* be used to implement NACK-based write backpressure.
*/
def register(handler: ActorRef, keepOpenOnPeerClosed: Boolean, useResumeWriting: Boolean): Command =
@ -621,15 +621,15 @@ object TcpMessage {
/**
* In order to close down a listening socket, send this message to that socket’s
* actor (that is the actor which previously had sent the [[Bound]] message). The
* listener socket actor will reply with a [[Unbound]] message.
* actor (that is the actor which previously had sent the [[Tcp.Bound]] message). The
* listener socket actor will reply with a [[Tcp.Unbound]] message.
*/
def unbind: Command = Unbind
/**
* A normal close operation will first flush pending writes and then close the
* socket. The sender of this command and the registered handler for incoming
* data will both be notified once the socket is closed using a [[Closed]]
* data will both be notified once the socket is closed using a [[Tcp.Closed]]
* message.
*/
def close: Command = Close
@ -638,7 +638,7 @@ object TcpMessage {
* A confirmed close operation will flush pending writes and half-close the
* connection, waiting for the peer to close the other half. The sender of this
* command and the registered handler for incoming data will both be notified
* once the socket is closed using a [[ConfirmedClosed]] message.
* once the socket is closed using a [[Tcp.ConfirmedClosed]] message.
*/
def confirmedClose: Command = ConfirmedClose
@ -647,28 +647,28 @@ object TcpMessage {
* command to the O/S kernel which should result in a TCP_RST packet being sent
* to the peer. The sender of this command and the registered handler for
* incoming data will both be notified once the socket is closed using a
* [[Aborted]] message.
* [[Tcp.Aborted]] message.
*/
def abort: Command = Abort
/**
* Each [[WriteCommand]] can optionally request a positive acknowledgment to be sent
* to the commanding actor. If such notification is not desired the [[WriteCommand#ack]]
* Each [[Tcp.WriteCommand]] can optionally request a positive acknowledgment to be sent
* to the commanding actor. If such notification is not desired the [[Tcp.WriteCommand#ack]]
* must be set to an instance of this class. The token contained within can be used
* to recognize which write failed when receiving a [[CommandFailed]] message.
* to recognize which write failed when receiving a [[Tcp.CommandFailed]] message.
*/
def noAck(token: AnyRef): NoAck = NoAck(token)
/**
* Default [[NoAck]] instance which is used when no acknowledgment information is
* Default [[Tcp.NoAck]] instance which is used when no acknowledgment information is
* explicitly provided. Its “token” is `null`.
*/
def noAck: NoAck = NoAck
/**
* Write data to the TCP connection. If no ack is needed use the special
* `NoAck` object. The connection actor will reply with a [[CommandFailed]]
* message if the write could not be enqueued. If [[WriteCommand#wantsAck]]
* returns true, the connection actor will reply with the supplied [[WriteCommand#ack]]
* `NoAck` object. The connection actor will reply with a [[Tcp.CommandFailed]]
* message if the write could not be enqueued. If [[Tcp.WriteCommand#wantsAck]]
* returns true, the connection actor will reply with the supplied [[Tcp.WriteCommand#ack]]
* token once the write has been successfully enqueued to the O/S kernel.
* <b>Note that this does not in any way guarantee that the data will be
* or have been sent!</b> Unfortunately there is no way to determine whether
@ -682,9 +682,9 @@ object TcpMessage {
/**
* Write `count` bytes starting at `position` from file at `filePath` to the connection.
* The count must be > 0. The connection actor will reply with a [[CommandFailed]]
* message if the write could not be enqueued. If [[WriteCommand#wantsAck]]
* returns true, the connection actor will reply with the supplied [[WriteCommand#ack]]
* The count must be > 0. The connection actor will reply with a [[Tcp.CommandFailed]]
* message if the write could not be enqueued. If [[Tcp.WriteCommand#wantsAck]]
* returns true, the connection actor will reply with the supplied [[Tcp.WriteCommand#ack]]
* token once the write has been successfully enqueued to the O/S kernel.
* <b>Note that this does not in any way guarantee that the data will be
* or have been sent!</b> Unfortunately there is no way to determine whether
@ -694,23 +694,23 @@ object TcpMessage {
WriteFile(filePath, position, count, ack)
/**
* When `useResumeWriting` is in effect as was indicated in the [[Register]] message
* When `useResumeWriting` is in effect as was indicated in the [[Tcp.Register]] message
* then this command needs to be sent to the connection actor in order to re-enable
* writing after a [[CommandFailed]] event. All [[WriteCommand]] processed by the
* connection actor between the first [[CommandFailed]] and subsequent reception of
* this message will also be rejected with [[CommandFailed]].
* writing after a [[Tcp.CommandFailed]] event. All [[Tcp.WriteCommand]] processed by the
* connection actor between the first [[Tcp.CommandFailed]] and subsequent reception of
* this message will also be rejected with [[Tcp.CommandFailed]].
*/
def resumeWriting: Command = ResumeWriting
/**
* Sending this command to the connection actor will disable reading from the TCP
* socket. TCP flow-control will then propagate backpressure to the sender side
* as buffers fill up on either end. To re-enable reading send [[ResumeReading]].
* as buffers fill up on either end. To re-enable reading send [[Tcp.ResumeReading]].
*/
def suspendReading: Command = SuspendReading
/**
* This command needs to be sent to the connection actor after a [[SuspendReading]]
* This command needs to be sent to the connection actor after a [[Tcp.SuspendReading]]
* command in order to resume reading from the socket.
*/
def resumeReading: Command = ResumeReading

8
akka-actor/src/main/scala/akka/io/TcpPipelineHandler.scala
View file

@ -94,7 +94,7 @@ object TcpPipelineHandler {
case class TcpEvent(@BeanProperty evt: Tcp.Event) extends Tcp.Command
/**
* create [[Props]] for a pipeline handler
* create [[akka.actor.Props]] for a pipeline handler
*/
def props[Ctx <: PipelineContext, Cmd, Evt](init: TcpPipelineHandler.Init[Ctx, Cmd, Evt], connection: ActorRef, handler: ActorRef) =
Props(classOf[TcpPipelineHandler[_, _, _]], init, connection, handler)
@ -104,8 +104,8 @@ object TcpPipelineHandler {
/**
* This actor wraps a pipeline and forwards commands and events between that
* one and a [[Tcp]] connection actor. In order to inject commands into the
* pipeline send an [[Init.Command]] message to this actor; events will be sent
* to the designated handler wrapped in [[Init.Event]] messages.
* pipeline send an [[TcpPipelineHandler.Init.Command]] message to this actor; events will be sent
* to the designated handler wrapped in [[TcpPipelineHandler.Init.Event]] messages.
*
* When the designated handler terminates the TCP connection is aborted. When
* the connection actor terminates this actor terminates as well; the designated
@ -164,7 +164,7 @@ class TcpPipelineHandler[Ctx <: PipelineContext, Cmd, Evt](
*
* While this adapter communicates to the stage above it via raw ByteStrings, it is possible to inject Tcp Command
* by sending them to the management port, and the adapter will simply pass them down to the stage below. Incoming Tcp Events
* that are not Receive events will be passed downwards wrapped in a [[TcpEvent]]; the [[TcpPipelineHandler]] will
* that are not Receive events will be passed downwards wrapped in a [[TcpPipelineHandler.TcpEvent]]; the [[TcpPipelineHandler]] will
* send these notifications to the registered event handler actor.
*/
class TcpReadWriteAdapter extends PipelineStage[PipelineContext, ByteString, Tcp.Command, ByteString, Tcp.Event] {

36
akka-actor/src/main/scala/akka/io/Udp.scala
View file

@ -26,7 +26,7 @@ import akka.actor._
* from whom data can be received. For “connected” UDP mode see [[UdpConnected]].
*
* For a full description of the design and philosophy behind this IO
* implementation please refer to {@see <a href="http://doc.akka.io/">the Akka online documentation</a>}.
* implementation please refer to <a href="http://doc.akka.io/">the Akka online documentation</a>.
*
* The Java API for generating UDP commands is available at [[UdpMessage]].
*/
@ -244,33 +244,33 @@ object UdpMessage {
import language.implicitConversions
/**
* Each [[Send]] can optionally request a positive acknowledgment to be sent
* to the commanding actor. If such notification is not desired the [[Send#ack]]
* Each [[Udp.Send]] can optionally request a positive acknowledgment to be sent
* to the commanding actor. If such notification is not desired the [[Udp.Send#ack]]
* must be set to an instance of this class. The token contained within can be used
* to recognize which write failed when receiving a [[CommandFailed]] message.
* to recognize which write failed when receiving a [[Udp.CommandFailed]] message.
*/
def noAck(token: AnyRef): NoAck = NoAck(token)
/**
* Default [[NoAck]] instance which is used when no acknowledgment information is
* Default [[Udp.NoAck]] instance which is used when no acknowledgment information is
* explicitly provided. Its “token” is `null`.
*/
def noAck: NoAck = NoAck
/**
* This message is understood by the “simple sender” which can be obtained by
* sending the [[SimpleSender]] query to the [[UdpExt#manager]] as well as by
* the listener actors which are created in response to [[Bind]]. It will send
* sending the [[Udp.SimpleSender]] query to the [[UdpExt#manager]] as well as by
* the listener actors which are created in response to [[Udp.Bind]]. It will send
* the given payload data as one UDP datagram to the given target address. The
* UDP actor will respond with [[CommandFailed]] if the send could not be
* UDP actor will respond with [[Udp.CommandFailed]] if the send could not be
* enqueued to the O/S kernel because the send buffer was full. If the given
* `ack` is not of type [[NoAck]] the UDP actor will reply with the given
* `ack` is not of type [[Udp.NoAck]] the UDP actor will reply with the given
* object as soon as the datagram has been successfully enqueued to the O/S
* kernel.
*
* The sending UDP socket’s address belongs to the “simple sender” which does
* not handle inbound datagrams and sends from an ephemeral port; therefore
* sending using this mechanism is not suitable if replies are expected, use
* [[Bind]] in that case.
* [[Udp.Bind]] in that case.
*/
def send(payload: ByteString, target: InetSocketAddress, ack: Event): Command = Send(payload, target, ack)
/**
@ -281,8 +281,8 @@ object UdpMessage {
/**
* Send this message to the [[UdpExt#manager]] in order to bind to the given
* local port (or an automatically assigned one if the port number is zero).
* The listener actor for the newly bound port will reply with a [[Bound]]
* message, or the manager will reply with a [[CommandFailed]] message.
* The listener actor for the newly bound port will reply with a [[Udp.Bound]]
* message, or the manager will reply with a [[Udp.CommandFailed]] message.
*/
def bind(handler: ActorRef, endpoint: InetSocketAddress, options: JIterable[SocketOption]): Command =
Bind(handler, endpoint, options.asScala.to)
@ -292,15 +292,15 @@ object UdpMessage {
def bind(handler: ActorRef, endpoint: InetSocketAddress): Command = Bind(handler, endpoint, Nil)
/**
* Send this message to the listener actor that previously sent a [[Bound]]
* Send this message to the listener actor that previously sent a [[Udp.Bound]]
* message in order to close the listening socket. The recipient will reply
* with an [[Unbound]] message.
* with an [[Udp.Unbound]] message.
*/
def unbind: Command = Unbind
/**
* Retrieve a reference to a “simple sender” actor of the UDP extension.
* The newly created “simple sender” will reply with the [[SimpleSenderReady]] notification.
* The newly created “simple sender” will reply with the [[Udp.SimpleSenderReady]] notification.
*
* The “simple sender” is a convenient service for being able to send datagrams
* when the originating address is meaningless, i.e. when no reply is expected.
@ -315,16 +315,16 @@ object UdpMessage {
def simpleSender: Command = SimpleSender
/**
* Send this message to a listener actor (which sent a [[Bound]] message) to
* Send this message to a listener actor (which sent a [[Udp.Bound]] message) to
* have it stop reading datagrams from the network. If the O/S kernel’s receive
* buffer runs full then subsequent datagrams will be silently discarded.
* Re-enable reading from the socket using the [[ResumeReading]] command.
* Re-enable reading from the socket using the [[Udp.ResumeReading]] command.
*/
def suspendReading: Command = SuspendReading
/**
* This message must be sent to the listener actor to re-enable reading from
* the socket after a [[SuspendReading]] command.
* the socket after a [[Udp.SuspendReading]] command.
*/
def resumeReading: Command = ResumeReading
}

28
akka-actor/src/main/scala/akka/io/UdpConnected.scala
View file

@ -25,7 +25,7 @@ import akka.actor._
* from whom data can be received. For “unconnected” UDP mode see [[Udp]].
*
* For a full description of the design and philosophy behind this IO
* implementation please refer to {@see <a href="http://doc.akka.io/">the Akka online documentation</a>}.
* implementation please refer to <a href="http://doc.akka.io/">the Akka online documentation</a>.
*
* The Java API for generating UDP commands is available at [[UdpConnectedMessage]].
*/
@ -103,7 +103,7 @@ object UdpConnected extends ExtensionId[UdpConnectedExt] with ExtensionIdProvide
case object Disconnect extends Command
/**
* Send this message to a listener actor (which sent a [[Bound]] message) to
* Send this message to a listener actor (which sent a [[Udp.Bound]] message) to
* have it stop reading datagrams from the network. If the O/S kernel’s receive
* buffer runs full then subsequent datagrams will be silently discarded.
* Re-enable reading from the socket using the [[ResumeReading]] command.
@ -123,7 +123,7 @@ object UdpConnected extends ExtensionId[UdpConnectedExt] with ExtensionIdProvide
/**
* When a connection actor receives a datagram from its socket it will send
* it to the handler designated in the [[Bind]] message using this message type.
* it to the handler designated in the [[Udp.Bind]] message using this message type.
*/
case class Received(data: ByteString) extends Event
@ -201,8 +201,8 @@ object UdpConnectedMessage {
/**
* This message is understood by the connection actors to send data to their
* designated destination. The connection actor will respond with
* [[CommandFailed]] if the send could not be enqueued to the O/S kernel
* because the send buffer was full. If the given `ack` is not of type [[NoAck]]
* [[UdpConnected.CommandFailed]] if the send could not be enqueued to the O/S kernel
* because the send buffer was full. If the given `ack` is not of type [[UdpConnected.NoAck]]
* the connection actor will reply with the given object as soon as the datagram
* has been successfully enqueued to the O/S kernel.
*/
@ -214,36 +214,36 @@ object UdpConnectedMessage {
/**
* Send this message to a connection actor (which had previously sent the
* [[Connected]] message) in order to close the socket. The connection actor
* will reply with a [[Disconnected]] message.
* [[UdpConnected.Connected]] message) in order to close the socket. The connection actor
* will reply with a [[UdpConnected.Disconnected]] message.
*/
def disconnect: Command = Disconnect
/**
* Each [[Send]] can optionally request a positive acknowledgment to be sent
* to the commanding actor. If such notification is not desired the [[Send#ack]]
* Each [[UdpConnected.Send]] can optionally request a positive acknowledgment to be sent
* to the commanding actor. If such notification is not desired the [[UdpConnected.Send#ack]]
* must be set to an instance of this class. The token contained within can be used
* to recognize which write failed when receiving a [[CommandFailed]] message.
* to recognize which write failed when receiving a [[UdpConnected.CommandFailed]] message.
*/
def noAck(token: AnyRef): NoAck = NoAck(token)
/**
* Default [[NoAck]] instance which is used when no acknowledgment information is
* Default [[UdpConnected.NoAck]] instance which is used when no acknowledgment information is
* explicitly provided. Its “token” is `null`.
*/
def noAck: NoAck = NoAck
/**
* Send this message to a listener actor (which sent a [[Bound]] message) to
* Send this message to a listener actor (which sent a [[Udp.Bound]] message) to
* have it stop reading datagrams from the network. If the O/S kernel’s receive
* buffer runs full then subsequent datagrams will be silently discarded.
* Re-enable reading from the socket using the [[ResumeReading]] command.
* Re-enable reading from the socket using the [[UdpConnected.ResumeReading]] command.
*/
def suspendReading: Command = SuspendReading
/**
* This message must be sent to the listener actor to re-enable reading from
* the socket after a [[SuspendReading]] command.
* the socket after a [[UdpConnected.SuspendReading]] command.
*/
def resumeReading: Command = ResumeReading

4
akka-actor/src/main/scala/akka/pattern/AskSupport.scala
View file

@ -41,7 +41,7 @@ trait AskSupport {
* val future = actor.ask(message)(timeout) // => ask(actor, message)(timeout)
* }}}
*
* All of the above use an implicit [[akka.actor.Timeout]].
* All of the above use an implicit [[akka.util.Timeout]].
*/
implicit def ask(actorRef: ActorRef): AskableActorRef = new AskableActorRef(actorRef)
@ -88,7 +88,7 @@ trait AskSupport {
* val future = selection.ask(message)(timeout) // => ask(selection, message)(timeout)
* }}}
*
* All of the above use an implicit [[akka.actor.Timeout]].
* All of the above use an implicit [[akka.util.Timeout]].
*/
implicit def ask(actorSelection: ActorSelection): AskableActorSelection = new AskableActorSelection(actorSelection)

28
akka-actor/src/main/scala/akka/routing/ConsistentHashingRouter.scala
View file

@ -35,7 +35,7 @@ object ConsistentHashingRouter {
* the hash, but the data to be hashed.
*
* If returning an `Array[Byte]` or String it will be used as is,
* otherwise the configured [[akka.akka.serialization.Serializer]]
* otherwise the configured [[akka.serialization.Serializer]]
* will be applied to the returned data.
*
* If messages can't implement this interface themselves,
@ -67,7 +67,7 @@ object ConsistentHashingRouter {
* the hash that is to be returned, but the data to be hashed.
*
* If returning an `Array[Byte]` or String it will be used as is,
* otherwise the configured [[akka.akka.serialization.Serializer]]
* otherwise the configured [[akka.serialization.Serializer]]
* will be applied to the returned data.
*/
type ConsistentHashMapping = PartialFunction[Any, Any]
@ -88,13 +88,14 @@ object ConsistentHashingRouter {
* this mapping.
*
* If returning an `Array[Byte]` or String it will be used as is,
* otherwise the configured [[akka.akka.serialization.Serializer]]
* otherwise the configured [[akka.serialization.Serializer]]
* will be applied to the returned data.
*/
trait ConsistentHashMapper {
def hashKey(message: Any): Any
}
}
/**
* A Router that uses consistent hashing to select a connection based on the
* sent message.
@ -126,18 +127,21 @@ object ConsistentHashingRouter {
*
* <h1>Supervision Setup</h1>
*
* The router creates a “head” actor which supervises and/or monitors the
* routees. Instances are created as children of this actor, hence the
* children are not supervised by the parent of the router. Common choices are
* to always escalate (meaning that fault handling is always applied to all
* children simultaneously; this is the default) or use the parent’s strategy,
* which will result in routed children being treated individually, but it is
* possible as well to use Routers to give different supervisor strategies to
* different groups of children.
* Any routees that are created by a router will be created as the router's children.
* The router is therefore also the children's supervisor.
*
* The supervision strategy of the router actor can be configured with
* [[#withSupervisorStrategy]]. If no strategy is provided, routers default to
* a strategy of “always escalate”. This means that errors are passed up to the
* router's supervisor for handling.
*
* The router's supervisor will treat the error as an error with the router itself.
* Therefore a directive to stop or restart will cause the router itself to stop or
* restart. The router, in turn, will cause its children to stop and restart.
*
* @param routees string representation of the actor paths of the routees that will be looked up
* using `actorFor` in [[akka.actor.ActorRefProvider]]
* @param virtualNodesFactor number of virtual nodes per node, used in [[akka.routing.ConsistantHash]]
* @param virtualNodesFactor number of virtual nodes per node, used in [[akka.routing.ConsistentHash]]
* @param hashMapping partial function from message to the data to
* use for the consistent hash key
*/

155
akka-actor/src/main/scala/akka/routing/Routing.scala
View file

@ -588,30 +588,17 @@ object RoundRobinRouter {
*
* <h1>Supervision Setup</h1>
*
* The router creates a “head” actor which supervises and/or monitors the
* routees. Instances are created as children of this actor, hence the
* children are not supervised by the parent of the router. Common choices are
* to always escalate (meaning that fault handling is always applied to all
* children simultaneously; this is the default) or use the parent’s strategy,
* which will result in routed children being treated individually, but it is
* possible as well to use Routers to give different supervisor strategies to
* different groups of children.
* Any routees that are created by a router will be created as the router's children.
* The router is therefore also the children's supervisor.
*
* {{{
* class MyActor extends Actor {
* override val supervisorStrategy = ...
* The supervision strategy of the router actor can be configured with
* [[#withSupervisorStrategy]]. If no strategy is provided, routers default to
* a strategy of “always escalate”. This means that errors are passed up to the
* router's supervisor for handling.
*
* val poolAsAWhole = context.actorOf(Props[SomeActor].withRouter(RoundRobinRouter(5)))
*
* val poolIndividuals = context.actorOf(Props[SomeActor].withRouter(
* RoundRobinRouter(5, supervisorStrategy = this.supervisorStrategy)))
*
* val specialChild = context.actorOf(Props[SomeActor].withRouter(
* RoundRobinRouter(5, supervisorStrategy = OneForOneStrategy() {
* ...
* })))
* }
* }}}
* The router's supervisor will treat the error as an error with the router itself.
* Therefore a directive to stop or restart will cause the router itself to stop or
* restart. The router, in turn, will cause its children to stop and restart.
*
* @param routees string representation of the actor paths of the routees that will be looked up
* using `actorFor` in [[akka.actor.ActorRefProvider]]
@ -723,30 +710,17 @@ object RandomRouter {
*
* <h1>Supervision Setup</h1>
*
* The router creates a “head” actor which supervises and/or monitors the
* routees. Instances are created as children of this actor, hence the
* children are not supervised by the parent of the router. Common choices are
* to always escalate (meaning that fault handling is always applied to all
* children simultaneously; this is the default) or use the parent’s strategy,
* which will result in routed children being treated individually, but it is
* possible as well to use Routers to give different supervisor strategies to
* different groups of children.
* Any routees that are created by a router will be created as the router's children.
* The router is therefore also the children's supervisor.
*
* {{{
* class MyActor extends Actor {
* override val supervisorStrategy = ...
* The supervision strategy of the router actor can be configured with
* [[#withSupervisorStrategy]]. If no strategy is provided, routers default to
* a strategy of “always escalate”. This means that errors are passed up to the
* router's supervisor for handling.
*
* val poolAsAWhole = context.actorOf(Props[SomeActor].withRouter(RandomRouter(5)))
*
* val poolIndividuals = context.actorOf(Props[SomeActor].withRouter(
* RandomRouter(5, supervisorStrategy = this.supervisorStrategy)))
*
* val specialChild = context.actorOf(Props[SomeActor].withRouter(
* RandomRouter(5, supervisorStrategy = OneForOneStrategy() {
* ...
* })))
* }
* }}}
* The router's supervisor will treat the error as an error with the router itself.
* Therefore a directive to stop or restart will cause the router itself to stop or
* restart. The router, in turn, will cause its children to stop and restart.
*
* @param routees string representation of the actor paths of the routees that will be looked up
* using `actorFor` in [[akka.actor.ActorRefProvider]]
@ -865,30 +839,17 @@ object SmallestMailboxRouter {
*
* <h1>Supervision Setup</h1>
*
* The router creates a “head” actor which supervises and/or monitors the
* routees. Instances are created as children of this actor, hence the
* children are not supervised by the parent of the router. Common choices are
* to always escalate (meaning that fault handling is always applied to all
* children simultaneously; this is the default) or use the parent’s strategy,
* which will result in routed children being treated individually, but it is
* possible as well to use Routers to give different supervisor strategies to
* different groups of children.
* Any routees that are created by a router will be created as the router's children.
* The router is therefore also the children's supervisor.
*
* {{{
* class MyActor extends Actor {
* override val supervisorStrategy = ...
* The supervision strategy of the router actor can be configured with
* [[#withSupervisorStrategy]]. If no strategy is provided, routers default to
* a strategy of “always escalate”. This means that errors are passed up to the
* router's supervisor for handling.
*
* val poolAsAWhole = context.actorOf(Props[SomeActor].withRouter(SmallestMailboxRouter(5)))
*
* val poolIndividuals = context.actorOf(Props[SomeActor].withRouter(
* SmallestMailboxRouter(5, supervisorStrategy = this.supervisorStrategy)))
*
* val specialChild = context.actorOf(Props[SomeActor].withRouter(
* SmallestMailboxRouter(5, supervisorStrategy = OneForOneStrategy() {
* ...
* })))
* }
* }}}
* The router's supervisor will treat the error as an error with the router itself.
* Therefore a directive to stop or restart will cause the router itself to stop or
* restart. The router, in turn, will cause its children to stop and restart.
*
* @param routees string representation of the actor paths of the routees that will be looked up
* using `actorFor` in [[akka.actor.ActorRefProvider]]
@ -1082,30 +1043,17 @@ object BroadcastRouter {
*
* <h1>Supervision Setup</h1>
*
* The router creates a “head” actor which supervises and/or monitors the
* routees. Instances are created as children of this actor, hence the
* children are not supervised by the parent of the router. Common choices are
* to always escalate (meaning that fault handling is always applied to all
* children simultaneously; this is the default) or use the parent’s strategy,
* which will result in routed children being treated individually, but it is
* possible as well to use Routers to give different supervisor strategies to
* different groups of children.
* Any routees that are created by a router will be created as the router's children.
* The router is therefore also the children's supervisor.
*
* {{{
* class MyActor extends Actor {
* override val supervisorStrategy = ...
* The supervision strategy of the router actor can be configured with
* [[#withSupervisorStrategy]]. If no strategy is provided, routers default to
* a strategy of “always escalate”. This means that errors are passed up to the
* router's supervisor for handling.
*
* val poolAsAWhole = context.actorOf(Props[SomeActor].withRouter(BroadcastRouter(5)))
*
* val poolIndividuals = context.actorOf(Props[SomeActor].withRouter(
* BroadcastRouter(5, supervisorStrategy = this.supervisorStrategy)))
*
* val specialChild = context.actorOf(Props[SomeActor].withRouter(
* BroadcastRouter(5, supervisorStrategy = OneForOneStrategy() {
* ...
* })))
* }
* }}}
* The router's supervisor will treat the error as an error with the router itself.
* Therefore a directive to stop or restart will cause the router itself to stop or
* restart. The router, in turn, will cause its children to stop and restart.
*
* @param routees string representation of the actor paths of the routees that will be looked up
* using `actorFor` in [[akka.actor.ActorRefProvider]]
@ -1208,30 +1156,17 @@ object ScatterGatherFirstCompletedRouter {
*
* <h1>Supervision Setup</h1>
*
* The router creates a “head” actor which supervises and/or monitors the
* routees. Instances are created as children of this actor, hence the
* children are not supervised by the parent of the router. Common choices are
* to always escalate (meaning that fault handling is always applied to all
* children simultaneously; this is the default) or use the parent’s strategy,
* which will result in routed children being treated individually, but it is
* possible as well to use Routers to give different supervisor strategies to
* different groups of children.
* Any routees that are created by a router will be created as the router's children.
* The router is therefore also the children's supervisor.
*
* {{{
* class MyActor extends Actor {
* override val supervisorStrategy = ...
* The supervision strategy of the router actor can be configured with
* [[#withSupervisorStrategy]]. If no strategy is provided, routers default to
* a strategy of “always escalate”. This means that errors are passed up to the
* router's supervisor for handling.
*
* val poolAsAWhole = context.actorOf(Props[SomeActor].withRouter(ScatterGatherFirstCompletedRouter(5)))
*
* val poolIndividuals = context.actorOf(Props[SomeActor].withRouter(
* ScatterGatherFirstCompletedRouter(5, supervisorStrategy = this.supervisorStrategy)))
*
* val specialChild = context.actorOf(Props[SomeActor].withRouter(
* ScatterGatherFirstCompletedRouter(5, supervisorStrategy = OneForOneStrategy() {
* ...
* })))
* }
* }}}
* The router's supervisor will treat the error as an error with the router itself.
* Therefore a directive to stop or restart will cause the router itself to stop or
* restart. The router, in turn, will cause its children to stop and restart.
*
* @param routees string representation of the actor paths of the routees that will be looked up
* using `actorFor` in [[akka.actor.ActorRefProvider]]