From 0ff920195c9073e91904c0d9eb63eb9edc9d8f57 Mon Sep 17 00:00:00 2001 From: Patrik Nordwall Date: Wed, 21 Dec 2011 21:24:57 +0100 Subject: [PATCH] Updated documentation. See #1458 --- .../akka/dispatch/AbstractDispatcher.scala | 2 +- .../akka/dispatch/BalancingDispatcher.scala | 4 +- .../main/scala/akka/dispatch/Dispatcher.scala | 46 +----------- .../scala/akka/dispatch/Dispatchers.scala | 75 +++++++++---------- .../akka/dispatch/PinnedDispatcher.scala | 3 + akka-docs/java/dispatchers.rst | 16 ++-- .../docs/dispatcher/DispatcherDocSpec.scala | 3 +- akka-docs/scala/dispatchers.rst | 15 ++-- 8 files changed, 59 insertions(+), 105 deletions(-) diff --git a/akka-actor/src/main/scala/akka/dispatch/AbstractDispatcher.scala b/akka-actor/src/main/scala/akka/dispatch/AbstractDispatcher.scala index 997623195f..905d2d6498 100644 --- a/akka-actor/src/main/scala/akka/dispatch/AbstractDispatcher.scala +++ b/akka-actor/src/main/scala/akka/dispatch/AbstractDispatcher.scala @@ -270,7 +270,7 @@ abstract class MessageDispatcher(val prerequisites: DispatcherPrerequisites) ext } /** - * Trait to be used for hooking in new dispatchers into Dispatchers factory. + * Base class to be used for hooking in new dispatchers into Dispatchers. */ abstract class MessageDispatcherConfigurator(val config: Config, val prerequisites: DispatcherPrerequisites) { diff --git a/akka-actor/src/main/scala/akka/dispatch/BalancingDispatcher.scala b/akka-actor/src/main/scala/akka/dispatch/BalancingDispatcher.scala index 78308d46ba..31ca64867c 100644 --- a/akka-actor/src/main/scala/akka/dispatch/BalancingDispatcher.scala +++ b/akka-actor/src/main/scala/akka/dispatch/BalancingDispatcher.scala @@ -23,8 +23,8 @@ import akka.util.Duration * Although the technique used in this implementation is commonly known as "work stealing", the actual implementation is probably * best described as "work donating" because the actor of which work is being stolen takes the initiative. *

