io.aeron

Class CncFileDescriptor

java.lang.Object

io.aeron.CncFileDescriptor

public class CncFileDescriptor
extends Object

Description of the command and control file used between driver and clients.

File Layout

  +-----------------------------+
  |          Meta Data          |
  +-----------------------------+
  |      to-driver Buffer       |
  +-----------------------------+
  |      to-clients Buffer      |
  +-----------------------------+
  |   Counters Metadata Buffer  |
  +-----------------------------+
  |    Counters Values Buffer   |
  +-----------------------------+
  |          Error Log          |
  +-----------------------------+
 

Metadata Layout CNC_VERSION

   0                   1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  |                      Aeron CnC Version                        |
  +---------------------------------------------------------------+
  |                   to-driver buffer length                     |
  +---------------------------------------------------------------+
  |                  to-clients buffer length                     |
  +---------------------------------------------------------------+
  |               Counters Metadata buffer length                 |
  +---------------------------------------------------------------+
  |                Counters Values buffer length                  |
  +---------------------------------------------------------------+
  |                   Error Log buffer length                     |
  +---------------------------------------------------------------+
  |                   Client Liveness Timeout                     |
  |                                                               |
  +---------------------------------------------------------------+
  |                    Driver Start Timestamp                     |
  |                                                               |
  +---------------------------------------------------------------+
  |                         Driver PID                            |
  |                                                               |
  +---------------------------------------------------------------+
 

Field Summary

Fields

Modifier and Type	Field and Description
static int	CLIENT_LIVENESS_TIMEOUT_FIELD_OFFSET Offset at which the client liveness timeout value can be found.
static String	CNC_FILE Name used for CnC file in the Aeron directory.
static int	CNC_VERSION Version of the CnC file using semantic versioning (SemanticVersion) stored as an 32-bit integer.
static int	CNC_VERSION_FIELD_OFFSET Offset at which the version field can be found.
static int	COUNTERS_METADATA_BUFFER_LENGTH_FIELD_OFFSET Offset at which the length field can be found for counter metadata, e.g.
static int	COUNTERS_VALUES_BUFFER_LENGTH_FIELD_OFFSET Offset at which the length field can be found for the counters values can be found.
static int	END_OF_METADATA_OFFSET The offset of the first byte past the metadata header which is aligned on a cache-line boundary.
static int	ERROR_LOG_BUFFER_LENGTH_FIELD_OFFSET Offset at which the length field can be found for buffer containing the error log can be found.
static int	META_DATA_LENGTH Length of the metadata header for the CnC file.
static int	PID_FIELD_OFFSET Offset at which the PID value for the driver can be found.
static int	START_TIMESTAMP_FIELD_OFFSET Offset at which the start timestamp value for the driver can be found.
static int	TO_CLIENTS_BUFFER_LENGTH_FIELD_OFFSET Offset at which the length field can be found for the broadcast buffer to the clients can be found.
static int	TO_DRIVER_BUFFER_LENGTH_FIELD_OFFSET Offset at which the length field can be found for the command ring buffer to the driver.

Constructor Summary

Constructors

Constructor and Description
CncFileDescriptor()

Method Summary

