upscaledb.h

Go to the documentation of this file.

/*
 * Copyright (C) 2005-2017 Christoph Rupp (chris@crupp.de).
 *
 * 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.
 *
 * See the file COPYING for License information.
 */

#ifndef UPS_UPSCALEDB_H
#define UPS_UPSCALEDB_H

#include <ups/types.h>

#ifdef __cplusplus
extern "C" {
#endif

/* deprecated */
#define UPS_API_REVISION        4

#define UPS_VERSION_MAJ     2
#define UPS_VERSION_MIN     2
#define UPS_VERSION_REV     1
#define UPS_FILE_VERSION    5

struct ups_db_t;
typedef struct ups_db_t ups_db_t;

struct ups_env_t;
typedef struct ups_env_t ups_env_t;

struct ups_cursor_t;
typedef struct ups_cursor_t ups_cursor_t;

typedef struct {
  uint32_t size;

  void *data;

  uint32_t flags;

} ups_record_t;

#define UPS_RECORD_USER_ALLOC   1

#define ups_make_record(PTR, SIZE) { SIZE, PTR, 0 }

typedef struct {
  uint16_t size;

  void *data;

  uint32_t flags;

  uint32_t _flags;

} ups_key_t;

#define ups_make_key(PTR, SIZE) { SIZE, PTR, 0, 0 }

#define UPS_KEY_USER_ALLOC    1

typedef struct {
  uint32_t name;

  uint64_t value;

} ups_parameter_t;


#define UPS_TYPE_BINARY                      0

#define UPS_TYPE_CUSTOM                      1

#define UPS_TYPE_UINT8                       3

#define UPS_TYPE_UINT16                      5

#define UPS_TYPE_UINT32                      7

#define UPS_TYPE_UINT64                      9

#define UPS_TYPE_REAL32                     11

#define UPS_TYPE_REAL64                     12

#define UPS_SUCCESS                     (  0)

#define UPS_INV_RECORD_SIZE             ( -2)

#define UPS_INV_KEY_SIZE                ( -3)
/* deprecated */
#define UPS_INV_KEYSIZE                 UPS_INV_KEY_SIZE

#define UPS_INV_PAGE_SIZE               ( -4)
/* deprecated */
#define UPS_INV_PAGESIZE                UPS_INV_PAGE_SIZE

#define UPS_OUT_OF_MEMORY               ( -6)

#define UPS_INV_PARAMETER               ( -8)

#define UPS_INV_FILE_HEADER             ( -9)

#define UPS_INV_FILE_VERSION            (-10)

#define UPS_KEY_NOT_FOUND               (-11)

#define UPS_DUPLICATE_KEY               (-12)

#define UPS_INTEGRITY_VIOLATED          (-13)

#define UPS_INTERNAL_ERROR              (-14)

#define UPS_WRITE_PROTECTED             (-15)

#define UPS_BLOB_NOT_FOUND              (-16)

#define UPS_IO_ERROR                    (-18)

#define UPS_NOT_IMPLEMENTED             (-20)

#define UPS_FILE_NOT_FOUND              (-21)

#define UPS_WOULD_BLOCK                 (-22)

#define UPS_NOT_READY                   (-23)

#define UPS_LIMITS_REACHED              (-24)

#define UPS_ALREADY_INITIALIZED         (-27)

#define UPS_NEED_RECOVERY               (-28)

#define UPS_CURSOR_STILL_OPEN           (-29)

#define UPS_FILTER_NOT_FOUND            (-30)

#define UPS_TXN_CONFLICT                (-31)
/* internal use: key was erased in a Txn */
#define UPS_KEY_ERASED_IN_TXN           (-32)

#define UPS_TXN_STILL_OPEN              (-33)

#define UPS_CURSOR_IS_NIL               (-100)

#define UPS_DATABASE_NOT_FOUND          (-200)

#define UPS_DATABASE_ALREADY_EXISTS     (-201)

#define UPS_DATABASE_ALREADY_OPEN       (-202)

#define UPS_ENVIRONMENT_ALREADY_OPEN    (-203)

#define UPS_LOG_INV_FILE_HEADER         (-300)

#define UPS_NETWORK_ERROR               (-400)

#define UPS_PLUGIN_NOT_FOUND            (-500)

#define UPS_PARSER_ERROR                (-501)

#define UPS_PLUGIN_ALREADY_EXISTS       (-502)

typedef void UPS_CALLCONV (*ups_error_handler_fun)(int level, const char *message);

#define UPS_DEBUG_LEVEL_DEBUG     0

#define UPS_DEBUG_LEVEL_NORMAL    1

#define UPS_DEBUG_LEVEL_FATAL     3

UPS_EXPORT void UPS_CALLCONV
ups_set_error_handler(ups_error_handler_fun f);

UPS_EXPORT const char * UPS_CALLCONV
ups_strerror(ups_status_t status);

UPS_EXPORT void UPS_CALLCONV
ups_get_version(uint32_t *major, uint32_t *minor,
            uint32_t *revision);

UPS_EXPORT ups_status_t UPS_CALLCONV
ups_env_create(ups_env_t **env, const char *filename,
            uint32_t flags, uint32_t mode, const ups_parameter_t *param);

UPS_EXPORT ups_status_t UPS_CALLCONV
ups_env_open(ups_env_t **env, const char *filename,
            uint32_t flags, const ups_parameter_t *param);

UPS_EXPORT ups_status_t UPS_CALLCONV
ups_env_get_parameters(ups_env_t *env, ups_parameter_t *param);

UPS_EXPORT ups_status_t UPS_CALLCONV
ups_env_create_db(ups_env_t *env, ups_db_t **db,
            uint16_t name, uint32_t flags, const ups_parameter_t *params);

UPS_EXPORT ups_status_t UPS_CALLCONV
ups_env_open_db(ups_env_t *env, ups_db_t **db,
            uint16_t name, uint32_t flags, const ups_parameter_t *params);

UPS_EXPORT ups_status_t UPS_CALLCONV
ups_env_rename_db(ups_env_t *env, uint16_t oldname,
            uint16_t newname, uint32_t flags);

UPS_EXPORT ups_status_t UPS_CALLCONV
ups_env_erase_db(ups_env_t *env, uint16_t name, uint32_t flags);

/* internal flag - only flush committed transactions, not the btree pages */
#define UPS_FLUSH_COMMITTED_TRANSACTIONS    1

UPS_EXPORT ups_status_t UPS_CALLCONV
ups_env_flush(ups_env_t *env, uint32_t flags);

/* internal use only - don't lock mutex */
#define UPS_DONT_LOCK        0xf0000000

UPS_EXPORT ups_status_t UPS_CALLCONV
ups_env_get_database_names(ups_env_t *env, uint16_t *names,
            uint32_t *length);

UPS_EXPORT ups_status_t UPS_CALLCONV
ups_env_close(ups_env_t *env, uint32_t flags);

struct ups_txn_t;
typedef struct ups_txn_t ups_txn_t;

UPS_EXPORT ups_status_t
ups_txn_begin(ups_txn_t **txn, ups_env_t *env, const char *name,
            void *reserved, uint32_t flags);

#define UPS_TXN_READ_ONLY                     1

/* Internal flag for @ref ups_txn_begin */
#define UPS_TXN_TEMPORARY                     2

UPS_EXPORT const char *
ups_txn_get_name(ups_txn_t *txn);

UPS_EXPORT ups_status_t
ups_txn_commit(ups_txn_t *txn, uint32_t flags);

UPS_EXPORT ups_status_t
ups_txn_abort(ups_txn_t *txn, uint32_t flags);

#define UPS_ENABLE_FSYNC                            0x00000001

/* internal flag */
#define UPS_IGNORE_MISSING_CALLBACK                 0x00000002 

#define UPS_READ_ONLY                               0x00000004

/* unused                                           0x00000008 */

/* unused                                           0x00000010 */

/* reserved                                         0x00000020 */

/* unused                                           0x00000040 */

#define UPS_IN_MEMORY                               0x00000080

/* reserved: DB_USE_MMAP (not persistent)           0x00000100 */

#define UPS_DISABLE_MMAP                            0x00000200

/* deprecated */
#define UPS_RECORD_NUMBER                           UPS_RECORD_NUMBER64

#define UPS_RECORD_NUMBER32                         0x00001000

#define UPS_RECORD_NUMBER64                         0x00002000

#define UPS_ENABLE_DUPLICATE_KEYS                   0x00004000
/* deprecated */
#define UPS_ENABLE_DUPLICATES                       UPS_ENABLE_DUPLICATE_KEYS

/* deprecated */
#define UPS_ENABLE_RECOVERY                         UPS_ENABLE_TRANSACTIONS

#define UPS_AUTO_RECOVERY                           0x00010000

#define UPS_ENABLE_TRANSACTIONS                     0x00020000

#define UPS_CACHE_UNLIMITED                         0x00040000

#define UPS_DISABLE_RECOVERY                        0x00080000

/* internal use only! (not persistent) */
#define UPS_IS_REMOTE_INTERNAL                      0x00200000

/* internal use only! (not persistent) */
#define UPS_DISABLE_RECLAIM_INTERNAL                0x00400000

/* internal use only! (persistent) */
#define UPS_FORCE_RECORDS_INLINE                    0x00800000

#define UPS_ENABLE_CRC32                            0x02000000

/* internal use only! (not persistent) */
#define UPS_DONT_FLUSH_TRANSACTIONS                 0x04000000

#define UPS_FLUSH_TRANSACTIONS_IMMEDIATELY          0x08000000

typedef int UPS_CALLCONV (*ups_compare_func_t)(ups_db_t *db,
                  const uint8_t *lhs, uint32_t lhs_length,
                  const uint8_t *rhs, uint32_t rhs_length);

UPS_EXPORT ups_status_t UPS_CALLCONV
ups_register_compare(const char *name, ups_compare_func_t func);

/* deprecated */
UPS_EXPORT ups_status_t UPS_CALLCONV
ups_db_set_compare_func(ups_db_t *db, ups_compare_func_t foo);

UPS_EXPORT ups_status_t UPS_CALLCONV
ups_db_find(ups_db_t *db, ups_txn_t *txn, ups_key_t *key,
            ups_record_t *record, uint32_t flags);

UPS_EXPORT ups_status_t UPS_CALLCONV
ups_db_insert(ups_db_t *db, ups_txn_t *txn, ups_key_t *key,
            ups_record_t *record, uint32_t flags);

#define UPS_OVERWRITE                   0x0001

#define UPS_DUPLICATE                   0x0002

#define UPS_DUPLICATE_INSERT_BEFORE     0x0004

#define UPS_DUPLICATE_INSERT_AFTER      0x0008

#define UPS_DUPLICATE_INSERT_FIRST      0x0010

#define UPS_DUPLICATE_INSERT_LAST       0x0020

/* internal flag */
#define UPS_DIRECT_ACCESS               0x0040

/* internal flag */
#define UPS_FORCE_DEEP_COPY             0x0100

/* internal flag */
#define UPS_HINT_APPEND                 0x00080000

/* internal flag */
#define UPS_HINT_PREPEND                0x00100000

UPS_EXPORT ups_status_t UPS_CALLCONV
ups_db_erase(ups_db_t *db, ups_txn_t *txn, ups_key_t *key, uint32_t flags);

/* internal flag for ups_db_erase() - do not use */
#define UPS_ERASE_ALL_DUPLICATES                1

UPS_EXPORT ups_status_t UPS_CALLCONV
ups_db_count(ups_db_t *db, ups_txn_t *txn, uint32_t flags, uint64_t *count);

UPS_EXPORT ups_status_t UPS_CALLCONV
ups_db_get_parameters(ups_db_t *db, ups_parameter_t *param);

#define UPS_PARAM_JOURNAL_SWITCH_THRESHOLD 0x00001

#define UPS_PARAM_CACHE_SIZE            0x00000100
/* deprecated */
#define UPS_PARAM_CACHESIZE             UPS_PARAM_CACHE_SIZE

#define UPS_PARAM_PAGE_SIZE             0x00000101
/* deprecated */
#define UPS_PARAM_PAGESIZE              UPS_PARAM_PAGE_SIZE

#define UPS_PARAM_KEY_SIZE              0x00000102
/* deprecated */
#define UPS_PARAM_KEYSIZE               UPS_PARAM_KEY_SIZE

#define UPS_PARAM_MAX_DATABASES         0x00000103

#define UPS_PARAM_KEY_TYPE              0x00000104

#define UPS_PARAM_LOG_DIRECTORY         0x00000105

#define UPS_PARAM_ENCRYPTION_KEY        0x00000106

#define UPS_PARAM_NETWORK_TIMEOUT_SEC   0x00000107

#define UPS_PARAM_RECORD_SIZE           0x00000108

#define UPS_PARAM_FILE_SIZE_LIMIT       0x00000109

#define UPS_PARAM_POSIX_FADVISE         0x00000110

#define UPS_PARAM_CUSTOM_COMPARE_NAME   0x00000111

#define UPS_PARAM_RECORD_TYPE           0x00000112

#define UPS_POSIX_FADVICE_NORMAL                 0

#define UPS_POSIX_FADVICE_RANDOM                 1

#define UPS_RECORD_SIZE_UNLIMITED       ((uint32_t)-1)

#define UPS_KEY_SIZE_UNLIMITED          ((uint16_t)-1)

#define UPS_PARAM_FLAGS                 0x00000200

#define UPS_PARAM_FILEMODE              0x00000201

#define UPS_PARAM_FILENAME              0x00000202

#define UPS_PARAM_DATABASE_NAME         0x00000203

#define UPS_PARAM_MAX_KEYS_PER_PAGE     0x00000204

#define UPS_PARAM_JOURNAL_COMPRESSION   0x00001000

#define UPS_PARAM_RECORD_COMPRESSION    0x00001001

#define UPS_PARAM_KEY_COMPRESSION       0x00001002

#define UPS_COMPRESSOR_NONE         0

#define UPS_COMPRESSOR_ZLIB         1

#define UPS_COMPRESSOR_SNAPPY       2

#define UPS_COMPRESSOR_LZF          3

#define UPS_COMPRESSOR_UINT32_VARBYTE       5
#define UPS_COMPRESSOR_UINT32_MASKEDVBYTE   UPS_COMPRESSOR_UINT32_VARBYTE

#define UPS_COMPRESSOR_UINT32_SIMDCOMP      6

/* deprecated */
#define UPS_COMPRESSOR_UINT32_GROUPVARINT   7

/* deprecated */
#define UPS_COMPRESSOR_UINT32_STREAMVBYTE   8

#define UPS_COMPRESSOR_UINT32_FOR          10

#define UPS_COMPRESSOR_UINT32_SIMDFOR      11

UPS_EXPORT ups_env_t *UPS_CALLCONV
ups_db_get_env(ups_db_t *db);

UPS_EXPORT ups_status_t UPS_CALLCONV
ups_db_close(ups_db_t *db, uint32_t flags);

#define UPS_AUTO_CLEANUP                1

#define UPS_DONT_CLEAR_LOG              2

#define UPS_TXN_AUTO_ABORT              4

#define UPS_TXN_AUTO_COMMIT             8

UPS_EXPORT ups_status_t UPS_CALLCONV
ups_cursor_create(ups_cursor_t **cursor, ups_db_t *db, ups_txn_t *txn,
            uint32_t flags);

UPS_EXPORT ups_status_t UPS_CALLCONV
ups_cursor_clone(ups_cursor_t *src, ups_cursor_t **dest);

UPS_EXPORT ups_status_t UPS_CALLCONV
ups_cursor_move(ups_cursor_t *cursor, ups_key_t *key,
            ups_record_t *record, uint32_t flags);

#define UPS_CURSOR_FIRST                0x0001

#define UPS_CURSOR_LAST                 0x0002

#define UPS_CURSOR_NEXT                 0x0004

#define UPS_CURSOR_PREVIOUS             0x0008

#define UPS_SKIP_DUPLICATES             0x0010

#define UPS_ONLY_DUPLICATES             0x0020

UPS_EXPORT ups_status_t UPS_CALLCONV
ups_cursor_overwrite(ups_cursor_t *cursor, ups_record_t *record,
            uint32_t flags);

UPS_EXPORT ups_status_t UPS_CALLCONV
ups_cursor_find(ups_cursor_t *cursor, ups_key_t *key,
            ups_record_t *record, uint32_t flags);

/* internal flag */
#define UPS_FIND_EQ_MATCH            0x4000

#define UPS_FIND_LT_MATCH               0x1000

#define UPS_FIND_GT_MATCH               0x2000

#define UPS_FIND_LEQ_MATCH      (UPS_FIND_LT_MATCH | UPS_FIND_EQ_MATCH)

#define UPS_FIND_GEQ_MATCH      (UPS_FIND_GT_MATCH | UPS_FIND_EQ_MATCH)

#define UPS_FIND_NEAR_MATCH     (UPS_FIND_LT_MATCH | UPS_FIND_GT_MATCH  \
                                  | UPS_FIND_EQ_MATCH)

UPS_EXPORT ups_status_t UPS_CALLCONV
ups_cursor_insert(ups_cursor_t *cursor, ups_key_t *key,
            ups_record_t *record, uint32_t flags);

UPS_EXPORT ups_status_t UPS_CALLCONV
ups_cursor_erase(ups_cursor_t *cursor, uint32_t flags);

UPS_EXPORT ups_status_t UPS_CALLCONV
ups_cursor_get_duplicate_count(ups_cursor_t *cursor,
            uint32_t *count, uint32_t flags);

UPS_EXPORT ups_status_t UPS_CALLCONV
ups_cursor_get_duplicate_position(ups_cursor_t *cursor,
            uint32_t *position);

UPS_EXPORT ups_status_t UPS_CALLCONV
ups_cursor_get_record_size(ups_cursor_t *cursor, uint32_t *size);

UPS_EXPORT ups_status_t UPS_CALLCONV
ups_cursor_close(ups_cursor_t *cursor);

#ifdef __cplusplus
} // extern "C"
#endif

#endif /* UPS_UPSCALEDB_H */