Package org.agrona
Class MarkFile
java.lang.Object
org.agrona.MarkFile
- All Implemented Interfaces:
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.
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final UnsafeBuffer
private final AtomicBoolean
private final MappedByteBuffer
private final File
private final File
private final int
private final int
-
Constructor Summary
ConstructorsConstructorDescriptionMarkFile
(File markFile, boolean shouldPreExist, int versionFieldOffset, int timestampFieldOffset, int totalFileLength, long timeoutMs, EpochClock epochClock, IntConsumer versionCheck, Consumer<String> logger) Create aMarkFile
if none present.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.MarkFile
(File directory, String filename, int versionFieldOffset, int timestampFieldOffset, long timeoutMs, EpochClock epochClock, IntConsumer versionCheck, Consumer<String> logger) Map a pre-existingMarkFile
if one present and is active.MarkFile
(MappedByteBuffer mappedBuffer, int versionFieldOffset, int timestampFieldOffset) Manage aMarkFile
given a mapped file and offsets of version and timestamp.MarkFile
(UnsafeBuffer buffer, int versionFieldOffset, int timestampFieldOffset) Manage aMarkFile
given a buffer and offsets of version and timestamp. -
Method Summary
Modifier and TypeMethodDescriptionbuffer()
Returns the underlyingUnsafeBuffer
.void
close()
void
deleteDirectory
(boolean ignoreFailures) Delete parent directory.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.static void
ensureMarkFileLink
(File serviceDir, File actualFile, String linkFilename) Ensure a link file exists if required for the actual mark file.static boolean
isActive
(MappedByteBuffer byteBuffer, EpochClock epochClock, long timeoutMs, int versionFieldOffset, int timestampFieldOffset, IntConsumer versionCheck, Consumer<String> logger) Check ifMarkFile
is active, i.e.boolean
isClosed()
Checks ifMarkFile
is closed.static MappedByteBuffer
mapExistingFile
(File markFile, Consumer<String> logger, long offset, long length) Map existingMarkFile
.static MappedByteBuffer
mapExistingMarkFile
(File markFile, int versionFieldOffset, int timestampFieldOffset, long timeoutMs, EpochClock epochClock, IntConsumer versionCheck, Consumer<String> logger) Map existingMarkFile
.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 existingMarkFile
.Returns the underlyingMappedByteBuffer
.markFile()
ReturnsMarkFile
.Returns parent directory.void
signalReady
(int version) Perform an ordered put of the version field.protected static void
sleep
(long durationMs) Put thread to sleep for the given duration and restore interrupted status if thread is interrupted while sleeping.void
timestampOrdered
(long timestamp) Set timestamp field using an ordered put.long
Perform volatile read of the timestamp field.long
Perform weak/plain read of the timestamp field.private static void
validateOffsets
(int versionFieldOffset, int timestampFieldOffset) int
Perform volatile read of the version field.int
Perform weak/plain read of the version field.static MappedByteBuffer
waitForFileMapping
(Consumer<String> logger, File markFile, long deadlineMs, EpochClock epochClock) Await the creation of theMarkFile
.
-
Field Details
-
versionFieldOffset
private final int versionFieldOffset -
timestampFieldOffset
private final int timestampFieldOffset -
parentDir
-
markFile
-
mappedBuffer
-
buffer
-
isClosed
-
-
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 aMarkFile
if none present. Checking if an activeMarkFile
exists and is active. ExistingMarkFile
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 newMarkFile
.timeoutMs
- for the activity check (in milliseconds).epochClock
- to use for time checks.versionCheck
- to use for existingMarkFile
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-existingMarkFile
if one present and is active.Total length of
MarkFile
will be mapped untilclose()
is called.- Parameters:
directory
- for theMarkFile
file.filename
- of theMarkFile
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 existingMarkFile
file and version field.logger
- to use to signal progress or null.
-
MarkFile
Manage aMarkFile
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 theMarkFile
fields.versionFieldOffset
- for the version field.timestampFieldOffset
- for the timestamp field.
-
MarkFile
Manage aMarkFile
given a buffer and offsets of version and timestamp.- Parameters:
buffer
- for theMarkFile
fieldsversionFieldOffset
- for the version fieldtimestampFieldOffset
- for the timestamp field
-
-
Method Details
-
isClosed
public boolean isClosed()Checks ifMarkFile
is closed.- Returns:
true
ifMarkFile
is closed.
-
close
public void close()- Specified by:
close
in interfaceAutoCloseable
-
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.- 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
Returns parent directory.- Returns:
- parent directory.
-
markFile
ReturnsMarkFile
.- Returns:
MarkFile
.
-
mappedByteBuffer
Returns the underlyingMappedByteBuffer
.- Returns:
- reference to the
MappedByteBuffer
.
-
buffer
Returns the underlyingUnsafeBuffer
.- 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 theMarkFile
.warnIfDirectoryExists
- should print warning if directory already exists.dirDeleteOnStart
- should directory be deleted if it already exists. When the flag is set tofalse
the check will be made to see if theMarkFile
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
- ifMarkFile
already exists and is active anddirDeleteOnStart=false
.
-
waitForFileMapping
public static MappedByteBuffer waitForFileMapping(Consumer<String> logger, File markFile, long deadlineMs, EpochClock epochClock) Await the creation of theMarkFile
.- Parameters:
logger
- to use for warnings.markFile
- theMarkFile
.deadlineMs
- deadline timeout in milliseconds.epochClock
- epoch clock.- Returns:
MappedByteBuffer
for theMarkFile
.- 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 existingMarkFile
.- Parameters:
markFile
- theMarkFile
.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 theMarkFile
.- Throws:
IllegalStateException
- if timeout is reached.IllegalStateException
- ifMarkFile
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 existingMarkFile
.- Parameters:
markFile
- theMarkFile
.shouldPreExist
- shouldMarkFile
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 theMarkFile
.- Throws:
IllegalStateException
- if timeout is reached.
-
mapExistingFile
public static MappedByteBuffer mapExistingFile(File markFile, Consumer<String> logger, long offset, long length) Map existingMarkFile
.- Parameters:
markFile
- theMarkFile
.logger
- for the warnings.offset
- offset to map at.length
- to map.- Returns:
MappedByteBuffer
for theMarkFile
.
-
isActive
public static boolean isActive(MappedByteBuffer byteBuffer, EpochClock epochClock, long timeoutMs, int versionFieldOffset, int timestampFieldOffset, IntConsumer versionCheck, Consumer<String> logger) Check ifMarkFile
is active, i.e. still in use.- Parameters:
byteBuffer
- theMappedByteBuffer
.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
ifMarkFile
is active.
-
ensureMarkFileLink
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 oflinkFilename
in theserviceDir
. IfactualFile
is an immediate child ofserviceDir
then any file with the name oflinkFilename
will be deleted from theserviceDir
(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.datlinkFilename
- 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.
-
validateOffsets
private static void validateOffsets(int versionFieldOffset, int timestampFieldOffset)
-