Documentation

[JanKoelzer]

• valueCallback must not capture other cells (via putX)
• valueCallback in whenNext might be called with the same value twice
• different valueCallback must not write mutable data. Note that reading is OK, e.g. methodToCell is mutable. Are there exceptions? Document them.
• use whenComplete carefully! A whenComplete cycle might not have progress, while a whileNext cycle has
• prefer whenNext over whenNextSequential, but use latter, if state is needed
• whenNextSequential calls all callbacks of this cell sequentially. (Callbacks for other cells run concurrently)

[JanKoelzer]

For second item, see

` test("trigger with newest") {
// In this test, if "triggerWithNewest" is included in the code,
// (1) the callback for cell1/cell2 is sometimes triggered with identical values
// (2) the callback for cell3/cell1 "heavy calc" is only triggered, if acutally needed
// If "triggerWithNewest" is not included, (1) does not happen, BUT values passed to the callback can "decrease"
// which seems even worse.

class PowerSetLattice[T] extends Lattice[Set[T]] {
  def join(left: Set[T], right: Set[T]): Set[T] =
    left ++ right
  def empty: Set[T] =
    Set[T]()
}

val latch = new CountDownLatch(1)

val pool = new HandlerPool
val completer1 = CellCompleter[DefaultKey[Set[Int]], Set[Int]](pool, new DefaultKey[Set[Int]])(new PowerSetLattice)
val cell1 = completer1.cell
val completer2 = CellCompleter[DefaultKey[Set[Int]], Set[Int]](pool, new DefaultKey[Set[Int]])(new PowerSetLattice)
val cell2 = completer2.cell
val completer3 = CellCompleter[DefaultKey[Set[Int]], Set[Int]](pool, new DefaultKey[Set[Int]])(new PowerSetLattice)
val cell3 = completer3.cell

cell1.whenNext(cell2, x => {
  println(x.size)
  Outcome(x, x.size == 10)
})
cell3.whenNext(cell1, _ => {
  println("heavy calculation")
  NoOutcome
})

cell1.onComplete(_=> latch.countDown())

for(i <- 1 to 10) {
  pool.execute(() => completer2.putNext(Set(i)))
  pool.execute(() => completer2.putNext(Set(i)))
}

latch.await()

pool.shutdown()

}
`