YugabyteDB (2.13.0.0-b42, bfc6a6643e7399ac8a0e81d06a3ee6d6571b33ab)

// Copyright (c) 2011-present, Facebook, Inc.  All rights reserved.

// This source code is licensed under the BSD-style license found in the

// LICENSE file in the root directory of this source tree. An additional grant

// of patent rights can be found in the PATENTS file in the same directory.

// Copyright (c) 2011 The LevelDB Authors. All rights reserved.

// Use of this source code is governed by a BSD-style license that can be

// found in the LICENSE file. See the AUTHORS file for names of contributors.

//

// The following only applies to changes made to this file as part of YugaByte development.

//

// Portions Copyright (c) YugaByte, Inc.

//

// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except

// in compliance with the License.  You may obtain a copy of the License at

//

// http://www.apache.org/licenses/LICENSE-2.0

//

// Unless required by applicable law or agreed to in writing, software distributed under the License

// is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express

// or implied.  See the License for the specific language governing permissions and limitations

// under the License.

//

// An iterator yields a sequence of key/value pairs from a source.

// The following class defines the interface.  Multiple implementations

// are provided by this library.  In particular, iterators are provided

// to access the contents of a Table or a DB.

//

// Multiple threads can invoke const methods on an Iterator without

// external synchronization, but if any of the threads may call a

// non-const method, all threads accessing the same Iterator must use

// external synchronization.

#ifndef YB_ROCKSDB_ITERATOR_H

#define YB_ROCKSDB_ITERATOR_H

#include <string>

#include "yb/util/slice.h"

#include "yb/rocksdb/status.h"

namespace rocksdb {

class Cleanable {

 public:

  Cleanable();

  ~Cleanable();

  // Clients are allowed to register function/arg1/arg2 triples that

  // will be invoked when this iterator is destroyed.

  //

  // Note that unlike all of the preceding methods, this method is

  // not abstract and therefore clients should not override it.

  typedef void (*CleanupFunction)(void* arg1, void* arg2);

  void RegisterCleanup(CleanupFunction function, void* arg1, void* arg2);

 protected:

  struct Cleanup {

    CleanupFunction function;

    void* arg1;

    void* arg2;

    Cleanup* next;

  };

  Cleanup cleanup_;

};

class Iterator : public Cleanable {

 public:

  Iterator() {}

  virtual ~Iterator() {}

  Iterator(const Iterator&) = delete;

  void operator=(const Iterator&) = delete;

  Iterator(Iterator&&) = default;

  Iterator& operator=(Iterator&&) = default;

  // An iterator is either positioned at a key/value pair, or

  // not valid.  This method returns true iff the iterator is valid.

  virtual bool Valid() const = 0;

  // Position at the first key in the source.  The iterator is Valid()

  // after this call iff the source is not empty.

  virtual void SeekToFirst() = 0;

  // Position at the last key in the source.  The iterator is

  // Valid() after this call iff the source is not empty.

  virtual void SeekToLast() = 0;

  // Position at the first key in the source that at or past target

  // The iterator is Valid() after this call iff the source contains

  // an entry that comes at or past target.

  virtual void Seek(const Slice& target) = 0;

  // Moves to the next entry in the source.  After this call, Valid() is

  // true iff the iterator was not positioned at the last entry in the source.

  // REQUIRES: Valid()

  virtual void Next() = 0;

  // Moves to the previous entry in the source.  After this call, Valid() is

  // true iff the iterator was not positioned at the first entry in source.

  // REQUIRES: Valid()

  virtual void Prev() = 0;

  // Return the key for the current entry.  The underlying storage for

  // the returned slice is valid only until the next modification of

  // the iterator.

  // 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.

  // REQUIRES: !AtEnd() && !AtStart()

  virtual Slice value() const = 0;

  // If an error has occurred, return it.  Else return an ok status.

  // If non-blocking IO is requested and this operation cannot be

  // satisfied without doing some IO, then this returns STATUS(Incomplete, ).

  virtual Status status() const = 0;

  // Property "rocksdb.iterator.is-key-pinned":

  //   If returning "1", this means that the Slice returned by key() is valid

  //   as long as the iterator is not deleted and ReleasePinnedData() is not

  //   called.

  //   It is guaranteed to always return "1" if

  //      - Iterator created with ReadOptions::pin_data = true

  //      - DB tables were created with

  //      BlockBasedTableOptions::use_delta_encoding

  //        set to false.

  // Property "rocksdb.iterator.super-version-number":

  //   LSM version used by the iterator. The same format as DB Property

  //   kCurrentSuperVersionNumber. See its comment for more information.

  virtual Status GetProperty(std::string prop_name, std::string* prop);

  // Upper bound was updated and iterator should revalidate its state, since it could change.

  // This only affects forward iteration. A previously invalid forward iterator can become valid

  // if the upper bound has increased.

  virtual void RevalidateAfterUpperBoundChange() {}

};

// Return an empty iterator (yields nothing).

extern Iterator* NewEmptyIterator();

// Return an empty iterator with the specified status.

extern Iterator* NewErrorIterator(const Status& status);

}  // namespace rocksdb

#endif // YB_ROCKSDB_ITERATOR_H