upscaledb
2.1.13
|
Typedefs | |
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) |
Functions | |
UPS_EXPORT ups_status_t UPS_CALLCONV | ups_register_compare (const char *name, ups_compare_func_t func) |
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) |
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) |
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) |
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 |
Flag for ups_db_close, ups_env_close
Definition at line 1956 of file upscaledb.h.
Referenced by upscaledb::db::close(), upscaledb::env::close(), and main().
#define UPS_AUTO_RECOVERY 0x00010000 |
Flag for ups_env_open. This flag is non persistent.
Definition at line 1297 of file upscaledb.h.
#define UPS_CACHE_UNLIMITED 0x00040000 |
Flag for ups_env_open, ups_env_create. This flag is non persistent.
Definition at line 1305 of file upscaledb.h.
#define UPS_COMPRESSOR_LZF 3 |
selects lzf compression http://oldhome.schmorp.de/marc/liblzf.html
Definition at line 1878 of file upscaledb.h.
#define UPS_COMPRESSOR_NONE 0 |
helper macro for disabling compression
Definition at line 1860 of file upscaledb.h.
#define UPS_COMPRESSOR_SNAPPY 2 |
selects google snappy compression http://code.google.com/p/snappy
Definition at line 1872 of file upscaledb.h.
#define UPS_COMPRESSOR_UINT32_FOR 10 |
uint32 key compression (FOR - Frame Of Reference)
Definition at line 1909 of file upscaledb.h.
#define UPS_COMPRESSOR_UINT32_GROUPVARINT 7 |
uint32 key compression (Group Varint compression)
Definition at line 1894 of file upscaledb.h.
#define UPS_COMPRESSOR_UINT32_MASKEDVBYTE 9 |
uint32 key compression (Masked Vbyte compression)
Definition at line 1904 of file upscaledb.h.
#define UPS_COMPRESSOR_UINT32_SIMDCOMP 6 |
uint32 key compression (simd compression)
Definition at line 1889 of file upscaledb.h.
#define UPS_COMPRESSOR_UINT32_SIMDFOR 11 |
uint32 key compression (FOR - Frame Of Reference w/ SIMD)
Definition at line 1914 of file upscaledb.h.
#define UPS_COMPRESSOR_UINT32_STREAMVBYTE 8 |
uint32 key compression (Stream Vbyte compression)
Definition at line 1899 of file upscaledb.h.
#define UPS_COMPRESSOR_UINT32_VARBYTE 5 |
uint32 key compression (varbyte) (experimental)
Definition at line 1884 of file upscaledb.h.
#define UPS_COMPRESSOR_ZLIB 1 |
selects zlib compression http://www.zlib.net/
Definition at line 1866 of file upscaledb.h.
#define UPS_DIRECT_ACCESS 0x0040 |
Flag for ups_db_find, ups_cursor_find, ups_cursor_move
Definition at line 1607 of file upscaledb.h.
#define UPS_DISABLE_MMAP 0x00000200 |
Flag for ups_env_open, ups_env_create. This flag is non persistent.
Definition at line 1273 of file upscaledb.h.
#define UPS_DISABLE_RECLAIM_INTERNAL 0x00400000 |
Definition at line 1315 of file upscaledb.h.
#define UPS_DISABLE_RECOVERY 0x00080000 |
Flag for ups_env_create, ups_env_open. This flag is non persistent.
Definition at line 1309 of file upscaledb.h.
#define UPS_DONT_CLEAR_LOG 2 |
Definition at line 1959 of file upscaledb.h.
#define UPS_DONT_FLUSH_TRANSACTIONS 0x04000000 |
Definition at line 1328 of file upscaledb.h.
#define UPS_DUPLICATE 0x0002 |
Flag for ups_db_insert and ups_cursor_insert
Definition at line 1592 of file upscaledb.h.
Referenced by copy_db(), main(), and run_demo().
#define UPS_DUPLICATE_INSERT_AFTER 0x0008 |
Flag for ups_cursor_insert
Definition at line 1598 of file upscaledb.h.
#define UPS_DUPLICATE_INSERT_BEFORE 0x0004 |
Flag for ups_cursor_insert
Definition at line 1595 of file upscaledb.h.
#define UPS_DUPLICATE_INSERT_FIRST 0x0010 |
Flag for ups_cursor_insert
Definition at line 1601 of file upscaledb.h.
#define UPS_DUPLICATE_INSERT_LAST 0x0020 |
Flag for ups_cursor_insert
Definition at line 1604 of file upscaledb.h.
#define UPS_ENABLE_CRC32 0x02000000 |
Flag for ups_env_open, ups_env_create. This flag is non persistent.
Definition at line 1325 of file upscaledb.h.
#define UPS_ENABLE_DUPLICATE_KEYS 0x00004000 |
Flag for ups_env_create_db. This flag is persisted in the Database.
Definition at line 1288 of file upscaledb.h.
Referenced by main(), and run_demo().
#define UPS_ENABLE_DUPLICATES UPS_ENABLE_DUPLICATE_KEYS |
Definition at line 1290 of file upscaledb.h.
#define UPS_ENABLE_FSYNC 0x00000001 |
Flag for ups_env_open, ups_env_create. This flag is non persistent.
Definition at line 1249 of file upscaledb.h.
#define UPS_ENABLE_RECOVERY UPS_ENABLE_TRANSACTIONS |
Definition at line 1293 of file upscaledb.h.
#define UPS_ENABLE_TRANSACTIONS 0x00020000 |
Flag for ups_env_create, ups_env_open. This flag is non persistent.
Definition at line 1301 of file upscaledb.h.
Referenced by main().
#define UPS_ERASE_ALL_DUPLICATES 1 |
Definition at line 1678 of file upscaledb.h.
#define UPS_FLUSH_WHEN_COMMITTED 0x01000000 |
Definition at line 1321 of file upscaledb.h.
#define UPS_FORCE_DEEP_COPY 0x0100 |
Definition at line 1615 of file upscaledb.h.
#define UPS_FORCE_RECORDS_INLINE 0x00800000 |
Definition at line 1318 of file upscaledb.h.
#define UPS_HINT_APPEND 0x00080000 |
Flag for ups_cursor_insert
Mutually exclusive with flag UPS_HINT_PREPEND.
Hints the upscaledb engine that the current key will compare as larger than any key already existing in the Database. The upscaledb engine will verify this postulation and when found not to be true, will revert to a regular insert operation as if this flag was not specified. The incurred cost then is only one additional key comparison.
Definition at line 1629 of file upscaledb.h.
#define UPS_HINT_PREPEND 0x00100000 |
Flag for ups_cursor_insert
Mutually exclusive with flag UPS_HINT_APPEND.
Hints the upscaledb engine that the current key will compare as smaller than any key already existing in the Database. The upscaledb engine will verify this postulation and when found not to be true, will revert to a regular insert operation as if this flag was not specified. The incurred cost then is only one additional key comparison.
Definition at line 1643 of file upscaledb.h.
#define UPS_HINTS_MASK 0x001F0000 |
Flag mask to extract the common hint flags from a find/move/insert/erase flag value.
Definition at line 1649 of file upscaledb.h.
#define UPS_IN_MEMORY 0x00000080 |
Flag for ups_env_create. This flag is non persistent.
Definition at line 1267 of file upscaledb.h.
Referenced by main().
#define UPS_IS_REMOTE_INTERNAL 0x00200000 |
Definition at line 1312 of file upscaledb.h.
#define UPS_KEY_SIZE_UNLIMITED ((uint16_t)-1) |
Value for unlimited key sizes
Definition at line 1807 of file upscaledb.h.
#define UPS_OVERWRITE 0x0001 |
Flag for ups_db_insert and ups_cursor_insert
When specified with ups_db_insert and in case a key is specified which stores duplicates in the Database, the first duplicate record will be overwritten.
When used with ups_cursor_insert and assuming the same conditions, the duplicate currently referenced by the Cursor will be overwritten.
Definition at line 1589 of file upscaledb.h.
#define UPS_PARAM_CACHE_SIZE 0x00000100 |
Parameter name for ups_env_open, ups_env_create; sets the cache size
Definition at line 1750 of file upscaledb.h.
#define UPS_PARAM_CACHESIZE UPS_PARAM_CACHE_SIZE |
Definition at line 1752 of file upscaledb.h.
#define UPS_PARAM_CUSTOM_COMPARE_NAME 0x00000111 |
Parameter name for ups_env_create_db
Definition at line 1795 of file upscaledb.h.
#define UPS_PARAM_DATABASE_NAME 0x00000203 |
Retrieve the Database 'name' number of this ups_db_t Database within the current ups_env_t Environment.
Definition at line 1830 of file upscaledb.h.
#define UPS_PARAM_ENCRYPTION_KEY 0x00000106 |
Parameter name for ups_env_open, ups_env_create; sets the AES encryption key
Definition at line 1777 of file upscaledb.h.
#define UPS_PARAM_FILE_SIZE_LIMIT 0x00000109 |
Parameter name for ups_env_create, ups_env_open; sets a limit for the file size (in bytes)
Definition at line 1788 of file upscaledb.h.
#define UPS_PARAM_FILEMODE 0x00000201 |
Retrieves the filesystem file access mode as was specified at the time of ups_env_create/ups_env_open invocation.
Definition at line 1815 of file upscaledb.h.
#define UPS_PARAM_FILENAME 0x00000202 |
Return a const char *
pointer to the current Environment/Database file name in the uint64_t value member, when the Database is actually stored on disc.
In-memory Databases will return a NULL (0) pointer instead.
Definition at line 1824 of file upscaledb.h.
#define UPS_PARAM_FLAGS 0x00000200 |
Retrieves the Database/Environment flags as were specified at the time of ups_env_create/ups_env_open invocation.
Definition at line 1811 of file upscaledb.h.
#define UPS_PARAM_JOURNAL_COMPRESSION 0x00001000 |
Parameter name for ups_env_create, ups_env_open; enables compression for the journal.
Definition at line 1843 of file upscaledb.h.
#define UPS_PARAM_JOURNAL_SWITCH_THRESHOLD 0x00001 |
Parameter name for ups_env_open, ups_env_create; Journal files are switched whenever the number of new Transactions exceeds this threshold.
Definition at line 1746 of file upscaledb.h.
#define UPS_PARAM_KEY_COMPRESSION 0x00001002 |
Parameter name for ups_env_create_db, ups_env_open_db; enables compression for the records of a Database.
Definition at line 1857 of file upscaledb.h.
#define UPS_PARAM_KEY_SIZE 0x00000102 |
Parameter name for ups_env_create_db; sets the key size
Definition at line 1760 of file upscaledb.h.
#define UPS_PARAM_KEY_TYPE 0x00000104 |
Parameter name for ups_env_create_db; sets the key type
Definition at line 1769 of file upscaledb.h.
Referenced by main(), and run_demo().
#define UPS_PARAM_KEYSIZE UPS_PARAM_KEY_SIZE |
Definition at line 1762 of file upscaledb.h.
#define UPS_PARAM_LOG_DIRECTORY 0x00000105 |
Parameter name for ups_env_open, ups_env_create; sets the path of the log files
Definition at line 1773 of file upscaledb.h.
#define UPS_PARAM_MAX_DATABASES 0x00000103 |
Parameter name for ups_env_get_parameters; retrieves the number of maximum Databases
Definition at line 1766 of file upscaledb.h.
#define UPS_PARAM_MAX_KEYS_PER_PAGE 0x00000204 |
Retrieve the maximum number of keys per page; this number depends on the currently active page and key sizes. Can be an estimate if keys do not have constant sizes or if duplicate keys are used.
Definition at line 1837 of file upscaledb.h.
#define UPS_PARAM_NETWORK_TIMEOUT_SEC 0x00000107 |
Parameter name for ups_env_open, ups_env_create; sets the network timeout (in seconds)
Definition at line 1781 of file upscaledb.h.
#define UPS_PARAM_PAGE_SIZE 0x00000101 |
Parameter name for ups_env_create; sets the page size
Definition at line 1755 of file upscaledb.h.
#define UPS_PARAM_PAGESIZE UPS_PARAM_PAGE_SIZE |
Definition at line 1757 of file upscaledb.h.
#define UPS_PARAM_POSIX_FADVISE 0x00000110 |
Parameter name for ups_env_create, ups_env_open; sets the parameter for posix_fadvise()
Definition at line 1792 of file upscaledb.h.
#define UPS_PARAM_RECORD_COMPRESSION 0x00001001 |
Parameter name for ups_env_create_db, ups_env_open_db; enables compression for the records of a Database.
Definition at line 1850 of file upscaledb.h.
#define UPS_PARAM_RECORD_SIZE 0x00000108 |
Parameter name for ups_env_create_db; sets the key size
Definition at line 1784 of file upscaledb.h.
Referenced by main(), and run_demo().
#define UPS_PARTIAL 0x0080 |
Flag for ups_db_insert, ups_cursor_insert, ups_db_find, ups_cursor_find, ups_cursor_move
Definition at line 1611 of file upscaledb.h.
#define UPS_POSIX_FADVICE_NORMAL 0 |
Value for UPS_PARAM_POSIX_FADVISE
Definition at line 1798 of file upscaledb.h.
#define UPS_POSIX_FADVICE_RANDOM 1 |
Value for UPS_PARAM_POSIX_FADVISE
Definition at line 1801 of file upscaledb.h.
#define UPS_READ_ONLY 0x00000004 |
Flag for ups_env_open, ups_env_open_db. This flag is non persistent.
Definition at line 1255 of file upscaledb.h.
#define UPS_RECORD_NUMBER UPS_RECORD_NUMBER64 |
Definition at line 1276 of file upscaledb.h.
#define UPS_RECORD_NUMBER32 0x00001000 |
Flag for ups_env_create_db. This flag is persisted in the Database.
Definition at line 1280 of file upscaledb.h.
Referenced by main().
#define UPS_RECORD_NUMBER64 0x00002000 |
Flag for ups_env_create_db. This flag is persisted in the Database.
Definition at line 1284 of file upscaledb.h.
Referenced by main().
#define UPS_RECORD_SIZE_UNLIMITED ((uint32_t)-1) |
Value for unlimited record sizes
Definition at line 1804 of file upscaledb.h.
#define UPS_TXN_AUTO_ABORT 4 |
Automatically abort all open Transactions (the default)
Definition at line 1962 of file upscaledb.h.
#define UPS_TXN_AUTO_COMMIT 8 |
Automatically commit all open Transactions
Definition at line 1965 of file upscaledb.h.
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) |
Typedef for a key comparison function
Definition at line 1338 of file upscaledb.h.
UPS_EXPORT ups_status_t UPS_CALLCONV ups_db_close | ( | ups_db_t * | db, |
uint32_t | flags | ||
) |
Closes the Database
This function flushes the Database and then closes the file handle. It also free the memory resources allocated in the db handle.
If the flag UPS_AUTO_CLEANUP is specified, upscaledb automatically calls ups_cursor_close on all open Cursors. This invalidates the ups_cursor_t handle!
If the flag is not specified, the application must close all Database Cursors with ups_cursor_close to prevent memory leaks.
db | A valid Database handle |
flags | Optional flags for closing the Database. Possible values are:
|
Referenced by upscaledb::db::close(), and main().
UPS_EXPORT ups_status_t UPS_CALLCONV ups_db_count | ( | ups_db_t * | db, |
ups_txn_t * | txn, | ||
uint32_t | flags, | ||
uint64_t * | count | ||
) |
Returns the number of keys stored in the Database
You can specify the UPS_SKIP_DUPLICATES if you do now want to include any duplicates in the count. This will also speed up the counting.
db | A valid Database handle |
txn | A Transaction handle, or NULL |
flags | Optional flags:
|
count | A pointer to a variable which will receive the calculated key count per page |
Referenced by upscaledb::db::count().
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 | ||
) |
Erases a Database item
This function erases a Database item. If the item key does not exist, UPS_KEY_NOT_FOUND is returned.
Note that ups_db_erase can not erase a single duplicate key. If the key has multiple duplicates, all duplicates of this key will be erased. Use ups_cursor_erase to erase a specific duplicate key.
db | A valid Database handle |
txn | A Transaction handle, or NULL |
key | The key to delete |
flags | Optional flags for erasing; unused, set to 0 |
Referenced by upscaledb::db::erase(), and main().
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 | ||
) |
Searches an item in the Database
This function searches the Database for key. If the key is found, record will receive the record of this item and UPS_SUCCESS is returned. If the key is not found, the function returns UPS_KEY_NOT_FOUND.
A ups_record_t structure should be initialized with zeroes before it is being used. This can be done with the C library routines memset(3) or bzero(2).
If the function completes successfully, the record pointer is initialized with the size of the record (in record.size) and the actual record data (in record.data). If the record is empty, size is 0 and data points to NULL.
The data pointer is a temporary pointer and will be overwritten by subsequent upscaledb API calls using the same Transaction (or, if Transactions are disabled, using the same Database). You can alter this behaviour by allocating the data pointer in the application and setting record.flags to UPS_RECORD_USER_ALLOC. Make sure that the allocated buffer is large enough.
When specifying UPS_DIRECT_ACCESS, the data pointer will point directly to the record that is stored in upscaledb; the data can be modified, but the pointer must not be reallocated or freed. The flag UPS_DIRECT_ACCESS is only allowed in In-Memory Databases and not if Transactions are enabled.
ups_db_find can not search for duplicate keys. If key has multiple duplicates, only the first duplicate is returned.
You can read only portions of the record by specifying the flag UPS_PARTIAL. In this case, upscaledb will read record->partial_size bytes of the record data at offset record->partial_offset. If necessary, the record data will be limited to the original record size. The number of actually read bytes is returned in record->partial_size. The original size of the record is stored in record->size.
UPS_PARTIAL is not allowed if record->size is <= 8 or if Transactions are enabled. In such a case, UPS_INV_PARAMETER is returned.
If Transactions are enabled (see UPS_ENABLE_TRANSACTIONS) and txn is NULL then upscaledb will create a temporary Transaction. When moving the Cursor, and the new key is currently modified in an active Transaction (one that is not yet committed or aborted) then upscaledb will skip this key and move to the next/previous one. However if flags are 0 (and the Cursor is not moved), and key or rec is NOT NULL, then upscaledb will return error UPS_TXN_CONFLICT.
db | A valid Database handle |
txn | A Transaction handle, or NULL |
key | The key of the item |
record | The record of the item |
flags | Optional flags for searching, which can be combined with bitwise OR. Possible flags are:
|
Referenced by upscaledb::db::find(), and main().
UPS_EXPORT ups_env_t* UPS_CALLCONV ups_db_get_env | ( | ups_db_t * | db | ) |
Retrieves the Environment handle of a Database
db | A valid Database handle |
UPS_EXPORT ups_status_t UPS_CALLCONV ups_db_get_parameters | ( | ups_db_t * | db, |
ups_parameter_t * | param | ||
) |
Retrieve the current value for a given Database setting
Only those values requested by the parameter array will be stored.
The following parameters are supported:
db | A valid Database handle |
param | An array of ups_parameter_t structures |
Referenced by upscaledb::db::get_parameters().
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 | ||
) |
Inserts a Database item
This function inserts a key/record pair as a new Database item.
If the key already exists in the Database, error UPS_DUPLICATE_KEY is returned.
If you wish to overwrite an existing entry specify the flag UPS_OVERWRITE.
You can write only portions of the record by specifying the flag UPS_PARTIAL. In this case, upscaledb will write partial_size bytes of the record data at offset partial_offset. The full record size will always be given in record->size! If partial_size+partial_offset exceed record->size then partial_size will be limited. To shrink or grow the record, adjust record->size. UPS_PARTIAL automatically overwrites existing records. Gaps will be filled with null-bytes if the record did not yet exist.
UPS_PARTIAL is not allowed if record->size is <= 8 or if Transactions are enabled. In such a case, UPS_INV_PARAMETER is returned.
If you wish to insert a duplicate key specify the flag UPS_DUPLICATE. (Note that the Database has to be created with UPS_ENABLE_DUPLICATE_KEYS in order to use duplicate keys.) The duplicate key is inserted after all other duplicate keys (see UPS_DUPLICATE_INSERT_LAST).
Record Number Databases (created with UPS_RECORD_NUMBER32 or UPS_RECORD_NUMBER64) expect either an empty key (with a size of 0 and data pointing to NULL), or a user-supplied key (with key.flag UPS_KEY_USER_ALLOC and a valid data pointer). If key.size is 0 and key.data is NULL, upscaledb will temporarily allocate memory for key->data, which will then point to an 4-byte (or 8-byte) unsigned integer.
For very fast sequential inserts please use ups_cursor_insert in combination with the flag UPS_HINT_APPEND.
db | A valid Database handle |
txn | A Transaction handle, or NULL |
key | The key of the new item |
record | The record of the new item |
flags | Optional flags for inserting. Possible flags are:
|
Referenced by copy_db(), upscaledb::db::insert(), and main().
UPS_EXPORT ups_status_t UPS_CALLCONV ups_db_set_compare_func | ( | ups_db_t * | db, |
ups_compare_func_t | foo | ||
) |
Referenced by main(), and upscaledb::db::set_compare_func().
UPS_EXPORT ups_status_t UPS_CALLCONV ups_register_compare | ( | const char * | name, |
ups_compare_func_t | func | ||
) |
Globally registers a function to compare custom keys
Supplying a comparison function is only allowed for the key type UPS_TYPE_CUSTOM; see the documentation of
When creating a database (
!!! The compare functions should be registered PRIOR to opening or creating Environments!
name | A (case-insensitive) name of the callback function |
func | A pointer to the compare function |