Dispatcher (SEDA configuration)

The Dispatcher is an important piece that allows you to configure the right semantics and parameters for optimal performance, throughput and scalability.

Akka supports dispatchers for both event-driven lightweight threads (allowing creation of millions threads on a single workstation) and regular thread-based threads (where each dispatcher is bound to a dedicated OS thread).

The event-driven dispatchers should be shared between multiple Active Objects and/or Actors for best performance. One best practice is to let each top-level Actor, e.g. the Actors you define in the declarative supervisor config, to get their own dispatcher but reuse the dispatcher for each new Actor that the top-level Actor creates. But you can also share dispatcher between multiple top-level Actors. This is very use-case specific and needs to be tried out on a case by case basis. The important thing is that Akka tries to provide you with the freedom you need to design and implement your system in the most efficient way in regards to performance, throughput and latency.

There are three different type of MessageDispatcher:

Thread-based

The ThreadBasedDispatcher binds a dedicated OS thread to each specific Actor. The messages are posted to a LinkedBlockingQueue which feeds the messages to the dispatcher one by one. A ThreadBasedDispatcher cannot be shared between actors.

// Scala style
val dispatcher = Dispatchers.newThreadBasedDispatcher(actor)

Event-based with thread pool

The EventBasedThreadPoolDispatcher binds a set of Actors to a thread pool backed up by a BlockingQueue. This dispatcher is highly configurable and supports a fluent configuration API to configure the BlockingQueue (type, max items etc.) as well as the thread pool. It comes with three different predefined BlockingQueue configurations:

• Bounded LinkedBlockingQueue
• Unbounded LinkedBlockingQueue
• SynchronousQueue

Here is an example

val dispatcher = Dispatchers.newEventBasedThreadPoolDispatcher
  .withNewThreadPoolWithBoundedBlockingQueue(100)
  .setCorePoolSize(16)
  .setMaxPoolSize(128)
  .setKeepAliveTimeInMillis(60000)
  .setRejectionPolicy(new CallerRunsPolicy)
  .buildThreadPool

Browse the ScalaDoc API or look at the code for all the options available.

Event-based single-threaded

The EventBasedSingleThreadDispatcher binds a set of Actors to a single OS thread where the execution in interleaved.

// Scala style
val dispatcher = Dispatchers.newEventBasedSingleThreadDispatcher

Java API

DispatcherFactory dispatcherFactory = new DispatcherFactory();
MessageDispatcher dispatcher = dispatcherFactory.newEventBasedThreadPoolDispatcher()

The dispatcher for an Active Object can be defined in the declarative configuration:

... // part of configuration
new Component(
  MyActiveObject.class, 
  new LifeCycle(new Permanent(), 1000), 
  dispatcher,
  1000)
...

It can also be set when creating a new Active Object programmatically.

MyPOJO pojo = factory.newInstance(MyPOJO.class, 1000, dispatcher);

Scala API

val dispatcher = Dispatchers.newEventBasedThreadPoolDispatcher

The dispatcher can be set in an Actor by setting the dispatcher member field (default if not overridden is EventBasedThreadPoolDispatcher):

class MyActor extends Actor {

  dispatcher = Dispatchers.newThreadBasedDispatcher(this)

   … // other stuff

}

You can also set the dispatcher for an Actor before it has been started:

actor.setDispatcher(dispatcher)

Concurrent mode

Akka supports running Actors and Active Objects in so-called “concurrent mode”. This means that the semantics of the Actor model (e.g. that an Actor only can process one message at a time) is abandoned and instead allowing multiple threads to access the Actor concurrently. You can use this option to optimize concurrency and performance in certain scenarios but you are on your own and need to synchronize access to shared state within the Actor using critical sections.

<akka>
  <actor>
    concurrent-mode = off # if turned on, then the same actor instance is allowed to execute concurrently - 
  </actor>
</akka>