Add immutable LIRS Cache implementation

project/Build.scala

@@ -147,7 +147,9 @@ object StorehausBuild extends Build {
     ).dependsOn(storehausTesting % "test->test")
   }
 
-  lazy val storehausCache = module("cache")
+  lazy val storehausCache = module("cache").settings(
+    libraryDependencies += "com.twitter" %% "algebird-core" % algebirdVersion
+  )
 
   lazy val storehausCore = module("core").settings(
     libraryDependencies ++= Seq(

storehaus-cache/src/main/scala/com/twitter/storehaus/cache/Clock.scala

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2013 Twitter Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License. You may obtain
+ * a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.twitter.storehaus.cache
+
+/**
+ * A clock is anything which provides a succession of values.
+ */
+
+trait Clock[@specialized(Int, Long) T, +This <: Clock[T, This]] {
+  def tick: (T, This)
+  def empty: This
+}
+
+trait IdProvider[@specialized(Int, Long) T] extends Clock[T, IdProvider[T]] {
+  def cull(oldId: T): IdProvider[T]
+}
+
+case class LongClock(v:Long = 0) extends Clock[Long, LongClock] {
+  def tick = (v, LongClock(v + 1))
+  def empty = LongClock()
+}

storehaus-cache/src/main/scala/com/twitter/storehaus/cache/CyclicIncrement.scala

@@ -0,0 +1,129 @@
+/*
+ * Copyright 2013 Twitter Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License. You may obtain
+ * a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.twitter.storehaus.cache
+
+import com.twitter.algebird.Successible
+
+/**
+ * This is an immutable implementation of a provider of cyclical increments. The motivation
+ * is that we need ordered identifiers for caches, but we do not want to just increment
+ * an int as this has a theoretical upper limit (this is functional programming, our stuff
+ * doesn't crash, right?). This class allows the reuse of numbers, making it highly unlikely
+ * to run out of identifiers (it is still possible, but in a way that would be unavoidable --
+ * if there is a key that stays in the stacks forever, thus never allowing us to reuse the
+ * increments after that key). This class ensures that when it is asked for a new increment,
+ * it will be greater than all currently outstanding increments at that time.
+ *
+ * @author Jonathan Coveney
+ */
+
+object CyclicIncrementProvider {
+  def intIncrementer: CyclicIncrementProvider[Int] = CyclicIncrementProvider(0)
+
+  def apply[@specialized(Int, Long) K: Ordering: Successible](zero: K): CyclicIncrementProvider[K] =
+    CyclicIncrementProvider(zero, SideA, 0, zero, 0, zero)
+
+  def apply[@specialized(Int, Long) K: Ordering: Successible]
+    (zero: K,
+     currentSide: Side,
+     currentSideCount: Int,
+     maxCurrentSideVal: K,
+     nextSideCount: Int,
+     maxNextSideVal: K): CyclicIncrementProvider[K] =
+    new CyclicIncrementProvider[K](zero, currentSide, currentSideCount, maxCurrentSideVal, nextSideCount, maxNextSideVal)
+}
+
+// Algorithm: we start on a side. We hand out values. Once we've handed out at least 1 value, we begin to give out values of side.nextSide. Once
+// all of the increments of the previous side have been culled, we now switch. side.nextSide becomes the current side. Then we repeat the algorithm.
+class CyclicIncrementProvider[@specialized(Int, Long) K: Ordering: Successible]
+  (zero: K,
+   currentSide: Side,
+   currentSideCount: Int,
+   maxCurrentSideVal: K,
+   nextSideCount: Int,
+   maxNextSideVal: K) extends IdProvider[CyclicIncrement[K]] {
+  def tick: (CyclicIncrement[K], CyclicIncrementProvider[K]) =
+    if (nextSideCount > 0 || currentSideCount > 0) {
+      // We hand one out of the next time
+      val nextVal =
+        Successible.next(maxNextSideVal)
+          .getOrElse(throw new IllegalStateException("Hit maximum value for increment"))
+      (currentSide.nextSide.makeCyclicIncrement(nextVal),
+       CyclicIncrementProvider[K](zero, currentSide, currentSideCount, maxCurrentSideVal, nextSideCount+1, nextVal))
+    } else {
+      // We hand out one of the current time
+      val nextVal =
+        Successible.next(maxCurrentSideVal)
+          .getOrElse(throw new IllegalStateException("Hit maximum value for increment"))
+      (currentSide.makeCyclicIncrement(nextVal),
+       CyclicIncrementProvider[K](zero, currentSide, currentSideCount+1, nextVal, nextSideCount, maxNextSideVal))
+    }
+
+  def cull(cyclicIncrement: CyclicIncrement[K]): CyclicIncrementProvider[K] =
+    if (cyclicIncrement.side == currentSide) {
+      val nextCurrentSidecount = currentSideCount - 1
+      if (nextCurrentSidecount == 0) {
+        CyclicIncrementProvider[K](zero, currentSide.nextSide, nextSideCount, maxNextSideVal, 0, zero)
+      } else {
+        CyclicIncrementProvider[K](zero, currentSide, nextCurrentSidecount, maxCurrentSideVal, nextSideCount, maxNextSideVal)
+      }
+    } else if (cyclicIncrement.side == currentSide.nextSide) {
+      CyclicIncrementProvider[K](zero, currentSide, currentSideCount, maxCurrentSideVal, nextSideCount-1, maxNextSideVal)
+    } else {
+      throw new IllegalStateException("Shouldn't be culling a value of given type")
+    }
+
+    override def toString =
+      "CyclicIncrementProvider: zero:%d currentSide:%s currentSideCount:%d maxCurrentSideVal:%d nextSideCount:%d maxNextSideVal:%d"
+        .format(zero, currentSide, currentSideCount, maxCurrentSideVal, nextSideCount, maxNextSideVal)
+
+    def empty = CyclicIncrementProvider(zero)
+}
+
+object CyclicIncrement {
+  implicit def ordering[K](implicit ordering:Ordering[K]): Ordering[CyclicIncrement[K]] = Ordering.by { _.value }
+}
+
+sealed trait CyclicIncrement[@specialized(Int, Long) K] {
+  def value: K
+  def ordering(implicit ord: Ordering[K]): Ordering[K] = ord
+  def side: Side
+  override def toString = side + ":" + value
+}
+
+case class SideACyclicIncrement[@specialized(Int, Long) K: Ordering](override val value: K) extends CyclicIncrement[K] { def side = SideA }
+case class SideBCyclicIncrement[@specialized(Int, Long) K: Ordering](override val value: K) extends CyclicIncrement[K] { def side = SideB }
+case class SideCCyclicIncrement[@specialized(Int, Long) K: Ordering](override val value: K) extends CyclicIncrement[K] { def side = SideC }
+
+sealed trait Side {
+  def nextSide: Side
+  def makeCyclicIncrement[@specialized(Int, Long) K: Ordering](value: K): CyclicIncrement[K]
+  override def toString = getClass.getSimpleName
+  def offset(that:Side) = if (this == that) 0 else if (nextSide == that) -1 else 1
+}
+object SideA extends Side {
+  def nextSide = SideB
+  def makeCyclicIncrement[@specialized(Int, Long) K: Ordering](value: K) = SideACyclicIncrement[K](value)
+}
+object SideB extends Side {
+  def nextSide = SideC
+  def makeCyclicIncrement[@specialized(Int, Long) K: Ordering](value: K) = SideBCyclicIncrement[K](value)
+}
+object SideC extends Side {
+  def nextSide = SideA
+  def makeCyclicIncrement[@specialized(Int, Long) K: Ordering](value: K) = SideCCyclicIncrement[K](value)
+}