opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/ReplicatedLog.java

   1 /*
   2  * Copyright (c) 2014 Cisco Systems, Inc. and others.  All rights reserved.
   3  *
   4  * This program and the accompanying materials are made available under the
   5  * terms of the Eclipse Public License v1.0 which accompanies this distribution,
   6  * and is available at http://www.eclipse.org/legal/epl-v10.html
   7  */
   8 package org.opendaylight.controller.cluster.raft;
   9
  10 import java.util.List;
  11 import java.util.function.Consumer;
  12 import org.eclipse.jdt.annotation.NonNull;
  13 import org.eclipse.jdt.annotation.Nullable;
  14
  15 /**
  16  * Represents the ReplicatedLog that needs to be kept in sync by the RaftActor.
  17  */
  18 public interface ReplicatedLog {
  19     long NO_MAX_SIZE = -1;
  20
  21     /**
  22      * Return the replicated log entry at the specified index.
  23      *
  24      * @param index the index of the log entry
  25      * @return the ReplicatedLogEntry if found, otherwise null if the adjusted index less than 0 or
  26      *         greater than the size of the in-memory journal
  27      */
  28     @Nullable ReplicatedLogEntry get(long index);
  29
  30     /**
  31      * Return the last replicated log entry in the log or null of not found.
  32      *
  33      * @return the last replicated log entry in the log or null of not found.
  34      */
  35     @Nullable ReplicatedLogEntry last();
  36
  37     /**
  38      * Return the index of the last entry in the log or -1 if the log is empty.
  39      *
  40      * @return the index of the last entry in the log or -1 if the log is empty.
  41      */
  42     long lastIndex();
  43
  44     /**
  45      * Return the term of the last entry in the log or -1 if the log is empty.
  46      *
  47      * @return the term of the last entry in the log or -1 if the log is empty.
  48      */
  49     long lastTerm();
  50
  51     /**
  52      * Removes entries from the in-memory log starting at the given index.
  53      *
  54      * @param index the index of the first log entry to remove
  55      * @return the adjusted index of the first log entry removed or -1 if the log entry is not found.
  56      */
  57     long removeFrom(long index);
  58
  59     /**
  60      * Removes entries from the in-memory log and the persisted log starting at the given index.
  61      *
  62      * <p>
  63      * The persisted information would then be used during recovery to properly
  64      * reconstruct the state of the in-memory replicated log
  65      *
  66      * @param index the index of the first log entry to remove
  67      * @return true if entries were removed, false otherwise
  68      */
  69     boolean removeFromAndPersist(long index);
  70
  71     /**
  72      * Appends an entry to the log.
  73      *
  74      * @param replicatedLogEntry the entry to append
  75      * @return true if the entry was successfully appended, false otherwise. An entry can fail to append if
  76      *         the index is already included in the log.
  77      */
  78     boolean append(ReplicatedLogEntry replicatedLogEntry);
  79
  80     /**
  81      * Optimization method to increase the capacity of the journal log prior to appending entries.
  82      *
  83      * @param amount the amount to increase by
  84      */
  85     void increaseJournalLogCapacity(int amount);
  86
  87     /**
  88      * Appends an entry to the in-memory log and persists it as well.
  89      *
  90      * @param replicatedLogEntry the entry to append
  91      * @param callback the callback to be notified when persistence is complete (optional).
  92      * @param doAsync if true, the persistent actor can receive subsequent messages to process in between the persist
  93      *        call and the execution of the associated callback. If false, subsequent messages are stashed and get
  94      *        delivered after persistence is complete and the associated callback is executed. In either case the
  95      *        callback is guaranteed to execute in the context of the actor associated with this log.
  96      * @return true if the entry was successfully appended, false otherwise.
  97      */
  98     boolean appendAndPersist(@NonNull ReplicatedLogEntry replicatedLogEntry,
  99             @Nullable Consumer<ReplicatedLogEntry> callback, boolean doAsync);
 100
 101     /**
 102      * Returns a list of log entries starting from the given index to the end of the log.
 103      *
 104      * @param index the index of the first log entry to get.
 105      * @return the List of entries
 106      */
 107     @NonNull List<ReplicatedLogEntry> getFrom(long index);
 108
 109     /**
 110      * Returns a list of log entries starting from the given index up to the given maximum of entries or
 111      * the given maximum accumulated size, whichever comes first.
 112      *
 113      * @param index the index of the first log entry to get
 114      * @param maxEntries the maximum number of entries to get
 115      * @param maxDataSize the maximum accumulated size of the log entries to get
 116      * @return the List of entries meeting the criteria.
 117      */
 118     @NonNull List<ReplicatedLogEntry> getFrom(long index, int maxEntries, long maxDataSize);
 119
 120     /**
 121      * Returns the number of entries in the journal.
 122      *
 123      * @return the number of entries
 124      */
 125     long size();
 126
 127     /**
 128      * Checks if the entry at the specified index is present or not.
 129      *
 130      * @param index the index of the log entry
 131      * @return true if the entry is present in the in-memory journal
 132      */
 133     boolean isPresent(long index);
 134
 135     /**
 136      * Checks if the entry is present in a snapshot.
 137      *
 138      * @param index the index of the log entry
 139      * @return true if the entry is in the snapshot. false if the entry is not in the snapshot even if the entry may
 140      *         be present in the replicated log
 141      */
 142     boolean isInSnapshot(long index);
 143
 144     /**
 145      * Returns the index of the snapshot.
 146      *
 147      * @return the index from which the snapshot was created. -1 otherwise.
 148      */
 149     long getSnapshotIndex();
 150
 151     /**
 152      * Returns the term of the snapshot.
 153      *
 154      * @return the term of the index from which the snapshot was created. -1 otherwise
 155      */
 156     long getSnapshotTerm();
 157
 158     /**
 159      * Sets the snapshot index in the replicated log.
 160      *
 161      * @param snapshotIndex the index to set
 162      */
 163     void setSnapshotIndex(long snapshotIndex);
 164
 165     /**
 166      * Sets snapshot term.
 167      *
 168      * @param snapshotTerm the term to set
 169      */
 170     void setSnapshotTerm(long snapshotTerm);
 171
 172     /**
 173      * Clears the journal entries with startIndex (inclusive) and endIndex (exclusive).
 174      *
 175      * @param startIndex the start index (inclusive)
 176      * @param endIndex the end index (exclusive)
 177      */
 178     void clear(int startIndex, int endIndex);
 179
 180     /**
 181      * Handles all the bookkeeping in order to perform a rollback in the event of SaveSnapshotFailure.
 182      *
 183      * @param snapshotCapturedIndex the new snapshot index
 184      * @param snapshotCapturedTerm the new snapshot term
 185      */
 186     void snapshotPreCommit(long snapshotCapturedIndex, long snapshotCapturedTerm);
 187
 188     /**
 189      * Sets the Replicated log to state after snapshot success.
 190      */
 191     void snapshotCommit();
 192
 193     /**
 194      * Restores the replicated log to a state in the event of a save snapshot failure.
 195      */
 196     void snapshotRollback();
 197
 198     /**
 199      * Returns the size of the data in the log (in bytes).
 200      *
 201      * @return the size of the data in the log (in bytes)
 202      */
 203     int dataSize();
 204
 205     /**
 206      * Determines if a snapshot needs to be captured based on the count/memory consumed and initiates the capture.
 207      *
 208      * @param replicatedLogEntry the last log entry.
 209      */
 210     void captureSnapshotIfReady(ReplicatedLogEntry replicatedLogEntry);
 211
 212     /**
 213      * Determines if a snapshot should be captured based on the count/memory consumed.
 214      *
 215      * @param logIndex the log index to use to determine if the log count has exceeded the threshold
 216      * @return true if a snapshot should be captured, false otherwise
 217      */
 218     boolean shouldCaptureSnapshot(long logIndex);
 219 }