hamsterdb Embedded Database  2.1.7
Macros | Functions
hamsterdb Environment Functions

Macros

#define HAM_DONT_LOCK   0xf0000000
 

Functions

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)
 
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)
 
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_env_get_parameters (ham_env_t *env, ham_parameter_t *param)
 
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)
 
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)
 
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)
 
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_env_erase_db (ham_env_t *env, ham_u16_t name, ham_u32_t flags)
 
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_env_flush (ham_env_t *env, ham_u32_t flags)
 
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_env_get_database_names (ham_env_t *env, ham_u16_t *names, ham_u32_t *count)
 
HAM_EXPORT ham_status_t
HAM_CALLCONV 
ham_env_close (ham_env_t *env, ham_u32_t flags)
 

Detailed Description

Macro Definition Documentation

#define HAM_DONT_LOCK   0xf0000000

Definition at line 938 of file hamsterdb.h.

Function Documentation

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).

Parameters
envA valid Environment handle
flagsOptional flags for closing the handle. Possible flags are:
Returns
HAM_SUCCESS upon success
HAM_INV_PARAMETER if env is NULL

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.

Parameters
envA pointer to an Environment handle
filenameThe 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.
flagsOptional flags for opening the Environment, combined with bitwise OR. Possible flags are:
  • HAM_ENABLE_FSYNC Flushes all file handles after committing or aborting a Transaction using fsync(), fdatasync() or FlushFileBuffers(). This file has no effect if Transactions are disabled. Slows down performance but makes sure that all file handles and operating system caches are transferred to disk, thus providing a stronger durability.
  • HAM_IN_MEMORY Creates an In-Memory Environment. No file will be created, and the Database contents are lost after the Environment is closed. The filename parameter can be NULL. Do NOT specify cache_size other than 0.
  • HAM_DISABLE_MMAP Do not use memory mapped files for I/O. By default, hamsterdb checks if it can use mmap, since mmap is faster than read/write. For performance reasons, this flag should not be used.
  • HAM_CACHE_UNLIMITED Do not limit the cache. Nearly as fast as an In-Memory Database. Not allowed in combination with a limited cache size.
  • HAM_ENABLE_TRANSACTIONS Enables Transactions for this Environment. This flag implies HAM_ENABLE_RECOVERY.
  • HAM_ENABLE_RECOVERY Enables logging/recovery for this Environment. Not allowed in combination with HAM_IN_MEMORY.
  • HAM_DISABLE_RECOVERY Disables logging/recovery for this Environment.
  • HAM_FLUSH_WHEN_COMMITTED Immediately flushes committed Transactions and writes them to the Btree. Disabled by default. If disabled then hamsterdb buffers committed Transactions and only starts flushing when too many Transactions were committed.
modeFile access rights for the new file. This is the mode parameter for creat(2). Ignored on Microsoft Windows. Default is 0644.
paramAn array of ham_parameter_t structures. The following parameters are available:
  • HAM_PARAM_CACHE_SIZE The size of the Database cache, in bytes. The default size is defined in src/config.h as HAM_DEFAULT_CACHE_SIZE - usually 2MB
  • HAM_PARAM_PAGE_SIZE The size of a file page, in bytes. It is recommended not to change the default size. The default size depends on hardware and operating system. Page sizes must be 1024 or a multiple of 2048.
  • HAM_PARAM_LOG_DIRECTORY The path of the log file and the journal files; default is the same path as the database file. Ignored for remote Environments.
  • HAM_PARAM_NETWORK_TIMEOUT_SEC Timeout (in seconds) when waiting for data from a remote server. By default, no timeout is set.
