stormpot

A fast object pool library.

License

License

Categories

Categories

ORM Data
GroupId

GroupId

com.github.chrisvest
ArtifactId

ArtifactId

stormpot
Last Version

Last Version

3.1
Release Date

Release Date

Type

Type

jar
Description

Description

stormpot
A fast object pool library.
Project URL

Project URL

http://chrisvest.github.io/stormpot
Source Code Management

Source Code Management

https://github.com/chrisvest/stormpot

Download stormpot

How to add to project

<!-- https://jarcasting.com/artifacts/com.github.chrisvest/stormpot/ -->
<dependency>
    <groupId>com.github.chrisvest</groupId>
    <artifactId>stormpot</artifactId>
    <version>3.1</version>
</dependency>
// https://jarcasting.com/artifacts/com.github.chrisvest/stormpot/
implementation 'com.github.chrisvest:stormpot:3.1'
// https://jarcasting.com/artifacts/com.github.chrisvest/stormpot/
implementation ("com.github.chrisvest:stormpot:3.1")
'com.github.chrisvest:stormpot:jar:3.1'
<dependency org="com.github.chrisvest" name="stormpot" rev="3.1">
  <artifact name="stormpot" type="jar" />
</dependency>
@Grapes(
@Grab(group='com.github.chrisvest', module='stormpot', version='3.1')
)
libraryDependencies += "com.github.chrisvest" % "stormpot" % "3.1"
[com.github.chrisvest/stormpot "3.1"]

Dependencies

test (7)

Group / Artifact Type Version
org.junit.jupiter : junit-jupiter-engine jar 5.7.0-M1
org.junit.jupiter : junit-jupiter-params jar 5.7.0-M1
org.assertj : assertj-core jar 3.15.0
io.dropwizard.metrics : metrics-core jar 4.1.8
io.micrometer : micrometer-core jar 1.4.2
org.hdrhistogram : HdrHistogram jar 2.1.12
org.openjdk.jol : jol-core jar 0.10

Project Modules

There are no modules declared in this project.

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.

Build status Code quality Code coverage

Stormpot is very mature, is used in production, and has done hundreds of trillions [1] 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 Apache 2 license.

  • Very high test coverage.

  • The highest throughput and lowest latency in its class. (since 2.1)

  • 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)

  • 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 Caffeine for object caching.

Installing

Stormpot 3.1 only depends on Java 11 or newer. Add it as a Maven dependency to your projects:

<dependency>
  <groupId>com.github.chrisvest</groupId>
  <artifactId>stormpot</artifactId>
  <version>3.1</version>
</dependency>

You can also build the latest snapshot from source with mvn clean install.

Getting Started

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

  1. A Poolable type of objects it can pool. You have to implement this yourself.

  2. An Allocator to allocate and deallocate the Poolable objects. You have to implement this yourself.

  3. And a place where it all comes together:

MyAllocator allocator = new MyAllocator();
Pool<MyPoolable> 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();
  }
}

Contributing

  • Report bugs preferably with a failing test. You can submit a pull-request that adds a failing test that demonstrates the behaviour you think is wrong or missing. Travis-CI will build it, report the failure and shorten the feedback cycle. If you don’t know how to write a test for something, then that’s fine too. Just open an issue describing your configuration and environment, what you observe, and what you think should happen instead.

  • Improve the documentation by all means! Just fork the project and start. If you have questions about implementation or behavioural details, then start a discussion about it by opening a pull-request or an issue. Documentation and javadoc is formatted with AsciiDoctor. The website and javadocs can be generated with mvn clean pre-site javadoc:javadoc.

  • Fix bugs or implement features by forking the project, but please start an issue about the bug or feature you want to work on (or find the existing issue) and describe the approach and design you have in mind. Keep in mind that Stormpot is implemented with a very strict adherence to TDD. Finally, make sure to respect the existing indentation and formatting. Use mvn checkstyle:check to check your formatting. If you are writing a test that takes more than a few hundred milliseconds to run, then put it in the stormpot.slow test package; either in the existing PoolIT suite, or in a new *IT suite. Use mvn clean test to run only the fast tests. Use mvn clean verify to also run the slow tests. Javadoc comments are formatted with AsciiDoctor. Get test coverage with mvn clean test site and open target/site/jacoco/index.html. Get mutation test coverage with mvn clean test-compile org.pitest:pitest-maven:mutationCoverage and open target/pit-reports/*/index.html.

  • Update Maven plugins with mvn versions:display-plugin-updates, or other dependencies with versions:display-dependency-updates.

  • Add to the ecosystem and make Stormpot more than just an object pool. This is a good thing to take on if you’d like to contribute code, but you find the Stormpot code base itself to be intimidating (which, by the way, I completely understand).

    • There is a repository for object pool benchmarks that is being maintained along side Stormpot. Adding more benchmarks and cases; analysing results; trying out optimisations. These are all useful things to do.

    • I started working on a JDBC connection pool based on Stormpot, but the project has stagnated. It is no doubt a useful thing to have, though. If you want to take on that problem, either with offset in the existing code or by starting over from scratch, then please go ahead.

    • I’m sure there are other interesting related problems out there to take on. There are many database drivers for various NoSQL databases, that have object pooling needs.

Whatever you decide to do, don’t hesitate to ask questions on the mailing list or on github if you have doubts or get stuck.


1. Fermi estimate.

Versions

Version
3.1
3.0.1
3.0
2.4.2
2.4.1
2.4
2.3
2.2
2.1
2.0
1.0.1
1.0