What does the "throughput-deadline-time" configuration option do?

I've stumbled on the throughput-deadline-time configuration property for Akka dispatchers, and it looks like an interesting option, however the only mention of it I could find in the whole documentation is the following:

  # Throughput deadline for Dispatcher, set to 0 or negative for no deadline
  throughput-deadline-time = 0ms

I think we can agree that this is not very helpful.

So what does throughput-deadline-time control, and what impact does it have when on my dispatcher?

So I had a look at the Akka source code, and found this method in the Mailbox that seems to implement the behavior of throughput-deadline-time:

/**
 * Process the messages in the mailbox
 */
@tailrec private final def processMailbox(
  left:       Int  = java.lang.Math.max(dispatcher.throughput, 1),
  deadlineNs: Long = if (dispatcher.isThroughputDeadlineTimeDefined == true) System.nanoTime + dispatcher.throughputDeadlineTime.toNanos else 0L):     Unit =
  if (shouldProcessMessage) {
    val next = dequeue()
    if (next ne null) {
      if (Mailbox.debug) println(actor.self + " processing message " + next)
      actor invoke next
      if (Thread.interrupted())
        throw new InterruptedException("Interrupted while processing actor messages")
      processAllSystemMessages()
      if ((left > 1) && ((dispatcher.isThroughputDeadlineTimeDefined == false) || (System.nanoTime - deadlineNs) < 0))
        processMailbox(left - 1, deadlineNs)
    }
  }

This piece of code makes it clear: throughput-deadline-time configures the maximum amount of time that will be spent processing the same mailbox, before switching to the mailbox of another actor.

In other words, if you configure a dispatcher with:

my-dispatcher {
  throughput = 100
  throughput-deadline-time = 1ms
}

Then the mailbox of the actors will process at most 100 messages at a time, during at most 1ms, whenever the first of those limits is hit, Akka switches to another actor/mailbox.