Merge pull request #698 from akka/wip-944-consistent-hashing-patriknw

Consistent hashing router, see #944

akka-docs/scala/code/docs/routing/ConsistentHashingRouterDocSpec.scala

@@ -0,0 +1,73 @@
+/**
+ * Copyright (C) 2009-2012 Typesafe Inc. <http://www.typesafe.com>
+ */
+package docs.routing
+
+import akka.testkit.AkkaSpec
+import akka.testkit.ImplicitSender
+
+object ConsistentHashingRouterDocSpec {
+
+  //#cache-actor
+  import akka.actor.Actor
+  import akka.routing.ConsistentHashingRouter.ConsistentHashable
+
+  class Cache extends Actor {
+    var cache = Map.empty[String, String]
+
+    def receive = {
+      case Entry(key, value) ⇒ cache += (key -> value)
+      case Get(key)          ⇒ sender ! cache.get(key)
+      case Evict(key)        ⇒ cache -= key
+    }
+  }
+
+  case class Evict(key: String)
+
+  case class Get(key: String) extends ConsistentHashable {
+    override def consistentHashKey: Any = key
+  }
+
+  case class Entry(key: String, value: String)
+  //#cache-actor
+
+}
+
+class ConsistentHashingRouterDocSpec extends AkkaSpec with ImplicitSender {
+
+  import ConsistentHashingRouterDocSpec._
+
+  "demonstrate usage of ConsistentHashableRouter" in {
+
+    //#consistent-hashing-router
+    import akka.actor.Props
+    import akka.routing.ConsistentHashingRouter
+    import akka.routing.ConsistentHashingRouter.ConsistentHashMapping
+    import akka.routing.ConsistentHashingRouter.ConsistentHashableEnvelope
+
+    def hashMapping: ConsistentHashMapping = {
+      case Evict(key) ⇒ key
+    }
+
+    val cache = system.actorOf(Props[Cache].withRouter(ConsistentHashingRouter(10,
+      hashMapping = hashMapping)), name = "cache")
+
+    cache ! ConsistentHashableEnvelope(
+      message = Entry("hello", "HELLO"), hashKey = "hello")
+    cache ! ConsistentHashableEnvelope(
+      message = Entry("hi", "HI"), hashKey = "hi")
+
+    cache ! Get("hello")
+    expectMsg(Some("HELLO"))
+
+    cache ! Get("hi")
+    expectMsg(Some("HI"))
+
+    cache ! Evict("hi")
+    cache ! Get("hi")
+    expectMsg(None)
+
+    //#consistent-hashing-router
+  }
+
+}

akka-docs/scala/code/docs/routing/RouterViaConfigDocSpec.scala

@@ -0,0 +1,158 @@
+/**
+ * Copyright (C) 2009-2012 Typesafe Inc. <http://www.typesafe.com>
+ */
+package docs.routing
+
+import akka.actor.{ Actor, Props, ActorSystem, ActorLogging }
+import com.typesafe.config.ConfigFactory
+import akka.routing.FromConfig
+import akka.routing.ConsistentHashingRouter.ConsistentHashable
+import akka.testkit.AkkaSpec
+import akka.testkit.ImplicitSender
+
+object RouterWithConfigDocSpec {
+
+  val config = ConfigFactory.parseString("""
+
+    //#config-round-robin
+    akka.actor.deployment {
+      /myrouter1 {
+        router = round-robin
+        nr-of-instances = 5
+      }
+    }
+    //#config-round-robin
+
+    //#config-resize
+    akka.actor.deployment {
+      /myrouter2 {
+        router = round-robin
+        resizer {
+          lower-bound = 2
+          upper-bound = 15
+        }
+      }
+    }
+    //#config-resize
+
+    //#config-random
+    akka.actor.deployment {
+      /myrouter3 {
+        router = random
+        nr-of-instances = 5
+      }
+    }
+    //#config-random
+
+    //#config-smallest-mailbox
+    akka.actor.deployment {
+      /myrouter4 {
+        router = smallest-mailbox
+        nr-of-instances = 5
+      }
+    }
+    //#config-smallest-mailbox
+
+    //#config-broadcast
+    akka.actor.deployment {
+      /myrouter5 {
+        router = broadcast
+        nr-of-instances = 5
+      }
+    }
+    //#config-broadcast
+
+    //#config-scatter-gather
+    akka.actor.deployment {
+      /myrouter6 {
+        router = scatter-gather
+        nr-of-instances = 5
+        within = 10 seconds
+      }
+    }
+    //#config-scatter-gather
+
+    //#config-consistent-hashing
+    akka.actor.deployment {
+      /myrouter7 {
+        router = consistent-hashing
+        nr-of-instances = 5
+        virtual-nodes-factor = 10
+      }
+    }
+    //#config-consistent-hashing
+
+    """)
+
+  case class Message(nbr: Int) extends ConsistentHashable {
+    override def consistentHashKey = nbr
+  }
+
+  class ExampleActor extends Actor with ActorLogging {
+    def receive = {
+      case Message(nbr) ⇒
+        log.debug("Received %s in router %s".format(nbr, self.path.name))
+        sender ! nbr
+    }
+  }
+
+}
+
+class RouterWithConfigDocSpec extends AkkaSpec(RouterWithConfigDocSpec.config) with ImplicitSender {
+
+  import RouterWithConfigDocSpec._
+
+  "demonstrate configured round-robin router" in {
+    //#configurableRouting
+    val router = system.actorOf(Props[ExampleActor].withRouter(FromConfig()),
+      "myrouter1")
+    //#configurableRouting
+    1 to 10 foreach { i ⇒ router ! Message(i) }
+    receiveN(10)
+  }
+
+  "demonstrate configured random router" in {
+    val router = system.actorOf(Props[ExampleActor].withRouter(FromConfig()),
+      "myrouter3")
+    1 to 10 foreach { i ⇒ router ! Message(i) }
+    receiveN(10)
+  }
+
+  "demonstrate configured smallest-mailbox router" in {
+    val router = system.actorOf(Props[ExampleActor].withRouter(FromConfig()),
+      "myrouter4")
+    1 to 10 foreach { i ⇒ router ! Message(i) }
+    receiveN(10)
+  }
+
+  "demonstrate configured broadcast router" in {
+    val router = system.actorOf(Props[ExampleActor].withRouter(FromConfig()),
+      "myrouter5")
+    1 to 10 foreach { i ⇒ router ! Message(i) }
+    receiveN(5 * 10)
+  }
+
+  "demonstrate configured scatter-gather router" in {
+    val router = system.actorOf(Props[ExampleActor].withRouter(FromConfig()),
+      "myrouter6")
+    1 to 10 foreach { i ⇒ router ! Message(i) }
+    receiveN(10)
+  }
+
+  "demonstrate configured consistent-hashing router" in {
+    val router = system.actorOf(Props[ExampleActor].withRouter(FromConfig()),
+      "myrouter7")
+    1 to 10 foreach { i ⇒ router ! Message(i) }
+    receiveN(10)
+  }
+
+  "demonstrate configured round-robin router with resizer" in {
+    //#configurableRoutingWithResizer
+    val router = system.actorOf(Props[ExampleActor].withRouter(FromConfig()),
+      "myrouter2")
+    //#configurableRoutingWithResizer
+    1 to 10 foreach { i ⇒ router ! Message(i) }
+    receiveN(10)
+  }
+
+}