Modifier and Type	Method and Description
static void	checkVersion(int cncVersion) Check the version of the CnC file is compatible with application.
static long	clientLivenessTimeoutNs(DirectBuffer metaDataBuffer) Get the timeout in nanoseconds for tracking client liveness and inter-service timeout.
static int	clientLivenessTimeoutOffset(int baseOffset) Offset in the buffer at which the client liveness timeout field exists.
static int	cncVersionOffset(int baseOffset) Offset in the buffer at which the version field exists.
static int	computeCncFileLength(int totalLengthOfBuffers, int alignment) Compute the length of the cnc file and return it.
static int	countersMetaDataBufferLengthOffset(int baseOffset) Offset in the buffer at which the counter metadata buffer length field exists.
static int	countersValuesBufferLengthOffset(int baseOffset) Offset in the buffer at which the counter value buffer length field exists.
static UnsafeBuffer	createCountersMetaDataBuffer(ByteBuffer buffer, DirectBuffer metaDataBuffer) Create the buffer which wraps the section in the CnC file for the counters metadata.
static UnsafeBuffer	createCountersValuesBuffer(ByteBuffer buffer, DirectBuffer metaDataBuffer) Create the buffer which wraps the section in the CnC file for the counter values.
static UnsafeBuffer	createErrorLogBuffer(ByteBuffer buffer, DirectBuffer metaDataBuffer) Create the buffer which wraps the section in the CnC file for the error log.
static UnsafeBuffer	createMetaDataBuffer(ByteBuffer buffer) Create the buffer which wraps the area in the CnC file for the metadata about the CnC file itself.
static UnsafeBuffer	createToClientsBuffer(ByteBuffer buffer, DirectBuffer metaDataBuffer) Create the buffer which wraps the section in the CnC file for the broadcast buffer from the driver to clients.
static UnsafeBuffer	createToDriverBuffer(ByteBuffer buffer, DirectBuffer metaDataBuffer) Create the buffer which wraps the area in the CnC file for the command buffer from clients to the driver.
static int	errorLogBufferLengthOffset(int baseOffset) Offset in the buffer at which the error buffer length field exists.
static void	fillMetaData(UnsafeBuffer cncMetaDataBuffer, int toDriverBufferLength, int toClientsBufferLength, int counterMetaDataBufferLength, int counterValuesBufferLength, long clientLivenessTimeoutNs, int errorLogBufferLength, long startTimestampMs, long pid) Fill the CnC file with metadata to define its sections.
static boolean	isCncFile(Path path, BasicFileAttributes ignored) Determines if this path name matches the cnc file name pattern.
static boolean	isCncFileLengthSufficient(DirectBuffer metaDataBuffer, int cncFileLength) Is the provided length for the CnC file sufficient given what is stored in the metadata.
static long	pid(DirectBuffer metaDataBuffer) Get the process PID hosting the driver.
static int	pidOffset(int baseOffset) Offset in the buffer at which the driver process PID field exists.
static void	signalCncReady(UnsafeBuffer cncMetaDataBuffer) Signal that the CnC file is ready for use by client by writing the version into the CnC file.
static long	startTimestampMs(DirectBuffer metaDataBuffer) Get the start timestamp in milliseconds for the media driver.
static int	startTimestampOffset(int baseOffset) Offset in the buffer at which the driver start time timestamp field exists.
static int	toClientsBufferLengthOffset(int baseOffset) Offset in the buffer at which the to clients buffer length field exists.
static int	toDriverBufferLengthOffset(int baseOffset) Offset in the buffer at which the to driver buffer length field exists.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CNC_FILE

public static final String CNC_FILE

Name used for CnC file in the Aeron directory.

See Also:

Constant Field Values

CNC_VERSION

public static final int CNC_VERSION

Version of the CnC file using semantic versioning (SemanticVersion) stored as an 32-bit integer.

CNC_VERSION_FIELD_OFFSET

public static final int CNC_VERSION_FIELD_OFFSET

Offset at which the version field can be found.

TO_DRIVER_BUFFER_LENGTH_FIELD_OFFSET

public static final int TO_DRIVER_BUFFER_LENGTH_FIELD_OFFSET

Offset at which the length field can be found for the command ring buffer to the driver.

TO_CLIENTS_BUFFER_LENGTH_FIELD_OFFSET

public static final int TO_CLIENTS_BUFFER_LENGTH_FIELD_OFFSET

Offset at which the length field can be found for the broadcast buffer to the clients can be found.

COUNTERS_METADATA_BUFFER_LENGTH_FIELD_OFFSET

public static final int COUNTERS_METADATA_BUFFER_LENGTH_FIELD_OFFSET

Offset at which the length field can be found for counter metadata, e.g. labels, can be found.

COUNTERS_VALUES_BUFFER_LENGTH_FIELD_OFFSET

public static final int COUNTERS_VALUES_BUFFER_LENGTH_FIELD_OFFSET

Offset at which the length field can be found for the counters values can be found.

CLIENT_LIVENESS_TIMEOUT_FIELD_OFFSET

public static final int CLIENT_LIVENESS_TIMEOUT_FIELD_OFFSET

Offset at which the client liveness timeout value can be found.

ERROR_LOG_BUFFER_LENGTH_FIELD_OFFSET

public static final int ERROR_LOG_BUFFER_LENGTH_FIELD_OFFSET

Offset at which the length field can be found for buffer containing the error log can be found.

