From d95014b9dfb344fb1cd82cb55e5db94f66cdbc3a Mon Sep 17 00:00:00 2001 From: Yanqin Jin Date: Tue, 10 Apr 2018 15:47:54 -0700 Subject: [PATCH] fix some text in comments. Summary: 1. Remove redundant text. 2. Make terminology consistent across all comments and doc of RocksDB. Also do our best to conform to conventions. Specifically, use 'callback' instead of 'call-back' [wikipedia](https://en.wikipedia.org/wiki/Callback_(computer_programming)). Closes https://github.com/facebook/rocksdb/pull/3693 Differential Revision: D7560396 Pulled By: riversand963 fbshipit-source-id: ba8c251c487f4e7d1872a1a8dc680f9e35a6ffb8 --- db/db_impl_compaction_flush.cc | 3 +-- db/listener_test.cc | 4 +-- include/rocksdb/listener.h | 39 ++++++++++++----------------- include/rocksdb/options.h | 4 +-- options/cf_options.h | 2 +- third-party/fbson/FbsonDocument.h | 2 +- third-party/fbson/FbsonJsonParser.h | 2 +- 7 files changed, 24 insertions(+), 32 deletions(-) diff --git a/db/db_impl_compaction_flush.cc b/db/db_impl_compaction_flush.cc index 421f6f72d..954c52a8c 100644 --- a/db/db_impl_compaction_flush.cc +++ b/db/db_impl_compaction_flush.cc @@ -2073,8 +2073,7 @@ bool DBImpl::MCOverlap(ManualCompactionState* m, ManualCompactionState* m1) { } // SuperVersionContext gets created and destructed outside of the lock -- -// we -// use this convinently to: +// we use this conveniently to: // * malloc one SuperVersion() outside of the lock -- new_superversion // * delete SuperVersion()s outside of the lock -- superversions_to_free // diff --git a/db/listener_test.cc b/db/listener_test.cc index 204c9216e..afb046f49 100644 --- a/db/listener_test.cc +++ b/db/listener_test.cc @@ -260,7 +260,7 @@ TEST_F(EventListenerTest, OnSingleDBFlushTest) { ASSERT_EQ(listener->flushed_column_family_names_.size(), i); } - // make sure call-back functions are called in the right order + // make sure callback functions are called in the right order for (size_t i = 0; i < cf_names.size(); ++i) { ASSERT_EQ(listener->flushed_dbs_[i], db_); ASSERT_EQ(listener->flushed_column_family_names_[i], cf_names[i]); @@ -296,7 +296,7 @@ TEST_F(EventListenerTest, MultiCF) { ASSERT_EQ(listener->flushed_column_family_names_.size(), i); } - // make sure call-back functions are called in the right order + // make sure callback functions are called in the right order for (size_t i = 0; i < cf_names.size(); i++) { ASSERT_EQ(listener->flushed_dbs_[i], db_); ASSERT_EQ(listener->flushed_column_family_names_[i], cf_names[i]); diff --git a/include/rocksdb/listener.h b/include/rocksdb/listener.h index 62f15d520..59bada079 100644 --- a/include/rocksdb/listener.h +++ b/include/rocksdb/listener.h @@ -230,12 +230,12 @@ struct ExternalFileIngestionInfo { TableProperties table_properties; }; -// EventListener class contains a set of call-back functions that will +// EventListener class contains a set of callback functions that will // be called when specific RocksDB event happens such as flush. It can // be used as a building block for developing custom features such as // stats-collector or external compaction algorithm. // -// Note that call-back functions should not run for an extended period of +// Note that callback functions should not run for an extended period of // time before the function returns, otherwise RocksDB may be blocked. // For example, it is not suggested to do DB::CompactFiles() (as it may // run for a long while) or issue many of DB::Put() (as Put may be blocked @@ -251,17 +251,10 @@ struct ExternalFileIngestionInfo { // [Locking] All EventListener callbacks are designed to be called without // the current thread holding any DB mutex. This is to prevent potential // deadlock and performance issue when using EventListener callback -// in a complex way. However, all EventListener call-back functions -// should not run for an extended period of time before the function -// returns, otherwise RocksDB may be blocked. For example, it is not -// suggested to do DB::CompactFiles() (as it may run for a long while) -// or issue many of DB::Put() (as Put may be blocked in certain cases) -// in the same thread in the EventListener callback. However, doing -// DB::CompactFiles() and DB::Put() in a thread other than the -// EventListener callback thread is considered safe. +// in a complex way. class EventListener { public: - // A call-back function to RocksDB which will be called whenever a + // A callback function to RocksDB which will be called whenever a // registered RocksDB flushes a file. The default implementation is // no-op. // @@ -271,7 +264,7 @@ class EventListener { virtual void OnFlushCompleted(DB* /*db*/, const FlushJobInfo& /*flush_job_info*/) {} - // A call-back function to RocksDB which will be called before a + // A callback function to RocksDB which will be called before a // RocksDB starts to flush memtables. The default implementation is // no-op. // @@ -281,9 +274,9 @@ class EventListener { virtual void OnFlushBegin(DB* /*db*/, const FlushJobInfo& /*flush_job_info*/) {} - // A call-back function for RocksDB which will be called whenever + // A callback function for RocksDB which will be called whenever // a SST file is deleted. Different from OnCompactionCompleted and - // OnFlushCompleted, this call-back is designed for external logging + // OnFlushCompleted, this callback is designed for external logging // service and thus only provide string parameters instead // of a pointer to DB. Applications that build logic basic based // on file creations and deletions is suggested to implement @@ -294,7 +287,7 @@ class EventListener { // returned value. virtual void OnTableFileDeleted(const TableFileDeletionInfo& /*info*/) {} - // A call-back function for RocksDB which will be called whenever + // A callback function for RocksDB which will be called whenever // a registered RocksDB compacts a file. The default implementation // is a no-op. // @@ -310,9 +303,9 @@ class EventListener { virtual void OnCompactionCompleted(DB* /*db*/, const CompactionJobInfo& /*ci*/) {} - // A call-back function for RocksDB which will be called whenever + // A callback function for RocksDB which will be called whenever // a SST file is created. Different from OnCompactionCompleted and - // OnFlushCompleted, this call-back is designed for external logging + // OnFlushCompleted, this callback is designed for external logging // service and thus only provide string parameters instead // of a pointer to DB. Applications that build logic basic based // on file creations and deletions is suggested to implement @@ -327,7 +320,7 @@ class EventListener { // returned value. virtual void OnTableFileCreated(const TableFileCreationInfo& /*info*/) {} - // A call-back function for RocksDB which will be called before + // A callback function for RocksDB which will be called before // a SST file is being created. It will follow by OnTableFileCreated after // the creation finishes. // @@ -337,7 +330,7 @@ class EventListener { virtual void OnTableFileCreationStarted( const TableFileCreationBriefInfo& /*info*/) {} - // A call-back function for RocksDB which will be called before + // A callback function for RocksDB which will be called before // a memtable is made immutable. // // Note that the this function must be implemented in a way such that @@ -350,7 +343,7 @@ class EventListener { virtual void OnMemTableSealed( const MemTableInfo& /*info*/) {} - // A call-back function for RocksDB which will be called before + // A callback function for RocksDB which will be called before // a column family handle is deleted. // // Note that the this function must be implemented in a way such that @@ -361,7 +354,7 @@ class EventListener { virtual void OnColumnFamilyHandleDeletionStarted( ColumnFamilyHandle* /*handle*/) {} - // A call-back function for RocksDB which will be called after an external + // A callback function for RocksDB which will be called after an external // file is ingested using IngestExternalFile. // // Note that the this function will run on the same thread as @@ -370,7 +363,7 @@ class EventListener { virtual void OnExternalFileIngested( DB* /*db*/, const ExternalFileIngestionInfo& /*info*/) {} - // A call-back function for RocksDB which will be called before setting the + // A callback function for RocksDB which will be called before setting the // background error status to a non-OK value. The new background error status // is provided in `bg_error` and can be modified by the callback. E.g., a // callback can suppress errors by resetting it to Status::OK(), thus @@ -384,7 +377,7 @@ class EventListener { virtual void OnBackgroundError(BackgroundErrorReason /* reason */, Status* /* bg_error */) {} - // A call-back function for RocksDB which will be called whenever a change + // A callback function for RocksDB which will be called whenever a change // of superversion triggers a change of the stall conditions. // // Note that the this function must be implemented in a way such that diff --git a/include/rocksdb/options.h b/include/rocksdb/options.h index 0e1ecb9de..5b7cc0cc9 100644 --- a/include/rocksdb/options.h +++ b/include/rocksdb/options.h @@ -423,7 +423,7 @@ struct DBOptions { // By default, writes to stable storage use fdatasync (on platforms // where this function is available). If this option is true, - // fsync is used instead. + // fsync is used instead. // // fsync and fdatasync are equally safe for our purposes and fdatasync is // faster, so it is rarely necessary to set this option. It is provided @@ -753,7 +753,7 @@ struct DBOptions { // Default: 0, turned off uint64_t wal_bytes_per_sync = 0; - // A vector of EventListeners which call-back functions will be called + // A vector of EventListeners which callback functions will be called // when specific RocksDB event happens. std::vector> listeners; diff --git a/options/cf_options.h b/options/cf_options.h index 9cc8ff704..2ab6b56bd 100644 --- a/options/cf_options.h +++ b/options/cf_options.h @@ -109,7 +109,7 @@ struct ImmutableCFOptions { bool preserve_deletes; - // A vector of EventListeners which call-back functions will be called + // A vector of EventListeners which callback functions will be called // when specific RocksDB event happens. std::vector> listeners; diff --git a/third-party/fbson/FbsonDocument.h b/third-party/fbson/FbsonDocument.h index fc7ca76ff..11b6fe28e 100644 --- a/third-party/fbson/FbsonDocument.h +++ b/third-party/fbson/FbsonDocument.h @@ -48,7 +48,7 @@ * and use index to retrieve from array. Array index is 0-based. * * ** External dictionary ** - * During query processing, you can also pass a call-back function, so the + * During query processing, you can also pass a callback function, so the * search will first try to check if the key string exists in the dictionary. * If so, search will be based on the id instead of the key string. * diff --git a/third-party/fbson/FbsonJsonParser.h b/third-party/fbson/FbsonJsonParser.h index 63b03e2b9..2c936d675 100644 --- a/third-party/fbson/FbsonJsonParser.h +++ b/third-party/fbson/FbsonJsonParser.h @@ -31,7 +31,7 @@ * FbsonErrType, and can be retrieved by calling getErrorCode(). * * ** External dictionary ** - * During parsing a JSON string, you can pass a call-back function to map a key + * During parsing a JSON string, you can pass a callback function to map a key * string to an id, and store the dictionary id in FBSON to save space. The * purpose of using an external dictionary is more towards a collection of * documents (which has common keys) rather than a single document, so that