- * The preferred way of creating dispatchers is to use - * the {@link akka.dispatch.Dispatchers} factory object. + * The preferred way of creating dispatchers is to define configuration of it and use the + * the `lookup` method in [[akka.dispatch.Dispatchers]]. * * @see akka.dispatch.BalancingDispatcher * @see akka.dispatch.Dispatchers diff --git a/akka-actor/src/main/scala/akka/dispatch/Dispatcher.scala b/akka-actor/src/main/scala/akka/dispatch/Dispatcher.scala index cbe77a0328..79331e0397 100644 --- a/akka-actor/src/main/scala/akka/dispatch/Dispatcher.scala +++ b/akka-actor/src/main/scala/akka/dispatch/Dispatcher.scala @@ -11,49 +11,11 @@ import akka.util.Duration import java.util.concurrent._ /** - * Default settings are: - * 

- *   - withNewThreadPoolWithLinkedBlockingQueueWithUnboundedCapacity
- *   - NR_START_THREADS = 16
- *   - NR_MAX_THREADS = 128
- *   - KEEP_ALIVE_TIME = 60000L // one minute
- *
- *

+ * The event-based ``Dispatcher`` binds a set of Actors to a thread pool backed up by a + * `BlockingQueue`. * - * The dispatcher has a fluent builder interface to build up a thread pool to suite your use-case. - * There is a default thread pool defined but make use of the builder if you need it. Here are some examples. - *

- * - * Scala API. - *

- * Example usage: - * 

- *   val dispatcher = new Dispatcher("name")
- *   dispatcher
- *     .withNewThreadPoolWithBoundedBlockingQueue(100)
- *     .setCorePoolSize(16)
- *     .setMaxPoolSize(128)
- *     .setKeepAliveTime(60 seconds)
- *     .buildThreadPool
- *
- *

- * - * Java API. - *

- * Example usage: - * 

- *   Dispatcher dispatcher = new Dispatcher("name");
- *   dispatcher
- *     .withNewThreadPoolWithBoundedBlockingQueue(100)
- *     .setCorePoolSize(16)
- *     .setMaxPoolSize(128)
- *     .setKeepAliveTime(60 seconds)
- *     .buildThreadPool();
- *
- *

- * - * But the preferred way of creating dispatchers is to use - * the {@link akka.dispatch.Dispatchers} factory object. + * The preferred way of creating dispatchers is to define configuration of it and use the + * the `lookup` method in [[akka.dispatch.Dispatchers]]. * * @param throughput positive integer indicates the dispatcher will only process so much messages at a time from the * mailbox, without checking the mailboxes of other actors. Zero or negative means the dispatcher diff --git a/akka-actor/src/main/scala/akka/dispatch/Dispatchers.scala b/akka-actor/src/main/scala/akka/dispatch/Dispatchers.scala index 0743870542..04784f151c 100644 --- a/akka-actor/src/main/scala/akka/dispatch/Dispatchers.scala +++ b/akka-actor/src/main/scala/akka/dispatch/Dispatchers.scala @@ -31,40 +31,20 @@ case class DefaultDispatcherPrerequisites( val scheduler: Scheduler) extends DispatcherPrerequisites object Dispatchers { + /** + * The id of the default dispatcher, also the full key of the + * configuration of the default dispatcher. + */ final val DefaultDispatcherId = "akka.actor.default-dispatcher" } /** - * It is recommended to define the dispatcher in configuration to allow for tuning + * Dispatchers are to be defined in configuration to allow for tuning * for different environments. Use the `lookup` method to create * a dispatcher as specified in configuration. * - * Scala API. Dispatcher factory. - *

- * Example usage: - * 

- *   val dispatcher = Dispatchers.newDispatcher("name")
- *   dispatcher
- *     .withNewThreadPoolWithLinkedBlockingQueueWithCapacity(100)
- *     .setCorePoolSize(16)
- *     .setMaxPoolSize(128)
- *     .setKeepAliveTime(60 seconds)
- *     .build
- *
- *

- * Java API. Dispatcher factory. - *

- * Example usage: - * 

- *   MessageDispatcher dispatcher = Dispatchers.newDispatcher("name");
- *   dispatcher
- *     .withNewThreadPoolWithLinkedBlockingQueueWithCapacity(100)
- *     .setCorePoolSize(16)
- *     .setMaxPoolSize(128)
- *     .setKeepAliveTime(60 seconds)
- *     .build();
- *
- *

+ * Look in `akka.actor.default-dispatcher` section of the reference.conf + * for documentation of dispatcher options. */ class Dispatchers(val settings: ActorSystem.Settings, val prerequisites: DispatcherPrerequisites) { @@ -73,9 +53,12 @@ class Dispatchers(val settings: ActorSystem.Settings, val prerequisites: Dispatc val defaultDispatcherConfig: Config = idConfig(DefaultDispatcherId).withFallback(settings.config.getConfig(DefaultDispatcherId)) + /** + * The one and only default dispatcher. + */ def defaultGlobalDispatcher: MessageDispatcher = lookup(DefaultDispatcherId) - // FIXME: Dispatchers registered here are are not removed, see ticket #1494 + // FIXME: Configurators registered here are are not removed, see ticket #1494 private val dispatcherConfigurators = new ConcurrentHashMap[String, MessageDispatcherConfigurator] /** @@ -132,19 +115,8 @@ class Dispatchers(val settings: ActorSystem.Settings, val prerequisites: Dispatc } /* - * Creates of obtains a dispatcher from a Config according to the format below. + * Creates a dispatcher from a Config. Internal test purpose only. * - * my-dispatcher { - * type = "Dispatcher" # Must be one of the following - * # Dispatcher, (BalancingDispatcher, only valid when all actors using it are of the same type), - * # A FQCN to a class inheriting MessageDispatcherConfigurator with a no-arg visible constructor - * name = "MyDispatcher" # Optional, will be a generated UUID if omitted - * keep-alive-time = 60 # Keep alive time for threads in akka.time-unit - * core-pool-size-factor = 1.0 # No of core threads ... ceil(available processors * factor) - * max-pool-size-factor = 4.0 # Max no of threads ... ceil(available processors * factor) - * allow-core-timeout = on # Allow core threads to time out - * throughput = 5 # Throughput for Dispatcher - * } * ex: from(config.getConfig(id)) * * The Config must also contain a `id` property, which is the identifier of the dispatcher. @@ -156,6 +128,14 @@ class Dispatchers(val settings: ActorSystem.Settings, val prerequisites: Dispatc configuratorFrom(cfg).dispatcher() } + /* + * Creates a MessageDispatcherConfigurator from a Config. + * + * The Config must also contain a `id` property, which is the identifier of the dispatcher. + * + * Throws: IllegalArgumentException if the value of "type" is not valid + * IllegalArgumentException if it cannot create the MessageDispatcherConfigurator + */ private def configuratorFrom(cfg: Config): MessageDispatcherConfigurator = { if (!cfg.hasPath("id")) throw new IllegalArgumentException("Missing dispatcher 'id' property in config: " + cfg.root.render) @@ -178,6 +158,11 @@ class Dispatchers(val settings: ActorSystem.Settings, val prerequisites: Dispatc } } +/** + * Configurator for creating [[akka.dispatch.Dispatcher]]. + * Returns the same dispatcher instance for for each invocation + * of the `dispatcher()` method. + */ class DispatcherConfigurator(config: Config, prerequisites: DispatcherPrerequisites) extends MessageDispatcherConfigurator(config, prerequisites) { @@ -198,6 +183,11 @@ class DispatcherConfigurator(config: Config, prerequisites: DispatcherPrerequisi override def dispatcher(): MessageDispatcher = instance } +/** + * Configurator for creating [[akka.dispatch.BalancingDispatcher]]. + * Returns the same dispatcher instance for for each invocation + * of the `dispatcher()` method. + */ class BalancingDispatcherConfigurator(config: Config, prerequisites: DispatcherPrerequisites) extends MessageDispatcherConfigurator(config, prerequisites) { @@ -218,6 +208,11 @@ class BalancingDispatcherConfigurator(config: Config, prerequisites: DispatcherP override def dispatcher(): MessageDispatcher = instance } +/** + * Configurator for creating [[akka.dispatch.PinnedDispatcher]]. + * Returns new dispatcher instance for for each invocation + * of the `dispatcher()` method. + */ class PinnedDispatcherConfigurator(config: Config, prerequisites: DispatcherPrerequisites) extends MessageDispatcherConfigurator(config, prerequisites) { /** diff --git a/akka-actor/src/main/scala/akka/dispatch/PinnedDispatcher.scala b/akka-actor/src/main/scala/akka/dispatch/PinnedDispatcher.scala index 4915afe8a2..8c1cc6dd9e 100644 --- a/akka-actor/src/main/scala/akka/dispatch/PinnedDispatcher.scala +++ b/akka-actor/src/main/scala/akka/dispatch/PinnedDispatcher.scala @@ -14,6 +14,9 @@ import java.util.concurrent.TimeUnit /** * Dedicates a unique thread for each actor passed in as reference. Served through its messageQueue. + * + * The preferred way of creating dispatchers is to define configuration of it and use the + * the `lookup` method in [[akka.dispatch.Dispatchers]]. */ class PinnedDispatcher( _prerequisites: DispatcherPrerequisites, diff --git a/akka-docs/java/dispatchers.rst b/akka-docs/java/dispatchers.rst index 29eba1769c..50bae0bd97 100644 --- a/akka-docs/java/dispatchers.rst +++ b/akka-docs/java/dispatchers.rst @@ -27,7 +27,8 @@ See below for details on which ones are available and how they can be configured Setting the dispatcher ---------------------- -You specify the dispatcher to use when creating an actor. +You specify the id of the dispatcher to use when creating an actor. The id corresponds to the :ref:`configuration` key +of the dispatcher settings. .. includecode:: code/akka/docs/dispatcher/DispatcherDocTestBase.java :include: imports,defining-dispatcher @@ -44,18 +45,15 @@ There are 4 different types of message dispatchers: It is recommended to define the dispatcher in :ref:`configuration` to allow for tuning for different environments. -Example of a custom event-based dispatcher, which can be fetched with ``system.dispatchers().lookup("my-dispatcher")`` +Example of a custom event-based dispatcher, which can be used with +``new Props().withCreator(MyUntypedActor.class).withDispatcher("my-dispatcher")`` as in the example above: .. includecode:: ../scala/code/akka/docs/dispatcher/DispatcherDocSpec.scala#my-dispatcher-config -Default values are taken from ``default-dispatcher``, i.e. all options doesn't need to be defined. - -.. warning:: - - Factory methods for creating dispatchers programmatically are available in ``akka.dispatch.Dispatchers``, i.e. - ``dispatchers`` of the ``ActorSystem``. These methods will probably be changed or removed before - 2.0 final release, because dispatchers need to be defined by configuration to work in a clustered setup. +Default values are taken from ``default-dispatcher``, i.e. all options doesn't need to be defined. See +:ref:`configuration` for the default values of the ``default-dispatcher``. You can also override +the values for the ``default-dispatcher`` in your configuration. Let's now walk through the different dispatchers in more detail. diff --git a/akka-docs/scala/code/akka/docs/dispatcher/DispatcherDocSpec.scala b/akka-docs/scala/code/akka/docs/dispatcher/DispatcherDocSpec.scala index 2b576fe479..6b4e17b63b 100644 --- a/akka-docs/scala/code/akka/docs/dispatcher/DispatcherDocSpec.scala +++ b/akka-docs/scala/code/akka/docs/dispatcher/DispatcherDocSpec.scala @@ -109,8 +109,7 @@ class DispatcherDocSpec extends AkkaSpec(DispatcherDocSpec.config) { "defining pinned dispatcher" in { //#defining-pinned-dispatcher - val name = "myactor" - val myActor = system.actorOf(Props[MyActor].withDispatcher("my-dispatcher"), name) + val myActor = system.actorOf(Props[MyActor].withDispatcher("my-dispatcher"), name = "myactor") //#defining-pinned-dispatcher } diff --git a/akka-docs/scala/dispatchers.rst b/akka-docs/scala/dispatchers.rst index 5f38b84641..3006152c49 100644 --- a/akka-docs/scala/dispatchers.rst +++ b/akka-docs/scala/dispatchers.rst @@ -27,7 +27,8 @@ See below for details on which ones are available and how they can be configured Setting the dispatcher ---------------------- -You specify the dispatcher to use when creating an actor. +You specify the id of the dispatcher to use when creating an actor. The id corresponds to the :ref:`configuration` key +of the dispatcher settings. .. includecode:: code/akka/docs/dispatcher/DispatcherDocSpec.scala :include: imports,defining-dispatcher @@ -44,18 +45,14 @@ There are 4 different types of message dispatchers: It is recommended to define the dispatcher in :ref:`configuration` to allow for tuning for different environments. -Example of a custom event-based dispatcher, which can be fetched with ``system.dispatchers.lookup("my-dispatcher")`` +Example of a custom event-based dispatcher, which can be used with ``Props[MyActor].withDispatcher("my-dispatcher")`` as in the example above: .. includecode:: code/akka/docs/dispatcher/DispatcherDocSpec.scala#my-dispatcher-config -Default values are taken from ``default-dispatcher``, i.e. all options doesn't need to be defined. - -.. warning:: - - Factory methods for creating dispatchers programmatically are available in ``akka.dispatch.Dispatchers``, i.e. - ``dispatchers`` of the ``ActorSystem``. These methods will probably be changed or removed before - 2.0 final release, because dispatchers need to be defined by configuration to work in a clustered setup. +Default values are taken from ``default-dispatcher``, i.e. all options doesn't need to be defined. See +:ref:`configuration` for the default values of the ``default-dispatcher``. You can also override +the values for the ``default-dispatcher`` in your configuration. Let's now walk through the different dispatchers in more detail.