Returns
HAM_SUCCESS upon success
HAM_INV_PARAMETER if the env pointer is NULL or an invalid combination of flags or parameters was specified
HAM_IO_ERROR if the file could not be opened or reading/writing failed
HAM_INV_FILE_VERSION if the Environment version is not compatible with the library version
HAM_OUT_OF_MEMORY if memory could not be allocated
HAM_INV_PAGE_SIZE if page_size is not 1024 or a multiple of 2048
HAM_INV_KEY_SIZE if key_size is too large (at least 4 keys must fit in a page)
HAM_WOULD_BLOCK if another process has locked the file
HAM_ENVIRONMENT_ALREADY_OPEN if env is already in use
See Also
ham_env_create
ham_env_close
ham_env_open

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:

  • HAM_TYPE_BINARY This is the default key type: a binary blob. Internally, hamsterdb uses memcmp(3) for the sort order. Key size depends on HAM_PARAM_KEY_SIZE and is unlimited (HAM_KEY_SIZE_UNLIMITED) by default.
  • HAM_TYPE_CUSTOM Similar to HAM_TYPE_BINARY, but uses a callback function for the sort order. This function is supplied by the application with
    See Also
    ham_db_set_compare_func.
  • HAM_TYPE_UINT8 Key is a 8bit (1 byte) unsigned integer
  • HAM_TYPE_UINT16 Key is a 16bit (2 byte) unsigned integer
  • HAM_TYPE_UINT32 Key is a 32bit (4 byte) unsigned integer
  • HAM_TYPE_UINT64 Key is a 64bit (8 byte) unsigned integer
  • HAM_TYPE_REAL32 Key is a 32bit (4 byte) float
  • HAM_TYPE_REAL64 Key is a 64bit (8 byte) doubles

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.

Parameters
envA valid Environment handle.
dbA valid Database handle, which will point to the created Database. To close the handle, use ham_db_close.
nameThe 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.
flagsOptional flags for creating the Database, combined with bitwise OR. Possible flags are:
  • HAM_ENABLE_DUPLICATE_KEYS Enable duplicate keys for this Database. By default, duplicate keys are disabled.
  • HAM_RECORD_NUMBER Creates an "auto-increment" Database. Keys in Record Number Databases are automatically assigned an incrementing 64bit value. If key->data is not NULL (and key->flags is HAM_KEY_USER_ALLOC and key->size is 8), the value of the current key is returned in key (a host-endian 64bit number of type ham_u64_t). If key-data is NULL and key->size is 0, key->data is temporarily allocated by hamsterdb.
paramsAn array of ham_parameter_t structures. The following parameters are available:
Returns
HAM_SUCCESS upon success
HAM_INV_PARAMETER if the env pointer is NULL or an invalid combination of flags was specified
HAM_DATABASE_ALREADY_EXISTS if a Database with this name already exists in this Environment
HAM_OUT_OF_MEMORY if memory could not be allocated
HAM_LIMITS_REACHED if the maximum number of Databases per Environment was already created

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

Parameters
envA valid Environment handle
nameThe 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.
flagsOptional flags for deleting the Database; unused, set to 0.
Returns
HAM_SUCCESS upon success
HAM_INV_PARAMETER if the env pointer is NULL or if the new Database name is reserved
HAM_DATABASE_NOT_FOUND if a Database with this name does not exist
HAM_DATABASE_ALREADY_OPEN if a Database with this name is still open

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.

Parameters
envA valid Environment handle
flagsOptional flags for flushing; unused, set to 0
Returns
HAM_SUCCESS upon success
HAM_INV_PARAMETER if db is NULL

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.

Parameters
envA valid Environment handle
namesPointer to an array for the Database names
countPointer to the size of the array; will be used to store the number of Databases when the function returns.
Returns
HAM_SUCCESS upon success
HAM_INV_PARAMETER if env, names or count is NULL
HAM_LIMITS_REACHED if names is not large enough to hold all Database names

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:

  • HAM_PARAM_CACHE_SIZE returns the cache size
  • HAM_PARAM_PAGE_SIZE returns the page size
  • HAM_PARAM_MAX_DATABASES returns the max. number of Databases of this Database's Environment
  • HAM_PARAM_FLAGS returns the flags which were used to open or create this Database
  • HAM_PARAM_FILEMODE returns the mode parameter which was specified when creating this Database
  • HAM_PARAM_FILENAME returns the filename (the value of this parameter is a const char * pointer casted to a ham_u64_t variable)
  • HAM_PARAM_LOG_DIRECTORY The path of the log file and the journal files. Ignored for remote Environments.
  • HAM_PARAM_JOURNAL_COMPRESSION Returns the selected algorithm for journal compression, or 0 if compression is disabled
Parameters
envA valid Environment handle
paramAn array of ham_parameter_t structures
Returns
HAM_SUCCESS upon success
HAM_INV_PARAMETER if the env pointer is NULL or param is NULL

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.

