lbry-rocksdb/docs/api/interfaces.rst

Interfaces
**********

Comparator
==========

.. py:class:: rocksdb.interfaces.Comparator

    A Comparator object provides a total order across slices that are
    used as keys in an sstable or a database.  A Comparator implementation
    must be thread-safe since rocksdb may invoke its methods concurrently
    from multiple threads.

    .. py:method:: compare(a, b)

        Three-way comparison.

        :param bytes a: First field to compare
        :param bytes b: Second field to compare
        :returns: * -1 if a < b
                  * 0 if a == b
                  * 1 if a > b
        :rtype: ``int``

    .. py:method:: name()

        The name of the comparator.  Used to check for comparator
        mismatches (i.e., a DB created with one comparator is
        accessed using a different comparator).

        The client of this package should switch to a new name whenever
        the comparator implementation changes in a way that will cause
        the relative ordering of any two keys to change.

        Names starting with "rocksdb." are reserved and should not be used
        by any clients of this package.

        :rtype: ``bytes``

Merge Operator
==============

    Essentially, a MergeOperator specifies the SEMANTICS of a merge, which only
    client knows. It could be numeric addition, list append, string
    concatenation, edit data structure, whatever.
    The library, on the other hand, is concerned with the exercise of this
    interface, at the right time (during get, iteration, compaction...)

    To use merge, the client needs to provide an object implementing one of
    the following interfaces:

    * AssociativeMergeOperator - for most simple semantics (always take
      two values, and merge them into one value, which is then put back
      into rocksdb).
      numeric addition and string concatenation are examples.

    * MergeOperator - the generic class for all the more complex operations.
      One method (FullMerge) to merge a Put/Delete value with a merge operand.
      Another method (PartialMerge) that merges two operands together.
      This is especially useful if your key values have a complex structure but
      you would still like to support client-specific incremental updates.

    AssociativeMergeOperator is simpler to implement.
    MergeOperator is simply more powerful.

    See this page for more details
    https://github.com/facebook/rocksdb/wiki/Merge-Operator

AssociativeMergeOperator
------------------------

.. py:class:: rocksdb.interfaces.AssociativeMergeOperator

    .. py:method:: merge(key, existing_value, value)

        Gives the client a way to express the read -> modify -> write semantics

        :param bytes key: The key that's associated with this merge operation
        :param bytes existing_value: The current value in the db.
                                      ``None`` indicates the key does not exist
                                      before this op
        :param bytes value: The value to update/merge the existing_value with

        :returns: ``True`` and the new value on success.
                  All values passed in will be client-specific values.
                  So if this method returns false, it is because client
                  specified bad data or there was internal corruption.
                  The client should assume that this will be treated as an
                  error by the library.

        :rtype: ``(bool, bytes)``

    .. py:method:: name()

        The name of the MergeOperator. Used to check for MergeOperator mismatches.
        For example a DB created with one MergeOperator is accessed using a
        different MergeOperator.

        :rtype: ``bytes``

MergeOperator
-------------

.. py:class:: rocksdb.interfaces.MergeOperator

    .. py:method:: full_merge(key, existing_value, operand_list)

        Gives the client a way to express the read -> modify -> write semantics

        :param bytes key: The key that's associated with this merge operation.
                           Client could multiplex the merge operator based on it
                           if the key space is partitioned and different subspaces
                           refer to different types of data which have different
                           merge operation semantics

        :param bytes existing_value: The current value in the db.
                                     ``None`` indicates the key does not exist
                                     before this op

        :param operand_list: The sequence of merge operations to apply.
        :type operand_list: list of bytes 

        :returns: ``True`` and the new value on success.
                  All values passed in will be client-specific values.
                  So if this method returns false, it is because client
                  specified bad data or there was internal corruption.
                  The client should assume that this will be treated as an
                  error by the library.

        :rtype: ``(bool, bytes)``

    .. py:method:: partial_merge(key, left_operand, right_operand)

        This function performs merge(left_op, right_op)
        when both the operands are themselves merge operation types
        that you would have passed to a DB::Merge() call in the same order.
        For example DB::Merge(key,left_op), followed by DB::Merge(key,right_op)).

        PartialMerge should combine them into a single merge operation that is
        returned together with ``True``
        This new value should be constructed such that a call to
        DB::Merge(key, new_value) would yield the same result as a call
        to DB::Merge(key, left_op) followed by DB::Merge(key, right_op).

        If it is impossible or infeasible to combine the two operations,
        return ``(False, None)`` The library will internally keep track of the
        operations, and apply them in the correct order once a base-value
        (a Put/Delete/End-of-Database) is seen.

        :param bytes key: the key that is associated with this merge operation.
        :param bytes left_operand: First operand to merge
        :param bytes right_operand: Second operand to merge
        :rtype: ``(bool, bytes)``

        .. note::

            Presently there is no way to differentiate between error/corruption
            and simply "return false". For now, the client should simply return
            false in any case it cannot perform partial-merge, regardless of reason.
            If there is corruption in the data, handle it in the FullMerge() function,
            and return false there.

    .. py:method:: name()

        The name of the MergeOperator. Used to check for MergeOperator mismatches.
        For example a DB created with one MergeOperator is accessed using a
        different MergeOperator.

        :rtype: ``bytes``

FilterPolicy
============

.. py:class:: rocksdb.interfaces.FilterPolicy

    .. py:method:: create_filter(keys)

        Create a bytestring which can act as a filter for keys.

        :param keys: list of keys (potentially with duplicates)
                     that are ordered according to the user supplied
                     comparator. 
        :type keys: list of bytes

        :returns: A filter that summarizes keys
        :rtype: ``bytes``

    .. py:method:: key_may_match(key, filter)

        Check if the key is maybe in the filter. 

        :param bytes key: Key for a single entry inside the database
        :param bytes filter: Contains the data returned by a preceding call
                              to create_filter on this class
        :returns: This method must return ``True`` if the key was in the list
                  of keys passed to create_filter().
                  This method may return ``True`` or ``False`` if the key was
                  not on the list, but it should aim to return ``False`` with
                  a high probability.
        :rtype: ``bool``

                     
    .. py:method:: name()

        Return the name of this policy.  Note that if the filter encoding
        changes in an incompatible way, the name returned by this method
        must be changed.  Otherwise, old incompatible filters may be
        passed to methods of this type.

        :rtype: ``bytes``


SliceTransform
==============

.. py:class:: rocksdb.interfaces.SliceTransform

    SliceTransform is currently used to implement the 'prefix-API' of rocksdb.
    https://github.com/facebook/rocksdb/wiki/Proposal-for-prefix-API

    .. py:method:: transform(src)

        :param bytes src: Full key to extract the prefix from.

        :returns:  A tuple of two interges ``(offset, size)``.
                   Where the first integer is the offset within the ``src``
                   and the second the size of the prefix after the offset.
                   Which means the prefix is generted by ``src[offset:offset+size]``

        :rtype: ``(int, int)``


    .. py:method:: in_domain(src)

        Decide if a prefix can be extraced from ``src``.
        Only if this method returns ``True`` :py:meth:`transform` will be
        called.

        :param bytes src: Full key to check.
        :rtype: ``bool``

    .. py:method:: in_range(prefix)

        Checks if prefix is a valid prefix

        :param bytes prefix: Prefix to check.
        :returns: ``True`` if ``prefix`` is a valid prefix.
        :rtype: ``bool``

    .. py:method:: name()

        Return the name of this transformation.

        :rtype: ``bytes``