README.adoc

May 31, 2026 ยท View on GitHub

== Stormpot

Stormpot is an object pooling library for Java. Use it to recycle objects that are expensive to create. The library will take care of creating and destroying your objects in the background.

image:https://github.com/chrisvest/stormpot/actions/workflows/maven.yml/badge.svg[Build status, link=https://github.com/chrisvest/stormpot/actions/workflows/maven.yml] image:https://codecov.io/gh/chrisvest/stormpot/branch/master/graph/badge.svg[Code coverage, link=https://codecov.io/gh/chrisvest/stormpot]

Stormpot is very mature, is used in production, and has done hundreds of trillions footnote:[Fermi estimate.] claim-release cycles in testing. It is faster and scales better than any competing pool.

=== Why choose Stormpot?

There are a number of options out there, when it comes to object pools on the JVM. Stormpot has been carefully designed for high performance, and robust operation. Some of the things that sets Stormpot apart include:

  • Business friendly http://www.apache.org/licenses/LICENSE-2.0.html[Apache 2 license].
  • Very high http://chrisvest.github.io/stormpot/site/jacoco/index.html[test coverage].
  • The https://medium.com/@chrisvest/released-stormpot-2-1-c31509142757[highest throughput and lowest latency] in its class. (since 2.1)
  • https://medium.com/@chrisvest/released-stormpot-2-2-ccd1e8639f07[Automatic recovery] from sporadic backend (Allocator) failures. (since 2.2)
  • Precise object leak detection with virtually no overhead. (since 2.3)
  • Optional background object expiration checking. (since 2.3)
  • Explicit object expiration. (since 2.4)
  • Gradual back-off for prolonged allocation failures. (since 3.0)
  • Support for Java Platform Module system. (since 3.0)
  • Support for a directly-allocating thread-less mode, via Pool.of(...). (since 3.0)
  • Convenient lambda-based API. (since 3.0)
  • Control over the thread-local caching mechanics, via PoolTaps. (since 3.0)
  • Support for operating without a background thread, via Pool.fromInline(). (since 3.1)
  • Support for configuring zero-sized (dormant) pools. (since 3.1)
  • Support for virtual threads. (since 4.0)
  • Support for more than 2 billion objects in a pool. (since 4.0)
  • Support for changing the Allocator after the pool has been created. (since 4.0)
  • Support for allocating/deallocating multiple objects in parallel. (since 4.2)
  • And other features that makes for a smooth runtime behaviour.

[NOTE]

Stormpot is an object pool; a homogeneous collection of objects, where it does not matter which particular instance is returned from claim since the objects are all similar. If your objects instead are heterogeneous, with different attributes and identified by a key, then what you need is a object cache. We recommend https://github.com/ben-manes/caffeine[Caffeine] for object caching.

=== Installing

Stormpot 4.0 only depends on Java 21 or newer. If you need to use Java 11 or newer, use Stormpot 3.2. Add it as a Maven dependency to your projects:

[source,xml]

com.github.chrisvest stormpot 4.2 ----

You can also build the latest snapshot from source with mvn clean install. Note that Stormpot 4.x requires Java 21 or newer.

=== Getting Started

Stormpot needs 3 things before it can pool objects for you:

. A http://chrisvest.github.io/stormpot/site/apidocs/stormpot/stormpot/Poolable.html[Poolable] type of objects it can pool. You have to implement this yourself. . An http://chrisvest.github.io/stormpot/site/apidocs/stormpot/stormpot/Allocator.html[Allocator] to allocate and deallocate the Poolable objects. You have to implement this yourself. . And a place where it all comes together:

[source,java]

MyAllocator allocator = new MyAllocator(); Pool pool = Pool.from(allocator).build(); Timeout timeout = new Timeout(1, TimeUnit.SECONDS);

MyPoolable object = pool.claim(timeout); try { // Do stuff with 'object'. // Note: 'claim' returns 'null' if it times out. } finally { if (object != null) { object.release(); } }