Class CountersReader

java.lang.Object
org.agrona.concurrent.status.CountersReader
Direct Known Subclasses:
CountersManager

public class CountersReader extends Object
Reads the counters metadata and values buffers.

This class is threadsafe and can be used across threads.

Values Buffer

   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
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  |                        Counter Value                          |
  |                                                               |
  +---------------------------------------------------------------+
  |                       Registration Id                         |
  |                                                               |
  +---------------------------------------------------------------+
  |                          Owner Id                             |
  |                                                               |
  +---------------------------------------------------------------+
  |                        Reference Id                           |
  |                                                               |
  +---------------------------------------------------------------+
  |                      96 bytes of padding                     ...
 ...                                                              |
  +---------------------------------------------------------------+
  |                   Repeats to end of buffer                   ...
  |                                                               |
 ...                                                              |
  +---------------------------------------------------------------+
 

Meta Data Buffer

   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
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  |                        Record State                           |
  +---------------------------------------------------------------+
  |                          Type Id                              |
  +---------------------------------------------------------------+
  |                  Free-for-reuse Deadline (ms)                 |
  |                                                               |
  +---------------------------------------------------------------+
  |                      112 bytes for key                       ...
 ...                                                              |
  +-+-------------------------------------------------------------+
  |R|                      Label Length                           |
  +-+-------------------------------------------------------------+
  |                     380 bytes of Label                       ...
 ...                                                              |
  +---------------------------------------------------------------+
  |                   Repeats to end of buffer                   ...
  |                                                               |
 ...                                                              |
  +---------------------------------------------------------------+
 
  • Field Details

    • DEFAULT_TYPE_ID

      public static final int DEFAULT_TYPE_ID
      Default type id of a counter when none is supplied.
      See Also:
    • DEFAULT_REGISTRATION_ID

      public static final long DEFAULT_REGISTRATION_ID
      Default registration id of a counter when none is set.
      See Also:
    • DEFAULT_OWNER_ID

      public static final long DEFAULT_OWNER_ID
      Default owner id of a counter when none is set.
      See Also:
    • DEFAULT_REFERENCE_ID

      public static final long DEFAULT_REFERENCE_ID
      Default reference id of a counter when none is set.
      See Also:
    • NULL_COUNTER_ID

      public static final int NULL_COUNTER_ID
      Can be used to representing a null counter id when passed as an argument.
      See Also:
    • RECORD_UNUSED

      public static final int RECORD_UNUSED
      Record has not been used.
      See Also:
    • RECORD_ALLOCATED

      public static final int RECORD_ALLOCATED
      Record currently allocated for use.
      See Also:
    • RECORD_RECLAIMED

      public static final int RECORD_RECLAIMED
      Record was active and now has been reclaimed.
      See Also:
    • NOT_FREE_TO_REUSE

      public static final long NOT_FREE_TO_REUSE
      Deadline to indicate counter is not free to be reused.
      See Also:
    • REGISTRATION_ID_OFFSET

      public static final int REGISTRATION_ID_OFFSET
      Offset in the record at which the registration id field is stored. When a counter is allocated the action can be given a registration id to indicate a specific term of use. This can be useful to differentiate the reuse of a counter id for another purpose even with the same type id.
      See Also:
    • OWNER_ID_OFFSET

      public static final int OWNER_ID_OFFSET
      Offset in the record at which the owner id field is stored. The owner is an abstract concept which can be used to associate counters to an owner for lifecycle management.
      See Also:
    • REFERENCE_ID_OFFSET

      public static final int REFERENCE_ID_OFFSET
      Offset in the record at which the reference id field is stored. This id can be used to associate this counter with a registration id for something else, such as an Image, Subscription, Publication, etc.
      See Also:
    • TYPE_ID_OFFSET

      public static final int TYPE_ID_OFFSET
      Offset in the record at which the type id field is stored.
      See Also:
    • FREE_FOR_REUSE_DEADLINE_OFFSET

      public static final int FREE_FOR_REUSE_DEADLINE_OFFSET
      Offset in the record at which the deadline (in milliseconds) for when counter may be reused.
      See Also:
    • KEY_OFFSET

      public static final int KEY_OFFSET
      Offset in the record at which the key is stored.
      See Also:
    • LABEL_OFFSET

      public static final int LABEL_OFFSET
      Offset in the record at which the label is stored.
      See Also:
    • FULL_LABEL_LENGTH

      public static final int FULL_LABEL_LENGTH
      Length of a counter label length including length prefix.
      See Also:
    • MAX_LABEL_LENGTH

      public static final int MAX_LABEL_LENGTH
      Maximum length of a label not including its length prefix.
      See Also:
    • MAX_KEY_LENGTH

      public static final int MAX_KEY_LENGTH
      Maximum length a key can be.
      See Also:
    • METADATA_LENGTH

      public static final int METADATA_LENGTH
      Length of a metadata record in bytes.
      See Also:
    • COUNTER_LENGTH

      public static final int COUNTER_LENGTH
      Length of the space allocated to a counter that includes padding to avoid false sharing.
      See Also:
    • maxCounterId

      protected final int maxCounterId
      Max counter ID.
    • metaDataBuffer

      protected final AtomicBuffer metaDataBuffer
      Meta-data buffer.
    • valuesBuffer

      protected final AtomicBuffer valuesBuffer
      Values buffer.
    • labelCharset

      protected final Charset labelCharset
      Charset for the label.
  • Constructor Details

    • CountersReader

      public CountersReader(AtomicBuffer metaDataBuffer, AtomicBuffer valuesBuffer)
      Construct a reader over buffers containing the values and associated metadata.

      Counter labels default to StandardCharsets.UTF_8.

      Parameters:
      metaDataBuffer - containing the counter metadata.
      valuesBuffer - containing the counter values.
    • CountersReader

      public CountersReader(AtomicBuffer metaDataBuffer, AtomicBuffer valuesBuffer, Charset labelCharset)
      Construct a reader over buffers containing the values and associated metadata.
      Parameters:
      metaDataBuffer - containing the counter metadata.
      valuesBuffer - containing the counter values.
      labelCharset - for the label encoding.
  • Method Details

    • maxCounterId

      public int maxCounterId()
      Get the maximum counter id which can be supported given the length of the values buffer.
      Returns:
      the maximum counter id which can be supported given the length of the values buffer.
    • metaDataBuffer

      public AtomicBuffer metaDataBuffer()
      Get the buffer containing the metadata for the counters.
      Returns:
      the buffer containing the metadata for the counters.
    • valuesBuffer

      public AtomicBuffer valuesBuffer()
      Get the buffer containing the values for the counters.
      Returns:
      the buffer containing the values for the counters.
    • labelCharset

      public Charset labelCharset()
      The Charset used for the encoded label.
      Returns:
      the Charset used for the encoded label.
    • counterOffset

      public static int counterOffset(int counterId)
      The offset in the counter buffer for a given counterId.
      Parameters:
      counterId - for which the offset should be provided.
      Returns:
      the offset in the counter buffer.
    • metaDataOffset

      public static int metaDataOffset(int counterId)
      The offset in the metadata buffer for a given id.
      Parameters:
      counterId - for the record.
      Returns:
      the offset at which the metadata record begins.
    • forEach

      public void forEach(IntObjConsumer<String> consumer)
      Iterate over all labels in the label buffer.
      Parameters:
      consumer - function to be called for each label.
    • forEach

      public void forEach(CountersReader.CounterConsumer consumer)
      Iterate over the counters and provide the value and basic metadata.
      Parameters:
      consumer - for each allocated counter.
    • forEach

      public void forEach(CountersReader.MetaData metaData)
      Iterate over all the metadata in the buffer.
      Parameters:
      metaData - function to be called for each metadata record.
    • findByRegistrationId

      public int findByRegistrationId(long registrationId)
      Iterate over allocated counters and find the first matching a given registration id.
      Parameters:
      registrationId - to find.
      Returns:
      the counter if found otherwise NULL_COUNTER_ID.
    • findByTypeIdAndRegistrationId

      public int findByTypeIdAndRegistrationId(int typeId, long registrationId)
      Iterate over allocated counters and find the first matching a given type id and registration id.
      Parameters:
      typeId - to find.
      registrationId - to find.
      Returns:
      the counter if found otherwise NULL_COUNTER_ID.
    • getCounterValue

      public long getCounterValue(int counterId)
      Get the value for a given counter id as a volatile read.
      Parameters:
      counterId - to be read.
      Returns:
      the current value of the counter.
    • getCounterRegistrationId

      public long getCounterRegistrationId(int counterId)
      Get the registration id for a given counter id as a volatile read. The registration identity may be assigned when the counter is allocated to help avoid ABA issues if the counter id is reused.
      Parameters:
      counterId - to be read.
      Returns:
      the current registration id of the counter.
      See Also:
    • getCounterOwnerId

      public long getCounterOwnerId(int counterId)
      Get the owner id for a given counter id as a normal read. The owner identity may be assigned when the counter is allocated to help associate it with the abstract concept of an owner for lifecycle management.
      Parameters:
      counterId - to be read.
      Returns:
      the current owner id of the counter.
      See Also:
    • getCounterReferenceId

      public long getCounterReferenceId(int counterId)
      Get the reference id for a given counter id as a normal read. The id may be assigned when the counter is allocated to help associate this counter with a registration id for an Image, Subscription, Publication, etc.
      Parameters:
      counterId - to be read.
      Returns:
      the current reference id of the counter.
      See Also:
    • getCounterState

      public int getCounterState(int counterId)
      Get the state for a given counter id as a volatile read.
      Parameters:
      counterId - to be read.
      Returns:
      the current state of the counter.
      See Also:
    • getCounterTypeId

      public int getCounterTypeId(int counterId)
      Get the type id for a given counter id.
      Parameters:
      counterId - to be read.
      Returns:
      the type id for a given counter id.
      See Also:
    • getFreeForReuseDeadline

      public long getFreeForReuseDeadline(int counterId)
      Get the deadline (ms) for when a given counter id may be reused.
      Parameters:
      counterId - to be read.
      Returns:
      deadline (ms) for when a given counter id may be reused or NOT_FREE_TO_REUSE if currently in use.
    • getCounterLabel

      public String getCounterLabel(int counterId)
      Get the label for a given counter id as a volatile read.
      Parameters:
      counterId - to be read.
      Returns:
      the label for the given counter id.
    • validateCounterId

      protected void validateCounterId(int counterId)
      Validate if counter Id is valid.
      Parameters:
      counterId - to validate.
      Throws:
      IllegalArgumentException - if counterId < 0 || counterId > maxCounterId.
    • labelValue

      private String labelValue(AtomicBuffer metaDataBuffer, int recordOffset)