Package org.agrona.concurrent

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 various memory ordering semantics.

Field Summary

Fields

Modifier and Type	Field	Description
static final int	ALIGNMENT	Buffer alignment in bytes to ensure atomic word accesses.
static final boolean	STRICT_ALIGNMENT_CHECKS	Should alignment checks for atomic operations be done or not.
static final String	STRICT_ALIGNMENT_CHECKS_PROP_NAME	Name of the system property that specify if the alignment checks for atomic operations are strict.

Fields inherited from interface org.agrona.DirectBuffer

DISABLE_ARRAY_CONTENT_PRINTOUT_PROP_NAME, DISABLE_BOUNDS_CHECKS_PROP_NAME, SHOULD_BOUNDS_CHECK, STR_HEADER_LEN

Method Summary

Modifier and Type	Method	Description
int	addIntOrdered(int index, int increment)	Atomically add a value to a given index with ordered store semantics.
long	addLongOrdered(int index, long increment)	Atomically adds a value to a given index with ordered store semantics.
boolean	compareAndSetInt(int index, int expectedValue, int updateValue)	Atomic compare and set of an int given an expected value.
boolean	compareAndSetLong(int index, long expectedValue, long updateValue)	Atomic compare and set of a long given an expected value.
int	getAndAddInt(int index, int delta)	Atomically add a delta to a value at a location returning the previous contents.
long	getAndAddLong(int index, long delta)	Atomically add a delta to a value at a location returning the previous contents.
int	getAndSetInt(int index, int value)	Atomically exchange a value at a location returning the previous contents.
long	getAndSetLong(int index, long value)	Atomically exchange a value at a location returning the previous contents.
byte	getByteVolatile(int index)	Atomically get the value at a given index with volatile semantics.
char	getCharVolatile(int index)	Atomically get the value at a given index with volatile semantics.
int	getIntVolatile(int index)	Atomically get the value at a given index with volatile semantics.
long	getLongVolatile(int index)	Atomically get the value at a given index with volatile semantics.
short	getShortVolatile(int index)	Atomically get the value at a given index with volatile semantics.
void	putByteVolatile(int index, byte value)	Atomically put a value to a given index with volatile semantics.
void	putCharVolatile(int index, char value)	Atomically put a value to a given index with volatile semantics.
void	putIntOrdered(int index, int value)	Atomically put a value to a given index with ordered semantics.
void	putIntVolatile(int index, int value)	Atomically put a value to a given index with volatile semantics.
void	putLongOrdered(int index, long value)	Atomically put a value to a given index with ordered store semantics.
void	putLongVolatile(int index, long value)	Atomically put a value to a given index with volatile semantics.
void	putShortVolatile(int index, short value)	Atomically put a value to a given index with volatile semantics.
void	verifyAlignment()	Verify that the underlying buffer is correctly aligned to prevent word tearing, other ordering issues and the JVM crashes.

Methods inherited from interface java.lang.Comparable

compareTo

Methods inherited from interface org.agrona.DirectBuffer

addressOffset, boundsCheck, byteArray, byteBuffer, capacity, checkLimit, getByte, getBytes, getBytes, getBytes, getBytes, getBytes, getChar, getChar, getDouble, getDouble, getFloat, getFloat, getInt, getInt, getLong, getLong, getShort, getShort, getStringAscii, getStringAscii, getStringAscii, getStringAscii, getStringAscii, getStringAscii, getStringUtf8, getStringUtf8, getStringUtf8, getStringWithoutLengthAscii, getStringWithoutLengthAscii, getStringWithoutLengthUtf8, parseIntAscii, parseLongAscii, parseNaturalIntAscii, parseNaturalLongAscii, wrap, wrap, wrap, wrap, wrap, wrap, wrap, wrapAdjustment

Methods inherited from interface org.agrona.MutableDirectBuffer

isExpandable, putByte, putBytes, putBytes, putBytes, putBytes, putBytes, putChar, putChar, putDouble, putDouble, putFloat, putFloat, putInt, putInt, putIntAscii, putLong, putLong, putLongAscii, putNaturalIntAscii, putNaturalIntAsciiFromEnd, putNaturalLongAscii, putNaturalPaddedIntAscii, putShort, putShort, putStringAscii, putStringAscii, putStringAscii, putStringAscii, putStringUtf8, putStringUtf8, putStringUtf8, putStringUtf8, putStringWithoutLengthAscii, putStringWithoutLengthAscii, putStringWithoutLengthAscii, putStringWithoutLengthAscii, putStringWithoutLengthUtf8, setMemory