START_TIMESTAMP_FIELD_OFFSET

public static final int START_TIMESTAMP_FIELD_OFFSET

Offset at which the start timestamp value for the driver can be found.

PID_FIELD_OFFSET

public static final int PID_FIELD_OFFSET

Offset at which the PID value for the driver can be found.

META_DATA_LENGTH

public static final int META_DATA_LENGTH

Length of the metadata header for the CnC file.

END_OF_METADATA_OFFSET

public static final int END_OF_METADATA_OFFSET

The offset of the first byte past the metadata header which is aligned on a cache-line boundary.

Constructor Detail

CncFileDescriptor

public CncFileDescriptor()

Method Detail

computeCncFileLength

public static int computeCncFileLength(int totalLengthOfBuffers,
                                       int alignment)

Compute the length of the cnc file and return it.

Parameters:

totalLengthOfBuffers - in bytes.

alignment - for file length to adhere to.

Returns:

cnc file length in bytes.

cncVersionOffset

public static int cncVersionOffset(int baseOffset)

Offset in the buffer at which the version field exists.

Parameters:

baseOffset - for the start of the metadata.

Returns:

offset in the buffer at which the version field exists.

toDriverBufferLengthOffset

public static int toDriverBufferLengthOffset(int baseOffset)

Offset in the buffer at which the to driver buffer length field exists.

Parameters:

baseOffset - for the start of the metadata.

Returns:

offset in the buffer at which the to driver buffer length field exists.

toClientsBufferLengthOffset

public static int toClientsBufferLengthOffset(int baseOffset)

Offset in the buffer at which the to clients buffer length field exists.

Parameters:

baseOffset - for the start of the metadata.

Returns:

offset in the buffer at which the to clients buffer length field exists.

countersMetaDataBufferLengthOffset

public static int countersMetaDataBufferLengthOffset(int baseOffset)

Offset in the buffer at which the counter metadata buffer length field exists.

Parameters:

baseOffset - for the start of the metadata.

Returns:

offset in the buffer at which the counter metadata buffer length field exists.

countersValuesBufferLengthOffset

public static int countersValuesBufferLengthOffset(int baseOffset)

Offset in the buffer at which the counter value buffer length field exists.

Parameters:

baseOffset - for the start of the metadata.

Returns:

offset in the buffer at which the counter value buffer length field exists.

clientLivenessTimeoutOffset

public static int clientLivenessTimeoutOffset(int baseOffset)

Offset in the buffer at which the client liveness timeout field exists.

Parameters:

baseOffset - for the start of the metadata.

Returns:

offset in the buffer at which the client liveness timeout field exists.

errorLogBufferLengthOffset

public static int errorLogBufferLengthOffset(int baseOffset)

Offset in the buffer at which the error buffer length field exists.

Parameters:

baseOffset - for the start of the metadata.

Returns:

offset in the buffer at which the error buffer length field exists.

startTimestampOffset

public static int startTimestampOffset(int baseOffset)

Offset in the buffer at which the driver start time timestamp field exists.

Parameters:

baseOffset - for the start of the metadata.

Returns:

offset in the buffer at which the driver start time timestamp field exists.

pidOffset

public static int pidOffset(int baseOffset)

Offset in the buffer at which the driver process PID field exists.

Parameters:

baseOffset - for the start of the metadata.

Returns:

offset in the buffer at which the driver process PID field exists.

fillMetaData

public static void fillMetaData(UnsafeBuffer cncMetaDataBuffer,
                                int toDriverBufferLength,
                                int toClientsBufferLength,
                                int counterMetaDataBufferLength,
                                int counterValuesBufferLength,
                                long clientLivenessTimeoutNs,
                                int errorLogBufferLength,
                                long startTimestampMs,
                                long pid)

Fill the CnC file with metadata to define its sections.

Parameters:

cncMetaDataBuffer - that wraps the metadata section of the CnC file.

toDriverBufferLength - for sending commands to the driver.

toClientsBufferLength - for broadcasting events to the clients.

counterMetaDataBufferLength - buffer length for counters metadata.

counterValuesBufferLength - buffer length for counter values.

clientLivenessTimeoutNs - timeout value in nanoseconds for client liveness and inter-service interval.

errorLogBufferLength - for recording the distinct error log.

startTimestampMs - epoch at which the driver started.

