DBATS
DataBase of Aggregated Time Series
|
DBATS API header file. More...
Data Structures | |
struct | dbats_bundle_info |
Time series bundle parameters (read only). More... | |
struct | dbats_config |
Configuration parameters (read only). More... | |
union | dbats_value |
A value stored in a DBATS database. More... | |
Macros | |
#define | DBATS_DB_VERSION 11 |
Version of db format written by this API. | |
#define | DBATS_KEYLEN 1024 |
max length of key name | |
#define | DBATS_KEY_IS_PREFIX 0x80000000 |
keyid describes a node, not a key | |
#define | dbats_abort_snap(snap) (dbats_abort_snap)(__FILE__, __LINE__, snap) |
Abort a transaction begun by dbats_select_snap(), undoing all changes made during the transaction and releasing any associated database locks and other resources. More... | |
Flags | |
#define | DBATS_CREATE 0x0001 |
create object if it doesn't exist | |
#define | DBATS_PRELOAD 0x0004 |
load fragments when snapshot is selected | |
#define | DBATS_READONLY 0x0008 |
don't allow writing | |
#define | DBATS_UNCOMPRESSED 0x0010 |
don't compress written time series data | |
#define | DBATS_EXCLUSIVE 0x0020 |
obtain exclusive lock on whole db | |
#define | DBATS_NO_TXN 0x0040 |
don't use transactions (fast but unsafe) | |
#define | DBATS_UPDATABLE 0x0080 |
allow updates to existing values | |
#define | DBATS_GLOB 0x0200 |
(internal use) | |
#define | DBATS_DELETE 0x0400 |
(internal use) | |
Typedefs | |
typedef struct dbats_handler | dbats_handler |
Opaque handle for a DBATS db. | |
typedef struct dbats_snapshot | dbats_snapshot |
Opaque handle for a DBATS snapshot. | |
typedef struct dbats_keyid_iterator | dbats_keyid_iterator |
Opaque handle for iterating over keys by id. | |
typedef struct dbats_keytree_iterator | dbats_keytree_iterator |
Opaque handle for iterating over keys by name. | |
Enumerations | |
enum | dbats_agg_func { DBATS_AGG_NONE = -1, DBATS_AGG_DATA, DBATS_AGG_MIN, DBATS_AGG_MAX, DBATS_AGG_AVG, DBATS_AGG_LAST, DBATS_AGG_SUM, DBATS_AGG_N } |
Aggregation function identifiers. More... | |
Functions | |
int | dbats_open (dbats_handler **handlerp, const char *path, uint16_t values_per_entry, uint32_t period, uint32_t flags, int mode) |
Open an existing or new DBATS database. More... | |
int | dbats_commit_open (dbats_handler *handler) |
Commit the transaction started by dbats_open(). More... | |
int | dbats_abort_open (dbats_handler *handler) |
Abort a transaction begun by dbats_open(), undoing all changes made during the transaction and releasing any associated database locks and other resources. More... | |
int | dbats_close (dbats_handler *handler) |
Close a database opened by dbats_open(). More... | |
int | dbats_aggregate (dbats_handler *handler, enum dbats_agg_func func, int steps) |
Defines an aggregate. More... | |
enum dbats_agg_func | dbats_find_agg_func (const char *name) |
Look up an aggregate function by name (case insensitive). More... | |
int | dbats_get_start_time (dbats_handler *handler, dbats_snapshot *snap, int bid, uint32_t *start) |
Get the earliest timestamp in a time series bundle. More... | |
int | dbats_get_end_time (dbats_handler *handler, dbats_snapshot *snap, int bid, uint32_t *end) |
Get the latest timestamp in a time series bundle. More... | |
int | dbats_series_limit (dbats_handler *handler, int bid, int keep) |
Configure the number of data points to keep for each time series of a bundle. More... | |
void | dbats_set_userdata (dbats_handler *handler, void *data) |
Store arbitrary user-defined data on a dbats_handler. More... | |
void * | dbats_get_userdata (dbats_handler *handler) |
Retreive user-defined data from a dbats_handler. More... | |
int | dbats_best_bundle (dbats_handler *handler, enum dbats_agg_func func, uint32_t start, uint32_t end, int max_points, int exclude) |
Find a bundle covering a time range. More... | |
uint32_t | dbats_normalize_time (const dbats_handler *handler, int bid, uint32_t *t) |
Round a time value down to a multiple of a bundle's period. More... | |
int | dbats_select_snap (dbats_handler *handler, dbats_snapshot **snapp, uint32_t time_value, uint32_t flags) |
Create a "snapshot", that is, a working copy of a fixed point in time that can be manipulated with dbats_get(), dbats_set(), etc. More... | |
int | dbats_commit_snap (dbats_snapshot *snap) |
Commit the transaction started by dbats_select_snap(). More... | |
int | dbats_get_key_id (dbats_handler *handler, dbats_snapshot *snap, const char *key, uint32_t *key_id_p, uint32_t flags) |
Get the id of a new or existing key. More... | |
int | dbats_bulk_get_key_id (dbats_handler *handler, dbats_snapshot *snap, uint32_t *n_keys_p, const char *const *keys, uint32_t *key_ids, uint32_t flags) |
Get the ids of a large number of new or existing keys. More... | |
int | dbats_get_key_name (dbats_handler *handler, dbats_snapshot *snap, uint32_t key_id, char *namebuf) |
Get the name of an existing key. More... | |
int | dbats_delete_keys (dbats_handler *dh, const char *pattern) |
For each metric key that matches pattern, delete the key and all its data. More... | |
int | dbats_set (dbats_snapshot *snap, uint32_t key_id, const dbats_value *valuep) |
Write a value to the primary time series for the specified key and snapshot (time). More... | |
int | dbats_set_by_key (dbats_snapshot *snap, const char *key, const dbats_value *valuep, int flags) |
Write a value to the primary time series for the specified key and the time selected by dbats_select_snap(). More... | |
int | dbats_get (dbats_snapshot *snap, uint32_t key_id, const dbats_value **valuepp, int bid) |
Read an entry (array of dbats_value) from the database for the specified bundle id and key and the time selected by dbats_select_snap(). More... | |
int | dbats_get_by_key (dbats_snapshot *snap, const char *key, const dbats_value **valuepp, int bid) |
Read an array of dbats_values from the database for the specified bundle id and key and the time selected by dbats_select_snap(). More... | |
int | dbats_num_keys (dbats_handler *handler, uint32_t *num_keys) |
Get the number of keys in the database. More... | |
int | dbats_glob_keyname_start (dbats_handler *handler, dbats_snapshot *snap, dbats_keytree_iterator **dkip, const char *pattern) |
Prepare to iterate over the list of keys and keytree nodes that match pattern, ordered by name. More... | |
int | dbats_glob_keyname_next (dbats_keytree_iterator *dki, uint32_t *key_id_p, char *namebuf) |
Get the next key id and key name in the sequence started by dbats_glob_keyname_start(). More... | |
int | dbats_glob_keyname_end (dbats_keytree_iterator *dki) |
End the sequence started by dbats_glob_keyname_start(). More... | |
int | dbats_walk_keyid_start (dbats_handler *handler, dbats_snapshot *snap, dbats_keyid_iterator **dkip) |
Prepare to iterate over the list of keys ordered by id (which is the same order the keys were defined). More... | |
int | dbats_walk_keyid_next (dbats_keyid_iterator *dki, uint32_t *key_id_p, char *namebuf) |
Get the next key id and key name in the sequence started by dbats_walk_keyid_start(). More... | |
int | dbats_walk_keyid_end (dbats_keyid_iterator *dki) |
End the sequence started by dbats_walk_keyid_start(). More... | |
const dbats_config * | dbats_get_config (dbats_handler *handler) |
Get configuration parameters from a DBATS database. More... | |
const dbats_bundle_info * | dbats_get_bundle_info (dbats_handler *handler, int bid) |
Get time series parameters from a DBATS database. More... | |
void | dbats_stat_print (const dbats_handler *handler) |
Variables | |
const char * | dbats_agg_func_label [] |
Labels for aggregation functions (e.g. dbats_agg_func_label[DBATS_AGG_MIN] is "min") | |
signal handling convenience functions | |
int | dbats_caught_signal |
The last signal caught by the DBATS signal handler, or 0 if no signal has been caught. | |
void | dbats_catch_signal (int sig) |
If signal sig is currently handled by SIG_DFL, change it to a DBATS signal handler that sets dbats_caught_signal . More... | |
void | dbats_catch_signals (void) |
Shorthand for calling dbats_catch_signal() on the following signals that are normally fatal: SIGINT , SIGHUP , SIGTERM , and SIGPIPE . | |
void | dbats_restore_signal (int sig) |
If signal sig was configured with dbats_catch_signal(), reset it to SIG_DFL. More... | |
void | dbats_deliver_signal (void) |
If any signal configured with dbats_catch_signal() has been caught since the handler was set, restore the SIG_DFL handler and raise the signal. More... | |
DBATS API header file.
DBATS is a database for storing millions of similar time series and aggregating them by time. A DBATS time series is a sequence of data entries measured at regular time intervals. A set of similar time series with the same period and entry size is a "bundle". Each time series in a bundle is identified by a user-defined string key and an automatically assigned integer key id. The primary bundle stores the original raw data. Additional "aggregate" bundles can be defined that merge sub-sequences of data points for a key in the primary bundle into single data points for the same key in the aggregate bundle.
Typical usage:
Functions that return an int will return one of the following types of values:
If multiple snapshots (in different processes or threads) are accessing the same DBATS database concurrently, the writers may deadlock. When this happens, one or more operations will be cancelled so that another may proceed. The cancelled operations will return DB_LOCK_DEADLOCK. After a function in a transaction returns DB_LOCK_DEADLOCK, no other dbats calls are allowed on that dbats_snapshot (or dbats_handler) until dbats_abort_snap() (or dbats_abort_open()) is called to clean up the cancelled transaction. When an operation needs to be cancelled, one with the lowest priority is preferred. There are three priority categories; from lowest to highest, they are: read only; writable, but haven't yet called dbats_set(); writable, and have called dbats_set(). Within the two writable categories, priority depends on timestamp, so that inserts of "live" data have higher priority than inserts of historic data.
Although this API will not prevent you from opening two snapshots for writing within a single thread, doing so is not recommended since it may lead to an unbreakable deadlock.
#define dbats_abort_snap | ( | snap | ) | (dbats_abort_snap)(__FILE__, __LINE__, snap) |
Abort a transaction begun by dbats_select_snap(), undoing all changes made during the transaction and releasing any associated database locks and other resources.
After calling this function, the snapshot is no longer valid.
[in] | snap | A dbats_snapshot created by dbats_select_snap(). |
enum dbats_agg_func |
Aggregation function identifiers.
int dbats_abort_open | ( | dbats_handler * | handler | ) |
Abort a transaction begun by dbats_open(), undoing all changes made during the transaction and releasing any associated database locks and other resources.
After calling this function, the dbats_handler is no longer valid.
[in] | handler | A dbats_handler created by dbats_open(). |
int dbats_aggregate | ( | dbats_handler * | handler, |
enum dbats_agg_func | func, | ||
int | steps | ||
) |
Defines an aggregate.
Should be called after opening a database with dbats_open() but before dbats_commit_open(), and before any other process has written data to the database. Values for DBATS_AGG_AVG are stored as dbats_value.d
; all other aggregates are stored as dbats_value.u64
.
For example, given a primary data bundle with a period of 60s (1 minute), dbats_aggregate(handler, DBATS_AGG_MAX, 120)
will define an aggregate bundle that tracks the maximum value seen in each sub-sequence of 120 primary values (2 hours).
[in] | handler | A dbats_handler created by dbats_open(). |
[in] | func | a dbats_agg_func indicating which aggregation function to apply to the data points. |
[in] | steps | number of primary data points to include in an aggregate point |
int dbats_best_bundle | ( | dbats_handler * | handler, |
enum dbats_agg_func | func, | ||
uint32_t | start, | ||
uint32_t | end, | ||
int | max_points, | ||
int | exclude | ||
) |
Find a bundle covering a time range.
Find the bundle that best covers the time range starting at start
. Only the primary bundle (0) and bundles with aggregation function func
are considered.
max_points
points, the bundle with fewer points is preferred.max_points
points, the bundle with more points is preferred.Note that it is possible for the selected bundle to have more than max_points
points if there is no other bundle that covers as much of the time range.
[in] | handler | A dbats_handler created by dbats_open(). |
[in] | func | aggregation function |
[in] | start | beginning of the time range |
[in] | end | end of the time range |
[in] | max_points | maximum number of data points wanted. If max_points is 0, it is treated as infinite. |
[in] | exclude | the first sample should or should not include the from value if exclude is 0 or 1, respectively. |
int dbats_bulk_get_key_id | ( | dbats_handler * | handler, |
dbats_snapshot * | snap, | ||
uint32_t * | n_keys_p, | ||
const char *const * | keys, | ||
uint32_t * | key_ids, | ||
uint32_t | flags | ||
) |
Get the ids of a large number of new or existing keys.
The keys must already exist unless the DBATS_CREATE flag is given. When creating a large number (> 20000) of keys, it is recommended to do so outside of a transaction to avoid excessive locking (this function will create keys in efficiently-sized batches and use its own transactions).
[in] | handler | A dbats_handler created by dbats_open(). |
[in] | snap | A dbats_snapshot created by dbats_select_snap(). |
[in,out] | *n_keys_p | On input, should point to an integer containing the number of keys in the keys array. On output, that integer will contain the number of ids written into key_ids . If this function returns 0, the output value of *n_keys_p will equal the input value; otherwise, the output value may be anywhere between 0 and the input value, indicating the number of keys that were successfully looked up or created before the error occurred. |
[in] | keys | an array of key names |
[out] | key_ids | an array of uint32_t where the ids for keys will be written. |
[in] | flags | a bitwise-OR combination of any of the following:
|
void dbats_catch_signal | ( | int | sig | ) |
If signal sig
is currently handled by SIG_DFL, change it to a DBATS signal handler that sets dbats_caught_signal
.
[in] | sig | the signal to handle |
int dbats_close | ( | dbats_handler * | handler | ) |
Close a database opened by dbats_open().
All snapshots must be committed or aborted before calling dbats_close().
[in] | handler | A dbats_handler created by dbats_open(). |
int dbats_commit_open | ( | dbats_handler * | handler | ) |
Commit the transaction started by dbats_open().
This will flush any pending writes to the database and release any associated database locks and other resources. If the database was created in this transaction, no other processes will be able to access the database until dbats_commit_open() is called.
[in] | handler | A dbats_handler created by dbats_open(). |
int dbats_commit_snap | ( | dbats_snapshot * | snap | ) |
Commit the transaction started by dbats_select_snap().
This will flush any pending writes to the database and release any associated database locks and other resources. Any data points that fall outside the limit set by dbats_series_limit() will be deleted. After calling this function, the snapshot is no longer valid.
[in] | snap | A dbats_snapshot created by dbats_select_snap(). |
int dbats_delete_keys | ( | dbats_handler * | dh, |
const char * | pattern | ||
) |
For each metric key that matches pattern, delete the key and all its data.
There must not be a snapshot open when this function is called.
[in] | handler | A dbats_handler created by dbats_open(). |
[in] | pattern | A fileglob-like pattern as described under dbats_glob_keyname_start(). |
void dbats_deliver_signal | ( | void | ) |
If any signal configured with dbats_catch_signal() has been caught since the handler was set, restore the SIG_DFL handler and raise
the signal.
This is useful after cleanly aborting transactions and closing the database, to exit the process with the same status that would have occurred if the signal had not been caught.
enum dbats_agg_func dbats_find_agg_func | ( | const char * | name | ) |
Look up an aggregate function by name (case insensitive).
[in] | name | the name of an aggregate function |
int dbats_get | ( | dbats_snapshot * | snap, |
uint32_t | key_id, | ||
const dbats_value ** | valuepp, | ||
int | bid | ||
) |
Read an entry (array of dbats_value) from the database for the specified bundle id and key and the time selected by dbats_select_snap().
[in] | snap | A dbats_snapshot created by dbats_select_snap(). |
[in] | key_id | the id of the key. |
[out] | valuepp | the address of a dbats_value*; after the call, *valuepp will point to an array of values_per_entry dbats_values read from the database. |
[in] | bid | bundle id (0 for the primary bundle). |
const dbats_bundle_info* dbats_get_bundle_info | ( | dbats_handler * | handler, |
int | bid | ||
) |
Get time series parameters from a DBATS database.
[in] | handler | A dbats_handler created by dbats_open(). |
[in] | bid | The id of the time series bundle (0 for the primary bundle). |
int dbats_get_by_key | ( | dbats_snapshot * | snap, |
const char * | key, | ||
const dbats_value ** | valuepp, | ||
int | bid | ||
) |
Read an array of dbats_values from the database for the specified bundle id and key and the time selected by dbats_select_snap().
Equivalent to dbats_get_key_id() followed by dbats_get(). Note that dbats_get() is significantly faster if you already know the key_id.
[in] | snap | A dbats_snapshot created by dbats_select_snap(). |
[in] | key | the name of the key. |
[out] | valuepp | the address of a dbats_value*; after the call, *valuepp will point to an array of values_per_entry dbats_values read from the database. |
[in] | bid | bundle id (0 for the primary bundle). |
const dbats_config* dbats_get_config | ( | dbats_handler * | handler | ) |
Get configuration parameters from a DBATS database.
[in] | handler | A dbats_handler created by dbats_open(). |
int dbats_get_end_time | ( | dbats_handler * | handler, |
dbats_snapshot * | snap, | ||
int | bid, | ||
uint32_t * | end | ||
) |
Get the latest timestamp in a time series bundle.
At least one key in the bundle will have a value at the end time.
[in] | handler | A dbats_handler created by dbats_open(). |
[in] | snap | A dbats_snapshot created by dbats_select_snap(). |
[in] | bid | bundle id (0 for the primary bundle). |
[out] | end | A pointer to a uint32_t that will be filled in with the time of the latest entry in the bundle, or 0 if an error occurred. |
int dbats_get_key_id | ( | dbats_handler * | handler, |
dbats_snapshot * | snap, | ||
const char * | key, | ||
uint32_t * | key_id_p, | ||
uint32_t | flags | ||
) |
Get the id of a new or existing key.
The key must already exist unless the DBATS_CREATE flag is given. When getting or creating multiple keys, it is faster to do it with dbats_bulk_get_key_id().
[in] | handler | A dbats_handler created by dbats_open(). |
[in] | snap | A dbats_snapshot created by dbats_select_snap(). |
[in] | key | the name of the key. |
[out] | key_id_p | a pointer to a uint32_t where the id for key will be written. |
[in] | flags | a bitwise-OR combination of any of the following:
|
int dbats_get_key_name | ( | dbats_handler * | handler, |
dbats_snapshot * | snap, | ||
uint32_t | key_id, | ||
char * | namebuf | ||
) |
Get the name of an existing key.
[in] | handler | A dbats_handler created by dbats_open(). |
[in] | snap | A dbats_snapshot created by dbats_select_snap(). |
[in] | key_id | the id of the key. |
[out] | namebuf | a pointer to an array of at least DBATS_KEYLEN characters where the key's name will be written. |
int dbats_get_start_time | ( | dbats_handler * | handler, |
dbats_snapshot * | snap, | ||
int | bid, | ||
uint32_t * | start | ||
) |
Get the earliest timestamp in a time series bundle.
At least one key in the bundle will have a value at the start time.
[in] | handler | A dbats_handler created by dbats_open(). |
[in] | snap | A dbats_snapshot created by dbats_select_snap(). |
[in] | bid | bundle id (0 for the primary bundle). |
[out] | start | A pointer to a uint32_t that will be filled in with the time of the earliest entry in the bundle, or 0 if an error occurred. |
void* dbats_get_userdata | ( | dbats_handler * | handler | ) |
Retreive user-defined data from a dbats_handler.
[in] | handler | A dbats_handler created by dbats_open(). |
int dbats_glob_keyname_end | ( | dbats_keytree_iterator * | dki | ) |
End the sequence started by dbats_glob_keyname_start().
[in] | dki | A dbats_keytree_iterator created by dbats_glob_keyname_start(). |
int dbats_glob_keyname_next | ( | dbats_keytree_iterator * | dki, |
uint32_t * | key_id_p, | ||
char * | namebuf | ||
) |
Get the next key id and key name in the sequence started by dbats_glob_keyname_start().
[in] | dki | A dbats_keytree_iterator created by dbats_glob_keyname_start(). |
[out] | key_id_p | A pointer to a uint32_t where the key_id will be written. If (keyid & DBATS_KEY_IS_PREFIX) is true, the result describes a keytree node; otherwise, it describes a keytree leaf (i.e., an actual key). |
[out] | namebuf | a pointer to an array of at least DBATS_KEYLEN characters where the key's name will be written, or NULL if you do not need the name. |
int dbats_glob_keyname_start | ( | dbats_handler * | handler, |
dbats_snapshot * | snap, | ||
dbats_keytree_iterator ** | dkip, | ||
const char * | pattern | ||
) |
Prepare to iterate over the list of keys and keytree nodes that match pattern, ordered by name.
If pattern is NULL, all keys (but not nodes) will be iterated over. Otherwise, keys and nodes matching the pattern will be iterated over. The pattern is similar to shell filename globbing, except that hierarchical components are separated by '.' instead of '/'.
Example:
If snap
is not NULL, the operations will occur within snap's
transaction; otherwise, if handler's
transaction has not been closed, they will occur within handler's
transaction; otherwise, this function will begin a new transaction which will be committed by dbats_glob_keyname_end().
[in] | handler | A dbats_handler created by dbats_open(). |
[in] | snap | A dbats_snapshot created by dbats_select_snap(). |
[out] | dkip | the address of a dbats_keytree_iterator*; after the call, *dkip will contain a pointer that must be passed to subsequent calls of dbats_glob_keyname_next() and dbats_glob_keyname_end(). |
[in] | pattern | A fileglob-like pattern |
uint32_t dbats_normalize_time | ( | const dbats_handler * | handler, |
int | bid, | ||
uint32_t * | t | ||
) |
Round a time value down to a multiple of a bundle's period.
[in] | handler | A dbats_handler created by dbats_open(). |
[in] | bid | bundle id (0 for the primary bundle). |
[in,out] | t | a unix time value (seconds since 1970-01-01 00:00:00 UTC, without leap seconds). Value will be rounded down to the nearest multiple of the data period, counting from 00:00 on the first Sunday of 1970, UTC. |
int dbats_num_keys | ( | dbats_handler * | handler, |
uint32_t * | num_keys | ||
) |
Get the number of keys in the database.
[in] | handler | A dbats_handler created by dbats_open(). |
[out] | num_keys | A pointer to a uint32_t that will be filled in with the number of keys in the databasse. |
int dbats_open | ( | dbats_handler ** | handlerp, |
const char * | path, | ||
uint16_t | values_per_entry, | ||
uint32_t | period, | ||
uint32_t | flags, | ||
int | mode | ||
) |
Open an existing or new DBATS database.
Some configuration parameters can be set only when creating a database; when opening an existing database, those parameters will be silently ignored. By default, the database will allow reading data values and inserting new data values, but not updating existing data values.
If dbats_open() succeeds, the process should not call dbats_open() again with the same path until the former handle is closed with dbats_close().
Opening a database also starts a transaction that can be used to configure the database. When configuration is complete, you must call dbats_commit_open() to commit the transaction. Before calling dbats_commit_open():
dbats_handler
concurrentlyAfter dbats_commit_open(), any number of threads may call dbats_select_snap() on the dbats_handler
.
[out] | handlerp | the address of a dbats_handler*; after the call, *handlerp will contain a pointer that must be passed to subsequent calls on this database. |
[in] | path | path of an existing directory containing a DBATS database or a nonexistant directory in which to create a new DBATS database. |
[in] | values_per_entry | number of dbats_values in the array read by dbats_get() or written by dbats_set() (ignored unless creating a new database). |
[in] | period | the number of seconds between primary data values (ignored unless creating a new database). |
[in] | flags | a bitwise-OR combination of any of the following:
|
[in] | mode | permissions for files created by this function (as defined by open(2)) and modified by the process's umask. A value of 0 is treated as 0644. (This function will automatically add write permission to certain transaction and locking related files as needed to allow read-only access.) |
path
does not exist and flags
did not contain DBATS_CREATE, or if the directory does exist but does not contain a valid database after waiting several seconds;void dbats_restore_signal | ( | int | sig | ) |
If signal sig
was configured with dbats_catch_signal(), reset it to SIG_DFL.
[in] | sig | the signal to handle |
int dbats_select_snap | ( | dbats_handler * | handler, |
dbats_snapshot ** | snapp, | ||
uint32_t | time_value, | ||
uint32_t | flags | ||
) |
Create a "snapshot", that is, a working copy of a fixed point in time that can be manipulated with dbats_get(), dbats_set(), etc.
All operations on this snapshot take place within a transaction; that is, they will not be visible to other processes/threads until they are committed with dbats_commit_snap(), or they can be undone with dbats_abort_snap(). If this function fails for any reason, it returns nonzero without beginning a transaction. If multiple snapshots are being used to write to the database in parallel (in other processes or threads), this function may block until those other snapshots complete their transactions. If a deadlock occurs within this function, it will automatically retry, up to a limit; if this limit is reached, this function will return DB_LOCK_DEADLOCK without beginning a transaction (so dbats_abort_snap() is not needed).
[in] | handler | A dbats_handler created by dbats_open(). |
[out] | snapp | the address of a dbats_snapshot*; after the call, *snapp will contain a pointer that must be passed to subsequent function calls. |
[in] | time_value | the desired time, which will be rounded down by dbats_normalize_time(). |
[in] | flags | a bitwise-OR combination of any of the following:
|
int dbats_series_limit | ( | dbats_handler * | handler, |
int | bid, | ||
int | keep | ||
) |
Configure the number of data points to keep for each time series of a bundle.
When a transaction started by dbats_select_snap() is committed, any data points that are keep
periods or more older than the latest point ever set (for any key) will be deleted. Once a point is deleted for being outside the limit, it can not be set again, even if the limit is changed. The limit for the primary data bundle (bid 0) can not be smaller than the number of steps in the largest aggregate.
For example, if a bundle with period 60s has a keep limit of 1440, values more than 1 day older than the last timestamp set for any key in the bundle will be deleted. If the bundle contains data for keys "foo" and "bar", and a new value for "foo" is set for 15:37:00 today, then (as soon as that transaction is committed) all values for both "foo" and "bar" up to 15:36:00 yesterday will be deleted.
[in] | handler | A dbats_handler created by dbats_open(). |
[in] | bid | bundle id (0 for the primary bundle). |
[in] | keep | The number of data points to keep in each time series of the bundle, or 0 to keep all points. |
int dbats_set | ( | dbats_snapshot * | snap, |
uint32_t | key_id, | ||
const dbats_value * | valuep | ||
) |
Write a value to the primary time series for the specified key and snapshot (time).
All aggregate values whose time ranges contain this primary data point will also be updated. Note that values are not guaranteed to be safely stored in the database until dbats_commit_snap() is called and returns successfully. In particular, when multiple processes are writing to the database, there is a non-negligible probability of losing data due to deadlock in dbats_set() or dbats_commit_snap(). You are advised to hold on to a copy of your original data until dbats_commit_snap() succeeds, so that you can repeat dbats_select_snap() and dbats_set() if needed.
[in] | snap | A dbats_snapshot created by dbats_select_snap(). |
[in] | key_id | the id of the key. |
[in] | valuep | a pointer to an array of values_per_entry dbats_value to be written to the database. Each dbats_value.u64 should contain a value. |
int dbats_set_by_key | ( | dbats_snapshot * | snap, |
const char * | key, | ||
const dbats_value * | valuep, | ||
int | flags | ||
) |
Write a value to the primary time series for the specified key and the time selected by dbats_select_snap().
Equivalent to dbats_get_key_id (handler, key, &key_id, flags) followed by dbats_set (handler, key_id, valuep). Note that dbats_set() is much faster than dbats_set_by_key() if you know the key_id already.
[in] | snap | A dbats_snapshot created by dbats_select_snap(). |
[in] | key | the name of the key. |
[in] | valuep | a pointer to an array of values_per_entry dbats_values to be written to the database. |
[in] | flags | a bitwise-OR combination of any of the following:
|
void dbats_set_userdata | ( | dbats_handler * | handler, |
void * | data | ||
) |
Store arbitrary user-defined data on a dbats_handler.
[in] | handler | A dbats_handler created by dbats_open(). |
[in] | data | a pointer to store on dbats_handler. |
int dbats_walk_keyid_end | ( | dbats_keyid_iterator * | dki | ) |
End the sequence started by dbats_walk_keyid_start().
[in] | dki | A dbats_keyid_iterator created by dbats_walk_keyid_start(). |
int dbats_walk_keyid_next | ( | dbats_keyid_iterator * | dki, |
uint32_t * | key_id_p, | ||
char * | namebuf | ||
) |
Get the next key id and key name in the sequence started by dbats_walk_keyid_start().
[in] | dki | A dbats_keyid_iterator created by dbats_walk_keyid_start(). |
[out] | key_id_p | A pointer to a uint32_t where the key_id will be written. |
[out] | namebuf | a pointer to an array of at least DBATS_KEYLEN characters where the key's name will be written, or NULL if you do not need the name. |
int dbats_walk_keyid_start | ( | dbats_handler * | handler, |
dbats_snapshot * | snap, | ||
dbats_keyid_iterator ** | dkip | ||
) |
Prepare to iterate over the list of keys ordered by id (which is the same order the keys were defined).
If snap
is not NULL, the operations will occur within snap's
transaction; otherwise they will occur within handler's
transaction. You must call dbats_walk_keyid_end() before committing the transaction.
Example:
[in] | handler | A dbats_handler created by dbats_open(). |
[in] | snap | A dbats_snapshot created by dbats_select_snap(). |
[out] | dkip | the address of a dbats_keyid_iterator*; after the call, *dkip will contain a pointer that must be passed to subsequent calls of dbats_walk_keyid_next() and dbats_walk_keyid_end(). |