From 87c8bb4bef1f173411e0a54f67620ab5b4c1cddf Mon Sep 17 00:00:00 2001 From: Levi Tamasi Date: Wed, 14 Sep 2022 14:33:05 -0700 Subject: [PATCH] Add comments describing {Put,Get}Entity, update/clarify comment for Get and iterator (#10676) Summary: Pull Request resolved: https://github.com/facebook/rocksdb/pull/10676 Reviewed By: riversand963 Differential Revision: D39512081 Pulled By: ltamasi fbshipit-source-id: 55704478ceb8081003eceeb0c5a3875cb806587e --- include/rocksdb/db.h | 29 +++++++++++++++++++++-------- include/rocksdb/iterator.h | 20 ++++++++++++-------- include/rocksdb/write_batch.h | 3 ++- include/rocksdb/write_batch_base.h | 3 ++- 4 files changed, 37 insertions(+), 18 deletions(-) diff --git a/include/rocksdb/db.h b/include/rocksdb/db.h index 1e7c19044..9359a45ba 100644 --- a/include/rocksdb/db.h +++ b/include/rocksdb/db.h @@ -407,7 +407,11 @@ class DB { return Put(options, DefaultColumnFamily(), key, ts, value); } - // UNDER CONSTRUCTION -- DO NOT USE + // Set the database entry for "key" in the column family specified by + // "column_family" to the wide-column entity defined by "columns". If the key + // already exists in the column family, it will be overwritten. + // + // Returns OK on success, and a non-OK status on error. virtual Status PutEntity(const WriteOptions& options, ColumnFamilyHandle* column_family, const Slice& key, const WideColumns& columns); @@ -511,16 +515,17 @@ class DB { // Note: consider setting options.sync = true. virtual Status Write(const WriteOptions& options, WriteBatch* updates) = 0; - // If the database contains an entry for "key" store the - // corresponding value in *value and return OK. + // If the column family specified by "column_family" contains an entry for + // "key", return the corresponding value in "*value". If the entry is a plain + // key-value, return the value as-is; if it is a wide-column entity, return + // the value of its default anonymous column (see kDefaultWideColumnName) if + // any, or an empty value otherwise. // // If timestamp is enabled and a non-null timestamp pointer is passed in, // timestamp is returned. // - // If there is no entry for "key" leave *value unchanged and return - // a status for which Status::IsNotFound() returns true. - // - // May return some other Status on an error. + // Returns OK on success. Returns NotFound and an empty value in "*value" if + // there is no entry for "key". Returns some other non-OK status on error. virtual inline Status Get(const ReadOptions& options, ColumnFamilyHandle* column_family, const Slice& key, std::string* value) { @@ -567,7 +572,15 @@ class DB { return Get(options, DefaultColumnFamily(), key, value, timestamp); } - // UNDER CONSTRUCTION -- DO NOT USE + // If the column family specified by "column_family" contains an entry for + // "key", return it as a wide-column entity in "*columns". If the entry is a + // wide-column entity, return it as-is; if it is a plain key-value, return it + // as an entity with a single anonymous column (see kDefaultWideColumnName) + // which contains the value. + // + // Returns OK on success. Returns NotFound and an empty wide-column entity in + // "*columns" if there is no entry for "key". Returns some other non-OK status + // on error. virtual Status GetEntity(const ReadOptions& /* options */, ColumnFamilyHandle* /* column_family */, const Slice& /* key */, diff --git a/include/rocksdb/iterator.h b/include/rocksdb/iterator.h index 269015c09..9d4c9f73a 100644 --- a/include/rocksdb/iterator.h +++ b/include/rocksdb/iterator.h @@ -81,17 +81,21 @@ class Iterator : public Cleanable { // REQUIRES: Valid() virtual Slice key() const = 0; - // Return the value for the current entry. The underlying storage for - // the returned slice is valid only until the next modification of the - // iterator (i.e. the next SeekToFirst/SeekToLast/Seek/SeekForPrev/Next/Prev - // operation). + // Return the value for the current entry. If the entry is a plain key-value, + // return the value as-is; if it is a wide-column entity, return the value of + // the default anonymous column (see kDefaultWideColumnName) if any, or an + // empty value otherwise. The underlying storage for the returned slice is + // valid only until the next modification of the iterator (i.e. the next + // SeekToFirst/SeekToLast/Seek/SeekForPrev/Next/Prev operation). // REQUIRES: Valid() virtual Slice value() const = 0; - // Return the wide columns for the current entry. The underlying storage for - // the returned structure is valid only until the next modification of the - // iterator (i.e. the next SeekToFirst/SeekToLast/Seek/SeekForPrev/Next/Prev - // operation). + // Return the wide columns for the current entry. If the entry is a + // wide-column entity, return it as-is; if it is a plain key-value, return it + // as an entity with a single anonymous column (see kDefaultWideColumnName) + // which contains the value. The underlying storage for the returned + // structure is valid only until the next modification of the iterator (i.e. + // the next SeekToFirst/SeekToLast/Seek/SeekForPrev/Next/Prev operation). // REQUIRES: Valid() virtual const WideColumns& columns() const { assert(false); diff --git a/include/rocksdb/write_batch.h b/include/rocksdb/write_batch.h index cbec33a65..dd516eabd 100644 --- a/include/rocksdb/write_batch.h +++ b/include/rocksdb/write_batch.h @@ -100,7 +100,8 @@ class WriteBatch : public WriteBatchBase { return Put(nullptr, key, value); } - // UNDER CONSTRUCTION -- DO NOT USE + // Store the mapping "key->{column1:value1, column2:value2, ...}" in the + // column family specified by "column_family". using WriteBatchBase::PutEntity; Status PutEntity(ColumnFamilyHandle* column_family, const Slice& key, const WideColumns& columns) override; diff --git a/include/rocksdb/write_batch_base.h b/include/rocksdb/write_batch_base.h index 33dae4f08..f6f39ef0b 100644 --- a/include/rocksdb/write_batch_base.h +++ b/include/rocksdb/write_batch_base.h @@ -42,7 +42,8 @@ class WriteBatchBase { const SliceParts& value); virtual Status Put(const SliceParts& key, const SliceParts& value); - // UNDER CONSTRUCTION -- DO NOT USE + // Store the mapping "key->{column1:value1, column2:value2, ...}" in the + // column family specified by "column_family". virtual Status PutEntity(ColumnFamilyHandle* column_family, const Slice& key, const WideColumns& columns) = 0;