Parameters
envA valid Environment handle
filenameThe filename of the Environment file, or URL of a hamsterdb Server
flagsOptional flags for opening the Environment, combined with bitwise OR. Possible flags are:
  • HAM_READ_ONLY Opens the file for reading only. Operations that need write access (i.e. ham_db_insert) will return HAM_WRITE_PROTECTED.
  • HAM_ENABLE_FSYNC Flushes all file handles after committing or aborting a Transaction using fsync(), fdatasync() or FlushFileBuffers(). This file has no effect if Transactions are disabled. Slows down performance but makes sure that all file handles and operating system caches are transferred to disk, thus providing a stronger durability.
  • HAM_DISABLE_MMAP Do not use memory mapped files for I/O. By default, hamsterdb checks if it can use mmap, since mmap is faster than read/write. For performance reasons, this flag should not be used.
  • HAM_CACHE_UNLIMITED Do not limit the cache. Nearly as fast as an In-Memory Database. Not allowed in combination with a limited cache size.
  • HAM_ENABLE_TRANSACTIONS Enables Transactions for this Environment. This flag imples HAM_ENABLE_RECOVERY.
  • HAM_ENABLE_RECOVERY Enables logging/recovery for this Environment. Will return HAM_NEED_RECOVERY, if the Environment is in an inconsistent state. Not allowed in combination with HAM_IN_MEMORY.
  • HAM_DISABLE_RECOVERY Disables logging/recovery for this Environment.
  • HAM_AUTO_RECOVERY Automatically recover the Environment, if necessary. This flag implies HAM_ENABLE_RECOVERY.
  • HAM_FLUSH_WHEN_COMMITTED Immediately flushes committed Transactions and writes them to the Btree. Disabled by default. If disabled then hamsterdb buffers committed Transactions and only starts flushing when too many Transactions were committed.
paramAn array of ham_parameter_t structures. The following parameters are available:
  • HAM_PARAM_CACHE_SIZE The size of the Database cache, in bytes. The default size is defined in src/config.h as HAM_DEFAULT_CACHE_SIZE - usually 2MB
  • HAM_PARAM_LOG_DIRECTORY The path of the log file and the journal files; default is the same path as the database file. Ignored for remote Environments.
  • HAM_PARAM_NETWORK_TIMEOUT_SEC Timeout (in seconds) when waiting for data from a remote server. By default, no timeout is set.
Returns
HAM_SUCCESS upon success.
HAM_INV_PARAMETER if the env pointer is NULL, an invalid combination of flags was specified
HAM_FILE_NOT_FOUND if the file does not exist
HAM_IO_ERROR if the file could not be opened or reading failed
HAM_INV_FILE_VERSION if the Environment version is not compatible with the library version.
HAM_OUT_OF_MEMORY if memory could not be allocated
HAM_WOULD_BLOCK if another process has locked the file
HAM_NEED_RECOVERY if the Database is in an inconsistent state
HAM_LOG_INV_FILE_HEADER if the logfile is corrupt
HAM_ENVIRONMENT_ALREADY_OPEN if env is already in use
HAM_NETWORK_ERROR if a remote server is not reachable

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.

Parameters
envA valid Environment handle
dbA valid Database handle, which will point to the opened Database. To close the handle, use
See Also
ham_db_close.
Parameters
nameThe name of the Database. If a Database with this name does not exist, the function will fail with HAM_DATABASE_NOT_FOUND.
flagsOptional flags for opening the Database, combined with bitwise OR. Possible flags are:
paramsReserved; set to NULL
Returns
HAM_SUCCESS upon success
HAM_INV_PARAMETER if the env pointer is NULL or an invalid combination of flags was specified
HAM_DATABASE_NOT_FOUND if a Database with this name does not exist in this Environment.
HAM_DATABASE_ALREADY_OPEN if this Database was already opened
HAM_OUT_OF_MEMORY if memory could not be allocated

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.

Parameters
envA valid Environment handle.
oldnameThe old name of the existing Database. If a Database with this name does not exist, the function will fail with HAM_DATABASE_NOT_FOUND.
newnameThe new name of this Database. If a Database with this name already exists, the function will fail with HAM_DATABASE_ALREADY_EXISTS.
flagsOptional flags for renaming the Database, combined with bitwise OR; unused, set to 0.
Returns
HAM_SUCCESS upon success
HAM_INV_PARAMETER if the env pointer is NULL or if the new Database name is reserved
HAM_DATABASE_NOT_FOUND if a Database with this name does not exist in this Environment
HAM_DATABASE_ALREADY_EXISTS if a Database with the new name already exists
HAM_OUT_OF_MEMORY if memory could not be allocated
HAM_NOT_READY if the Environment env was not initialized correctly (i.e. not yet opened or created)

Referenced by hamsterdb::env::rename_db().