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

include/rocksdb/db.h

@@ -161,16 +161,37 @@ class DB {
   static Status Open(const Options& options, const std::string& name,
                      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
   // (though can often succeed if quickly closed) and the read-write
   // instance is unaffected. See also OpenAsSecondary.
+
+  // Open the database for read only.
   //
   // Not supported in ROCKSDB_LITE, in which case the function will
   // return Status::NotSupported.
@@ -178,17 +199,12 @@ class DB {
                                 DB** dbptr,
                                 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
   // return Status::NotSupported.
@@ -198,71 +214,71 @@ class DB {
       std::vector<ColumnFamilyHandle*>* handles, DB** dbptr,
       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.
+  // Options.max_open_files should be set to -1.
   // The name argument specifies the name of the primary db that you have used
   // to open the primary instance.
   // The secondary_path argument points to a directory where the secondary
   // instance stores its info log.
   // 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.
-  // Open DB as secondary instance with only the default column family.
+  //
   // Return OK on success, non-OK on failures.
   static Status OpenAsSecondary(const Options& options, const std::string& name,
                                 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
   // to open the primary instance.
   // The secondary_path argument points to a directory where the secondary
   // instance stores its info log.
   // 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
   // family handles.
   // The dbptr is an out-arg corresponding to the opened secondary instance.
   // 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 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(
       const DBOptions& db_options, const std::string& name,
       const std::string& secondary_path,
       const std::vector<ColumnFamilyDescriptor>& column_families,
       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.
   // 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
   // handles, the data of the column family is still accessible to the
   // secondary.
-  // TODO: we will support WAL tailing soon.
   virtual Status TryCatchUpWithPrimary() {
     return Status::NotSupported("Supported only by secondary instance");
   }