1 // Copyright (c) 2011-present, Facebook, Inc.  All rights reserved.
2 //  This source code is licensed under both the GPLv2 (found in the
3 //  COPYING file in the root directory) and Apache 2.0 License
4 //  (found in the LICENSE.Apache file in the root directory).
5 
6 #pragma once
7 
8 #include <map>
9 #include <string>
10 
11 #include "rocksdb/rocksdb_namespace.h"
12 
13 namespace ROCKSDB_NAMESPACE {
14 
15 class WriteBatch;
16 
17 // WALFilter allows an application to inspect write-ahead-log (WAL)
18 // records or modify their processing on recovery.
19 // Please see the details below.
20 class WalFilter {
21  public:
22   enum class WalProcessingOption {
23     // Continue processing as usual
24     kContinueProcessing = 0,
25     // Ignore the current record but continue processing of log(s)
26     kIgnoreCurrentRecord = 1,
27     // Stop replay of logs and discard logs
28     // Logs won't be replayed on subsequent recovery
29     kStopReplay = 2,
30     // Corrupted record detected by filter
31     kCorruptedRecord = 3,
32     // Marker for enum count
33     kWalProcessingOptionMax = 4
34   };
35 
~WalFilter()36   virtual ~WalFilter() {}
37 
38   // Provide ColumnFamily->LogNumber map to filter
39   // so that filter can determine whether a log number applies to a given
40   // column family (i.e. that log hasn't been flushed to SST already for the
41   // column family).
42   // We also pass in name->id map as only name is known during
43   // recovery (as handles are opened post-recovery).
44   // while write batch callbacks happen in terms of column family id.
45   //
46   // @params cf_lognumber_map column_family_id to lognumber map
47   // @params cf_name_id_map   column_family_name to column_family_id map
48 
ColumnFamilyLogNumberMap(const std::map<uint32_t,uint64_t> &,const std::map<std::string,uint32_t> &)49   virtual void ColumnFamilyLogNumberMap(
50       const std::map<uint32_t, uint64_t>& /*cf_lognumber_map*/,
51       const std::map<std::string, uint32_t>& /*cf_name_id_map*/) {}
52 
53   // LogRecord is invoked for each log record encountered for all the logs
54   // during replay on logs on recovery. This method can be used to:
55   //  * inspect the record (using the batch parameter)
56   //  * ignoring current record
57   //    (by returning WalProcessingOption::kIgnoreCurrentRecord)
58   //  * reporting corrupted record
59   //    (by returning WalProcessingOption::kCorruptedRecord)
60   //  * stop log replay
61   //    (by returning kStop replay) - please note that this implies
62   //    discarding the logs from current record onwards.
63   //
64   // @params log_number     log_number of the current log.
65   //                        Filter might use this to determine if the log
66   //                        record is applicable to a certain column family.
67   // @params log_file_name  log file name - only for informational purposes
68   // @params batch          batch encountered in the log during recovery
69   // @params new_batch      new_batch to populate if filter wants to change
70   //                        the batch (for example to filter some records out,
71   //                        or alter some records).
72   //                        Please note that the new batch MUST NOT contain
73   //                        more records than original, else recovery would
74   //                        be failed.
75   // @params batch_changed  Whether batch was changed by the filter.
76   //                        It must be set to true if new_batch was populated,
77   //                        else new_batch has no effect.
78   // @returns               Processing option for the current record.
79   //                        Please see WalProcessingOption enum above for
80   //                        details.
LogRecordFound(unsigned long long,const std::string &,const WriteBatch & batch,WriteBatch * new_batch,bool * batch_changed)81   virtual WalProcessingOption LogRecordFound(
82       unsigned long long /*log_number*/, const std::string& /*log_file_name*/,
83       const WriteBatch& batch, WriteBatch* new_batch, bool* batch_changed) {
84     // Default implementation falls back to older function for compatibility
85     return LogRecord(batch, new_batch, batch_changed);
86   }
87 
88   // Please see the comments for LogRecord above. This function is for
89   // compatibility only and contains a subset of parameters.
90   // New code should use the function above.
LogRecord(const WriteBatch &,WriteBatch *,bool *)91   virtual WalProcessingOption LogRecord(const WriteBatch& /*batch*/,
92                                         WriteBatch* /*new_batch*/,
93                                         bool* /*batch_changed*/) const {
94     return WalProcessingOption::kContinueProcessing;
95   }
96 
97   // Returns a name that identifies this WAL filter.
98   // The name will be printed to LOG file on start up for diagnosis.
99   virtual const char* Name() const = 0;
100 };
101 
102 }  // namespace ROCKSDB_NAMESPACE
103