buf_01 - Teragrep Buffer Library for Java

A library for providing leased access to Java MemorySegments.

Features

• ArenaMemorySegmentLeaseSupplier provides the MemorySegment from the given Arena with the configured size. This is used by the Pool. Closing the supplier will also close the Arena.

• Pool consists of Parent leases.

• Each parent lease can be sliced from offset to end into a sub lease.

• Sub leases cannot be pooled, but they can be close()'d.

• Parent lease must be returned to the pool by the same entity who took it from the pool.

• All subleases must be closed before the parent lease can be returned to the pool.

• The parent lease will fill the underlying MemorySegment with zeroes when returned to the pool.

• In order to retrieve n bytes worth of MemorySegments, the included LeaseMultiGet object can be used. The pool itself will provide the first one from the inner queue data structure.

Documentation

See the official documentation on docs.teragrep.com.

How to compile

The project can be build using Maven. You can set the Java version by specifying the path with JAVA_HOME.

JAVA_HOME=/usr/lib/jvm/temurin-25-jdk mvn clean package

How to use

A MemorySegment can be taken from the Pool in the following manner:

import com.teragrep.buf_01.buffer.lease.MemorySegmentLeaseStub;
import com.teragrep.buf_01.buffer.lease.PoolableLease;
import com.teragrep.buf_01.buffer.supply.ArenaMemorySegmentLeaseSupplier;
import com.teragrep.poj_01.pool.Pool;
import com.teragrep.poj_01.pool.UnboundPool;
import java.lang.foreign.MemorySegment;

final Pool<PoolableLease<MemorySegment>> leasePool = new UnboundPool<>(new ArenaMemorySegmentLeaseSupplier(Arena.ofShared(), 1024), new MemorySegmentLeaseStub());
final PoolableLease<MemorySegment> lease = leasePool.get();
final MemorySegment memorySegment = lease.leasedObject();

It can also be sliced, and used like another MemorySegment: Remember to close the slice after it is no longer needed.

import java.lang.foreign.MemorySegment;
final Lease<MemorySegment> slice = lease.sliced(512);
slice.close();

After all slices have been closed and the parent MemorySegment is no longer of use:

pool.offer(lease);

Contributing

You can involve yourself with our project by opening an issue or submitting a pull request.

Contribution requirements:

1. All changes must be accompanied by a new or changed test. If you think testing is not required in your pull request, include a sufficient explanation as why you think so.

2. Security checks must pass

3. Pull requests must align with the principles and values of extreme programming.

4. Pull requests must follow the principles of Object Thinking and Elegant Objects (EO).

Read more in our Contributing Guideline.

Contributor License Agreement

Contributors must sign Teragrep Contributor License Agreement before a pull request is accepted to organization’s repositories.

You need to submit the CLA only once. After submitting the CLA you can contribute to all Teragrep’s repositories.