Package org.agrona

Class MarkFile

java.lang.Object
org.agrona.MarkFile
All Implemented Interfaces:
AutoCloseable
public class MarkFile extends Object implements AutoCloseable
A MarkFile is used to mark the presence of a running component and to track liveness.

The assumptions are: (1) the version field is an int in size, (2) the timestamp field is a long in size, and (3) the version field comes before the timestamp field.

  • Constructor Details

    • MarkFile

      public MarkFile(File directory, String filename, boolean warnIfDirectoryExists, boolean dirDeleteOnStart, int versionFieldOffset, int timestampFieldOffset, int totalFileLength, long timeoutMs, EpochClock epochClock, IntConsumer versionCheck, Consumer<String> logger)
      Create a directory and mark file if none present. Checking if an active Mark file exists and is active. Old Mark file is deleted and recreated if not active.

      Total length of Mark file will be mapped until close() is called.

      Parameters:
      directory - for the Mark file.
      filename - of the Mark file.
      warnIfDirectoryExists - for logging purposes.
      dirDeleteOnStart - if desired.
      versionFieldOffset - to use for version field access.
      timestampFieldOffset - to use for timestamp field access.
      totalFileLength - to allocate when creating new Mark file.
      timeoutMs - for the activity check (in milliseconds).
      epochClock - to use for time checks.
      versionCheck - to use for existing Mark file and version field.
      logger - to use to signal progress or null.

    • MarkFile

      public MarkFile(File markFile, boolean shouldPreExist, int versionFieldOffset, int timestampFieldOffset, int totalFileLength, long timeoutMs, EpochClock epochClock, IntConsumer versionCheck, Consumer<String> logger)
      Create a MarkFile if none present. Checking if an active MarkFile exists and is active. Existing MarkFile is used if not active.

      Total length of Mark file will be mapped until close() is called.

      Parameters:
      markFile - to use.
      shouldPreExist - or not.
      versionFieldOffset - to use for version field access.
      timestampFieldOffset - to use for timestamp field access.
      totalFileLength - to allocate when creating new MarkFile.
      timeoutMs - for the activity check (in milliseconds).
      epochClock - to use for time checks.
      versionCheck - to use for existing MarkFile and version field.
      logger - to use to signal progress or null.

    • MarkFile

      public MarkFile(File directory, String filename, int versionFieldOffset, int timestampFieldOffset, long timeoutMs, EpochClock epochClock, IntConsumer versionCheck, Consumer<String> logger)
      Map a pre-existing MarkFile if one present and is active.

      Total length of MarkFile will be mapped until close() is called.

      Parameters:
      directory - for the MarkFile file.
      filename - of the MarkFile file.
      versionFieldOffset - to use for version field access.
      timestampFieldOffset - to use for timestamp field access.
      timeoutMs - for the activity check (in milliseconds) and for how long to wait for file to exist.
      epochClock - to use for time checks.
      versionCheck - to use for existing MarkFile file and version field.
      logger - to use to signal progress or null.

    • MarkFile

      public MarkFile(MappedByteBuffer mappedBuffer, int versionFieldOffset, int timestampFieldOffset)
      Manage a MarkFile given a mapped file and offsets of version and timestamp.

      If mappedBuffer is not null, then it will be unmapped upon close().

      Parameters:
      mappedBuffer - for the MarkFile fields.
      versionFieldOffset - for the version field.
      timestampFieldOffset - for the timestamp field.

    • MarkFile

      public MarkFile(UnsafeBuffer buffer, int versionFieldOffset, int timestampFieldOffset)
      Manage a MarkFile given a buffer and offsets of version and timestamp.
      Parameters:
      buffer - for the MarkFile fields
      versionFieldOffset - for the version field
      timestampFieldOffset - for the timestamp field

  • Method Details

    • isClosed

      public boolean isClosed()
      Checks if MarkFile is closed.
      Returns:
      true if MarkFile is closed.

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable

    • signalReady

      public void signalReady(int version)
      Perform an ordered put of the version field.
      Parameters:
      version - to be signaled.

    • versionVolatile

      public int versionVolatile()
      Perform volatile read of the version field.
      Returns:
      value of the version field.

    • versionWeak

      public int versionWeak()
      Perform weak/plain read of the version field.
      Returns:
      value of the version field.

    • timestampOrdered

      public void timestampOrdered(long timestamp)
      Set timestamp field using an ordered put.

      This method is identical to timestampRelease(long) and that method is preferred.

      Parameters:
      timestamp - to be set.

    • timestampRelease

      public void timestampRelease(long timestamp)
      Set timestamp field using a release put.
      Parameters:
      timestamp - to be set.

    • timestampVolatile

      public long timestampVolatile()
      Perform volatile read of the timestamp field.
      Returns:
      value of the timestamp field.

    • timestampWeak

      public long timestampWeak()
      Perform weak/plain read of the timestamp field.
      Returns:
      value of the timestamp field.

    • deleteDirectory

      public void deleteDirectory(boolean ignoreFailures)
      Delete parent directory.
      Parameters:
      ignoreFailures - should the failures be silently ignored.

    • parentDirectory

      public File parentDirectory()
      Returns parent directory.
      Returns:
      parent directory.

    • markFile

      public File markFile()
      Returns MarkFile.
      Returns:
      MarkFile.

    • mappedByteBuffer

      public MappedByteBuffer mappedByteBuffer()
      Returns the underlying MappedByteBuffer.
      Returns:
      reference to the MappedByteBuffer.

    • buffer

      public UnsafeBuffer buffer()
      Returns the underlying UnsafeBuffer.
      Returns:
      reference to the UnsafeBuffer.

    • ensureDirectoryExists

      public static void ensureDirectoryExists(File directory, String filename, boolean warnIfDirectoryExists, boolean dirDeleteOnStart, int versionFieldOffset, int timestampFieldOffset, long timeoutMs, EpochClock epochClock, IntConsumer versionCheck, Consumer<String> logger)
      Ensure the directory exists, i.e. create if it does not exist yet and re-create if it already exists.
      Parameters:
      directory - to create.
      filename - of the MarkFile.
      warnIfDirectoryExists - should print warning if directory already exists.
      dirDeleteOnStart - should directory be deleted if it already exists. When the flag is set to false the check will be made to see if the MarkFile is active.

      Note: the directory will be deleted anyway even if the flag is false.

      versionFieldOffset - offset of the version field.
      timestampFieldOffset - offset of the timestamp field.
      timeoutMs - timeout in milliseconds.
      epochClock - epoch clock.
      versionCheck - MarkFile version check function.
      logger - to use for reporting warnings.
      Throws:
      IllegalStateException - if MarkFile already exists and is active and dirDeleteOnStart=false.

    • waitForFileMapping

      public static MappedByteBuffer waitForFileMapping(Consumer<String> logger, File markFile, long deadlineMs, EpochClock epochClock)
      Await the creation of the MarkFile.
      Parameters:
      logger - to use for warnings.
      markFile - the MarkFile.
      deadlineMs - deadline timeout in milliseconds.
      epochClock - epoch clock.
      Returns:
      MappedByteBuffer for the MarkFile.
      Throws:
      IllegalStateException - if deadline timeout is reached.

    • mapExistingMarkFile

      public static MappedByteBuffer mapExistingMarkFile(File markFile, int versionFieldOffset, int timestampFieldOffset, long timeoutMs, EpochClock epochClock, IntConsumer versionCheck, Consumer<String> logger)
      Map existing MarkFile.
      Parameters:
      markFile - the MarkFile.
      versionFieldOffset - offset of the version field.
      timestampFieldOffset - offset of the timestamp field.
      timeoutMs - timeout in milliseconds.
      epochClock - epoch clock.
      versionCheck - version check function.
      logger - for the warnings.
      Returns:
      MappedByteBuffer for the MarkFile.
      Throws:
      IllegalStateException - if timeout is reached.
      IllegalStateException - if MarkFile has wrong size.

    • mapNewOrExistingMarkFile

      public static MappedByteBuffer mapNewOrExistingMarkFile(File markFile, boolean shouldPreExist, int versionFieldOffset, int timestampFieldOffset, long totalFileLength, long timeoutMs, EpochClock epochClock, IntConsumer versionCheck, Consumer<String> logger)
      Map new of existing MarkFile.
      Parameters:
      markFile - the MarkFile.
      shouldPreExist - should MarkFile already exist.
      versionFieldOffset - offset of the version field.
      timestampFieldOffset - offset of the timestamp field.
      totalFileLength - total file length to be mapped.
      timeoutMs - timeout in milliseconds.
      epochClock - epoch clock.
      versionCheck - version check function.
      logger - for the warnings.
      Returns:
      MappedByteBuffer for the MarkFile.
      Throws:
      IllegalStateException - if timeout is reached.

    • mapExistingFile

      public static MappedByteBuffer mapExistingFile(File markFile, Consumer<String> logger, long offset, long length)
      Map existing MarkFile.
      Parameters:
      markFile - the MarkFile.
      logger - for the warnings.
      offset - offset to map at.
      length - to map.
      Returns:
      MappedByteBuffer for the MarkFile.

    • isActive

      public static boolean isActive(MappedByteBuffer byteBuffer, EpochClock epochClock, long timeoutMs, int versionFieldOffset, int timestampFieldOffset, IntConsumer versionCheck, Consumer<String> logger)
      Check if MarkFile is active, i.e. still in use.
      Parameters:
      byteBuffer - the MappedByteBuffer.
      epochClock - epoch clock.
      timeoutMs - timeout in milliseconds.
      versionFieldOffset - offset of the version field.
      timestampFieldOffset - offset of the timestamp field.
      versionCheck - version check function.
      logger - for the warnings.
      Returns:
      true if MarkFile is active.

    • ensureMarkFileLink

      public static void ensureMarkFileLink(File serviceDir, File actualFile, String linkFilename)
      Ensure a link file exists if required for the actual mark file. A link file will contain the pathname of the actual mark file's parent directory. This is useful if the mark file should be stored on a different storage medium to the directory of the service. This will create a file with name of linkFilename in the serviceDir. If actualFile is an immediate child of serviceDir then any file with the name of linkFilename will be deleted from the serviceDir (so that links won't be present if not required).
      Parameters:
      serviceDir - directory where the mark file would normally be stored (e.g. archiveDir, clusterDir).
      actualFile - location of actual mark file, e.g. /dev/shm/service/node0/archive-mark.dat
      linkFilename - short name that should be used for the link file, e.g. archive-mark.lnk

    • sleep

      protected static void sleep(long durationMs)
      Put thread to sleep for the given duration and restore interrupted status if thread is interrupted while sleeping.
      Parameters:
      durationMs - sleep duration in milliseconds.