pid - for the process hosting the driver.

signalCncReady

public static void signalCncReady(UnsafeBuffer cncMetaDataBuffer)

Signal that the CnC file is ready for use by client by writing the version into the CnC file.

Parameters:

cncMetaDataBuffer - for the CnC file.

createMetaDataBuffer

public static UnsafeBuffer createMetaDataBuffer(ByteBuffer buffer)

Create the buffer which wraps the area in the CnC file for the metadata about the CnC file itself.

Parameters:

buffer - for the CnC file.

Returns:

the buffer which wraps the area in the CnC file for the metadata about the CnC file itself.

createToDriverBuffer

public static UnsafeBuffer createToDriverBuffer(ByteBuffer buffer,
                                                DirectBuffer metaDataBuffer)

Create the buffer which wraps the area in the CnC file for the command buffer from clients to the driver.

Parameters:

buffer - for the CnC file.

metaDataBuffer - within the CnC file.

Returns:

a buffer which wraps the section in the CnC file for the command buffer from clients to the driver.

createToClientsBuffer

public static UnsafeBuffer createToClientsBuffer(ByteBuffer buffer,
                                                 DirectBuffer metaDataBuffer)

Create the buffer which wraps the section in the CnC file for the broadcast buffer from the driver to clients.

Parameters:

buffer - for the CnC file.

metaDataBuffer - within the CnC file.

Returns:

a buffer which wraps the section in the CnC file for the broadcast buffer from the driver to clients.

createCountersMetaDataBuffer

public static UnsafeBuffer createCountersMetaDataBuffer(ByteBuffer buffer,
                                                        DirectBuffer metaDataBuffer)

Create the buffer which wraps the section in the CnC file for the counters metadata.

Parameters:

buffer - for the CnC file.

metaDataBuffer - within the CnC file.

Returns:

a buffer which wraps the section in the CnC file for the counters metadata.

createCountersValuesBuffer

public static UnsafeBuffer createCountersValuesBuffer(ByteBuffer buffer,
                                                      DirectBuffer metaDataBuffer)

Create the buffer which wraps the section in the CnC file for the counter values.

Parameters:

buffer - for the CnC file.

metaDataBuffer - within the CnC file.

Returns:

a buffer which wraps the section in the CnC file for the counter values.

createErrorLogBuffer

public static UnsafeBuffer createErrorLogBuffer(ByteBuffer buffer,
                                                DirectBuffer metaDataBuffer)

Create the buffer which wraps the section in the CnC file for the error log.

Parameters:

buffer - for the CnC file.

metaDataBuffer - within the CnC file.

Returns:

a buffer which wraps the section in the CnC file for the error log.

clientLivenessTimeoutNs

public static long clientLivenessTimeoutNs(DirectBuffer metaDataBuffer)

Get the timeout in nanoseconds for tracking client liveness and inter-service timeout.

Parameters:

metaDataBuffer - for the CnC file.

Returns:

the timeout in milliseconds for tracking client liveness.

startTimestampMs

public static long startTimestampMs(DirectBuffer metaDataBuffer)

Get the start timestamp in milliseconds for the media driver.

Parameters:

metaDataBuffer - for the CnC file.

Returns:

the start timestamp in milliseconds for the media driver.

pid

public static long pid(DirectBuffer metaDataBuffer)

Get the process PID hosting the driver.

Parameters:

metaDataBuffer - for the CnC file.

Returns:

the process PID hosting the driver.

checkVersion

public static void checkVersion(int cncVersion)

Check the version of the CnC file is compatible with application.

Parameters:

cncVersion - of the CnC file.

Throws:

AeronException - if the major versions are not compatible.

isCncFileLengthSufficient

public static boolean isCncFileLengthSufficient(DirectBuffer metaDataBuffer,
                                                int cncFileLength)

Is the provided length for the CnC file sufficient given what is stored in the metadata.

Parameters:

metaDataBuffer - for the CnC file.

cncFileLength - to check if it is sufficient based on what is stored in the metadata.

Returns:

true is the length is correct otherwise false.

isCncFile

public static boolean isCncFile(Path path,
                                BasicFileAttributes ignored)

Determines if this path name matches the cnc file name pattern.

Parameters:

path - to examine.

ignored - only needed for bi-predicate signature matching.

Returns:

true if the name matches.