Class LogCache

java.lang.Object
org.jgroups.raft.util.LogCache
All Implemented Interfaces:
Closeable, AutoCloseable, Log, LogCacheControl, LogCapability
public final class LogCache extends Object implements Log, LogCacheControl
Bounded caching Log facade. Reads are returned from the cache (if available), writes invalidate the corresponding entries. Keeps the last N entries only (N is configurable).
Since:
1.0.8
Author:
Bela Ban

  • Constructor Summary

    Constructors
    Constructor
    Description
    LogCache(Log log)
     
    LogCache(Log log, int max_size)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    long
    append(long index, LogEntries entries)
    Appends entries starting at the given index and advances Log.lastAppended() accordingly.
    int
    cacheSize()
    Returns the current number of entries in the cache.
    void
    clear()
    Evicts all cached entries without disabling the cache.
    void
    close()
     
    long
    commitIndex()
    Returns the current commit index.
    Log
    commitIndex(long new_index)
    Persists the commit index.
    long
    currentTerm()
    Returns the current Raft term.
    Log
    currentTerm(long new_term)
    Persists the current Raft term.
    void
    deleteAllEntriesStartingFrom(long start_index)
    Deletes all entries at and after start_index.
    String
    description()
    Returns a human-readable summary of the cache and its underlying log.
    void
    disable()
    Disables caching.
    void
    enable(int maxSize)
    Enables caching with the given maximum number of entries.
    <T extends LogCapability>
    T
    findCapability(Class<T> capability)
    Looks up an optional capability provided by this log or any log in the delegation chain.
    long
    firstAppended()
    Returns the index of the first entry in the log.
    void
    forEach(ObjLongConsumer<LogEntry> function)
    Applies the function to every entry in the log.
    void
    forEach(ObjLongConsumer<LogEntry> function, long start_index, long end_index)
    Applies the function to each entry in the range [max(start_index, firstAppended) ..
    LogEntry
    get(long index)
    Returns the entry at the given index.
    ByteBuffer
    getSnapshot()
    Returns the most recently stored snapshot.
    double
    hitRatio()
    Returns the fraction of cache lookups that were served from the cache.
    void
    init(String log_name, Map<String,String> args)
    Initializes this log with the given identity and optional configuration.
    long
    lastAppended()
    Returns the index of the last appended entry.
    int
    maxSize()
    Returns the maximum number of entries the cache will retain.
    void
    maxSize(int size)
    Sets the maximum number of entries the cache will retain.
    int
    numAccesses()
    Returns the total number of cache lookups (hits + misses).
    int
    numTrims()
    Returns the number of times the cache has been trimmed to stay within capacity.
    int
    readSnapshotRegion(long offset, byte[] dst, int dstOffset, int length)
    Reads up to length bytes from the snapshot data starting at offset.
    void
    reinitializeTo(long index, LogEntry le)
    Resets the log to contain only the given entry at the given index.
    void
    resetStats()
    Resets all cache statistics (accesses, hits, trims) to zero.
    void
    setSnapshot(InputStream input)
    Stores a snapshot of the state machine, replacing any previously stored snapshot.
    void
    setSnapshot(ByteBuffer sn)
    Stores a snapshot of the state machine, replacing any previously stored snapshot.
    long
    sizeInBytes()
    Returns the approximate size of the log data in bytes.
    long
    snapshotSize()
    Returns the size of the snapshot.
    String
    toString()
     
    String
    toStringDetails()
     
    void
    trim()
    Evicts the oldest entries until the cache size is within the configured maximum.
    void
    truncate(long index_exclusive)
    Removes all entries before the given index.
    boolean
    useFsync()
    Returns whether writes are forced to stable storage before mutating operations return.
    Log
    useFsync(boolean f)
    Controls whether mutating operations force data to stable storage (fsync) before returning.
    org.jgroups.Address
    votedFor()
    Returns the candidate this node voted for in the current term.
    Log
    votedFor(org.jgroups.Address member)
    Persists the vote for the given candidate in the current term.

    Methods inherited from class Object

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

    Methods inherited from interface Log

    size

  • Constructor Details

    • LogCache

      public LogCache(Log log)

    • LogCache

      public LogCache(Log log, int max_size)

  • Method Details

    • maxSize

      public int maxSize()
      Description copied from interface: LogCacheControl
      Returns the maximum number of entries the cache will retain.
      Specified by:
      maxSize in interface LogCacheControl
      Returns:
      the cache capacity

    • maxSize

      public void maxSize(int size)
      Description copied from interface: LogCacheControl
      Sets the maximum number of entries the cache will retain.
      Specified by:
      maxSize in interface LogCacheControl
      Parameters:
      size - the new cache capacity

    • cacheSize

      public int cacheSize()
      Description copied from interface: LogCacheControl
      Returns the current number of entries in the cache.
      Specified by:
      cacheSize in interface LogCacheControl
      Returns:
      the number of cached entries

    • numTrims

      public int numTrims()
      Description copied from interface: LogCacheControl
      Returns the number of times the cache has been trimmed to stay within capacity.
      Specified by:
      numTrims in interface LogCacheControl
      Returns:
      the trim count

    • numAccesses

      public int numAccesses()
      Description copied from interface: LogCacheControl
      Returns the total number of cache lookups (hits + misses).
      Specified by:
      numAccesses in interface LogCacheControl
      Returns:
      the total access count

    • hitRatio

      public double hitRatio()
      Description copied from interface: LogCacheControl
      Returns the fraction of cache lookups that were served from the cache.
      Specified by:
      hitRatio in interface LogCacheControl
      Returns:
      the hit ratio, between 0.0 and 1.0, or 0.0 if no accesses have occurred

    • description

      public String description()
      Description copied from interface: LogCacheControl
      Returns a human-readable summary of the cache and its underlying log.
      Specified by:
      description in interface LogCacheControl
      Returns:
      a description string

    • resetStats

      public void resetStats()
      Description copied from interface: LogCacheControl
      Resets all cache statistics (accesses, hits, trims) to zero.
      Specified by:
      resetStats in interface LogCacheControl

    • useFsync

      public Log useFsync(boolean f)
      Description copied from interface: Log
      Controls whether mutating operations force data to stable storage (fsync) before returning.
      Specified by:
      useFsync in interface Log
      Parameters:
      f - true to force all writes to stable storage
      Returns:
      this log

    • useFsync

      public boolean useFsync()
      Description copied from interface: Log
      Returns whether writes are forced to stable storage before mutating operations return.
      Specified by:
      useFsync in interface Log
      Returns:
      true if fsync is enabled

    • init

      public void init(String log_name, Map<String,String> args) throws Exception
      Description copied from interface: Log
      Initializes this log with the given identity and optional configuration. Must be called exactly once before any other method.
      Specified by:
      init in interface Log
      Parameters:
      log_name - a name used to derive the storage identity (file name, database table, etc.). Two logs initialized with the same name in the same environment share state.
      args - implementation-specific configuration parameters, may be null
      Throws:
      Exception - if initialization fails (missing directory, permission denied, corrupt storage, etc.)

    • currentTerm

      public long currentTerm()
      Description copied from interface: Log
      Returns the current Raft term.
      Specified by:
      currentTerm in interface Log
      Returns:
      the current term, or 0 if not yet set

    • currentTerm

      public Log currentTerm(long new_term) throws IOException
      Description copied from interface: Log
      Persists the current Raft term. The Raft protocol guarantees that terms are monotonically increasing.
      Specified by:
      currentTerm in interface Log
      Parameters:
      new_term - the term to persist
      Returns:
      this log
      Throws:
      IOException - if the term cannot be persisted

    • votedFor

      public org.jgroups.Address votedFor()
      Description copied from interface: Log
      Returns the candidate this node voted for in the current term.
      Specified by:
      votedFor in interface Log
      Returns:
      the address of the voted-for candidate, or null if no vote has been cast in this term

    • votedFor

      public Log votedFor(org.jgroups.Address member) throws IOException
      Description copied from interface: Log
      Persists the vote for the given candidate in the current term. The Raft protocol guarantees at most one vote per term. Passing null clears the vote, typically at term boundaries.
      Specified by:
      votedFor in interface Log
      Parameters:
      member - the candidate address, or null to clear the vote
      Returns:
      this log
      Throws:
      IOException - if the vote cannot be persisted

    • commitIndex

      public long commitIndex()
      Description copied from interface: Log
      Returns the current commit index.
      Specified by:
      commitIndex in interface Log
      Returns:
      the commit index, or 0 if no entries have been committed

    • commitIndex

      public Log commitIndex(long new_index) throws IOException
      Description copied from interface: Log
      Persists the commit index.
      Specified by:
      commitIndex in interface Log
      Parameters:
      new_index - the new commit index
      Returns:
      this log
      Throws:
      IOException - if the commit index cannot be persisted

    • firstAppended

      public long firstAppended()
      Description copied from interface: Log
      Returns the index of the first entry in the log.
      Specified by:
      firstAppended in interface Log
      Returns:
      the first entry index, or 0 if the log is empty

    • lastAppended

      public long lastAppended()
      Description copied from interface: Log
      Returns the index of the last appended entry.
      Specified by:
      lastAppended in interface Log
      Returns:
      the last appended index, or 0 if the log is empty

    • getSnapshot

      public ByteBuffer getSnapshot() throws IOException
      Description copied from interface: Log
      Returns the most recently stored snapshot.
      Specified by:
      getSnapshot in interface Log
      Returns:
      the snapshot data, or null if no snapshot has been stored
      Throws:
      IOException - if the snapshot cannot be read

    • setSnapshot

      public void setSnapshot(ByteBuffer sn) throws IOException
      Description copied from interface: Log
      Stores a snapshot of the state machine, replacing any previously stored snapshot.
      Specified by:
      setSnapshot in interface Log
      Parameters:
      sn - the snapshot data
      Throws:
      IOException - if the snapshot cannot be stored

    • setSnapshot

      public void setSnapshot(InputStream input) throws IOException
      Description copied from interface: Log
      Stores a snapshot of the state machine, replacing any previously stored snapshot.
      Specified by:
      setSnapshot in interface Log
      Parameters:
      input - an input stream to read the snapshot data from
      Throws:
      IOException - if the snapshot cannot be stored

    • snapshotSize

      public long snapshotSize() throws IOException
      Description copied from interface: Log
      Returns the size of the snapshot.
      Specified by:
      snapshotSize in interface Log
      Returns:
      returns the size of the stored snapshot.
      Throws:
      IOException - if not possible to extract the snapshot size

    • readSnapshotRegion

      public int readSnapshotRegion(long offset, byte[] dst, int dstOffset, int length) throws IOException
      Description copied from interface: Log
      Reads up to length bytes from the snapshot data starting at offset.
      Specified by:
      readSnapshotRegion in interface Log
      Parameters:
      offset - offset to start reading from
      dst - buffer to store the read bytes
      dstOffset - offset to start writing the bytes at the destination buffer
      length - how many bytes to try to read
      Returns:
      the number of actual read bytes
      Throws:
      IOException - if not possible to read the snapshot

    • append

      public long append(long index, LogEntries entries) throws IOException
      Description copied from interface: Log
      Appends entries starting at the given index and advances Log.lastAppended() accordingly.

      On partial failure, lastAppended must reflect the last successfully written entry rather than reverting to the value before the call. For example, if lastAppended was 1 and 100 entries were submitted but the operation failed at entry 51, lastAppended must be 50 after the exception.

      Specified by:
      append in interface Log
      Parameters:
      index - the index at which to begin appending
      entries - the entries to append
      Returns:
      the index of the last appended entry
      Throws:
      IOException - if one or more entries cannot be written to storage

    • get

      public LogEntry get(long index) throws IOException
      Description copied from interface: Log
      Returns the entry at the given index.
      Specified by:
      get in interface Log
      Parameters:
      index - the log index to retrieve
      Returns:
      the entry, or null if no entry exists at that index
      Throws:
      IOException - if the entry cannot be read from storage

    • truncate

      public void truncate(long index_exclusive) throws IOException
      Description copied from interface: Log
      Removes all entries before the given index. After this call, Log.firstAppended() equals index_exclusive.

      If index_exclusive exceeds Log.commitIndex(), the commit index is used instead to prevent truncating committed entries.

      Specified by:
      truncate in interface Log
      Parameters:
      index_exclusive - entries strictly before this index are removed
      Throws:
      IOException - if the truncation cannot be completed

    • reinitializeTo

      public void reinitializeTo(long index, LogEntry le) throws IOException
      Description copied from interface: Log
      Resets the log to contain only the given entry at the given index. Sets Log.firstAppended(), Log.lastAppended(), and Log.commitIndex() to index. The next entry will be appended at index + 1.

      Typically called after installing a snapshot received from the leader.

      Specified by:
      reinitializeTo in interface Log
      Parameters:
      index - the new starting index
      le - the single entry to store
      Throws:
      IOException - if the log cannot be reinitialized

    • deleteAllEntriesStartingFrom

      public void deleteAllEntriesStartingFrom(long start_index) throws IOException
      Description copied from interface: Log
      Deletes all entries at and after start_index. Updates Log.lastAppended() and Log.currentTerm() to reflect the remaining log.
      Specified by:
      deleteAllEntriesStartingFrom in interface Log
      Parameters:
      start_index - the first index to delete (inclusive)
      Throws:
      IOException - if the deletion cannot be completed

    • forEach

      public void forEach(ObjLongConsumer<LogEntry> function, long start_index, long end_index) throws IOException
      Description copied from interface: Log
      Applies the function to each entry in the range [max(start_index, firstAppended) .. min(end_index, lastAppended)], inclusive.
      Specified by:
      forEach in interface Log
      Parameters:
      function - invoked with each entry and its index
      start_index - the start of the range (inclusive), clamped to Log.firstAppended()
      end_index - the end of the range (inclusive), clamped to Log.lastAppended()
      Throws:
      IOException - if an entry cannot be read

    • forEach

      public void forEach(ObjLongConsumer<LogEntry> function) throws IOException
      Description copied from interface: Log
      Applies the function to every entry in the log. Equivalent to forEach(function, firstAppended(), lastAppended()).
      Specified by:
      forEach in interface Log
      Parameters:
      function - invoked with each entry and its index
      Throws:
      IOException - if an entry cannot be read

    • sizeInBytes

      public long sizeInBytes()
      Description copied from interface: Log
      Returns the approximate size of the log data in bytes.
      Specified by:
      sizeInBytes in interface Log
      Returns:
      the size in bytes

    • close

      public void close() throws IOException
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException

    • enable

      public void enable(int maxSize)
      Description copied from interface: LogCacheControl
      Enables caching with the given maximum number of entries.
      Specified by:
      enable in interface LogCacheControl
      Parameters:
      maxSize - the maximum number of entries to retain in the cache

    • disable

      public void disable()
      Description copied from interface: LogCacheControl
      Disables caching.

      The cache is cleared and all subsequent operations pass through to the underlying log.

      Specified by:
      disable in interface LogCacheControl

    • clear

      public void clear()
      Description copied from interface: LogCacheControl
      Evicts all cached entries without disabling the cache.
      Specified by:
      clear in interface LogCacheControl

    • trim

      public void trim()
      Description copied from interface: LogCacheControl
      Evicts the oldest entries until the cache size is within the configured maximum.
      Specified by:
      trim in interface LogCacheControl

    • findCapability

      public <T extends LogCapability> T findCapability(Class<T> capability)
      Description copied from interface: Log
      Looks up an optional capability provided by this log or any log in the delegation chain.

      Implementations that wrap another Log should delegate to the wrapped log when they do not provide the requested capability themselves.

      Specified by:
      findCapability in interface Log
      Type Parameters:
      T - the capability type
      Parameters:
      capability - the capability interface to look up
      Returns:
      the capability instance, or null if not available

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • toStringDetails

      public String toStringDetails()