Memory Effects and Threading

The Stormpot pooling library exhibits and guarantees a number of memory effects, that can be relied upon in concurrent and multi-threaded programs.

Happens-Before Edges

Stormpot inserts a number of happens-before edges into the flow-graph of the program. These help ensure that the thread-safety properties of any code using the pool, is pretty much what one would reasonably and intuitively expect. Basically, if you follow recommended coding practices, where you don’t share claimed objects between threads, but leave the concurrency to the pool, then you won’t have any problems. As you implement Stormpot interfaces, and call methods on the Stormpot API, make sure that you read the associated javadoc, and pay attention to any notes and warnings about concurrency and thread-safety. If you do that, the pool will take care of the rest in a sensible manner.

The happens-before edges the pool introduces, are these:

  1. The allocation, through Allocator#allocate, of an object happens-before any claim, through Pool#claim, of that object.

  2. The claim of an object happens-before any subsequent release of the object.

  3. The release, through Poolable#release, of an object happens-before any subsequent claim of that object.

  4. The release of an object happens-before the deallocation, through Allocator#deallocate, of that object.

  5. The reallocation, through Reallocator#reallocate, of an object happens-before any claim of that object.

  6. The release of an object happens-before any reallocation, through Reallocator#reallocate, of that object.

  7. The deallocation of all objects happens-before the Completion#await method successfully returns true.

Interruption

The (only two) blocking methods, Pool#claim and Completion#await, behave correctly with respect to interruption: If a thread is interrupted when it calls one of these methods, or the thread is interrupted while waiting in one these methods, then an java.lang.InterruptedException will be thrown, and the threads interruption flag will be cleared.

When a pool is shut down, it may interrupt its background allocation thread, which may be interacting with the allocator at the time. For this reason, Allocator implementations should be interruption-safe.