DOCSEARCHbyAlgolia
Submit Docs

Agrona Documentation

repository·master·Indexed 25 days ago

https://github.com/aeron-io/agrona

A high-performance Java library providing specialized data structures, buffers, and utilities for low-latency, high-throughput applications. Key features include thread-safe direct and atomic buffers, primitive collections to avoid boxing, lock-less queues, Ring/Broadcast buffers for IPC, a Scalable Timer Wheel, and a lock-less IdGenerator. It is frequently used alongside Aeron and Simple Binary Encoding (SBE).

Tokens
1.7K
Snippets
4
Records
19
Agent score
85%

What's inside Agrona

  1. Overview of Agrona utilities

    master

    Agrona is a library of high-performance data structures and utility methods designed for low-latency Java applications. It is frequently used alongside Aeron and Simple Binary Encoding (SBE).

    Key utilities include:

    • Buffers: Thread-safe direct and atomic buffers for on-heap and off-heap memory with memory ordering semantics.
    • Primitive Collections: Array-backed lists, open-addressing/linear-probing maps (int/long keys to objects or int/long values), and sets for primitives to avoid boxing.
    • Concurrency & Communication: Lock-less queues, Ring/Broadcast buffers (off-heap for IPC), and a Simple Agent framework for concurrent services.
    • Scheduling & Timing: Scalable Timer Wheel (O(1) register/cancel) and various Clock implementations.
    • Telemetry & Coordination: Off-heap counters and a lock-less IdGenerator (Twitter Snowflake algorithm).
    • I/O: InputStream and OutputStream implementations that wrap direct buffers.
    • Error Logging: DistinctErrorLog to prevent disk exhaustion from repetitive errors.

  3. Configure JVM options for UnsafeApi and Checksums

    master

    Certain Agrona features require specific JVM flags to access internal modules:

    1. UnsafeApi: To use org.agrona.UnsafeApi, you must specify: --add-opens java.base/jdk.internal.misc=ALL-UNNAMED

    2. Checksums: To use org.agrona.checksum.Crc32c or org.agrona.checksum.Crc32, you must specify: --add-opens java.base/java.util.zip=ALL-UNNAMED

  4. Manage MarkFile activation and failures

    master

    When using org.agrona.MarkFile.mapNewOrExistingMarkFile, Agrona prevents concurrent activation by setting the activity timestamp (timestampFieldOffset) to a special sentinel value: org.agrona.MarkFile.ACTIVATION_IN_PROGRESS_TIMESTAMP.

    Note: If an activation attempt fails, the timestamp remains at this sentinel value, which will prevent subsequent restart attempts of the process. It is highly recommended to manually reset the activity timestamp if an activation failure occurs.

  5. Use ShutdownSignalBarrier for clean service termination

    master

    When using ShutdownSignalBarrier alongside other services, ensure the barrier is closed last in your try-with-resources block. This ensures that your service (e.g., MyService) has sufficient time to terminate completely before the barrier closes and allows the JVM to exit.

    // Correct order: service closes first, then barrier closes
class UsageSample
{
    public static void main(final String[] args) 
    {
        try (ShutdownSignalBarrier barrier = new ShutdownSignalBarrier();
             MyService service = new MyService())
        {
            barrier.await();
        }
    }
}

  6. Use ShutdownSignalBarrier instead of SigInt

    master

    As of version 2.3.0, org.agrona.concurrent.SigInt is deprecated and has been removed in 2.4.0. You must use org.agrona.concurrent.ShutdownSignalBarrier instead.

    ShutdownSignalBarrier uses JVM shutdown hooks instead of intercepting OS signals, which allows other shutdown hooks in your application to execute correctly.

    Warning: You must explicitly close the ShutdownSignalBarrier (e.g., using a try-with-resources block) to ensure the JVM can terminate. Failure to close it may prevent the JVM from exiting.

    // New pattern using ShutdownSignalBarrier
class FlagSample
{
    public static void main(final String[] args)
    {
        final AtomicBoolean running = new AtomicBoolean(true);
        try (ShutdownSignalBarrier barrier = new ShutdownSignalBarrier(() -> running.set(false)))
        {
            while (running.get())
            {
                ...
            }
        }
    }
}

  7. Build Agrona from source

    master

    To build Agrona, you must use Gradle and have the latest release of Java installed. Agrona is tested with Java 17, 21, 25, and the next available EA build.

    Run the following command from the project root to perform a full clean and build:

    $ ./gradlew

  8. Run JCStress concurrency tests manually

    master
    To run the JCStress concurrency tests without using Gradle directly, you must first build the shadow JAR and then execute it using the java -jar command. You must provide the specific JCStress test name and include the required JVM arguments to export java.base/jdk.internal.misc to the unnamed module.

  10. Handle Agent termination in AgentRunner.close()

    master

    In version 2.5.0, the org.agrona.concurrent.AgentRunner.close() methods are no longer interruptible. When calling close() or close(int, java.util.function.Consumer<java.lang.Thread>), the thread will remain in the waiting loop until the agent thread has fully terminated, rather than exiting immediately upon interruption.

    Important: Ensure that your org.agrona.concurrent.Agent.doWork implementation eventually terminates. Do not use blocking operations that cannot be interrupted, and ensure you handle thread interruption correctly within doWork to avoid hanging the AgentRunner during shutdown.