akka-docs/scala/code/docs/routing/RouterViaConfigExample.scala

@@ -1,52 +0,0 @@
-/**
- * Copyright (C) 2009-2012 Typesafe Inc. <http://www.typesafe.com>
- */
-package docs.routing
-
-import akka.actor.{ Actor, Props, ActorSystem }
-import com.typesafe.config.ConfigFactory
-import akka.routing.FromConfig
-
-case class Message(nbr: Int)
-
-class ExampleActor extends Actor {
-  def receive = {
-    case Message(nbr) ⇒ println("Received %s in router %s".format(nbr, self.path.name))
-  }
-}
-
-object RouterWithConfigExample extends App {
-  val config = ConfigFactory.parseString("""
-    //#config
-    akka.actor.deployment {
-      /router {
-        router = round-robin
-        nr-of-instances = 5
-      }
-    }
-    //#config
-    //#config-resize
-    akka.actor.deployment {
-      /router2 {
-        router = round-robin
-        resizer {
-          lower-bound = 2
-          upper-bound = 15
-        }
-      }
-    }
-    //#config-resize
-      """)
-  val system = ActorSystem("Example", config)
-  //#configurableRouting
-  val router = system.actorOf(Props[ExampleActor].withRouter(FromConfig()),
-    "router")
-  //#configurableRouting
-  1 to 10 foreach { i ⇒ router ! Message(i) }
-
-  //#configurableRoutingWithResizer
-  val router2 = system.actorOf(Props[ExampleActor].withRouter(FromConfig()),
-    "router2")
-  //#configurableRoutingWithResizer
-  1 to 10 foreach { i ⇒ router2 ! Message(i) }
-}

akka-docs/scala/routing.rst

@@ -15,15 +15,16 @@ is really easy to create your own. The routers shipped with Akka are:
 * ``akka.routing.SmallestMailboxRouter``
 * ``akka.routing.BroadcastRouter``
 * ``akka.routing.ScatterGatherFirstCompletedRouter``
+* ``akka.routing.ConsistentHashingRouter``
 
 Routers In Action
 ^^^^^^^^^^^^^^^^^
 
 This is an example of how to create a router that is defined in configuration:
 
-.. includecode:: code/docs/routing/RouterViaConfigExample.scala#config
+.. includecode:: code/docs/routing/RouterViaConfigDocSpec.scala#config-round-robin
 
-.. includecode:: code/docs/routing/RouterViaConfigExample.scala#configurableRouting
+.. includecode:: code/docs/routing/RouterViaConfigDocSpec.scala#configurableRouting
 
 This is an example of how to programmatically create a router and set the number of routees it should create:
 
@@ -125,7 +126,7 @@ not have an effect on the number of actors in the pool.
 
 Setting the strategy is easily done:
 
