1
0
Fork 0
arangodb/arangod/VocBase/primary-collection.h

514 lines
22 KiB
C

////////////////////////////////////////////////////////////////////////////////
/// @brief primary collection with global read-write lock
///
/// @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. Frank Celler
/// @author Copyright 2011-2013, triAGENS GmbH, Cologne, Germany
////////////////////////////////////////////////////////////////////////////////
#ifndef TRIAGENS_VOC_BASE_PRIMARY_COLLECTION_H
#define TRIAGENS_VOC_BASE_PRIMARY_COLLECTION_H 1
#include "VocBase/collection.h"
#include "BasicsC/json.h"
#include "ShapedJson/json-shaper.h"
#include "VocBase/barrier.h"
#include "VocBase/marker.h"
#include "VocBase/transaction.h"
#include "VocBase/update-policy.h"
#include "VocBase/voc-types.h"
#ifdef __cplusplus
extern "C" {
#endif
// -----------------------------------------------------------------------------
// --SECTION-- forward declarations
// -----------------------------------------------------------------------------
struct TRI_cap_constraint_s;
struct TRI_doc_deletion_key_marker_s;
struct TRI_doc_document_key_marker_s;
struct TRI_doc_update_policy_s;
struct TRI_key_generator_s;
struct TRI_primary_collection_s;
// -----------------------------------------------------------------------------
// --SECTION-- public macros
// -----------------------------------------------------------------------------
////////////////////////////////////////////////////////////////////////////////
/// @addtogroup VocBase
/// @{
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// @brief read locks the documents and indexes
////////////////////////////////////////////////////////////////////////////////
#define TRI_READ_LOCK_DOCUMENTS_INDEXES_PRIMARY_COLLECTION(a) \
TRI_ReadLockReadWriteLock(&(a)->_lock)
////////////////////////////////////////////////////////////////////////////////
/// @brief tries to read lock the documents and indexes
////////////////////////////////////////////////////////////////////////////////
#define TRI_TRY_READ_LOCK_DOCUMENTS_INDEXES_PRIMARY_COLLECTION(a) \
TRI_TryReadLockReadWriteLock(&(a)->_lock)
////////////////////////////////////////////////////////////////////////////////
/// @brief read unlocks the documents and indexes
////////////////////////////////////////////////////////////////////////////////
#define TRI_READ_UNLOCK_DOCUMENTS_INDEXES_PRIMARY_COLLECTION(a) \
TRI_ReadUnlockReadWriteLock(&(a)->_lock)
////////////////////////////////////////////////////////////////////////////////
/// @brief write locks the documents and indexes
////////////////////////////////////////////////////////////////////////////////
#define TRI_WRITE_LOCK_DOCUMENTS_INDEXES_PRIMARY_COLLECTION(a) \
TRI_WriteLockReadWriteLock(&(a)->_lock)
////////////////////////////////////////////////////////////////////////////////
/// @brief tries to write lock the documents and indexes
////////////////////////////////////////////////////////////////////////////////
#define TRI_TRY_WRITE_LOCK_DOCUMENTS_INDEXES_PRIMARY_COLLECTION(a) \
TRI_TryWriteLockReadWriteLock(&(a)->_lock)
////////////////////////////////////////////////////////////////////////////////
/// @brief write unlocks the documents and indexes
////////////////////////////////////////////////////////////////////////////////
#define TRI_WRITE_UNLOCK_DOCUMENTS_INDEXES_PRIMARY_COLLECTION(a) \
TRI_WriteUnlockReadWriteLock(&(a)->_lock)
////////////////////////////////////////////////////////////////////////////////
/// @}
////////////////////////////////////////////////////////////////////////////////
// -----------------------------------------------------------------------------
// --SECTION-- public types
// -----------------------------------------------------------------------------
////////////////////////////////////////////////////////////////////////////////
/// @addtogroup VocBase
/// @{
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// @brief master pointer
////////////////////////////////////////////////////////////////////////////////
typedef struct TRI_doc_mptr_s {
TRI_voc_rid_t _rid; // this is the revision identifier
TRI_voc_fid_t _fid; // this is the datafile identifier
void const* _data; // this is the pointer to the beginning of the raw marker
char* _key; // this is the document identifier (string)
struct TRI_doc_mptr_s* _prev; // previous master pointer
struct TRI_doc_mptr_s* _next; // next master pointer
}
TRI_doc_mptr_t;
////////////////////////////////////////////////////////////////////////////////
/// @brief datafile info
////////////////////////////////////////////////////////////////////////////////
typedef struct TRI_doc_datafile_info_s {
TRI_voc_fid_t _fid;
TRI_voc_ssize_t _numberAlive;
TRI_voc_ssize_t _numberDead;
TRI_voc_ssize_t _numberDeletion;
TRI_voc_ssize_t _numberTransaction; // populated only during compaction
TRI_voc_ssize_t _numberShapes;
TRI_voc_ssize_t _numberAttributes;
int64_t _sizeAlive;
int64_t _sizeDead;
int64_t _sizeTransaction; // populated only during compaction
int64_t _sizeShapes;
int64_t _sizeAttributes;
}
TRI_doc_datafile_info_t;
////////////////////////////////////////////////////////////////////////////////
/// @brief collection info
////////////////////////////////////////////////////////////////////////////////
typedef struct TRI_doc_collection_info_s {
TRI_voc_ssize_t _numberDatafiles;
TRI_voc_ssize_t _numberJournalfiles;
TRI_voc_ssize_t _numberCompactorfiles;
TRI_voc_ssize_t _numberShapefiles;
TRI_voc_ssize_t _numberAlive;
TRI_voc_ssize_t _numberDead;
TRI_voc_ssize_t _numberDeletion;
TRI_voc_ssize_t _numberTransaction; // populated only during compaction
TRI_voc_ssize_t _numberShapes;
TRI_voc_ssize_t _numberAttributes;
int64_t _sizeAlive;
int64_t _sizeDead;
int64_t _sizeTransaction; // populated only during compaction
int64_t _sizeShapes;
int64_t _sizeAttributes;
int64_t _datafileSize;
int64_t _journalfileSize;
int64_t _compactorfileSize;
int64_t _shapefileSize;
}
TRI_doc_collection_info_t;
////////////////////////////////////////////////////////////////////////////////
/// @brief primary collection
///
/// A primary collection is a collection of documents. These documents are
/// represented as @ref ShapedJson "shaped JSON objects". Each document has a
/// place in memory which is determined by the position in the memory mapped
/// file. As datafiles are compacted during garbage collection, this position
/// can change over time. Each active document also has a master pointer of type
/// @ref TRI_doc_mptr_t. This master pointer never changes and is valid as long
/// as the object is not deleted.
///
/// It is important to use locks for create, read, update, and delete. The
/// functions @FN{create}, @FN{update}, and
/// @FN{destroy} are only allowed within a @FN{beginWrite} and
/// @FN{endWrite}. The function @FN{read} is only allowed within a
/// @FN{beginRead} and @FN{endRead}. Note that @FN{read} returns a copy of the
/// master pointer.
///
/// If a document is deleted, it's master pointer becomes invalid. However, the
/// document itself still exists. Executing a query and constructing its result
/// set, must be done inside a "beginRead" and "endRead".
///
/// @FUN{int beginRead (TRI_primary_collection_t*)}
///////////////////////////////////////////////
///
/// Starts a read transaction. Query and calls to @FN{read} are allowed within a
/// read transaction, but not calls to @FN{create}, @FN{update}, or
/// @FN{destroy}. Returns @ref TRI_ERROR_NO_ERROR if the transaction could be
/// started. This call might block until a running write transaction is
/// finished.
///
/// @FUN{int endRead (TRI_primary_collection_t*)}
/////////////////////////////////////////////
///
/// Ends a read transaction. Should only be called after a successful
/// "beginRead".
///
/// @FUN{int beginWrite (TRI_primary_collection_t*)}
////////////////////////////////////////////////
///
/// Starts a write transaction. Query and calls to @FN{create}, @FN{read},
/// @FN{update}, and @FN{destroy} are allowed within a write
/// transaction. Returns @ref TRI_ERROR_NO_ERROR if the transaction could be
/// started. This call might block until a running write transaction is
/// finished.
///
/// @FUN{int endWrite (TRI_primary_collection_t*)}
//////////////////////////////////////////////
///
/// Ends a write transaction. Should only be called after a successful
/// @LIT{beginWrite}.
///
/// @FUN{TRI_doc_mptr_t const create (TRI_primary_collection_t*, TRI_df_marker_type_e, TRI_shaped_json_t const*, bool @FA{release})}
///
/// Adds a new document to the collection and returns the master pointer of the
/// newly created entry. In case of an error, the attribute @LIT{_did} of the
/// result is @LIT{0} and "TRI_errno()" is set accordingly. The function DOES
/// NOT acquire a write lock. This must be done by the caller. If @FA{release}
/// is true, it will release the write lock as soon as possible.
///
/// @FUN{TRI_doc_mptr_t const read (TRI_primary_collection_t*, TRI_voc_key_t)}
//////////////////////////////////////////////////////////////////////////
///
/// Returns the master pointer of the document with the given identifier. If the
/// document does not exist or is deleted, then the identifier @LIT{_did} of
/// the result is @LIT{0}. The function DOES NOT acquire or release a read
/// lock. This must be done by the caller.
///
/// @FUN{TRI_doc_mptr_t const update (TRI_primary_collection_t*, TRI_shaped_json_t const*, TRI_voc_key_t, TRI_voc_rid_t @FA{rid}, TRI_voc_rid_t* @FA{current}, TRI_doc_update_policy_e, bool @FA{release})}
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
///
/// Updates an existing document of the collection and returns copy of a valid
/// master pointer in case of success. Otherwise, the attribute @LIT{_did} of
/// the result is @LIT{0} and the "TRI_errno()" is set accordingly. The function
/// DOES NOT acquire a write lock. This must be done by the caller. However, if
/// @FA{release} is true, it will release the write lock as soon as possible.
///
/// If the policy is @ref TRI_doc_update_policy_e "TRI_DOC_UPDATE_LAST_WRITE",
/// than the revision @FA{rid} is ignored and the update is always performed. If
/// the policy is @ref TRI_doc_update_policy_e "TRI_DOC_UPDATE_ERROR" and the
/// revision @FA{rid} is given (i. e. not equal 0), then the update is only
/// performed if the current revision matches the given. In any case the current
/// revision after the updated of the document is returned in @FA{current}.
///
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
///
/// @FUN{int destroy (TRI_primary_collection_t*, TRI_voc_key_t, TRI_voc_rid_t, TRI_voc_rid_t @FA{rid}, TRI_voc_rid_t* @FA{current}, TRI_doc_update_policy_e, bool @FA{release})}
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
///
/// Deletes an existing document from the given collection and returns @ref
/// TRI_ERROR_NO_ERROR in case of success. Otherwise, an error is returned and
/// the "TRI_errno()" is set accordingly. The function DOES NOT acquire a write
/// lock. However, if @FA{release} is true, it will release the write lock as
/// soon as possible.
///
/// If the policy is @ref TRI_doc_update_policy_e "TRI_DOC_UPDATE_ERROR" and the
/// revision is given, then it must match the current revision of the
/// document. If the delete was executed, than @FA{current} contains the last
/// valid revision of the document. If the delete was aborted, than @FA{current}
/// contains the revision of the still alive document.
///
/// @FUN{TRI_doc_collection_info_t* figures (TRI_primary_collection_t*)}
////////////////////////////////////////////////////////////////////
///
/// Returns informatiom about the collection. You must hold a read lock and must
/// destroy the result after usage.
////////////////////////////////////////////////////////////////////////////////
typedef struct TRI_primary_collection_s {
TRI_collection_t base;
// .............................................................................
// this lock protects the _primaryIndex plus the _allIndexes
// and _headers attributes in derived types
// .............................................................................
TRI_read_write_lock_t _lock;
TRI_shaper_t* _shaper;
TRI_barrier_list_t _barrierList;
TRI_associative_pointer_t _datafileInfo;
TRI_associative_pointer_t _primaryIndex;
struct TRI_key_generator_s* _keyGenerator;
struct TRI_cap_constraint_s* _capConstraint;
int64_t _numberDocuments;
TRI_read_write_lock_t _compactionLock;
double _lastCompaction;
int (*beginRead) (struct TRI_primary_collection_s*);
int (*endRead) (struct TRI_primary_collection_s*);
int (*beginWrite) (struct TRI_primary_collection_s*);
int (*endWrite) (struct TRI_primary_collection_s*);
int (*beginReadTimed) (struct TRI_primary_collection_s*, uint64_t, uint64_t);
int (*beginWriteTimed) (struct TRI_primary_collection_s*, uint64_t, uint64_t);
#ifdef TRI_ENABLE_MAINTAINER_MODE
void (*dump) (struct TRI_primary_collection_s*);
#endif
int (*notifyTransaction) (struct TRI_primary_collection_s*, TRI_transaction_status_e);
int (*insert) (struct TRI_transaction_collection_s*, const TRI_voc_key_t, TRI_voc_rid_t, TRI_doc_mptr_t*, TRI_df_marker_type_e, TRI_shaped_json_t const*, void const*, const bool, const bool, const bool);
int (*read) (struct TRI_transaction_collection_s*, const TRI_voc_key_t, TRI_doc_mptr_t*, const bool);
int (*update) (struct TRI_transaction_collection_s*, const TRI_voc_key_t, TRI_voc_rid_t, TRI_doc_mptr_t*, TRI_shaped_json_t const*, struct TRI_doc_update_policy_s const*, const bool, const bool);
int (*remove) (struct TRI_transaction_collection_s*, const TRI_voc_key_t, TRI_voc_rid_t, struct TRI_doc_update_policy_s const*, const bool, const bool);
TRI_doc_collection_info_t* (*figures) (struct TRI_primary_collection_s* collection);
TRI_voc_size_t (*size) (struct TRI_primary_collection_s* collection);
}
TRI_primary_collection_t;
////////////////////////////////////////////////////////////////////////////////
/// @brief document datafile marker with key
////////////////////////////////////////////////////////////////////////////////
typedef struct TRI_doc_document_key_marker_s {
TRI_df_marker_t base;
TRI_voc_rid_t _rid; // this is the tick for a create and update
TRI_voc_tid_t _tid;
TRI_shape_sid_t _shape;
uint16_t _offsetKey;
uint16_t _offsetJson;
#ifdef TRI_PADDING_32
char _padding_df_marker[4];
#endif
}
TRI_doc_document_key_marker_t;
////////////////////////////////////////////////////////////////////////////////
/// @brief edge datafile marker with key
////////////////////////////////////////////////////////////////////////////////
typedef struct TRI_doc_edge_key_marker_s {
TRI_doc_document_key_marker_t base;
TRI_voc_cid_t _toCid;
TRI_voc_cid_t _fromCid;
uint16_t _offsetToKey;
uint16_t _offsetFromKey;
#ifdef TRI_PADDING_32
char _padding_df_marker[4];
#endif
}
TRI_doc_edge_key_marker_t;
////////////////////////////////////////////////////////////////////////////////
/// @brief document datafile deletion marker
////////////////////////////////////////////////////////////////////////////////
typedef struct TRI_doc_deletion_key_marker_s {
TRI_df_marker_t base;
TRI_voc_rid_t _rid; // this is the tick for the deletion
TRI_voc_tid_t _tid;
uint16_t _offsetKey;
}
TRI_doc_deletion_key_marker_t;
////////////////////////////////////////////////////////////////////////////////
/// @}
////////////////////////////////////////////////////////////////////////////////
// -----------------------------------------------------------------------------
// --SECTION-- constructors and destructors
// -----------------------------------------------------------------------------
////////////////////////////////////////////////////////////////////////////////
/// @addtogroup VocBase
/// @{
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// @brief initializes a primary collection structure
////////////////////////////////////////////////////////////////////////////////
int TRI_InitPrimaryCollection (TRI_primary_collection_t*, TRI_shaper_t*);
////////////////////////////////////////////////////////////////////////////////
/// @brief destroys a primary collection
////////////////////////////////////////////////////////////////////////////////
void TRI_DestroyPrimaryCollection (TRI_primary_collection_t*);
////////////////////////////////////////////////////////////////////////////////
/// @}
////////////////////////////////////////////////////////////////////////////////
// -----------------------------------------------------------------------------
// --SECTION-- protected functions
// -----------------------------------------------------------------------------
////////////////////////////////////////////////////////////////////////////////
/// @addtogroup VocBase
/// @{
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// @brief removes a datafile description
////////////////////////////////////////////////////////////////////////////////
void TRI_RemoveDatafileInfoPrimaryCollection (TRI_primary_collection_t*,
TRI_voc_fid_t);
////////////////////////////////////////////////////////////////////////////////
/// @brief finds a datafile description
////////////////////////////////////////////////////////////////////////////////
TRI_doc_datafile_info_t* TRI_FindDatafileInfoPrimaryCollection (TRI_primary_collection_t*,
TRI_voc_fid_t,
bool);
////////////////////////////////////////////////////////////////////////////////
/// @brief creates a new journal
////////////////////////////////////////////////////////////////////////////////
TRI_datafile_t* TRI_CreateJournalPrimaryCollection (TRI_primary_collection_t*,
TRI_voc_size_t);
////////////////////////////////////////////////////////////////////////////////
/// @brief closes an existing journal
////////////////////////////////////////////////////////////////////////////////
bool TRI_CloseJournalPrimaryCollection (TRI_primary_collection_t*,
size_t);
////////////////////////////////////////////////////////////////////////////////
/// @brief creates a new compactor file
////////////////////////////////////////////////////////////////////////////////
TRI_datafile_t* TRI_CreateCompactorPrimaryCollection (TRI_primary_collection_t*,
TRI_voc_fid_t,
TRI_voc_size_t);
////////////////////////////////////////////////////////////////////////////////
/// @brief closes an existing compactor file
////////////////////////////////////////////////////////////////////////////////
bool TRI_CloseCompactorPrimaryCollection (TRI_primary_collection_t*,
size_t);
////////////////////////////////////////////////////////////////////////////////
/// @brief dump information about all datafiles of a collection
////////////////////////////////////////////////////////////////////////////////
void TRI_DebugDatafileInfoPrimaryCollection (TRI_primary_collection_t*);
////////////////////////////////////////////////////////////////////////////////
/// @brief iterate over all documents in the collection, using a user-defined
/// callback function. Returns the total number of documents in the collection
///
/// The user can abort the iteration by return "false" from the callback
/// function.
///
/// Note: the function will not acquire any locks. It is the task of the caller
/// to ensure the collection is properly locked
////////////////////////////////////////////////////////////////////////////////
size_t TRI_DocumentIteratorPrimaryCollection (TRI_primary_collection_t*,
void*,
bool (*callback)(TRI_doc_mptr_t const*,
TRI_primary_collection_t*, void*));
////////////////////////////////////////////////////////////////////////////////
/// @}
////////////////////////////////////////////////////////////////////////////////
#ifdef __cplusplus
}
#endif
#endif
// Local Variables:
// mode: outline-minor
// outline-regexp: "/// @brief\\|/// {@inheritDoc}\\|/// @addtogroup\\|/// @page\\|// --SECTION--\\|/// @\\}"
// End: