Eliminate jstructural

Affects: io7m-com/.github#2

README.in

@@ -0,0 +1,56 @@
+
+## jpuddle
+
+Java classes to pool heavyweight objects.
+
+## Features
+
+* High coverage test suite.
+* [OSGi-ready](https://www.osgi.org/)
+* [JPMS-ready](https://en.wikipedia.org/wiki/Java_Platform_Module_System)
+* ISC license.
+
+## Motivation
+
+Object pooling is a programming technique where instead of creating new objects
+to service requests, a small pool of objects is created and the objects within
+the pool are reused repeatedly to service requests instead. This was
+traditionally used by Java programs as a performance optimization in an
+attempt to reduce memory allocations and therefore reduce the amount of
+garbage collection that occurs. On modern Java virtual machines, however,
+object pooling as a means to improve performance in this manner is strongly
+contraindicated: Object allocations are extremely fast (on the order of a
+few tens of nanoseconds), escape analysis often eliminates allocations
+entirely, and modern garbage collectors are optimized to make short-lived
+objects essentially free.
+
+With this in mind, it may not be clear why the `com.io7m.jpuddle` package
+should exist at all! The answer is that object pooling is still useful when
+the objects represent external resources that may be very expensive to acquire
+and/or the program should avoid acquiring too many of these resources at any
+given time. An example of this sort of use case is allocating short-lived
+framebuffer objects on a GPU. Graphics memory is typically in relatively
+short supply and creating an object on the GPU is generally considered to be
+an expensive and slow process (relative to simply allocating an object on the
+CPU side). A pool of framebuffer objects can be created that the application
+can reuse repeatedly without needing to create new objects, and the size of the
+pool can be bounded so that the application does not try to exceed the
+available GPU memory.
+
+## Usage
+
+Implement the `JPPoolableListenerType` interface for the object you want
+to pool. The interface contains methods needed to estimate sizes for pool
+management, and methods to create and delete objects.
+
+Then, create a pool with a soft limit of `100` objects and a hard limit of
+`200` objects:
+
+```
+JPPoolableListenerType<T> listener;
+
+var p =
+  JPPoolSynchronous.newPool(listener, 100L, 200L);
+```
+
+Use the `get()` method to retrieve objects from the pool.

README.md

@@ -13,3 +13,60 @@ jpuddle
 | OpenJDK (Temurin) LTS | Linux | [![Build (OpenJDK (Temurin) LTS, Linux)](https://img.shields.io/github/actions/workflow/status/io7m-com/jpuddle/main.linux.temurin.lts.yml)](https://www.github.com/io7m-com/jpuddle/actions?query=workflow%3Amain.linux.temurin.lts)|
 | OpenJDK (Temurin) Current | Windows | [![Build (OpenJDK (Temurin) Current, Windows)](https://img.shields.io/github/actions/workflow/status/io7m-com/jpuddle/main.windows.temurin.current.yml)](https://www.github.com/io7m-com/jpuddle/actions?query=workflow%3Amain.windows.temurin.current)|
 | OpenJDK (Temurin) LTS | Windows | [![Build (OpenJDK (Temurin) LTS, Windows)](https://img.shields.io/github/actions/workflow/status/io7m-com/jpuddle/main.windows.temurin.lts.yml)](https://www.github.com/io7m-com/jpuddle/actions?query=workflow%3Amain.windows.temurin.lts)|
+
+## jpuddle
+
+Java classes to pool heavyweight objects.
+
+## Features
+
+* High coverage test suite.
+* [OSGi-ready](https://www.osgi.org/)
+* [JPMS-ready](https://en.wikipedia.org/wiki/Java_Platform_Module_System)
+* ISC license.
+
+## Motivation
+
+Object pooling is a programming technique where instead of creating new objects
+to service requests, a small pool of objects is created and the objects within
+the pool are reused repeatedly to service requests instead. This was
+traditionally used by Java programs as a performance optimization in an
+attempt to reduce memory allocations and therefore reduce the amount of
+garbage collection that occurs. On modern Java virtual machines, however,
+object pooling as a means to improve performance in this manner is strongly
+contraindicated: Object allocations are extremely fast (on the order of a
+few tens of nanoseconds), escape analysis often eliminates allocations
+entirely, and modern garbage collectors are optimized to make short-lived
+objects essentially free.
+
+With this in mind, it may not be clear why the `com.io7m.jpuddle` package
+should exist at all! The answer is that object pooling is still useful when
+the objects represent external resources that may be very expensive to acquire
+and/or the program should avoid acquiring too many of these resources at any
+given time. An example of this sort of use case is allocating short-lived
+framebuffer objects on a GPU. Graphics memory is typically in relatively
+short supply and creating an object on the GPU is generally considered to be
+an expensive and slow process (relative to simply allocating an object on the
+CPU side). A pool of framebuffer objects can be created that the application
+can reuse repeatedly without needing to create new objects, and the size of the
+pool can be bounded so that the application does not try to exceed the
+available GPU memory.
+
+## Usage
+
+Implement the `JPPoolableListenerType` interface for the object you want
+to pool. The interface contains methods needed to estimate sizes for pool
+management, and methods to create and delete objects.
+
+Then, create a pool with a soft limit of `100` objects and a hard limit of
+`200` objects:
+
+```
+JPPoolableListenerType<T> listener;
+
+var p =
+  JPPoolSynchronous.newPool(listener, 100L, 200L);
+```
+
+Use the `get()` method to retrieve objects from the pool.
+