Field Details

ALIGNMENT

static final int ALIGNMENT

Buffer alignment in bytes to ensure atomic word accesses.

See Also:

• Constant Field Values

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:

• Constant Field Values

STRICT_ALIGNMENT_CHECKS

static final boolean STRICT_ALIGNMENT_CHECKS

Should alignment checks for atomic operations be done or not. The value is platform-dependent:

• On x64 it is controlled by the STRICT_ALIGNMENT_CHECKS_PROP_NAME system property.
• On other platforms it is always true.

See Also:

• STRICT_ALIGNMENT_CHECKS_PROP_NAME

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:

• ALIGNMENT

getLongVolatile

long getLongVolatile(int index)

Atomically get the value at a given index with volatile semantics.

This call has sequential-consistent semantics.

Parameters:

index - in bytes from which to get.

Returns:

the value for at a given index.

putLongVolatile

void putLongVolatile(int index,
 long value)

Atomically put a value to a given index with volatile semantics.

This call has sequential-consistent semantics.

Parameters:

index - in bytes for where to put.

value - for at a given index.

putLongOrdered

void putLongOrdered(int index,
 long value)

Atomically put a value to a given index with ordered store semantics.

This call has release semantics.

Parameters:

index - in bytes for where to put.

value - for at a given index.

addLongOrdered

long addLongOrdered(int index,
 long increment)

Atomically adds a value to a given index with ordered store semantics. Use a negative increment to decrement.

The load has no ordering semantics. The store has release semantics.

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.

This call has sequential-consistent semantics.

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.

This call has sequential-consistent semantics.

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.

This call has sequential-consistent semantics.

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)

Atomically get the value at a given index with volatile semantics.

This call has sequential-consistent semantics.

Parameters:

index - in bytes from which to get.

Returns:

the value for at a given index.

putIntVolatile

void putIntVolatile(int index,
 int value)

Atomically put a value to a given index with volatile semantics.

This call has sequential-consistent semantics.

Parameters:

index - in bytes for where to put.

value - for at a given index.

putIntOrdered

void putIntOrdered(int index,
 int value)

Atomically put a value to a given index with ordered semantics.

This call has release semantics.

Parameters:

index - in bytes for where to put.

value - for at a given index.

addIntOrdered

int addIntOrdered(int index,
 int increment)

Atomically add a value to a given index with ordered store semantics. Use a negative increment to decrement.

The load has no ordering semantics. The store has release semantics.

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.

This call has sequential-consistent semantics.

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.

This call has sequential-consistent semantics.

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.

This call has sequential-consistent semantics.

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)

Atomically get the value at a given index with volatile semantics.

This call has sequential-consistent semantics.

Parameters:

index - in bytes from which to get.

Returns:

the value for at a given index.

putShortVolatile

void putShortVolatile(int index,
 short value)

Atomically put a value to a given index with volatile semantics.

This call has sequential-consistent semantics.

Parameters:

index - in bytes for where to put.

value - for at a given index.

getCharVolatile

char getCharVolatile(int index)

Atomically get the value at a given index with volatile semantics.

This call has sequential-consistent semantics.

Parameters:

index - in bytes from which to get.

Returns:

the value for at a given index.

putCharVolatile

void putCharVolatile(int index,
 char value)

Atomically put a value to a given index with volatile semantics.

This call has sequential-consistent semantics.

Parameters:

index - in bytes for where to put.

value - for at a given index.

getByteVolatile

byte getByteVolatile(int index)

Atomically get the value at a given index with volatile semantics.

This call has sequential-consistent semantics.

Parameters:

index - in bytes from which to get.

Returns:

the value for at a given index.

putByteVolatile

void putByteVolatile(int index,
 byte value)

Atomically put a value to a given index with volatile semantics.

This call has sequential-consistent semantics.

Parameters:

index - in bytes for where to put.

value - for at a given index.