Update/Fix API comments for OpenForReadOnly() and OpenAsSecondary() (#9807)

Summary:
Updates/fixes to API comments for OpenForReadOnly() and OpenAsSecondary()

Pull Request resolved: https://github.com/facebook/rocksdb/pull/9807

Reviewed By: ajkr

Differential Revision: D35419206

Pulled By: ramvadiv

fbshipit-source-id: ac2514a14e4ec77b2ed34c5dca6251528c5b92f1
main
Ramkumar Vadivelu 3 years ago committed by Facebook GitHub Bot
parent 3ae9c5309b
commit 633b7f15d5
  1. 121
      include/rocksdb/db.h

@ -161,16 +161,37 @@ class DB {
static Status Open(const Options& options, const std::string& name, static Status Open(const Options& options, const std::string& name,
DB** dbptr); DB** dbptr);
// Open the database for read only. All DB interfaces // Open DB with column families.
// that modify data, like put/delete, will return error. // db_options specify database specific options
// If the db is opened in read only mode, then no compactions // column_families is the vector of all column families in the database,
// will happen. // containing column family name and options. You need to open ALL column
// families in the database. To get the list of column families, you can use
// ListColumnFamilies().
// //
// While a given DB can be simultaneously open via OpenForReadOnly // The default column family name is 'default' and it's stored
// by any number of readers, if a DB is simultaneously open by Open // in ROCKSDB_NAMESPACE::kDefaultColumnFamilyName.
// If everything is OK, handles will on return be the same size
// as column_families --- handles[i] will be a handle that you
// will use to operate on column family column_family[i].
// Before delete DB, you have to close All column families by calling
// DestroyColumnFamilyHandle() with all the handles.
static Status Open(const DBOptions& db_options, const std::string& name,
const std::vector<ColumnFamilyDescriptor>& column_families,
std::vector<ColumnFamilyHandle*>* handles, DB** dbptr);
// OpenForReadOnly() creates a Read-only instance that supports reads alone.
//
// All DB interfaces that modify data, like put/delete, will return error.
// Automatic Flush and Compactions are disabled and any manual calls
// to Flush/Compaction will return error.
//
// While a given DB can be simultaneously opened via OpenForReadOnly
// by any number of readers, if a DB is simultaneously opened by Open
// and OpenForReadOnly, the read-only instance has undefined behavior // and OpenForReadOnly, the read-only instance has undefined behavior
// (though can often succeed if quickly closed) and the read-write // (though can often succeed if quickly closed) and the read-write
// instance is unaffected. See also OpenAsSecondary. // instance is unaffected. See also OpenAsSecondary.
// Open the database for read only.
// //
// Not supported in ROCKSDB_LITE, in which case the function will // Not supported in ROCKSDB_LITE, in which case the function will
// return Status::NotSupported. // return Status::NotSupported.
@ -178,17 +199,12 @@ class DB {
DB** dbptr, DB** dbptr,
bool error_if_wal_file_exists = false); bool error_if_wal_file_exists = false);
// Open the database for read only with column families. When opening DB with // Open the database for read only with column families.
// read only, you can specify only a subset of column families in the
// database that should be opened. However, you always need to specify default
// column family. The default column family name is 'default' and it's stored
// in ROCKSDB_NAMESPACE::kDefaultColumnFamilyName
// //
// While a given DB can be simultaneously open via OpenForReadOnly // When opening DB with read only, you can specify only a subset of column
// by any number of readers, if a DB is simultaneously open by Open // families in the database that should be opened. However, you always need
// and OpenForReadOnly, the read-only instance has undefined behavior // to specify default column family. The default column family name is
// (though can often succeed if quickly closed) and the read-write // 'default' and it's stored in ROCKSDB_NAMESPACE::kDefaultColumnFamilyName
// instance is unaffected. See also OpenAsSecondary.
// //
// Not supported in ROCKSDB_LITE, in which case the function will // Not supported in ROCKSDB_LITE, in which case the function will
// return Status::NotSupported. // return Status::NotSupported.
@ -198,71 +214,71 @@ class DB {
std::vector<ColumnFamilyHandle*>* handles, DB** dbptr, std::vector<ColumnFamilyHandle*>* handles, DB** dbptr,
bool error_if_wal_file_exists = false); bool error_if_wal_file_exists = false);
// The following OpenAsSecondary functions create a secondary instance that // OpenAsSecondary() creates a secondary instance that supports read-only
// can dynamically tail the MANIFEST of a primary that must have already been // operations and supports dynamic catch up with the primary (through a
// created. User can call TryCatchUpWithPrimary to make the secondary // call to TryCatchUpWithPrimary()).
// instance catch up with primary (WAL tailing is NOT supported now) whenever //
// the user feels necessary. Column families created by the primary after the // All DB interfaces that modify data, like put/delete, will return error.
// secondary instance starts are currently ignored by the secondary instance. // Automatic Flush and Compactions are disabled and any manual calls
// Column families opened by secondary and dropped by the primary will be // to Flush/Compaction will return error.
// dropped by secondary as well. However the user of the secondary instance //
// can still access the data of such dropped column family as long as they // Multiple secondary instances can co-exist at the same time.
// do not destroy the corresponding column family handle. //
// WAL tailing is not supported at present, but will arrive soon.
// Open DB as secondary instance
// //
// The options argument specifies the options to open the secondary instance. // The options argument specifies the options to open the secondary instance.
// Options.max_open_files should be set to -1.
// The name argument specifies the name of the primary db that you have used // The name argument specifies the name of the primary db that you have used
// to open the primary instance. // to open the primary instance.
// The secondary_path argument points to a directory where the secondary // The secondary_path argument points to a directory where the secondary
// instance stores its info log. // instance stores its info log.
// The dbptr is an out-arg corresponding to the opened secondary instance. // The dbptr is an out-arg corresponding to the opened secondary instance.
// The pointer points to a heap-allocated database, and the user should // The pointer points to a heap-allocated database, and the caller should
// delete it after use. // delete it after use.
// Open DB as secondary instance with only the default column family. //
// Return OK on success, non-OK on failures. // Return OK on success, non-OK on failures.
static Status OpenAsSecondary(const Options& options, const std::string& name, static Status OpenAsSecondary(const Options& options, const std::string& name,
const std::string& secondary_path, DB** dbptr); const std::string& secondary_path, DB** dbptr);
// Open DB as secondary instance with column families. You can open a subset // Open DB as secondary instance with specified column families
// of column families in secondary mode. //
// The db_options specify the database specific options. // When opening DB in secondary mode, you can specify only a subset of column
// families in the database that should be opened. However, you always need
// to specify default column family. The default column family name is
// 'default' and it's stored in ROCKSDB_NAMESPACE::kDefaultColumnFamilyName
//
// Column families created by the primary after the secondary instance starts
// are currently ignored by the secondary instance. Column families opened
// by secondary and dropped by the primary will be dropped by secondary as
// well (on next invocation of TryCatchUpWithPrimary()). However the user
// of the secondary instance can still access the data of such dropped column
// family as long as they do not destroy the corresponding column family
// handle.
//
// The options argument specifies the options to open the secondary instance.
// Options.max_open_files should be set to -1.
// The name argument specifies the name of the primary db that you have used // The name argument specifies the name of the primary db that you have used
// to open the primary instance. // to open the primary instance.
// The secondary_path argument points to a directory where the secondary // The secondary_path argument points to a directory where the secondary
// instance stores its info log. // instance stores its info log.
// The column_families argument specifies a list of column families to open. // The column_families argument specifies a list of column families to open.
// If any of the column families does not exist, the function returns non-OK // If default column family is not specified or if any specified column
// status. // families does not exist, the function returns non-OK status.
// The handles is an out-arg corresponding to the opened database column // The handles is an out-arg corresponding to the opened database column
// family handles. // family handles.
// The dbptr is an out-arg corresponding to the opened secondary instance. // The dbptr is an out-arg corresponding to the opened secondary instance.
// The pointer points to a heap-allocated database, and the caller should // The pointer points to a heap-allocated database, and the caller should
// delete it after use. Before deleting the dbptr, the user should also // delete it after use. Before deleting the dbptr, the user should also
// delete the pointers stored in handles vector. // delete the pointers stored in handles vector.
// Return OK on success, on-OK on failures. //
// Return OK on success, non-OK on failures.
static Status OpenAsSecondary( static Status OpenAsSecondary(
const DBOptions& db_options, const std::string& name, const DBOptions& db_options, const std::string& name,
const std::string& secondary_path, const std::string& secondary_path,
const std::vector<ColumnFamilyDescriptor>& column_families, const std::vector<ColumnFamilyDescriptor>& column_families,
std::vector<ColumnFamilyHandle*>* handles, DB** dbptr); std::vector<ColumnFamilyHandle*>* handles, DB** dbptr);
// Open DB with column families.
// db_options specify database specific options
// column_families is the vector of all column families in the database,
// containing column family name and options. You need to open ALL column
// families in the database. To get the list of column families, you can use
// ListColumnFamilies(). Also, you can open only a subset of column families
// for read-only access.
// The default column family name is 'default' and it's stored
// in ROCKSDB_NAMESPACE::kDefaultColumnFamilyName.
// If everything is OK, handles will on return be the same size
// as column_families --- handles[i] will be a handle that you
// will use to operate on column family column_family[i].
// Before delete DB, you have to close All column families by calling
// DestroyColumnFamilyHandle() with all the handles.
static Status Open(const DBOptions& db_options, const std::string& name,
const std::vector<ColumnFamilyDescriptor>& column_families,
std::vector<ColumnFamilyHandle*>* handles, DB** dbptr);
// Open DB and run the compaction. // Open DB and run the compaction.
// It's a read-only operation, the result won't be installed to the DB, it // It's a read-only operation, the result won't be installed to the DB, it
@ -1701,7 +1717,6 @@ class DB {
// secondary instance does not delete the corresponding column family // secondary instance does not delete the corresponding column family
// handles, the data of the column family is still accessible to the // handles, the data of the column family is still accessible to the
// secondary. // secondary.
// TODO: we will support WAL tailing soon.
virtual Status TryCatchUpWithPrimary() { virtual Status TryCatchUpWithPrimary() {
return Status::NotSupported("Supported only by secondary instance"); return Status::NotSupported("Supported only by secondary instance");
} }

Loading…
Cancel
Save