mirror of https://gitee.com/bigwinds/arangodb
546 lines
22 KiB
C
546 lines
22 KiB
C
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief collections
|
|
///
|
|
/// @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_COLLECTION_H
|
|
#define TRIAGENS_VOC_BASE_COLLECTION_H 1
|
|
|
|
#include "BasicsC/common.h"
|
|
|
|
#include "BasicsC/vector.h"
|
|
|
|
#include "VocBase/datafile.h"
|
|
#include "VocBase/vocbase.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @page DurhamCollections Collections
|
|
///
|
|
/// Data is stored in datafiles. A set of datafiles forms a collection. A
|
|
/// datafile can be read-only and sealed or read-write. All datafiles of a
|
|
/// collection are stored in a directory. This directory contains the following
|
|
/// files:
|
|
///
|
|
/// - parameter.json: The parameters of a collection.
|
|
///
|
|
/// - datafile-NNN.db: A read-only datafile. The number NNN is the datafile
|
|
/// identifier, see @ref TRI_datafile_t.
|
|
///
|
|
/// - journal-NNN.db: A read-write datafile used as journal. All new entries
|
|
/// of a collection are appended to a journal. The number NNN is the
|
|
/// datafile identifier, see @ref TRI_datafile_t.
|
|
///
|
|
/// - index-NNN.json: An index description. The number NNN is the index
|
|
/// identifier, see @ref TRI_index_t.
|
|
///
|
|
/// The structure @ref TRI_collection_t is abstract. Currently, there are
|
|
/// two concrete sub-classes @ref TRI_document_collection_t and
|
|
/// @ref TRI_shape_collection_t.
|
|
///
|
|
/// @section ShapeCollection Shape Collection
|
|
///
|
|
/// @copydetails TRI_shape_collection_t
|
|
///
|
|
/// @section PrimaryCollection Document Collection
|
|
///
|
|
/// @copydetails TRI_primary_collection_t
|
|
///
|
|
/// @section DocumentCollection Simple Document Collection
|
|
///
|
|
/// @copydetails TRI_document_collection_t
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
// -----------------------------------------------------------------------------
|
|
// --SECTION-- forwards
|
|
// -----------------------------------------------------------------------------
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @addtogroup VocBase
|
|
/// @{
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
struct TRI_json_s;
|
|
struct TRI_vocbase_col_s;
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @}
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
// -----------------------------------------------------------------------------
|
|
// --SECTION-- public constants
|
|
// -----------------------------------------------------------------------------
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @addtogroup VocBase
|
|
/// @{
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief collection name regex
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
#define TRI_COL_NAME_REGEX "[a-zA-Z_][0-9a-zA-Z_-]*"
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief collection version
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
#define TRI_COL_VERSION (4)
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief collection meta info filename
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
#define TRI_COL_PARAMETER_FILE "parameter.json"
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief predefined system collection name for databases
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
#define TRI_COL_NAME_DATABASES "_databases"
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief predefined system collection name for endpoints
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
#define TRI_COL_NAME_ENDPOINTS "_endpoints"
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief predefined system collection name for prefixes
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
#define TRI_COL_NAME_PREFIXES "_prefixes"
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief predefined system collection name for replication
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
#define TRI_COL_NAME_REPLICATION "_replication"
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief predefined system collection name for transactions
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
#define TRI_COL_NAME_TRANSACTION "_trx"
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief predefined collection name for users
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
#define TRI_COL_NAME_USERS "_users"
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @}
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
// -----------------------------------------------------------------------------
|
|
// --SECTION-- public macros
|
|
// -----------------------------------------------------------------------------
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @addtogroup VocBase
|
|
/// @{
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief return whether the collection is a document collection
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
#define TRI_IS_DOCUMENT_COLLECTION(type) \
|
|
((type) == TRI_COL_TYPE_DOCUMENT || (type) == TRI_COL_TYPE_EDGE)
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @}
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
// -----------------------------------------------------------------------------
|
|
// --SECTION-- public types
|
|
// -----------------------------------------------------------------------------
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @addtogroup VocBase
|
|
/// @{
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief collection file structure
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
typedef struct TRI_col_file_structure_s {
|
|
TRI_vector_string_t _journals;
|
|
TRI_vector_string_t _compactors;
|
|
TRI_vector_string_t _datafiles;
|
|
TRI_vector_string_t _indexes;
|
|
}
|
|
TRI_col_file_structure_t;
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief state of the datafile
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
typedef enum {
|
|
TRI_COL_STATE_CLOSED = 1, // collection is closed
|
|
TRI_COL_STATE_READ = 2, // collection is opened read only
|
|
TRI_COL_STATE_WRITE = 3, // collection is opened read/append
|
|
TRI_COL_STATE_OPEN_ERROR = 4, // an error has occurred while opening
|
|
TRI_COL_STATE_WRITE_ERROR = 5 // an error has occurred while writing
|
|
}
|
|
TRI_col_state_e;
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief collection version
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
typedef uint32_t TRI_col_version_t;
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief collection enum
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
typedef enum {
|
|
TRI_COL_TYPE_SHAPE = 1,
|
|
TRI_COL_TYPE_DOCUMENT = 2,
|
|
TRI_COL_TYPE_EDGE = 3
|
|
}
|
|
TRI_col_type_e;
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief document datafile header marker
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
typedef struct TRI_col_header_marker_s {
|
|
TRI_df_marker_t base; // 24 bytes
|
|
|
|
TRI_col_type_t _type; // 4 bytes
|
|
|
|
#ifdef TRI_PADDING_32
|
|
char _padding_col_header_marker[4];
|
|
#endif
|
|
|
|
TRI_voc_cid_t _cid; // 8 bytes
|
|
}
|
|
TRI_col_header_marker_t;
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief collection info block saved to disk as json
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
typedef struct TRI_col_info_s {
|
|
TRI_col_version_t _version; // collection version
|
|
TRI_col_type_e _type; // collection type
|
|
TRI_voc_cid_t _cid; // collection identifier
|
|
TRI_voc_rid_t _revision; // last revision id written
|
|
TRI_voc_size_t _maximalSize; // maximal size of memory mapped file
|
|
|
|
char _name[TRI_COL_PATH_LENGTH]; // name of the collection
|
|
struct TRI_json_s* _keyOptions; // options for key creation
|
|
|
|
// flags
|
|
bool _deleted; // if true, collection has been deleted
|
|
bool _doCompact; // if true, collection will be compacted
|
|
bool _isSystem; // if true, this is a system collection
|
|
bool _isVolatile; // if true, collection is memory-only
|
|
bool _waitForSync; // if true, wait for msync
|
|
}
|
|
TRI_col_info_t;
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief collection
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
typedef struct TRI_collection_s {
|
|
TRI_col_info_t _info;
|
|
|
|
TRI_vocbase_t* _vocbase;
|
|
|
|
TRI_col_state_e _state; // state of the collection
|
|
int _lastError; // last (critical) error
|
|
|
|
char* _directory; // directory of the collection
|
|
|
|
TRI_vector_pointer_t _datafiles; // all datafiles
|
|
TRI_vector_pointer_t _journals; // all journals
|
|
TRI_vector_pointer_t _compactors; // all compactor files
|
|
TRI_vector_string_t _indexFiles; // all index filenames
|
|
}
|
|
TRI_collection_t;
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @}
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
// -----------------------------------------------------------------------------
|
|
// --SECTION-- constructors and destructors
|
|
// -----------------------------------------------------------------------------
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @addtogroup VocBase
|
|
/// @{
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief initializes a collection info block
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
void TRI_InitCollectionInfo (TRI_vocbase_t*,
|
|
TRI_col_info_t*,
|
|
char const*,
|
|
TRI_col_type_e,
|
|
TRI_voc_size_t,
|
|
struct TRI_json_s*);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief copy a collection info block
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
void TRI_CopyCollectionInfo (TRI_col_info_t*,
|
|
const TRI_col_info_t* const);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief free a collection info block
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
void TRI_FreeCollectionInfoOptions (TRI_col_info_t*);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief get the full directory name for a collection
|
|
///
|
|
/// it is the caller's responsibility to check if the returned string is NULL
|
|
/// and to free it if not.
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
char* TRI_GetDirectoryCollection (char const*,
|
|
char const*,
|
|
TRI_col_type_e,
|
|
TRI_voc_cid_t);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief creates a new collection
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
TRI_collection_t* TRI_CreateCollection (TRI_vocbase_t*,
|
|
TRI_collection_t*,
|
|
char const*,
|
|
const TRI_col_info_t* const);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief frees the memory allocated, but does not free the pointer
|
|
///
|
|
/// Note that the collection must be closed first.
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
void TRI_DestroyCollection (TRI_collection_t*);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief frees the memory allocated and frees the pointer
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
void TRI_FreeCollection (TRI_collection_t*);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @}
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
// -----------------------------------------------------------------------------
|
|
// --SECTION-- public functions
|
|
// -----------------------------------------------------------------------------
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @addtogroup VocBase
|
|
/// @{
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief return JSON information about the collection from the collection's
|
|
/// "parameter.json" file. This function does not require the collection to be
|
|
/// loaded.
|
|
/// The caller must make sure that the files is not modified while this
|
|
/// function is called.
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
struct TRI_json_s* TRI_ReadJsonCollectionInfo (struct TRI_vocbase_col_s*);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief iterate over the index (JSON) files of a collection, using a callback
|
|
/// function for each.
|
|
/// This function does not require the collection to be loaded.
|
|
/// The caller must make sure that the files is not modified while this
|
|
/// function is called.
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
int TRI_IterateJsonIndexesCollectionInfo (struct TRI_vocbase_col_s*,
|
|
int (*)(struct TRI_vocbase_col_s*, char const*, void*),
|
|
void*);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief syncs the active journal of a collection
|
|
/// note: the caller must make sure any required locks are held
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
int TRI_SyncCollection (TRI_collection_t*);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief jsonify a parameter info block
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
struct TRI_json_s* TRI_CreateJsonCollectionInfo (TRI_col_info_t const*);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief creates a parameter info block from file
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
int TRI_LoadCollectionInfo (char const*,
|
|
TRI_col_info_t*,
|
|
const bool);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief saves a parameter info block to file
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
int TRI_SaveCollectionInfo (char const*,
|
|
const TRI_col_info_t* const,
|
|
const bool);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief updates the parameter info block
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
int TRI_UpdateCollectionInfo (TRI_vocbase_t*,
|
|
TRI_collection_t*,
|
|
TRI_col_info_t const*);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief renames a collection
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
int TRI_RenameCollection (TRI_collection_t*, char const*);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @}
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
// -----------------------------------------------------------------------------
|
|
// --SECTION-- protected functions
|
|
// -----------------------------------------------------------------------------
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @addtogroup VocBase
|
|
/// @{
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief iterates over a collection
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
bool TRI_IterateCollection (TRI_collection_t*,
|
|
bool (*)(TRI_df_marker_t const*, void*, TRI_datafile_t*, bool),
|
|
void*);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief iterates over all index files of a collection
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
void TRI_IterateIndexCollection (TRI_collection_t*,
|
|
bool (*)(char const*, void*),
|
|
void*);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief opens an existing collection
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
TRI_collection_t* TRI_OpenCollection (TRI_vocbase_t*,
|
|
TRI_collection_t*,
|
|
char const*);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief closes an open collection
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
int TRI_CloseCollection (TRI_collection_t*);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief returns information about the collection files
|
|
///
|
|
/// Note that the collection must not be loaded
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
TRI_col_file_structure_t TRI_FileStructureCollectionDirectory (char const*);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief frees the information
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
void TRI_DestroyFileStructureCollection (TRI_col_file_structure_t*);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief upgrade a collection
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
int TRI_UpgradeCollection (TRI_vocbase_t*,
|
|
const char* const,
|
|
TRI_col_info_t*);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief iterate over the markers in the collection's journals
|
|
///
|
|
/// this function is called on server startup for all collections. we do this
|
|
/// to get the last tick used in a collection
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
bool TRI_IterateTicksCollection (const char* const,
|
|
bool (*)(TRI_df_marker_t const*, void*, TRI_datafile_t*, bool),
|
|
void*);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief determine whether a collection name is a system collection name
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
bool TRI_IsSystemCollectionName (char const*);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief return the type name for a collection
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
char* TRI_TypeNameCollection (const TRI_col_type_e);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @}
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif
|
|
|
|
// Local Variables:
|
|
// mode: outline-minor
|
|
// outline-regexp: "/// @brief\\|/// {@inheritDoc}\\|/// @addtogroup\\|/// @page\\|// --SECTION--\\|/// @\\}"
|
|
// End:
|