mirror of https://gitee.com/bigwinds/arangodb
196 lines
7.9 KiB
C
196 lines
7.9 KiB
C
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief index iterator
|
|
///
|
|
/// @file
|
|
///
|
|
/// DISCLAIMER
|
|
///
|
|
/// Copyright 2004-2013 triAGENS GmbH, Cologne, Germany
|
|
///
|
|
/// 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.
|
|
///
|
|
/// Copyright holder is triAGENS GmbH, Cologne, Germany
|
|
///
|
|
/// @author Dr. Oreste Costa-Panaia
|
|
/// @author Copyright 2011-2013, triAGENS GmbH, Cologne, Germany
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
#ifndef TRIAGENS_INDEX_ITERATORS_INDEX_ITERATOR_H
|
|
#define TRIAGENS_INDEX_ITERATORS_INDEX_ITERATOR_H 1
|
|
|
|
#include "BasicsC/common.h"
|
|
#include "IndexOperators/index-operator.h"
|
|
#include "ShapedJson/shaped-json.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
// -----------------------------------------------------------------------------
|
|
// --SECTION-- public types
|
|
// -----------------------------------------------------------------------------
|
|
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @addtogroup indexIterator
|
|
/// @{
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief Iterator structure used to store results for indexes
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
|
// .............................................................................
|
|
// Essentially an interator consists of a sequence of 'intervals'. The iterator
|
|
// iterators over each 'interval'. The exact meaning of an 'interval' will
|
|
// vary with the type of index that the iterator is used for. For example,
|
|
// in a Skiplist Index, 'intervals' are actual intervals with end points. For
|
|
// a Bitarray index there is only one 'interval' which consists of a vector list
|
|
// of document handles.
|
|
// .............................................................................
|
|
|
|
typedef struct TRI_index_iterator_interval_s {
|
|
void* _leftEndPoint; // typecast to whatever the index requires
|
|
void* _rightEndPoint; // typecast to whatever the index requires -- can be NULL
|
|
} TRI_index_iterator_interval_t;
|
|
|
|
|
|
|
|
// .............................................................................
|
|
// The structure of an index iterator
|
|
// TODO: for safety sakes whenever we define a structure which we will pass
|
|
// around as an object, add an identifier to the object as the first field
|
|
// within the structure -- this will let everyone one whether or not you
|
|
// have a valid object.
|
|
// .............................................................................
|
|
|
|
typedef struct TRI_index_iterator_s {
|
|
void* _index; // the actual index which uses this iterator -- typecast back to the appropriate index structure
|
|
TRI_vector_t _intervals; // zero or more intervals of the type TRI_index_iterator_interval_t
|
|
size_t _currentInterval; // the current interval we are operating with
|
|
void* _cursor; // initially null -- the position within an interval -- typecast to appropriate structure
|
|
void* _currentDocument; // the result of a call to _next or _prev is stored here.
|
|
|
|
// ...........................................................................
|
|
// Iteration callback functions:
|
|
//
|
|
// _filter := a function which performs a final filter on a document before
|
|
// releasing it as available. This function is provided by the
|
|
// client using the index. If null, then not filter is performed.
|
|
//
|
|
// _hasNext := returns true if there is a next document WITHOUT advancing the
|
|
// iterator.
|
|
//
|
|
// _next := increments the iterator by 1 and returns a document handle if available.
|
|
// Will return NULL if no document is available or if the _filter function
|
|
// above excludes the document.
|
|
//
|
|
// _nexts := similar to _next, except it advances the iterator by jumpSize
|
|
//
|
|
// _hasPrev := returns true if there is a previous document WITHOUT advancing
|
|
// the iterator.
|
|
//
|
|
// _prev := decrements the iterator by 1 and returns a document handle if available.
|
|
// Will return NULL if no document is available or if the _filter function
|
|
// above excludes the document.
|
|
//
|
|
// _prevs := similar to _prev., except it retreats the iterator by jumpSize.
|
|
//
|
|
// Note that if jumpSize is negative in the functions _nexts and _prevs, then
|
|
// the role of these functions is reversed.
|
|
//
|
|
// Note that these functions are assigned when an interator is returned for
|
|
// an index lookup request. There is NO globally accessible create index
|
|
// iterator function
|
|
// ...........................................................................
|
|
|
|
bool (*_filter) (struct TRI_index_iterator_s*);
|
|
bool (*_hasNext) (struct TRI_index_iterator_s*);
|
|
void* (*_next) (struct TRI_index_iterator_s*);
|
|
void* (*_nexts) (struct TRI_index_iterator_s*, int64_t jumpSize);
|
|
bool (*_hasPrev) (struct TRI_index_iterator_s*);
|
|
void* (*_prev) (struct TRI_index_iterator_s*);
|
|
void* (*_prevs) (struct TRI_index_iterator_s*, int64_t jumpSize);
|
|
void (*_reset) (struct TRI_index_iterator_s*, bool beginning);
|
|
|
|
|
|
// ...........................................................................
|
|
// Index related callback functions:
|
|
//
|
|
// _destroyIterator := since the structure of the 'intervals' is dependent
|
|
// on the type of index used, then this callback will
|
|
// correctly deallocate memory to all of the interval
|
|
// structures and the cursor structure.
|
|
//
|
|
// Note that these functions are assigned when an interator is returned for
|
|
// an index lookup request. There is NO globally accessible create index
|
|
// iterator function
|
|
// ...........................................................................
|
|
|
|
void (*_destroyIterator) (struct TRI_index_iterator_s*);
|
|
|
|
} TRI_index_iterator_t;
|
|
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @}
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
|
|
|
// -----------------------------------------------------------------------------
|
|
// --SECTION-- public methods
|
|
// -----------------------------------------------------------------------------
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @addtogroup indexIterator
|
|
/// @{
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
|
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief destroys an index iterator but does not free the pointer
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
void TRI_DestroyIndexIterator (TRI_index_iterator_t*);
|
|
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief Free an index iterator
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
void TRI_FreeIndexIterator (TRI_index_iterator_t*);
|
|
|
|
|
|
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @}
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif
|
|
|
|
// Local Variables:
|
|
// mode: outline-minor
|
|
// outline-regexp: "/// @brief\\|/// {@inheritDoc}\\|/// @addtogroup\\|/// @page\\|// --SECTION--\\|/// @\\}"
|
|
// End:
|
|
|