hamsterdb Embedded Database
2.1.7
|
Macros | |
#define | HAM_DONT_LOCK 0xf0000000 |
#define HAM_DONT_LOCK 0xf0000000 |
Definition at line 938 of file hamsterdb.h.
HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_close | ( | ham_env_t * | env, |
ham_u32_t | flags | ||
) |
Closes the Database Environment
This function closes the Database Environment. It also frees the memory resources allocated in the env handle, and tries to truncate the file (see below).
If the flag HAM_AUTO_CLEANUP is specified, hamsterdb automatically calls ham_db_close with flag HAM_AUTO_CLEANUP on all open Databases (which closes all open Databases and their Cursors). This invalidates the ham_db_t and ham_cursor_t handles!
If the flag is not specified, the application must close all Database handles with ham_db_close to prevent memory leaks.
This function also aborts all Transactions which were not yet committed, and therefore renders all Transaction handles invalid. If the flag HAM_TXN_AUTO_COMMIT is specified, all Transactions will be committed.
This function also tries to truncate the file and "cut off" unused space at the end of the file to reduce the file size. This feature is disabled on Win32 if memory mapped I/O is used (see HAM_DISABLE_MMAP).
env | A valid Environment handle |
flags | Optional flags for closing the handle. Possible flags are:
|
Referenced by hamsterdb::env::close(), and main().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_create | ( | ham_env_t ** | env, |
const char * | filename, | ||
ham_u32_t | flags, | ||
ham_u32_t | mode, | ||
const ham_parameter_t * | param | ||
) |
Creates a Database Environment
A Database Environment is a collection of Databases, which are all stored in one physical file (or in-memory). The maximum number of Databases depends on the page size; the default is above 600.
Each Database in an Environment is identified by a positive 16bit value (except 0 and values at or above 0xf000). Databases in an Environment can be created with ham_env_create_db or opened with ham_env_open_db.
Specify a URL instead of a filename (i.e. "ham://localhost:8080/customers.db") to access a remote hamsterdb Server.
To enable ACID Transactions, supply the flag HAM_ENABLE_TRANSACTIONS. By default, hamsterdb will use a Journal for recovering the Environment and its data in case of a crash, and also to re-apply committed Transactions which were not yet flushed to disk. This Journalling can be disabled with the flag HAM_DISABLE_RECOVERY. (It is disabled if the Environment is in-memory.)
If Transactions are not required, but hamsterdb should still be able to recover in case of a crash or power outage, then the flag HAM_ENABLE_RECOVERY will enable the Journal (without allowing Transactions.)
For performance reasons the Journal does not use fsync(2) (or FlushFileBuffers on Win32) to flush modified buffers to disk. Use the flag HAM_ENABLE_FSYNC to force the use of fsync.
env | A pointer to an Environment handle |
filename | The filename of the Environment file. If the file already exists, it is overwritten. Can be NULL for an In-Memory Environment. Can be a URL ("ham://<hostname>:<port>/<environment>") for remote access. |
flags | Optional flags for opening the Environment, combined with bitwise OR. Possible flags are:
|
mode | File access rights for the new file. This is the mode parameter for creat(2). Ignored on Microsoft Windows. Default is 0644. |
param | An array of ham_parameter_t structures. The following parameters are available:
|
Referenced by hamsterdb::env::create(), and main().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_create_db | ( | ham_env_t * | env, |
ham_db_t ** | db, | ||
ham_u16_t | name, | ||
ham_u32_t | flags, | ||
const ham_parameter_t * | params | ||
) |
Creates a new Database in a Database Environment
An Environment can contain a (limited) amount of Databases; the exact limit depends on the page size and is above 600.
Each Database in an Environment is identified by a positive 16bit value. 0 and values at or above 0xf000 are reserved.
This function initializes the ham_db_t handle (the second parameter). When the handle is no longer in use, it should be closed with ham_db_close. Alternatively, the Database handle is closed automatically if ham_env_close is called with the flag HAM_AUTO_CLEANUP.
A Database can be configured and optimized for the data that is inserted. The data is described through flags and parameters. hamsterdb differentiates between several data characteristics, and offers predefined "types" to describe the keys. Numeric key types are stored in host endian format and are NOT endian converted! In general, the default key type (HAM_TYPE_BINARY) is slower than the other types, and fixed-length binary keys (HAM_TYPE_BINARY in combination with HAM_PARAM_KEY_SIZE) is faster than variable-length binary keys. It is therefore recommended to set the key size and record size, although it is not required. See the Wiki documentation for Evaluating and Benchmarking on how to test different configurations and optimize for performance.
The key type is set with HAM_PARAM_KEY_TYPE and can have either of the following values:
If the key type is ommitted then HAM_TYPE_BINARY is the default.
If binary/custom keys are so big that they cannot be stored in the Btree, then the full key will be stored in an overflow area, which has performance implications when accessing such keys.
In addition to the flags above, you can specify HAM_ENABLE_DUPLICATE_KEYS to insert duplicate keys, i.e. to model 1:n or n:m relationships.
If the size of the records is always constant, then HAM_PARAM_RECORD_SIZE should be used to specify this size. This allows hamsterdb to optimize the record storage, and small records will automatically be stored in the Btree's leaf nodes instead of a separately allocated blob, allowing faster access. A record size of 0 is valid and suited for boolean values ("key exists" vs "key doesn't exist"). The default record size is HAM_RECORD_SIZE_UNLIMITED.
env | A valid Environment handle. |
db | A valid Database handle, which will point to the created Database. To close the handle, use ham_db_close. |
name | The name of the Database. If a Database with this name already exists, the function will fail with HAM_DATABASE_ALREADY_EXISTS. Database names from 0xf000 to 0xffff and 0 are reserved. |
flags | Optional flags for creating the Database, combined with bitwise OR. Possible flags are:
|
params | An array of ham_parameter_t structures. The following parameters are available:
|
Referenced by hamsterdb::env::create_db(), and main().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_erase_db | ( | ham_env_t * | env, |
ham_u16_t | name, | ||
ham_u32_t | flags | ||
) |
Deletes a Database from an Environment
env | A valid Environment handle |
name | The name of the Database to delete. If a Database with this name does not exist, the function will fail with HAM_DATABASE_NOT_FOUND. If the Database was already opened, the function will fail with HAM_DATABASE_ALREADY_OPEN. |
flags | Optional flags for deleting the Database; unused, set to 0. |
Referenced by hamsterdb::env::erase_db().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_flush | ( | ham_env_t * | env, |
ham_u32_t | flags | ||
) |
Flushes the Environment
This function flushes the Environment caches and writes the whole file to disk. All Databases of this Environment are flushed as well.
Since In-Memory Databases do not have a file on disk, the function will have no effect and will return HAM_SUCCESS.
env | A valid Environment handle |
flags | Optional flags for flushing; unused, set to 0 |
Referenced by hamsterdb::env::flush().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_get_database_names | ( | ham_env_t * | env, |
ham_u16_t * | names, | ||
ham_u32_t * | count | ||
) |
Returns the names of all Databases in an Environment
This function returns the names of all Databases and the number of Databases in an Environment.
The memory for names must be allocated by the user. count must be the size of names when calling the function, and will be the number of Databases when the function returns. The function returns HAM_LIMITS_REACHED if names is not big enough; in this case, the caller should resize the array and call the function again.
env | A valid Environment handle |
names | Pointer to an array for the Database names |
count | Pointer to the size of the array; will be used to store the number of Databases when the function returns. |
Referenced by hamsterdb::env::get_database_names().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_get_parameters | ( | ham_env_t * | env, |
ham_parameter_t * | param | ||
) |
Retrieve the current value for a given Environment setting
Only those values requested by the parameter array will be stored.
The following parameters are supported:
env | A valid Environment handle |
param | An array of ham_parameter_t structures |
Referenced by hamsterdb::env::get_parameters().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_open | ( | ham_env_t ** | env, |
const char * | filename, | ||
ham_u32_t | flags, | ||
const ham_parameter_t * | param | ||
) |
Opens an existing Database Environment
This function opens an existing Database Environment.
A Database Environment is a collection of Databases, which are all stored in one physical file (or in-memory).
Each Database in an Environment is identified by a positive 16bit value (except 0 and values at or above 0xf000). Databases in an Environment can be created with ham_env_create_db or opened with ham_env_open_db.
Specify a URL instead of a filename (i.e. "ham://localhost:8080/customers.db") to access a remote hamsterdb Server.
Also see the documentation ham_env_create about Transactions, Recovery and the use of fsync.
env | A valid Environment handle |
filename | The filename of the Environment file, or URL of a hamsterdb Server |
flags | Optional flags for opening the Environment, combined with bitwise OR. Possible flags are:
|
param | An array of ham_parameter_t structures. The following parameters are available:
|
Referenced by main(), and hamsterdb::env::open().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_open_db | ( | ham_env_t * | env, |
ham_db_t ** | db, | ||
ham_u16_t | name, | ||
ham_u32_t | flags, | ||
const ham_parameter_t * | params | ||
) |
Opens a Database in a Database Environment
Each Database in an Environment is identified by a positive 16bit value (except 0 and values at or above 0xf000).
This function initializes the ham_db_t handle (the second parameter). When the handle is no longer in use, it should be closed with ham_db_close. Alternatively, the Database handle is closed automatically if ham_env_close is called with the flag HAM_AUTO_CLEANUP.
env | A valid Environment handle |
db | A valid Database handle, which will point to the opened Database. To close the handle, use |
name | The name of the Database. If a Database with this name does not exist, the function will fail with HAM_DATABASE_NOT_FOUND. |
flags | Optional flags for opening the Database, combined with bitwise OR. Possible flags are:
|
params | Reserved; set to NULL |
Referenced by main(), and hamsterdb::env::open_db().
HAM_EXPORT ham_status_t HAM_CALLCONV ham_env_rename_db | ( | ham_env_t * | env, |
ham_u16_t | oldname, | ||
ham_u16_t | newname, | ||
ham_u32_t | flags | ||
) |
Renames a Database in an Environment.
env | A valid Environment handle. |
oldname | The old name of the existing Database. If a Database with this name does not exist, the function will fail with HAM_DATABASE_NOT_FOUND. |
newname | The new name of this Database. If a Database with this name already exists, the function will fail with HAM_DATABASE_ALREADY_EXISTS. |
flags | Optional flags for renaming the Database, combined with bitwise OR; unused, set to 0. |
Referenced by hamsterdb::env::rename_db().