-.. includecode:: ../../akka-actor-tests/src/test/scala/akka/routing/RoutingSpec.scala
+.. includecode:: ../../akka-actor-tests/src/test/scala/akka/routing/RoutingSpec.scala#supervision
    :include: supervision
    :exclude: custom-strategy
 
@@ -179,6 +180,10 @@ is exactly what you would expect from a round-robin router to happen.
 (The name of an actor is automatically created in the format ``$letter`` unless you specify it -
 hence the names printed above.)
 
+This is an example of how to define a round-robin router in configuration:
+
+.. includecode:: code/docs/routing/RouterViaConfigDocSpec.scala#config-round-robin
+
 RandomRouter
 ************
 As the name implies this router type selects one of its routees randomly and forwards
@@ -206,6 +211,10 @@ When run you should see a similar output to this:
 The result from running the random router should be different, or at least random, every time you run it.
 Try to run it a couple of times to verify its behavior if you don't trust us.
 
+This is an example of how to define a random router in configuration:
+
+.. includecode:: code/docs/routing/RouterViaConfigDocSpec.scala#config-random
+
 SmallestMailboxRouter
 *********************
 A Router that tries to send to the non-suspended routee with fewest messages in mailbox.
@@ -221,6 +230,11 @@ Code example:
 
 .. includecode:: code/docs/routing/RouterTypeExample.scala#smallestMailboxRouter
 
+
+This is an example of how to define a smallest-mailbox router in configuration:
+
+.. includecode:: code/docs/routing/RouterViaConfigDocSpec.scala#config-smallest-mailbox
+
 BroadcastRouter
 ***************
 A broadcast router forwards the message it receives to *all* its routees.
@@ -240,6 +254,11 @@ When run you should see a similar output to this:
 
 As you can see here above each of the routees, five in total, received the broadcast message.
 
+This is an example of how to define a broadcast router in configuration:
+
+.. includecode:: code/docs/routing/RouterViaConfigDocSpec.scala#config-broadcast
+
+
 ScatterGatherFirstCompletedRouter
 *********************************
 The ScatterGatherFirstCompletedRouter will send the message on to all its routees as a future.
@@ -257,6 +276,51 @@ When run you should see this:
 From the output above you can't really see that all the routees performed the calculation, but they did!
 The result you see is from the first routee that returned its calculation to the router.
 
+This is an example of how to define a scatter-gather router in configuration:
+
+.. includecode:: code/docs/routing/RouterViaConfigDocSpec.scala#config-scatter-gather
+
+
+ConsistentHashingRouter
+***********************
+
+The ConsistentHashingRouter uses `consistent hashing <http://en.wikipedia.org/wiki/Consistent_hashing>`_
+to select a connection based on the sent message. This 
+`article <http://weblogs.java.net/blog/tomwhite/archive/2007/11/consistent_hash.html>`_ gives good 
+insight into how consistent hashing is implemented.
+
+There is 3 ways to define what data to use for the consistent hash key.
+
+* You can define ``hashMapping`` of the router to map incoming
+  messages to their consistent hash key. This makes the decision
+  transparent for the sender.
+
+* The messages may implement ``akka.routing.ConsistentHashingRouter.ConsistentHashable``.
+  The key is part of the message and it's convenient to define it together
+  with the message definition.
+ 
+* The messages can be be wrapped in a ``akka.routing.ConsistentHashingRouter.ConsistentHashableEnvelope``
+  to define what data to use for the consistent hash key. The sender knows
+  the key to use.
+ 
+These ways to define the consistent hash key can be use together and at
+the same time for one router. The ``hashMapping`` is tried first.
+
+Code example:
+
+.. includecode:: code/docs/routing/ConsistentHashingRouterDocSpec.scala#cache-actor
+
+.. includecode:: code/docs/routing/ConsistentHashingRouterDocSpec.scala#consistent-hashing-router
+
+In the above example you see that the ``Get`` message implements ``ConsistentHashable`` itself,
+while the ``Entry`` message is wrapped in a ``ConsistentHashableEnvelope``. The ``Evict``
+message is handled by the ``hashMapping`` partial function.
+
+This is an example of how to define a consistent-hashing router in configuration:
+
+.. includecode:: code/docs/routing/RouterViaConfigDocSpec.scala#config-consistent-hashing
+
+
 Broadcast Messages
 ^^^^^^^^^^^^^^^^^^
 
@@ -278,9 +342,9 @@ of routees dynamically.
 
 This is an example of how to create a resizable router that is defined in configuration:
 
-.. includecode:: code/docs/routing/RouterViaConfigExample.scala#config-resize
+.. includecode:: code/docs/routing/RouterViaConfigDocSpec.scala#config-resize
 
-.. includecode:: code/docs/routing/RouterViaConfigExample.scala#configurableRoutingWithResizer
+.. includecode:: code/docs/routing/RouterViaConfigDocSpec.scala#configurableRoutingWithResizer
 
 Several more configuration options are available and described in ``akka.actor.deployment.default.resizer``
 section of the reference :ref:`configuration`.