From 5876d694cbfda19cc4229fe4ca85b33d87fb81ea Mon Sep 17 00:00:00 2001 From: Xin Dong Date: Tue, 24 Mar 2020 13:26:59 -0700 Subject: [PATCH 1/7] Use snake case to be consistent with conventions --- bindings/python/fdb/impl.py | 14 +++++++------- bindings/ruby/lib/fdbimpl.rb | 6 +++--- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/bindings/python/fdb/impl.py b/bindings/python/fdb/impl.py index 974fcdce98..12114b0e83 100644 --- a/bindings/python/fdb/impl.py +++ b/bindings/python/fdb/impl.py @@ -450,15 +450,15 @@ class TransactionRead(_FDBBase): return self.get_range(key.start, key.stop, reverse=(key.step == -1)) return self.get(key) - def get_estimated_range_size_bytes(self, beginKey, endKey): - if beginKey is None: - beginKey = b'' - if endKey is None: - endKey = b'\xff' + def get_estimated_range_size_bytes(self, begin_key, end_key): + if begin_key is None: + begin_key = b'' + if end_key is None: + end_key = b'\xff' return FutureInt64(self.capi.fdb_transaction_get_estimated_range_size_bytes( self.tpointer, - beginKey, len(beginKey), - endKey, len(endKey) + begin_key, len(begin_key), + end_key, len(end_key) )) diff --git a/bindings/ruby/lib/fdbimpl.rb b/bindings/ruby/lib/fdbimpl.rb index e5e5266197..043cce23b6 100644 --- a/bindings/ruby/lib/fdbimpl.rb +++ b/bindings/ruby/lib/fdbimpl.rb @@ -819,9 +819,9 @@ module FDB get_range(prefix, FDB.strinc(prefix), options, &block) end - def get_estimated_range_size_bytes(beginKey, endKey) - bkey = FDB.key_to_bytes(beginKey) - ekey = FDB.key_to_bytes(endKey) + def get_estimated_range_size_bytes(begin_key, end_key) + bkey = FDB.key_to_bytes(begin_key) + ekey = FDB.key_to_bytes(end_key) Int64Future.new(FDBC.fdb_transaction_get_estimated_range_size_bytes(@tpointer, bkey, bkey.bytesize, ekey, ekey.bytesize)) end From 0fb728d0193fe06bb82e71fd927e9d76703f70fe Mon Sep 17 00:00:00 2001 From: Xin Dong Date: Tue, 24 Mar 2020 13:27:20 -0700 Subject: [PATCH 2/7] Updated API documentations for the new getEstimatedRangeBytes api --- documentation/sphinx/source/api-c.rst | 5 +++++ documentation/sphinx/source/api-python.rst | 7 +++++++ documentation/sphinx/source/api-ruby.rst | 7 +++++++ 3 files changed, 19 insertions(+) diff --git a/documentation/sphinx/source/api-c.rst b/documentation/sphinx/source/api-c.rst index d31c735112..33b318bbf7 100644 --- a/documentation/sphinx/source/api-c.rst +++ b/documentation/sphinx/source/api-c.rst @@ -474,6 +474,11 @@ Applications must provide error handling and an appropriate retry loop around th ``snapshot`` |snapshot| +.. function:: FDBFuture* fdb_transaction_get_estimated_range_size_bytes( FDBTransaction* tr, uint8_t const* begin_key_name, int begin_key_name_length, uint8_t const* end_key_name, int end_key_name_length) + Returns an estimated byte size of the key range. + + |future-return0| the estimated size of the key range given. |future-return1| call :func:`fdb_future_get_int64()` to extract the size, |future-return2| + .. function:: FDBFuture* fdb_transaction_get_key(FDBTransaction* transaction, uint8_t const* key_name, int key_name_length, fdb_bool_t or_equal, int offset, fdb_bool_t snapshot) Resolves a :ref:`key selector ` against the keys in the database snapshot represented by ``transaction``. diff --git a/documentation/sphinx/source/api-python.rst b/documentation/sphinx/source/api-python.rst index 2b5efe7d9c..c66c45f308 100644 --- a/documentation/sphinx/source/api-python.rst +++ b/documentation/sphinx/source/api-python.rst @@ -899,6 +899,13 @@ Transaction options .. _api-python-future: +Transaction misc functions +-------------------------- + +.. method:: Transaction.get_estimated_range_size_bytes(begin_key, end_key) + + Get the estimated byte size of the given key range. Returns a ::class::`FutureInt64`. + Future objects ============== diff --git a/documentation/sphinx/source/api-ruby.rst b/documentation/sphinx/source/api-ruby.rst index 46a1293b36..3279ca9866 100644 --- a/documentation/sphinx/source/api-ruby.rst +++ b/documentation/sphinx/source/api-ruby.rst @@ -837,6 +837,13 @@ Transaction options .. _transact: +Transaction misc functions +-------------------------- + +.. method:: Transaction.get_estimated_range_size_bytes(begin_key, end_key) + + Get the estimated byte size of the given key range. Returns a ::class::`Int64Future`. + The transact method =================== From 91037114e5cbb342bd027ca430418edda0b8c6c8 Mon Sep 17 00:00:00 2001 From: Xin Dong Date: Tue, 24 Mar 2020 13:35:07 -0700 Subject: [PATCH 3/7] Fix documentation build --- documentation/sphinx/source/api-python.rst | 2 +- documentation/sphinx/source/api-ruby.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/sphinx/source/api-python.rst b/documentation/sphinx/source/api-python.rst index c66c45f308..c8931c0234 100644 --- a/documentation/sphinx/source/api-python.rst +++ b/documentation/sphinx/source/api-python.rst @@ -904,7 +904,7 @@ Transaction misc functions .. method:: Transaction.get_estimated_range_size_bytes(begin_key, end_key) - Get the estimated byte size of the given key range. Returns a ::class::`FutureInt64`. + Get the estimated byte size of the given key range. Returns a :class:`FutureInt64`. Future objects ============== diff --git a/documentation/sphinx/source/api-ruby.rst b/documentation/sphinx/source/api-ruby.rst index 3279ca9866..7d45a6ef0b 100644 --- a/documentation/sphinx/source/api-ruby.rst +++ b/documentation/sphinx/source/api-ruby.rst @@ -842,7 +842,7 @@ Transaction misc functions .. method:: Transaction.get_estimated_range_size_bytes(begin_key, end_key) - Get the estimated byte size of the given key range. Returns a ::class::`Int64Future`. + Get the estimated byte size of the given key range. Returns a :class:`Int64Future`. The transact method =================== From 233a6bb2a79d294ffbf3d05c64f8cc7eee680d8d Mon Sep 17 00:00:00 2001 From: Xin Dong Date: Tue, 24 Mar 2020 16:31:46 -0700 Subject: [PATCH 4/7] Address review comments --- documentation/sphinx/source/api-python.rst | 18 +++++++++--------- documentation/sphinx/source/api-ruby.rst | 17 ++++++++++------- 2 files changed, 19 insertions(+), 16 deletions(-) diff --git a/documentation/sphinx/source/api-python.rst b/documentation/sphinx/source/api-python.rst index c8931c0234..fe1aee3b45 100644 --- a/documentation/sphinx/source/api-python.rst +++ b/documentation/sphinx/source/api-python.rst @@ -796,6 +796,13 @@ Most applications should use the read version that FoundationDB determines autom |infrequent| |transaction-get-versionstamp-blurb| +Transaction misc functions +-------------------------- + +.. method:: Transaction.get_estimated_range_size_bytes(begin_key, end_key) + + Get the estimated byte size of the given key range. Returns a :class:`FutureInt64`. + .. _api-python-transaction-options: Transaction options @@ -899,13 +906,6 @@ Transaction options .. _api-python-future: -Transaction misc functions --------------------------- - -.. method:: Transaction.get_estimated_range_size_bytes(begin_key, end_key) - - Get the estimated byte size of the given key range. Returns a :class:`FutureInt64`. - Future objects ============== @@ -969,9 +969,9 @@ Asynchronous methods return one of the following subclasses of :class:`Future`: Represents a future string object and responds to the same methods as string in Python. They may be passed to FoundationDB methods that expect a string. -.. class:: FutureVersion +.. class:: FutureInt64 - Represents a future version (integer). You must call the :meth:`Future.wait()` method on this object to retrieve the version as an integer. + Represents a future integer. You must call the :meth:`Future.wait()` method on this object to retrieve the integer. .. class:: FutureStringArray diff --git a/documentation/sphinx/source/api-ruby.rst b/documentation/sphinx/source/api-ruby.rst index 7d45a6ef0b..4385017729 100644 --- a/documentation/sphinx/source/api-ruby.rst +++ b/documentation/sphinx/source/api-ruby.rst @@ -740,6 +740,13 @@ Most applications should use the read version that FoundationDB determines autom |infrequent| |transaction-get-versionstamp-blurb| +Transaction misc functions +-------------------------- + +.. method:: Transaction.get_estimated_range_size_bytes(begin_key, end_key) + + Get the estimated byte size of the given key range. Returns a :class:`Int64Future`. + Transaction options ------------------- @@ -837,13 +844,6 @@ Transaction options .. _transact: -Transaction misc functions --------------------------- - -.. method:: Transaction.get_estimated_range_size_bytes(begin_key, end_key) - - Get the estimated byte size of the given key range. Returns a :class:`Int64Future`. - The transact method =================== @@ -969,6 +969,9 @@ Asynchronous methods return one of the following subclasses of :class:`Future`: For a :class:`FutureNil` object returned by :meth:`Transaction.commit` or :meth:`Transaction.on_error`, you must call :meth:`FutureNil.wait`, which will return ``nil`` if the operation succeeds or raise an :exc:`FDB::Error` if an error occurred. Failure to call :meth:`FutureNil.wait` on a returned :class:`FutureNil` object means that any potential errors raised by the asynchronous operation that returned the object *will not be seen*, and represents a significant error in your code. +.. class:: Int64Future + This type is a future integer. + .. _ruby streaming mode: Streaming modes From 1501a365fb12c52d4d5c0930c78cd9a053c9fe72 Mon Sep 17 00:00:00 2001 From: Xin Dong Date: Wed, 25 Mar 2020 09:33:19 -0700 Subject: [PATCH 5/7] Address review comments --- documentation/sphinx/source/api-ruby.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/documentation/sphinx/source/api-ruby.rst b/documentation/sphinx/source/api-ruby.rst index 4385017729..2e6e014fc9 100644 --- a/documentation/sphinx/source/api-ruby.rst +++ b/documentation/sphinx/source/api-ruby.rst @@ -953,7 +953,7 @@ Asynchronous methods return one of the following subclasses of :class:`Future`: An implementation quirk of :class:`Value` is that it will never evaluate to ``false``, even if its value is ``nil``. It is important to use ``if value.nil?`` rather than ``if ~value`` when checking to see if a key was not present in the database. -.. class:: Version +.. class:: Int64Future This type is a future :class:`Integer` object. Objects of this type respond to the same methods as objects of type :class:`Integer`, and may be passed to any method that expects a :class:`Integer`. @@ -969,8 +969,6 @@ Asynchronous methods return one of the following subclasses of :class:`Future`: For a :class:`FutureNil` object returned by :meth:`Transaction.commit` or :meth:`Transaction.on_error`, you must call :meth:`FutureNil.wait`, which will return ``nil`` if the operation succeeds or raise an :exc:`FDB::Error` if an error occurred. Failure to call :meth:`FutureNil.wait` on a returned :class:`FutureNil` object means that any potential errors raised by the asynchronous operation that returned the object *will not be seen*, and represents a significant error in your code. -.. class:: Int64Future - This type is a future integer. .. _ruby streaming mode: From 30f3753699702b18aeb387ff3981147e96bf526d Mon Sep 17 00:00:00 2001 From: Xin Dong Date: Wed, 25 Mar 2020 09:41:47 -0700 Subject: [PATCH 6/7] Replace the Version to Int64Future --- documentation/sphinx/source/api-ruby.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/sphinx/source/api-ruby.rst b/documentation/sphinx/source/api-ruby.rst index 2e6e014fc9..cb48faf20e 100644 --- a/documentation/sphinx/source/api-ruby.rst +++ b/documentation/sphinx/source/api-ruby.rst @@ -519,7 +519,7 @@ Snapshot reads Like :meth:`Transaction.get_range_start_with`, but as a snapshot read. -.. method:: Transaction.snapshot.get_read_version() -> Version +.. method:: Transaction.snapshot.get_read_version() -> Int64Future Identical to :meth:`Transaction.get_read_version` (since snapshot and strictly serializable reads use the same read version). @@ -728,7 +728,7 @@ Most applications should use the read version that FoundationDB determines autom |infrequent| Sets the database version that the transaction will read from the database. The database cannot guarantee causal consistency if this method is used (the transaction's reads will be causally consistent only if the provided read version has that property). -.. method:: Transaction.get_read_version() -> Version +.. method:: Transaction.get_read_version() -> Int64Future |infrequent| Returns the transaction's read version. From 353fcb20965f938040185ea1bbe393c57f805e24 Mon Sep 17 00:00:00 2001 From: Xin Dong Date: Wed, 25 Mar 2020 10:02:38 -0700 Subject: [PATCH 7/7] Update Go binding documentations for the new API to be consistent with others --- bindings/go/src/fdb/transaction.go | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/bindings/go/src/fdb/transaction.go b/bindings/go/src/fdb/transaction.go index 069564bc7f..0c6240a7ef 100644 --- a/bindings/go/src/fdb/transaction.go +++ b/bindings/go/src/fdb/transaction.go @@ -318,8 +318,8 @@ func (t *transaction) getEstimatedRangeSizeBytes(beginKey Key, endKey Key) Futur } } -// GetEstimatedRangeSizeBytes will get the byte size of the key range based on the -// byte sample collected by FDB +// GetEstimatedRangeSizeBytes will get an estimate for the number of bytes +// stored in the given range. func (t Transaction) GetEstimatedRangeSizeBytes(r ExactRange) FutureInt64 { beginKey, endKey := r.FDBRangeKeys() return t.getEstimatedRangeSizeBytes(