Interface AtomicBuffer

All Superinterfaces:
Comparable<DirectBuffer>, DirectBuffer, MutableDirectBuffer
All Known Implementing Classes:
UnsafeBuffer

public interface AtomicBuffer extends MutableDirectBuffer
Abstraction over a range of buffer types that allows type to be accessed with memory ordering semantics.
  • Field Details

    • ALIGNMENT

      static final int ALIGNMENT
      Buffer alignment in bytes to ensure atomic word accesses.
      See Also:
    • STRICT_ALIGNMENT_CHECKS_PROP_NAME

      static final String STRICT_ALIGNMENT_CHECKS_PROP_NAME
      Name of the system property that specify if the alignment checks for atomic operations are strict. If the checks are strict then the verifyAlignment() method will throw an exception if the underlying buffer is a byte[].
      See Also:
    • STRICT_ALIGNMENT_CHECKS

      static final boolean STRICT_ALIGNMENT_CHECKS
      Should alignment checks for atomic operations be done or not. The value is platform-dependent:
      See Also:
  • Method Details

    • verifyAlignment

      void verifyAlignment()
      Verify that the underlying buffer is correctly aligned to prevent word tearing, other ordering issues and the JVM crashes. In particular this method verifies that the starting offset of the underlying buffer is properly aligned. However, the actual atomic call must ensure that the index is properly aligned, i.e. it must be aligned to the size of the operand. For example a call to any of the following methods putIntOrdered(int, int), putIntVolatile(int, int), addIntOrdered(int, int), getIntVolatile(int), getAndAddInt(int, int) or getAndSetInt(int, int), must have the index aligned by four bytes (e.g. 0, 4, 8, 12, 60 etc.).

      Users are encouraged to call this method after constructing the AtomicBuffer instance in order to ensure that the underlying buffer supports atomic access to long values.

      Agrona provides an agent (org.agrona.agent.BufferAlignmentAgent) that checks the alignment of indexes for all operations at runtime. The agent throws an exception if the unaligned access is detected.

      Note: on some platforms unaligned atomic access can lead to the JVM crashes, e.g.:

       
       # Java VM: OpenJDK 64-Bit Server VM (25.352-b08 mixed mode bsd-aarch64 compressed oops)
       #
       # siginfo: si_signo: 10 (SIGBUS), si_code: 1 (BUS_ADRALN)
       
       
      Throws:
      IllegalStateException - if the starting offset into the buffer is not properly aligned.
      See Also:
    • getLongVolatile

      long getLongVolatile(int index)
      Get the value at a given index with volatile semantics.
      Parameters:
      index - in bytes from which to get.
      Returns:
      the value for at a given index.
    • putLongVolatile

      void putLongVolatile(int index, long value)
      Put a value to a given index with volatile semantics.
      Parameters:
      index - in bytes for where to put.
      value - for at a given index.
    • putLongOrdered

      void putLongOrdered(int index, long value)
      Put a value to a given index with ordered store semantics.
      Parameters:
      index - in bytes for where to put.
      value - for at a given index.
    • addLongOrdered

      long addLongOrdered(int index, long increment)
      Add a value to a given index with ordered store semantics. Use a negative increment to decrement.
      Parameters:
      index - in bytes for where to put.
      increment - by which the value at the index will be adjusted.
      Returns:
      the previous value at the index.
    • compareAndSetLong

      boolean compareAndSetLong(int index, long expectedValue, long updateValue)
      Atomic compare and set of a long given an expected value.
      Parameters:
      index - in bytes for where to put.
      expectedValue - at to be compared.
      updateValue - to be exchanged.
      Returns:
      set successful or not.
    • getAndSetLong

      long getAndSetLong(int index, long value)
      Atomically exchange a value at a location returning the previous contents.
      Parameters:
      index - in bytes for where to put.
      value - for at a given index.
      Returns:
      previous value at the index.
    • getAndAddLong

      long getAndAddLong(int index, long delta)
      Atomically add a delta to a value at a location returning the previous contents. To decrement a negative delta can be provided.
      Parameters:
      index - in bytes for where to put.
      delta - to be added to the value at the index.
      Returns:
      previous value.
    • getIntVolatile

      int getIntVolatile(int index)
      Get the value at a given index with volatile semantics.
      Parameters:
      index - in bytes from which to get.
      Returns:
      the value for at a given index.
    • putIntVolatile

      void putIntVolatile(int index, int value)
      Put a value to a given index with volatile semantics.
      Parameters:
      index - in bytes for where to put.
      value - for at a given index.
    • putIntOrdered

      void putIntOrdered(int index, int value)
      Put a value to a given index with ordered semantics.
      Parameters:
      index - in bytes for where to put.
      value - for at a given index.
    • addIntOrdered

      int addIntOrdered(int index, int increment)
      Add a value to a given index with ordered store semantics. Use a negative increment to decrement.
      Parameters:
      index - in bytes for where to put.
      increment - by which the value at the index will be adjusted.
      Returns:
      the previous value at the index.
    • compareAndSetInt

      boolean compareAndSetInt(int index, int expectedValue, int updateValue)
      Atomic compare and set of an int given an expected value.
      Parameters:
      index - in bytes for where to put.
      expectedValue - at to be compared.
      updateValue - to be exchanged.
      Returns:
      successful or not.
    • getAndSetInt

      int getAndSetInt(int index, int value)
      Atomically exchange a value at a location returning the previous contents.
      Parameters:
      index - in bytes for where to put.
      value - for at a given index.
      Returns:
      previous value.
    • getAndAddInt

      int getAndAddInt(int index, int delta)
      Atomically add a delta to a value at a location returning the previous contents. To decrement a negative delta can be provided.
      Parameters:
      index - in bytes for where to put.
      delta - to be added to the value at the index.
      Returns:
      previous value.
    • getShortVolatile

      short getShortVolatile(int index)
      Get the value at a given index with volatile semantics.
      Parameters:
      index - in bytes from which to get.
      Returns:
      the value for at a given index.
    • putShortVolatile

      void putShortVolatile(int index, short value)
      Put a value to a given index with volatile semantics.
      Parameters:
      index - in bytes for where to put.
      value - for at a given index.
    • getCharVolatile

      char getCharVolatile(int index)
      Get the value at a given index with volatile semantics.
      Parameters:
      index - in bytes from which to get.
      Returns:
      the value for at a given index.
    • putCharVolatile

      void putCharVolatile(int index, char value)
      Put a value to a given index with volatile semantics.
      Parameters:
      index - in bytes for where to put.
      value - for at a given index.
    • getByteVolatile

      byte getByteVolatile(int index)
      Get the value at a given index with volatile semantics.
      Parameters:
      index - in bytes from which to get.
      Returns:
      the value for at a given index.
    • putByteVolatile

      void putByteVolatile(int index, byte value)
      Put a value to a given index with volatile semantics.
      Parameters:
      index - in bytes for where to put.
      value - for at a given index.