tkrzw_langc.h File Reference

C language binding of Tkrzw. More...

#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>

Classes
struct	TkrzwStatus
	Pair of a status code and a message. More...
struct	TkrzwFuture
	Future interface, just for type check. More...
struct	TkrzwDBM
	DBM interface, just for type check. More...
struct	TkrzwDBMIter
	Iterator interface, just for type check. More...
struct	TkrzwAsyncDBM
	Asynchronous DBM interface, just for type check. More...
struct	TkrzwFile
	File interface, just for type check. More...
struct	TkrzwIndex
	Index interface, just for type check. More...
struct	TkrzwIndexIter
	Index iterator interface, just for type check. More...
struct	TkrzwStr
	String pointer and its size. More...
struct	TkrzwKeyValuePair
	Pair of a key and its value. More...
struct	TkrzwKeyProcPair
	Pair of a key and its processor. More...

Typedefs
typedef const char *(*	tkrzw_record_processor) (void *, const char *, int32_t, const char *, int32_t, int32_t *)
	Type of the record processor function. More...
typedef void(*	tkrzw_file_processor) (void *arg, const char *)
	Type of the file processor function. More...

Enumerations
enum	{   TKRZW_STATUS_SUCCESS = 0 , TKRZW_STATUS_UNKNOWN_ERROR = 1 , TKRZW_STATUS_SYSTEM_ERROR = 2 , TKRZW_STATUS_NOT_IMPLEMENTED_ERROR = 3 ,   TKRZW_STATUS_PRECONDITION_ERROR = 4 , TKRZW_STATUS_INVALID_ARGUMENT_ERROR = 5 , TKRZW_STATUS_CANCELED_ERROR = 6 , TKRZW_STATUS_NOT_FOUND_ERROR = 7 ,   TKRZW_STATUS_PERMISSION_ERROR = 8 , TKRZW_STATUS_INFEASIBLE_ERROR = 9 , TKRZW_STATUS_DUPLICATION_ERROR = 10 , TKRZW_STATUS_BROKEN_DATA_ERROR = 11 ,   TKRZW_STATUS_NETWORK_ERROR = 12 , TKRZW_STATUS_APPLICATION_ERROR = 13 }
	Enumeration for status codes. More...

Functions
void	tkrzw_set_last_status (int32_t code, const char *message)
	Sets the status code and the message as if it is from the last system operation. More...
TkrzwStatus	tkrzw_get_last_status ()
	Gets the status code and the message of the last system operation. More...
int32_t	tkrzw_get_last_status_code ()
	Gets the status code of the last system operation. More...
const char *	tkrzw_get_last_status_message ()
	Gets the status message of the last system operation. More...
const char *	tkrzw_status_code_name (int32_t code)
	Gets the string name of a status code. More...
double	tkrzw_get_wall_time ()
	Gets the number of seconds since the UNIX epoch. More...
int64_t	tkrzw_get_memory_capacity ()
	Gets the memory capacity of the platform. More...
int64_t	tkrzw_get_memory_usage ()
	Gets the current memory usage of the process. More...
uint64_t	tkrzw_primary_hash (const char *data_ptr, int32_t data_size, uint64_t num_buckets)
	Primary hash function for the hash database. More...
uint64_t	tkrzw_secondary_hash (const char *data_ptr, int32_t data_size, uint64_t num_shards)
	Secondary hash function for sharding. More...
void	tkrzw_free_str_array (TkrzwStr *array, int32_t size)
	Releases an allocated array and its elements of allocated strings. More...
void	tkrzw_free_str_map (TkrzwKeyValuePair *array, int32_t size)
	Releases an allocated array and its elements of allocated key-value pairs. More...
TkrzwKeyValuePair *	tkrzw_search_str_map (TkrzwKeyValuePair *array, int32_t size, const char *key_ptr, int32_t key_size)
	Searches an array of key-value pairs for a record with the given key. More...
int32_t	tkrzw_str_search_regex (const char *text, const char *pattern)
	Searches a string for a pattern matching a regular expression. More...
char *	tkrzw_str_replace_regex (const char *text, const char *pattern, const char *replace)
	Replaces substrings matching a pattern of regular expression. More...
int32_t	tkrzw_str_edit_distance_lev (const char *a, const char *b, bool utf)
	Gets the Levenshtein edit distance of two strings. More...
char *	tkrzw_str_escape_c (const char *ptr, int32_t size, bool esc_nonasc, int32_t *res_size)
	Escapes C-style meta characters in a string. More...
char *	tkrzw_str_unescape_c (const char *ptr, int32_t size, int32_t *res_size)
	Unescapes C-style escape sequences in a string. More...
char *	tkrzw_str_append (char *modified, const char *appended)
	Appends a string at the end of another allocated string. More...
void	tkrzw_future_free (TkrzwFuture *future)
	Releases the future object. More...
bool	tkrzw_future_wait (TkrzwFuture *future, double timeout)
	Waits for the operation of the future object to be done. More...
void	tkrzw_future_get (TkrzwFuture *future)
	Gets the status of the operation of the future object. More...
char *	tkrzw_future_get_str (TkrzwFuture *future, int32_t *size)
	Gets the status and the extra string data of the operation of the future object. More...
TkrzwKeyValuePair *	tkrzw_future_get_str_pair (TkrzwFuture *future)
	Gets the status and the extra string pair of the operation of the future object. More...
TkrzwStr *	tkrzw_future_get_str_array (TkrzwFuture *future, int32_t *num_elems)
	Gets the status and the extra string array of the operation of the future object. More...
TkrzwKeyValuePair *	tkrzw_future_get_str_map (TkrzwFuture *future, int32_t *num_elems)
	Gets the status and the extra string map of the operation of the future object. More...
int64_t	tkrzw_future_get_int (TkrzwFuture *future)
	Gets the status and the extra integer data of the operation of the future object. More...
TkrzwDBM *	tkrzw_dbm_open (const char *path, bool writable, const char *params)
	Opens a database file and makes a database object. More...
bool	tkrzw_dbm_close (TkrzwDBM *dbm)
	Closes the database file and releases the database object. More...
bool	tkrzw_dbm_process (TkrzwDBM *dbm, const char *key_ptr, int32_t key_size, tkrzw_record_processor proc, void *proc_arg, bool writable)
	Processes a record with callback functions. More...
bool	tkrzw_dbm_check (TkrzwDBM *dbm, const char *key_ptr, int32_t key_size)
	Checks if a record exists or not. More...
char *	tkrzw_dbm_get (TkrzwDBM *dbm, const char *key_ptr, int32_t key_size, int32_t *value_size)
	Gets the value of a record of a key. More...
TkrzwKeyValuePair *	tkrzw_dbm_get_multi (TkrzwDBM *dbm, const TkrzwStr *keys, int32_t num_keys, int32_t *num_matched)
	Gets the values of multiple records of keys. More...
bool	tkrzw_dbm_set (TkrzwDBM *dbm, const char *key_ptr, int32_t key_size, const char *value_ptr, int32_t value_size, bool overwrite)
	Sets a record of a key and a value. More...
char *	tkrzw_dbm_set_and_get (TkrzwDBM *dbm, const char *key_ptr, int32_t key_size, const char *value_ptr, int32_t value_size, bool overwrite, int32_t *old_value_size)
	Sets a record and get the old value. More...
bool	tkrzw_dbm_set_multi (TkrzwDBM *dbm, const TkrzwKeyValuePair *records, int32_t num_records, bool overwrite)
	Sets multiple records. More...
bool	tkrzw_dbm_remove (TkrzwDBM *dbm, const char *key_ptr, int32_t key_size)
	Removes a record of a key. More...
char *	tkrzw_dbm_remove_and_get (TkrzwDBM *dbm, const char *key_ptr, int32_t key_size, int32_t *value_size)
	Removes a record and get the value. More...
bool	tkrzw_dbm_remove_multi (TkrzwDBM *dbm, const TkrzwStr *keys, int32_t num_keys)
	Removes records of keys. More...
bool	tkrzw_dbm_append (TkrzwDBM *dbm, const char *key_ptr, int32_t key_size, const char *value_ptr, int32_t value_size, const char *delim_ptr, int32_t delim_size)
	Appends data at the end of a record of a key. More...
bool	tkrzw_dbm_append_multi (TkrzwDBM *dbm, const TkrzwKeyValuePair *records, int32_t num_records, const char *delim_ptr, int32_t delim_size)
	Appends data to multiple records. More...
bool	tkrzw_dbm_compare_exchange (TkrzwDBM *dbm, const char *key_ptr, int32_t key_size, const char *expected_ptr, int32_t expected_size, const char *desired_ptr, int32_t desired_size)
	Compares the value of a record and exchanges if the condition meets. More...
char *	tkrzw_dbm_compare_exchange_and_get (TkrzwDBM *dbm, const char *key_ptr, int32_t key_size, const char *expected_ptr, int32_t expected_size, const char *desired_ptr, int32_t desired_size, int32_t *actual_size)
	Does compare-and-exchange and/or gets the old value of the record. More...
int64_t	tkrzw_dbm_increment (TkrzwDBM *dbm, const char *key_ptr, int32_t key_size, int64_t increment, int64_t initial)
	Increments the numeric value of a record. More...
bool	tkrzw_dbm_process_multi (TkrzwDBM *dbm, TkrzwKeyProcPair *key_proc_pairs, int32_t num_pairs, bool writable)
	Processes multiple records with processors. More...
bool	tkrzw_dbm_compare_exchange_multi (TkrzwDBM *dbm, const TkrzwKeyValuePair *expected, int32_t num_expected, const TkrzwKeyValuePair *desired, int32_t num_desired)
	Compares the values of records and exchanges if the condition meets. More...
bool	tkrzw_dbm_rekey (TkrzwDBM *dbm, const char *old_key_ptr, int32_t old_key_size, const char *new_key_ptr, int32_t new_key_size, bool overwrite, bool copying)
	Changes the key of a record. More...
bool	tkrzw_dbm_process_first (TkrzwDBM *dbm, tkrzw_record_processor proc, void *proc_arg, bool writable)
	Processes the first record with a processor. More...
bool	tkrzw_dbm_pop_first (TkrzwDBM *dbm, char **key_ptr, int32_t *key_size, char **value_ptr, int32_t *value_size)
	Gets the first record and removes it. More...
bool	tkrzw_dbm_push_last (TkrzwDBM *dbm, const char *value_ptr, int32_t value_size, double wtime)
	Adds a record with a key of the current timestamp. More...
bool	tkrzw_dbm_process_each (TkrzwDBM *dbm, tkrzw_record_processor proc, void *proc_arg, bool writable)
	Processes each and every record in the database with a processor. More...
int64_t	tkrzw_dbm_count (TkrzwDBM *dbm)
	Gets the number of records. More...
int64_t	tkrzw_dbm_get_file_size (TkrzwDBM *dbm)
	Gets the current file size of the database. More...
char *	tkrzw_dbm_get_file_path (TkrzwDBM *dbm)
	Gets the path of the database file. More...
double	tkrzw_dbm_get_timestamp (TkrzwDBM *dbm)
	Gets the timestamp in seconds of the last modified time. More...
bool	tkrzw_dbm_clear (TkrzwDBM *dbm)
	Removes all records. More...
bool	tkrzw_dbm_rebuild (TkrzwDBM *dbm, const char *params)
	Rebuilds the entire database. More...
bool	tkrzw_dbm_should_be_rebuilt (TkrzwDBM *dbm)
	Checks whether the database should be rebuilt. More...
bool	tkrzw_dbm_synchronize (TkrzwDBM *dbm, bool hard, tkrzw_file_processor proc, void *proc_arg, const char *params)
	Synchronizes the content of the database to the file system. More...
bool	tkrzw_dbm_copy_file_data (TkrzwDBM *dbm, const char *dest_path, bool sync_hard)
	Copies the content of the database files to other files. More...
bool	tkrzw_dbm_export (TkrzwDBM *dbm, TkrzwDBM *dest_dbm)
	Exports all records to another database. More...
bool	tkrzw_dbm_export_to_flat_records (TkrzwDBM *dbm, TkrzwFile *dest_file)
	Exports all records of a database to a flat record file. More...
bool	tkrzw_dbm_import_from_flat_records (TkrzwDBM *dbm, TkrzwFile *src_file)
	Imports records to a database from a flat record file. More...
bool	tkrzw_dbm_export_keys_as_lines (TkrzwDBM *dbm, TkrzwFile *dest_file)
	Exports the keys of all records of a database as lines to a text file. More...
TkrzwKeyValuePair *	tkrzw_dbm_inspect (TkrzwDBM *dbm, int32_t *num_records)
	Inspects the database. More...
bool	tkrzw_dbm_is_writable (TkrzwDBM *dbm)
	Checks whether the database is writable. More...
bool	tkrzw_dbm_is_healthy (TkrzwDBM *dbm)
	Checks whether the database condition is healthy. More...
bool	tkrzw_dbm_is_ordered (TkrzwDBM *dbm)
	Checks whether ordered operations are supported. More...
TkrzwStr *	tkrzw_dbm_search (TkrzwDBM *dbm, const char *mode, const char *pattern_ptr, int32_t pattern_size, int32_t capacity, int32_t *num_matched)
	Searches a database and get keys which match a pattern, according to a mode expression. More...
TkrzwDBMIter *	tkrzw_dbm_make_iterator (TkrzwDBM *dbm)
	Makes an iterator for each record. More...
void	tkrzw_dbm_iter_free (TkrzwDBMIter *iter)
	Releases the iterator object. More...
bool	tkrzw_dbm_iter_first (TkrzwDBMIter *iter)
	Initializes the iterator to indicate the first record. More...
bool	tkrzw_dbm_iter_last (TkrzwDBMIter *iter)
	Initializes the iterator to indicate the last record. More...
bool	tkrzw_dbm_iter_jump (TkrzwDBMIter *iter, const char *key_ptr, int32_t key_size)
	Initializes the iterator to indicate a specific record. More...
bool	tkrzw_dbm_iter_jump_lower (TkrzwDBMIter *iter, const char *key_ptr, int32_t key_size, bool inclusive)
	Initializes the iterator to indicate the last record whose key is lower than a given key. More...
bool	tkrzw_dbm_iter_jump_upper (TkrzwDBMIter *iter, const char *key_ptr, int32_t key_size, bool inclusive)
	Initializes the iterator to indicate the first record whose key is upper than a given key. More...
bool	tkrzw_dbm_iter_next (TkrzwDBMIter *iter)
	Moves the iterator to the next record. More...
bool	tkrzw_dbm_iter_previous (TkrzwDBMIter *iter)
	Moves the iterator to the previous record. More...
bool	tkrzw_dbm_iter_process (TkrzwDBMIter *iter, tkrzw_record_processor proc, void *proc_arg, bool writable)
	Processes the current record with a processor. More...
bool	tkrzw_dbm_iter_get (TkrzwDBMIter *iter, char **key_ptr, int32_t *key_size, char **value_ptr, int32_t *value_size)
	Gets the key and the value of the current record of the iterator. More...
char *	tkrzw_dbm_iter_get_key (TkrzwDBMIter *iter, int32_t *key_size)
	Gets the key of the current record, in a simple way. More...
char *	tkrzw_dbm_iter_get_value (TkrzwDBMIter *iter, int32_t *value_size)
	Gets the key of the current record, in a simple way. More...
bool	tkrzw_dbm_iter_set (TkrzwDBMIter *iter, const char *value_ptr, int32_t value_size)
	Sets the value of the current record. More...
bool	tkrzw_dbm_iter_remove (TkrzwDBMIter *iter)
	Removes the current record. More...
bool	tkrzw_dbm_iter_step (TkrzwDBMIter *iter, char **key_ptr, int32_t *key_size, char **value_ptr, int32_t *value_size)
	Gets the current record and moves the iterator to the next record. More...
bool	tkrzw_dbm_restore_database (const char *old_file_path, const char *new_file_path, const char *class_name, int64_t end_offset, const char *cipher_key)
	Restores a broken database as a new healthy database. More...
TkrzwAsyncDBM *	tkrzw_async_dbm_new (TkrzwDBM *dbm, int32_t num_worker_threads)
	Creates an asynchronous database adapter. More...
void	tkrzw_async_dbm_free (TkrzwAsyncDBM *async)
	Releases the asynchronous database adapter. More...
TkrzwFuture *	tkrzw_async_dbm_get (TkrzwAsyncDBM *async, const char *key_ptr, int32_t key_size)
	Gets the value of a record of a key asynchronously. More...
TkrzwFuture *	tkrzw_async_dbm_get_multi (TkrzwAsyncDBM *async, const TkrzwStr *keys, int32_t num_keys)
	Gets the values of multiple records of keys asynchronously. More...
TkrzwFuture *	tkrzw_async_dbm_set (TkrzwAsyncDBM *async, const char *key_ptr, int32_t key_size, const char *value_ptr, int32_t value_size, bool overwrite)
	Sets a record of a key and a value asynchronously. More...
TkrzwFuture *	tkrzw_async_dbm_set_multi (TkrzwAsyncDBM *async, const TkrzwKeyValuePair *records, int32_t num_records, bool overwrite)
	Sets multiple records asynchronously. More...
TkrzwFuture *	tkrzw_async_dbm_remove (TkrzwAsyncDBM *async, const char *key_ptr, int32_t key_size)
	Removes a record of a key asynchronously. More...
TkrzwFuture *	tkrzw_async_dbm_remove_multi (TkrzwAsyncDBM *async, const TkrzwStr *keys, int32_t num_keys)
	Removes records of keys asynchronously. More...
TkrzwFuture *	tkrzw_async_dbm_append (TkrzwAsyncDBM *async, const char *key_ptr, int32_t key_size, const char *value_ptr, int32_t value_size, const char *delim_ptr, int32_t delim_size)
	Appends data at the end of a record of a key asynchronously. More...
TkrzwFuture *	tkrzw_async_dbm_append_multi (TkrzwAsyncDBM *async, const TkrzwKeyValuePair *records, int32_t num_records, const char *delim_ptr, int32_t delim_size)
	Appends data to multiple records asynchronously. More...
TkrzwFuture *	tkrzw_async_dbm_compare_exchange (TkrzwAsyncDBM *async, const char *key_ptr, int32_t key_size, const char *expected_ptr, int32_t expected_size, const char *desired_ptr, int32_t desired_size)
	Compares the value of a record and exchanges if the condition meets asynchronously. More...
TkrzwFuture *	tkrzw_async_dbm_increment (TkrzwAsyncDBM *async, const char *key_ptr, int32_t key_size, int64_t increment, int64_t initial)
	Increments the numeric value of a record asynchronously. More...
TkrzwFuture *	tkrzw_async_dbm_compare_exchange_multi (TkrzwAsyncDBM *async, const TkrzwKeyValuePair *expected, int32_t num_expected, const TkrzwKeyValuePair *desired, int32_t num_desired)
	Compares the values of records and exchanges if the condition meets asynchronously. More...
TkrzwFuture *	tkrzw_async_dbm_rekey (TkrzwAsyncDBM *async, const char *old_key_ptr, int32_t old_key_size, const char *new_key_ptr, int32_t new_key_size, bool overwrite, bool copying)
	Changes the key of a record asynchronously. More...
TkrzwFuture *	tkrzw_async_dbm_pop_first (TkrzwAsyncDBM *async)
	Gets the first record and removes it asynchronously. More...
TkrzwFuture *	tkrzw_async_dbm_push_last (TkrzwAsyncDBM *async, const char *value_ptr, int32_t value_size, double wtime)
	Adds a record with a key of the current timestamp. More...
TkrzwFuture *	tkrzw_async_dbm_clear (TkrzwAsyncDBM *async)
	Removes all records asynchronously. More...
TkrzwFuture *	tkrzw_async_dbm_rebuild (TkrzwAsyncDBM *async, const char *params)
	Rebuilds the entire database asynchronously. More...
TkrzwFuture *	tkrzw_async_dbm_synchronize (TkrzwAsyncDBM *async, bool hard, const char *params)
	Synchronizes the content of the database to the file system asynchronously. More...
TkrzwFuture *	tkrzw_async_dbm_copy_file_data (TkrzwAsyncDBM *async, const char *dest_path, bool sync_hard)
	Copies the content of the database files to other files. More...
TkrzwFuture *	tkrzw_async_dbm_export (TkrzwAsyncDBM *async, TkrzwDBM *dest_dbm)
	Exports all records to another database. More...
TkrzwFuture *	tkrzw_async_dbm_export_to_flat_records (TkrzwAsyncDBM *async, TkrzwFile *dest_file)
	Exports all records of a database to a flat record file. More...
TkrzwFuture *	tkrzw_async_dbm_import_from_flat_records (TkrzwAsyncDBM *async, TkrzwFile *src_file)
	Imports records to a database from a flat record file. More...
TkrzwFuture *	tkrzw_async_dbm_search (TkrzwAsyncDBM *async, const char *mode, const char *pattern_ptr, int32_t pattern_size, int32_t capacity)
	Searches a database and get keys asynchronously. More...
TkrzwFile *	tkrzw_file_open (const char *path, bool writable, const char *params)
	Opens a file. More...
bool	tkrzw_file_close (TkrzwFile *file)
	Closes the file. More...
bool	tkrzw_file_read (TkrzwFile *file, int64_t off, void *buf, size_t size)
	Reads data. More...
bool	tkrzw_file_write (TkrzwFile *file, int64_t off, const void *buf, size_t size)
	Writes data. More...
bool	tkrzw_file_append (TkrzwFile *file, const void *buf, size_t size, int64_t *off)
	Appends data at the end of the file. More...
bool	tkrzw_file_truncate (TkrzwFile *file, int64_t size)
	Truncates the file. More...
bool	tkrzw_file_synchronize (TkrzwFile *file, bool hard, int64_t off, int64_t size)
	Synchronizes the content of the file to the file system. More...
int64_t	tkrzw_file_get_size (TkrzwFile *file)
	Gets the size of the file. More...
char *	tkrzw_file_get_path (TkrzwFile *file)
	Gets the path of the file. More...
TkrzwStr *	tkrzw_file_search (TkrzwFile *file, const char *mode, const char *pattern_ptr, int32_t pattern_size, int32_t capacity, int32_t *num_matched)
	Searches the file and get lines which match a pattern, according to a mode expression. More...
TkrzwIndex *	tkrzw_index_open (const char *path, bool writable, const char *params)
	Opens an index file and makes an index object. More...
bool	tkrzw_index_close (TkrzwIndex *index)
	Closes the index file and releases the index object. More...
bool	tkrzw_index_check (TkrzwIndex *index, const char *key_ptr, int32_t key_size, const char *value_ptr, int32_t value_size)
	Checks whether a record exists in the index. More...
TkrzwStr *	tkrzw_index_get_values (TkrzwIndex *index, const char *key_ptr, int32_t key_size, int32_t max, int32_t *num_elems)
	Gets all values of records of a key. More...
bool	tkrzw_index_add (TkrzwIndex *index, const char *key_ptr, int32_t key_size, const char *value_ptr, int32_t value_size)
	Adds a record. More...
bool	tkrzw_index_remove (TkrzwIndex *index, const char *key_ptr, int32_t key_size, const char *value_ptr, int32_t value_size)
	Remove a record. More...
int32_t	tkrzw_index_count (TkrzwIndex *index)
	Gets the number of records. More...
char *	tkrzw_index_get_file_path (TkrzwIndex *index)
	Gets the path of the index file. More...
bool	tkrzw_index_clear (TkrzwIndex *index)
	Removes all records. More...
bool	tkrzw_index_rebuild (TkrzwIndex *index)
	Rebuilds the entire database. More...
bool	tkrzw_index_synchronize (TkrzwIndex *index, bool hard)
	Synchronizes the content of the database to the file system. More...
bool	tkrzw_index_is_writable (TkrzwIndex *index)
	Checks whether the database is writable. More...
TkrzwIndexIter *	tkrzw_index_make_iterator (TkrzwIndex *index)
	Makes an iterator for each record. More...
void	tkrzw_index_iter_free (TkrzwIndexIter *iter)
	Releases the iterator object. More...
void	tkrzw_index_iter_first (TkrzwIndexIter *iter)
	Initializes the iterator to indicate the first record. More...
void	tkrzw_index_iter_last (TkrzwIndexIter *iter)
	Initializes the iterator to indicate the last record. More...
void	tkrzw_index_iter_jump (TkrzwIndexIter *iter, const char *key_ptr, int32_t key_size, const char *value_ptr, int32_t value_size)
	Initializes the iterator to indicate a specific range. More...
void	tkrzw_index_iter_next (TkrzwIndexIter *iter)
	Moves the iterator to the next record. More...
void	tkrzw_index_iter_previous (TkrzwIndexIter *iter)
	Moves the iterator to the previous record. More...
bool	tkrzw_index_iter_get (TkrzwIndexIter *iter, char **key_ptr, int32_t *key_size, char **value_ptr, int32_t *value_size)
	Gets the key and the value of the current record of the iterator. More...

Variables
const char *const	TKRZW_PACKAGE_VERSION
	The string expression of the package version. More...
const char *const	TKRZW_LIBRARY_VERSION
	The string expression of the library version. More...
const char *const	TKRZW_OS_NAME
	The recognized OS name. More...
const int32_t	TKRZW_PAGE_SIZE
	The size of a memory page on the OS. More...
const int64_t	TKRZW_INT64MIN
	The minimum value of int64_t. More...
const int64_t	TKRZW_INT64MAX
	The maximum value of int64_t. More...
const char *const	TKRZW_ANY_DATA
	The special string_view value to represent any data. More...
const char *const	TKRZW_REC_PROC_NOOP
	The special string indicating no operation. More...
const char *const	TKRZW_REC_PROC_REMOVE
	The special string indicating removing operation. More...

Detailed Description

C language binding of Tkrzw.

Typedef Documentation

tkrzw_record_processor

typedef const char*(* tkrzw_record_processor) (void *, const char *, int32_t, const char *, int32_t, int32_t *)

Type of the record processor function.

The first parameter is an opaque argument set by the caller. The second parameter is the key pointer. The third parameter is the key size. The fourth parameter is the value pointer or NULL if there's no existing record. The fifth parameter is the value size or -1 if there's no existing record. The sixth parameter is the pointer where the size of the region of the return value is to be stored.

tkrzw_file_processor

typedef void(* tkrzw_file_processor) (void *arg, const char *)

Type of the file processor function.

The first parameter is an opaque argument set by the caller. The second parameter is the path of file.

Enumeration Type Documentation

anonymous enum

anonymous enum

Enumeration for status codes.

Enumerator
TKRZW_STATUS_SUCCESS	Success.
TKRZW_STATUS_UNKNOWN_ERROR	Generic error whose cause is unknown.
TKRZW_STATUS_SYSTEM_ERROR	Generic error from underlying systems.
TKRZW_STATUS_NOT_IMPLEMENTED_ERROR	Error that the feature is not implemented.
TKRZW_STATUS_PRECONDITION_ERROR	Error that a precondition is not met.
TKRZW_STATUS_INVALID_ARGUMENT_ERROR	Error that a given argument is invalid.
TKRZW_STATUS_CANCELED_ERROR	Error that the operation is canceled.
TKRZW_STATUS_NOT_FOUND_ERROR	Error that a specific resource is not found.
TKRZW_STATUS_PERMISSION_ERROR	Error that the operation is not permitted.
TKRZW_STATUS_INFEASIBLE_ERROR	Error that the operation is infeasible.
TKRZW_STATUS_DUPLICATION_ERROR	Error that a specific resource is duplicated.
TKRZW_STATUS_BROKEN_DATA_ERROR	Error that internal data are broken.
TKRZW_STATUS_NETWORK_ERROR	Error caused by networking failure.
TKRZW_STATUS_APPLICATION_ERROR	Generic error caused by the application logic.

Function Documentation

tkrzw_set_last_status()

void tkrzw_set_last_status	(	int32_t	code,
		const char *	message
	)

Sets the status code and the message as if it is from the last system operation.

Parameters

code	The status code.
message	The status message. If it is NULL, no message is set.

tkrzw_get_last_status()

TkrzwStatus tkrzw_get_last_status

(

)

Gets the status code and the message of the last system operation.

Returns

The status code and the message of the last system operation.

The region of the message string is available until the this function or tkrzw_get_last_status_message function is called next time.

tkrzw_get_last_status_code()

int32_t tkrzw_get_last_status_code

(

)

Gets the status code of the last system operation.

Returns

The status code of the last system operation.

tkrzw_get_last_status_message()

const char* tkrzw_get_last_status_message

(

)

Gets the status message of the last system operation.

Returns

The status message of the last system operation.

The region of the message string is available until the this function or tkrzw_get_last_status function is called next time.

tkrzw_status_code_name()

const char* tkrzw_status_code_name

(

int32_t

code

)

Gets the string name of a status code.

Parameters

code	The status code.

Returns

The name of the status code.

tkrzw_get_wall_time()

double tkrzw_get_wall_time

(

)

Gets the number of seconds since the UNIX epoch.

Returns

The number of seconds since the UNIX epoch with microsecond precision.

tkrzw_get_memory_capacity()

int64_t tkrzw_get_memory_capacity

(

)

Gets the memory capacity of the platform.

Returns

The memory capacity of the platform in bytes, or -1 on failure.

tkrzw_get_memory_usage()

int64_t tkrzw_get_memory_usage

(

)

Gets the current memory usage of the process.

Returns

The current memory usage of the process in bytes, or -1 on failure.

tkrzw_primary_hash()

uint64_t tkrzw_primary_hash	(	const char *	data_ptr,
		int32_t	data_size,
		uint64_t	num_buckets
	)

Primary hash function for the hash database.

Parameters

data_ptr	The pointer to the data to calculate the hash value for.
data_size	The size of the data. If it is negative, strlen(data_ptr) is used.
num_buckets	The number of buckets of the hash table.

Returns

The hash value.

tkrzw_secondary_hash()

uint64_t tkrzw_secondary_hash	(	const char *	data_ptr,
		int32_t	data_size,
		uint64_t	num_shards
	)

Secondary hash function for sharding.

Parameters

data_ptr	The pointer to the data to calculate the hash value for.
data_size	The size of the data. If it is negative, strlen(data_ptr) is used.
num_shards	The number of shards.

Returns

The hash value.

tkrzw_free_str_array()

void tkrzw_free_str_array	(	TkrzwStr *	array,
		int32_t	size
	)

Releases an allocated array and its elements of allocated strings.

Parameters

array	The pointer to the array to release.
size	The number of the elements of the array.

tkrzw_free_str_map()

void tkrzw_free_str_map	(	TkrzwKeyValuePair *	array,
		int32_t	size
	)

Releases an allocated array and its elements of allocated key-value pairs.

Parameters

array	The pointer to the array to release.
size	The number of the elements of the array.

tkrzw_search_str_map()

TkrzwKeyValuePair* tkrzw_search_str_map	(	TkrzwKeyValuePair *	array,
		int32_t	size,
		const char *	key_ptr,
		int32_t	key_size
	)

Searches an array of key-value pairs for a record with the given key.

Parameters

array	The pointer to the array to search.
size	The number of the elements of the array.
key_ptr	The key pointer to search for.
key_size	The key size. If it is negative, strlen(key_ptr) is used.

Returns

The pointer to the matched record or NULL on failure.

tkrzw_str_search_regex()

int32_t tkrzw_str_search_regex	(	const char *	text,
		const char *	pattern
	)

Searches a string for a pattern matching a regular expression.

Parameters

text	The text to search.
pattern	The regular expression pattern to search for.

Returns

The position of the first matching pattern. If there's no matching pattern. -1 is returned. If the regular expression is invalid, -2 is returned.

tkrzw_str_replace_regex()

char* tkrzw_str_replace_regex	(	const char *	text,
		const char *	pattern,
		const char *	replace
	)

Replaces substrings matching a pattern of regular expression.

Parameters

text	The text to process.
pattern	The regular expression pattern to search for.
replace	The replacing expression. "$&" means the entire matched pattern. "$1", "$2", and etc represent n-th bracketed patterns.

Returns

The pointer to the result string, which should be released by the free function.

tkrzw_str_edit_distance_lev()

int32_t tkrzw_str_edit_distance_lev	(	const char *	a,
		const char *	b,
		bool	utf
	)

Gets the Levenshtein edit distance of two strings.

Parameters

a	A string.
b	The other string.
utf	If true, text is treated as UTF-8. If false, it is treated as raw bytes.

Returns

The Levenshtein edit distance of the two strings.

tkrzw_str_escape_c()

char* tkrzw_str_escape_c	(	const char *	ptr,
		int32_t	size,
		bool	esc_nonasc,
		int32_t *	res_size
	)

Escapes C-style meta characters in a string.

Parameters

ptr	The pointer to the string to convert.
size	The size of the string to convert. If it is negative, strlen(ptr) is used.
esc_nonasc	If true, non-ASCII characters are excaped.
res_size	The pointer to the variable to store the result string size. If it is NULL, it is not used.

Returns

The result string, which should be released by the free function.

tkrzw_str_unescape_c()

char* tkrzw_str_unescape_c	(	const char *	ptr,
		int32_t	size,
		int32_t *	res_size
	)

Unescapes C-style escape sequences in a string.

Parameters

ptr	The pointer to the string to convert.
size	The size of the string to convert. If it is negative, strlen(ptr) is used.
res_size	The pointer to the variable to store the result string size. If it is NULL, it is not used.

Returns

The result string, which should be released by the free function.

tkrzw_str_append()

char* tkrzw_str_append	(	char *	modified,
		const char *	appended
	)

Appends a string at the end of another allocated string.

Parameters

modified	The string to be modified. It must be allocated by malloc. The ownership is taken. If it is NULL, a new string is allocated.
appended	The string to be appended at the end.

Returns

The result string, which should be released by the free function.

tkrzw_future_free()

void tkrzw_future_free

(

TkrzwFuture *

future

)

Releases the future object.

Parameters

future

The future object.

tkrzw_future_wait()

bool tkrzw_future_wait	(	TkrzwFuture *	future,
		double	timeout
	)

Waits for the operation of the future object to be done.

Parameters

future	The future object.
timeout	The waiting time in seconds. If it is negative, no timeout is set.

Returns

True if the operation has done. False if timeout occurs.

tkrzw_future_get()

void tkrzw_future_get

(

TkrzwFuture *

future

)

Gets the status of the operation of the future object.

Parameters

future

the future object.

The status is set as the last system operation status so the data can be accessed by the tkrzw_get_last_status and so on. This can be called with the future which is associated to the single status without any extra data. This can be called only once for each future. object.

tkrzw_future_get_str()

char* tkrzw_future_get_str	(	TkrzwFuture *	future,
		int32_t *	size
	)

Gets the status and the extra string data of the operation of the future object.

Parameters

future	the future object.
size	The pointer to the variable to store the extra string size. If it is NULL, it is not used.

Returns

The pointer to the extra string data, which should be released by the free function. An empty string is returned on failure. The string data is trailed by a null code so that the region can be treated as a C-style string.

The status is set as the last system operation status so the data can be accessed by the tkrzw_get_last_status and so on. This can be called with the future which is associated to the status with an extra string data. This can be called only once for each future. object.

tkrzw_future_get_str_pair()

TkrzwKeyValuePair* tkrzw_future_get_str_pair

(

TkrzwFuture *

future

)

Gets the status and the extra string pair of the operation of the future object.

Parameters

future

the future object.

Returns

The pointer to the extra string pair, which should be released by the free function. An empty string pair is returned on failure.

The status is set as the last system operation status so the data can be accessed by the tkrzw_get_last_status and so on. This can be called with the future which is associated to the status with an extra string pair. This can be called only once for each future. object.

tkrzw_future_get_str_array()

TkrzwStr* tkrzw_future_get_str_array	(	TkrzwFuture *	future,
		int32_t *	num_elems
	)

Gets the status and the extra string array of the operation of the future object.

Parameters

future	the future object.
num_elems	The pointer to the variable to store the number of elements of the extra string array.

Returns

The pointer to an array of the extra string array, which should be released by the tkrzw_free_str_array function. An empty array is returned on failure.

The status is set as the last system operation status so the data can be accessed by the tkrzw_get_last_status and so on. This can be called with the future which is associated to the status with an extra string array. This can be called only once for each future. object.

tkrzw_future_get_str_map()

TkrzwKeyValuePair* tkrzw_future_get_str_map	(	TkrzwFuture *	future,
		int32_t *	num_elems
	)

Gets the status and the extra string map of the operation of the future object.

Parameters

future	the future object.
num_elems	The pointer to the variable to store the number of elements of the extra string map.

Returns

The pointer to an array of the extra string map, which should be released by the tkrzw_free_str_map function. An empty array is returned on failure.

The status is set as the last system operation status so the data can be accessed by the tkrzw_get_last_status and so on. This can be called with the future which is associated to the status with an extra string map. This can be called only once for each future. object.

tkrzw_future_get_int()

int64_t tkrzw_future_get_int

(

TkrzwFuture *

future

)

Gets the status and the extra integer data of the operation of the future object.

Parameters

future

the future object.

Returns

The extra integer data.

The status is set as the last system operation status so the data can be accessed by the tkrzw_get_last_status and so on. This can be called with the future which is associated to the status with an extra integer data. This can be called only once for each future. object.

tkrzw_dbm_open()

TkrzwDBM* tkrzw_dbm_open	(	const char *	path,
		bool	writable,
		const char *	params
	)

Opens a database file and makes a database object.

Parameters

path	A path of the file.
writable	If true, the file is writable. If false, it is read-only.
params	Optional parameters in "key=value,key=value" format. The options for the file opening operation are set by "truncate", "no_create", "no_wait", "no_lock", and "sync_hard". The option for the number of shards is set by "num_shards". Other options are the same as PolyDBM::OpenAdvanced.

Returns

The new database object, which should be released by the tkrzw_dbm_close function. NULL is returned on failure.

tkrzw_dbm_close()

bool tkrzw_dbm_close

(

TkrzwDBM *

dbm

)

Closes the database file and releases the database object.

Parameters

dbm	The database object.

Returns

True on success or false on failure.

tkrzw_dbm_process()

bool tkrzw_dbm_process	(	TkrzwDBM *	dbm,
		const char *	key_ptr,
		int32_t	key_size,
		tkrzw_record_processor	proc,
		void *	proc_arg,
		bool	writable
	)

Processes a record with callback functions.

Parameters

dbm	The database object.
key_ptr	The key pointer.
key_size	The key size. If it is negative, strlen(key_ptr) is used.
proc	The callback function to process the record.
proc_arg	An arbitrary data which is given to the callback function.
writable	True if the processor can edit the record.

Returns

True on success or false on failure.

If the specified record exists, the value is given to the callback function. If it doesn't exist, NULL is given instead. The callback function returns TKRZW_REC_PROC_NOOP to keep the current value, TKRZW_REC_PROC_REMOVE to remove the record, or a string pointer to a new value to set. The ownership of the return value is not taken.

tkrzw_dbm_check()

bool tkrzw_dbm_check	(	TkrzwDBM *	dbm,
		const char *	key_ptr,
		int32_t	key_size
	)

Checks if a record exists or not.

Parameters

dbm	The database object.
key_ptr	The key pointer.
key_size	The key size. If it is negative, strlen(key_ptr) is used.

Returns

True if the record exists, or false if not.

tkrzw_dbm_get()

char* tkrzw_dbm_get	(	TkrzwDBM *	dbm,
		const char *	key_ptr,
		int32_t	key_size,
		int32_t *	value_size
	)

Gets the value of a record of a key.

Parameters

dbm	The database object.
key_ptr	The key pointer.
key_size	The key size. If it is negative, strlen(key_ptr) is used.
value_size	The pointer to the variable to store the value size. If it is NULL, it is not used.

Returns

The pointer to the value data, which should be released by the free function. NULL is returned on failure. The value data is trailed by a null code so that the region can be treated as a C-style string.

If there's no matching record, NOT_FOUND_ERROR status code is set.

tkrzw_dbm_get_multi()

TkrzwKeyValuePair* tkrzw_dbm_get_multi	(	TkrzwDBM *	dbm,
		const TkrzwStr *	keys,
		int32_t	num_keys,
		int32_t *	num_matched
	)

Gets the values of multiple records of keys.

Parameters

dbm	The database object.
keys	An array of the keys of records to retrieve.
num_keys	The number of elements of the key array.
num_matched	The pointer to the variable to store the number of the elements of the return value.

Returns

The pointer to an array of matched key-value pairs. This function returns an empty array on failure. If all records of the given keys are found, the status is set SUCCESS. If one or more records are missing, NOT_FOUND_ERROR is set. The array and its elements are allocated dynamically so they should be released by the tkrzw_free_str_map function.

tkrzw_dbm_set()

bool tkrzw_dbm_set	(	TkrzwDBM *	dbm,
		const char *	key_ptr,
		int32_t	key_size,
		const char *	value_ptr,
		int32_t	value_size,
		bool	overwrite
	)

Sets a record of a key and a value.

Parameters

dbm	The database object.
key_ptr	The key pointer.
key_size	The key size. If it is negative, strlen(key_ptr) is used.
value_ptr	The value pointer.
value_size	The value size. If it is negative, strlen(value_ptr) is used.
overwrite	Whether to overwrite the existing value if there's a record with the same key. If true, the existing value is overwritten by the new value. If false, the operation is given up and an error status is set.

Returns

True on success or false on failure.

If overwriting is abandoned, DUPLICATION_ERROR status code is set.

tkrzw_dbm_set_and_get()

char* tkrzw_dbm_set_and_get	(	TkrzwDBM *	dbm,
		const char *	key_ptr,
		int32_t	key_size,
		const char *	value_ptr,
		int32_t	value_size,
		bool	overwrite,
		int32_t *	old_value_size
	)

Sets a record and get the old value.

Parameters

dbm	The database object.
key_ptr	The key pointer.
key_size	The key size. If it is negative, strlen(key_ptr) is used.
value_ptr	The new value pointer.
value_size	The new value size. If it is negative, strlen(value_ptr) is used.
overwrite	Whether to overwrite the existing value if there's a record with the same key. If true, the existing value is overwritten by the new value. If false, the operation is given up and an error status is set.
old_value_size	The pointer to the variable to store the value size. If it is NULL, it is not used.

Returns

The pointer to the old value data, which should be released by the free function. NULL is returned if there's no existing record. The value data is trailed by a null code so that the region can be treated as a C-style string.

If overwriting is abandoned, DUPLICATION_ERROR status code is set.

tkrzw_dbm_set_multi()

bool tkrzw_dbm_set_multi	(	TkrzwDBM *	dbm,
		const TkrzwKeyValuePair *	records,
		int32_t	num_records,
		bool	overwrite
	)

Sets multiple records.

Parameters

dbm	The database object.
records	An array of the key-value pairs of records to store.
num_records	The number of elements of the record array.
overwrite	Whether to overwrite the existing value if there's a record with the same key. If true, the existing value is overwritten by the new value. If false, the operation is given up and an error status is set.

Returns

True on success or false on failure. If there are records avoiding overwriting, false is returned and DUPLICATION_ERROR status code is set.

tkrzw_dbm_remove()

bool tkrzw_dbm_remove	(	TkrzwDBM *	dbm,
		const char *	key_ptr,
		int32_t	key_size
	)

Removes a record of a key.

Parameters

dbm	The database object.
key_ptr	The key pointer.
key_size	The key size. If it is negative, strlen(key_ptr) is used.

Returns

True on success or false on failure.

If there's no matching record, NOT_FOUND_ERROR status code is set.

tkrzw_dbm_remove_and_get()

char* tkrzw_dbm_remove_and_get	(	TkrzwDBM *	dbm,
		const char *	key_ptr,
		int32_t	key_size,
		int32_t *	value_size
	)

Removes a record and get the value.

Parameters

dbm	The database object.
key_ptr	The key pointer.
key_size	The key size. If it is negative, strlen(key_ptr) is used.
value_size	The pointer to the variable to store the value size. If it is NULL, it is not used.

Returns

The pointer to the value data, which should be released by the free function. NULL is returned if there's no existing record. The value data is trailed by a null code so that the region can be treated as a C-style string.

If there's no matching record, NOT_FOUND_ERROR status code is set.

tkrzw_dbm_remove_multi()

bool tkrzw_dbm_remove_multi	(	TkrzwDBM *	dbm,
		const TkrzwStr *	keys,
		int32_t	num_keys
	)

Removes records of keys.

Parameters

dbm	The database object.
keys	An array of the keys of records to retrieve.
num_keys	The number of elements of the key array.

Returns

True on success or false on failure. If there are missing records, false is returned and NOT_FOUND_ERROR status code is set.

tkrzw_dbm_append()

bool tkrzw_dbm_append	(	TkrzwDBM *	dbm,
		const char *	key_ptr,
		int32_t	key_size,
		const char *	value_ptr,
		int32_t	value_size,
		const char *	delim_ptr,
		int32_t	delim_size
	)

Appends data at the end of a record of a key.

Parameters

dbm	The database object.
key_ptr	The key pointer.
key_size	The key size. If it is negative, strlen(key_ptr) is used.
value_ptr	The value pointer.
value_size	The value size. If it is negative, strlen(value_ptr) is used.
delim_ptr	The delimiter pointer.
delim_size	The delimiter size. If it is negative, strlen(delim_ptr) is used.

Returns

True on success or false on failure.

If there's no existing record, the value is set without the delimiter.

tkrzw_dbm_append_multi()

bool tkrzw_dbm_append_multi	(	TkrzwDBM *	dbm,
		const TkrzwKeyValuePair *	records,
		int32_t	num_records,
		const char *	delim_ptr,
		int32_t	delim_size
	)

Appends data to multiple records.

Parameters

dbm	The database object.
records	An array of the key-value pairs of records to append.
num_records	The number of elements of the record array.
delim_ptr	The delimiter pointer.
delim_size	The delimiter size. If it is negative, strlen(delim_ptr) is used.

Returns

True on success or false on failure.

If there's no existing record, the value is set without the delimiter.

tkrzw_dbm_compare_exchange()

bool tkrzw_dbm_compare_exchange	(	TkrzwDBM *	dbm,
		const char *	key_ptr,
		int32_t	key_size,
		const char *	expected_ptr,
		int32_t	expected_size,
		const char *	desired_ptr,
		int32_t	desired_size
	)

Compares the value of a record and exchanges if the condition meets.

Parameters

dbm	The database object.
key_ptr	The key pointer.
key_size	The key size. If it is negative, strlen(key_ptr) is used.
expected_ptr	The expected value pointer. If it is NULL, no existing record is expected. If it is TKRZW_ANY_DATA, an existing record with any value is expacted.
expected_size	The expected value size. If it is negative, strlen(expected_ptr) is used.
desired_ptr	The desired value pointer. If it is NULL, the record is to be removed. expected. If it is TKRZW_ANY_DATA, no update is done.
desired_size	The desired value size. If it is negative, strlen(desired_ptr) is used.

Returns

True on success or false on failure.

If the condition doesn't meet, INFEASIBLE_ERROR status code is set.

tkrzw_dbm_compare_exchange_and_get()

char* tkrzw_dbm_compare_exchange_and_get	(	TkrzwDBM *	dbm,
		const char *	key_ptr,
		int32_t	key_size,
		const char *	expected_ptr,
		int32_t	expected_size,
		const char *	desired_ptr,
		int32_t	desired_size,
		int32_t *	actual_size
	)

Does compare-and-exchange and/or gets the old value of the record.

Parameters

dbm	The database object.
key_ptr	The key pointer.
key_size	The key size. If it is negative, strlen(key_ptr) is used.
expected_ptr	The expected value pointer. If it is NULL, no existing record is expected. If it is TKRZW_ANY_DATA, an existing record with any value is expacted.
expected_size	The expected value size. If it is negative, strlen(expected_ptr) is used.
desired_ptr	The desired value pointer. If it is NULL, the record is to be removed. expected. If it is TKRZW_ANY_DATA, no update is done.
desired_size	The desired value size. If it is negative, strlen(desired_ptr) is used.
actual_size	The pointer to the variable to store the value size. If it is NULL, it is not used.

Returns

The pointer to the old value data, which should be released by the free function. NULL is returned if there's no existing record. The value data is trailed by a null code so that the region can be treated as a C-style string.

If the condition doesn't meet, INFEASIBLE_ERROR status code is set.

tkrzw_dbm_increment()

int64_t tkrzw_dbm_increment	(	TkrzwDBM *	dbm,
		const char *	key_ptr,
		int32_t	key_size,
		int64_t	increment,
		int64_t	initial
	)

Increments the numeric value of a record.

Parameters

dbm	The database object.
key_ptr	The key pointer.
key_size	The key size. If it is negative, strlen(key_ptr) is used.
increment	The incremental value. If it is TKRZW_INT64MIN, the current value is not changed and a new record is not created.
initial	The initial value.

Returns

The current value or TKRZW_INT64MIN on failure.

The record value is stored as an 8-byte big-endian integer. Negative is also supported.

tkrzw_dbm_process_multi()

bool tkrzw_dbm_process_multi	(	TkrzwDBM *	dbm,
		TkrzwKeyProcPair *	key_proc_pairs,
		int32_t	num_pairs,
		bool	writable
	)

Processes multiple records with processors.

Parameters

dbm	The database object.
key_proc_pairs	An array of pairs of the keys and their processor functions.
num_pairs	The number of the array.
writable	True if the processors can edit the records.

Returns

True on success or false on failure.

If the specified record exists, the value is given to the callback function. If it doesn't exist, NULL is given instead. The callback function returns TKRZW_REC_PROC_NOOP to keep the current value, TKRZW_REC_PROC_REMOVE to remove the record, or a string pointer to a new value to set. The ownership of the return value is not taken.

tkrzw_dbm_compare_exchange_multi()

bool tkrzw_dbm_compare_exchange_multi	(	TkrzwDBM *	dbm,
		const TkrzwKeyValuePair *	expected,
		int32_t	num_expected,
		const TkrzwKeyValuePair *	desired,
		int32_t	num_desired
	)

Compares the values of records and exchanges if the condition meets.

Parameters

dbm	The database object.
expected	An array of the record keys and their expected values. If the value is NULL, no existing record is expected. If the value is TKRZW_ANY_DATA, an existing record with any value is expacted.
num_expected	The number of the expected array.
desired	An array of the record keys and their desired values. If the value is NULL, the record is to be removed.
num_desired	The number of the desired array.

Returns

True on success or false on failure.

If the condition doesn't meet, INFEASIBLE_ERROR is returned.

tkrzw_dbm_rekey()

bool tkrzw_dbm_rekey	(	TkrzwDBM *	dbm,
		const char *	old_key_ptr,
		int32_t	old_key_size,
		const char *	new_key_ptr,
		int32_t	new_key_size,
		bool	overwrite,
		bool	copying
	)

Changes the key of a record.

Parameters

dbm	The database object.
old_key_ptr	The old key pointer.
old_key_size	The old key size. If it is negative, strlen(old_key_ptr) is used.
new_key_ptr	The new key pointer.
new_key_size	The new key size. If it is negative, strlen(new_key_ptr) is used.
overwrite	Whether to overwrite the existing record of the new key.
copying	Whether to retain the record of the old key.

Returns

True on success or false on failure.

If there's no matching record to the old key, NOT_FOUND_ERROR is set. If the overwrite flag is false and there is an existing record of the new key, DUPLICATION ERROR is set. This method is done atomically by ProcessMulti. The other threads observe that the record has either the old key or the new key. No intermediate states are observed.

tkrzw_dbm_process_first()

bool tkrzw_dbm_process_first	(	TkrzwDBM *	dbm,
		tkrzw_record_processor	proc,
		void *	proc_arg,
		bool	writable
	)

Processes the first record with a processor.

Parameters

dbm	The database object.
proc	The callback function to process the record.
proc_arg	An arbitrary data which is given to the callback function.
writable	True if the processor can edit the record.

If the first record exists, the callback function is called. Otherwise, this method fails and the callback is not called. If the callback function returns TKRZW_REC_PROC_NOOP, TKRZW_REC_PROC_REMOVE, or a string pointer to a new value, whose ownership is not taken.

tkrzw_dbm_pop_first()

bool tkrzw_dbm_pop_first	(	TkrzwDBM *	dbm,
		char **	key_ptr,
		int32_t *	key_size,
		char **	value_ptr,
		int32_t *	value_size
	)

Gets the first record and removes it.

Parameters

dbm	The database object.
key_ptr	The pointer to a variable which points to the region containing the record key. If this function returns true, the region should be released by the free function. If it is NULL, it is not used.
key_size	The pointer to a variable which stores the size of the region containing the record key. If it is NULL, it is not used.
value_ptr	The pointer to a variable which points to the region containing the record value. If this function returns true, the region should be released by the free function. If it is NULL, it is not used.
value_size	The pointer to a variable which stores the size of the region containing the record value. If it is NULL, it is not used.

Returns

True on success or false on failure.

tkrzw_dbm_push_last()

bool tkrzw_dbm_push_last	(	TkrzwDBM *	dbm,
		const char *	value_ptr,
		int32_t	value_size,
		double	wtime
	)

Adds a record with a key of the current timestamp.

Parameters

dbm	The database object.
value_ptr	The value pointer.
value_size	The value size. If it is negative, strlen(value_ptr) is used.
wtime	The current wall time used to generate the key. If it is negative, the system clock is used.

Returns

True on success or false on failure.

The key is generated as an 8-bite big-endian binary string of the timestamp. If there is an existing record matching the generated key, the key is regenerated and the attempt is repeated until it succeeds.

tkrzw_dbm_process_each()

bool tkrzw_dbm_process_each	(	TkrzwDBM *	dbm,
		tkrzw_record_processor	proc,
		void *	proc_arg,
		bool	writable
	)

Processes each and every record in the database with a processor.

Parameters

dbm	The database object.
proc	The callback function to process the record.
proc_arg	An arbitrary data which is given to the callback function.
writable	True if the processor can edit the record.

If the specified record exists, the value is given to the callback function. If it doesn't exist, NULL is given instead. The callback function returns TKRZW_REC_PROC_NOOP to keep the current value, TKRZW_REC_PROC_REMOVE to remove the record, or a string pointer to a new value to set. The ownership of the return value is not taken. It is also called once before the iteration and once after the iteration with both the key and the value being NULL.

tkrzw_dbm_count()

int64_t tkrzw_dbm_count

(

TkrzwDBM *

dbm

)

Gets the number of records.

Parameters

dbm	The database object.

Returns

The number of records or -1 on failure.

tkrzw_dbm_get_file_size()

int64_t tkrzw_dbm_get_file_size

(

TkrzwDBM *

dbm

)

Gets the current file size of the database.

Parameters

dbm	The database object.

Returns

The current file size of the database or -1 on failure.

tkrzw_dbm_get_file_path()

char* tkrzw_dbm_get_file_path

(

TkrzwDBM *

dbm

)

Gets the path of the database file.

Parameters

dbm	The database object.

Returns

The pointer to the path data, which should be released by the free function. NULL is returned on failure.

tkrzw_dbm_get_timestamp()

double tkrzw_dbm_get_timestamp

(

TkrzwDBM *

dbm

)

Gets the timestamp in seconds of the last modified time.

Parameters

dbm	The database object.

Returns

The timestamp of the last modified time, or NaN on failure.

tkrzw_dbm_clear()

bool tkrzw_dbm_clear

(

TkrzwDBM *

dbm

)

Removes all records.

Parameters

dbm	The database object.

Returns

True on success or false on failure.

tkrzw_dbm_rebuild()

bool tkrzw_dbm_rebuild	(	TkrzwDBM *	dbm,
		const char *	params
	)

Rebuilds the entire database.

Parameters

dbm	The database object.
params	Optional parameters in "key=value,key=value" format. The parameters work in the same way as with PolyDBM::RebuildAdvanced.

Returns

True on success or false on failure.

tkrzw_dbm_should_be_rebuilt()

bool tkrzw_dbm_should_be_rebuilt

(

TkrzwDBM *

dbm

)

Checks whether the database should be rebuilt.

Returns

True to be rebuilt, or false to not be rebuilt.

tkrzw_dbm_synchronize()

bool tkrzw_dbm_synchronize	(	TkrzwDBM *	dbm,
		bool	hard,
		tkrzw_file_processor	proc,
		void *	proc_arg,
		const char *	params
	)

Synchronizes the content of the database to the file system.

Parameters

dbm	The database object.
hard	True to do physical synchronization with the hardware or false to do only logical synchronization with the file system.
proc	The callback function to process the file, which is called while the content of the file is synchronized. If it is NULL, it is ignored.
proc_arg	An arbitrary data which is given to the callback function.
params	Optional parameters in "key=value,key=value" format. The parameters work in the same way as with PolyDBM::OpenAdvanced.

Returns

True on success or false on failure.

tkrzw_dbm_copy_file_data()

bool tkrzw_dbm_copy_file_data	(	TkrzwDBM *	dbm,
		const char *	dest_path,
		bool	sync_hard
	)

Copies the content of the database files to other files.

Parameters

dbm	The database object.
dest_path	The path prefix to the destination files.
sync_hard	True to do physical synchronization with the hardware.

Returns

True on success or false on failure.

Copying is done while the content is synchronized and stable. So, this method is suitable for making a backup file while running a database service.

tkrzw_dbm_export()

bool tkrzw_dbm_export	(	TkrzwDBM *	dbm,
		TkrzwDBM *	dest_dbm
	)

Exports all records to another database.

Parameters

dbm	The database object.
dest_dbm	The destination database object.

Returns

True on success or false on failure.

tkrzw_dbm_export_to_flat_records()

bool tkrzw_dbm_export_to_flat_records	(	TkrzwDBM *	dbm,
		TkrzwFile *	dest_file
	)

Exports all records of a database to a flat record file.

Parameters

dbm	The database object.
dest_file	The file object to write records in.

Returns

True on success or false on failure.

tkrzw_dbm_import_from_flat_records()

bool tkrzw_dbm_import_from_flat_records	(	TkrzwDBM *	dbm,
		TkrzwFile *	src_file
	)

Imports records to a database from a flat record file.

Parameters

dbm	The database object.
src_file	The file object to read records from.

Returns

True on success or false on failure.

tkrzw_dbm_export_keys_as_lines()

bool tkrzw_dbm_export_keys_as_lines	(	TkrzwDBM *	dbm,
		TkrzwFile *	dest_file
	)

Exports the keys of all records of a database as lines to a text file.

Parameters

dbm	The database object of the database.
dest_file	The file object to write keys in.

Returns

True on success or false on failure.

tkrzw_dbm_inspect()

TkrzwKeyValuePair* tkrzw_dbm_inspect	(	TkrzwDBM *	dbm,
		int32_t *	num_records
	)

Inspects the database.

Parameters

dbm	The database object.
num_records	The pointer to the variable to store the number of the elements of the return value.

Returns

The pointer to an array of property key-value pairs. This function returns an empty array on failure. The array and its elements are allocated dynamically so they should be released by the tkrzw_free_str_map function.

tkrzw_dbm_is_writable()

bool tkrzw_dbm_is_writable

(

TkrzwDBM *

dbm

)

Checks whether the database is writable.

Parameters

dbm	The database object.

Returns

True if the database is writable, or false if not.

tkrzw_dbm_is_healthy()

bool tkrzw_dbm_is_healthy

(

TkrzwDBM *

dbm

)

Checks whether the database condition is healthy.

Parameters

dbm	The database object.

Returns

True if the database condition is healthy, or false if not.

tkrzw_dbm_is_ordered()

bool tkrzw_dbm_is_ordered

(

TkrzwDBM *

dbm

)

Checks whether ordered operations are supported.

Parameters

dbm	The database object.

Returns

True if ordered operations are supported, or false if not.

tkrzw_dbm_search()

TkrzwStr* tkrzw_dbm_search	(	TkrzwDBM *	dbm,
		const char *	mode,
		const char *	pattern_ptr,
		int32_t	pattern_size,
		int32_t	capacity,
		int32_t *	num_matched
	)

Searches a database and get keys which match a pattern, according to a mode expression.

Parameters

dbm	The database object.
mode	The search mode. "contain" extracts keys containing the pattern. "begin" extracts keys beginning with the pattern. "end" extracts keys ending with the pattern. "regex" extracts keys partially matches the pattern of a regular expression. "edit" extracts keys whose edit distance to the pattern is the least. "editbin" extracts keys whose edit distance to the binary pattern is the least. "containcase", "containword", and "containcaseword" extract keys considering case and word boundary. "contain*", "containcase*", "containword*", and "containcaseword*" take a null-code-separatable pattern and do batch operations for each element. Ordered databases support "upper" and "lower" which extract keys whose positions are equal to or upper/lower than the pattern. "upperex" and "lowerex" are their exclusive versions.
pattern_ptr	The pattern pointer.
pattern_size	The pattern size. If it is negative, strlen(pattern_ptr) is used.
capacity	The maximum records to obtain. 0 means unlimited.
num_matched	The pointer to the variable to store the number of the element of the return value.

Returns

The pointer to an array of matched keys or NULL on failure. If not NULL, the array and its elements are allocated dynamically so they should be released by the tkrzw_free_str_array function.

tkrzw_dbm_make_iterator()

TkrzwDBMIter* tkrzw_dbm_make_iterator

(

TkrzwDBM *

dbm

)

Makes an iterator for each record.

Parameters

dbm	The database object.

Returns

The new iterator object, which should be released by the tkrzw_dbm_iter_free function.

tkrzw_dbm_iter_free()

void tkrzw_dbm_iter_free

(

TkrzwDBMIter *

iter

)

Releases the iterator object.

Parameters

iter	The iterator object.

tkrzw_dbm_iter_first()

bool tkrzw_dbm_iter_first

(

TkrzwDBMIter *

iter

)

Initializes the iterator to indicate the first record.

Parameters

iter	The iterator object.

Returns

True on success or false on failure.

Even if there's no record, the operation doesn't fail.

tkrzw_dbm_iter_last()

bool tkrzw_dbm_iter_last

(

TkrzwDBMIter *

iter

)

Initializes the iterator to indicate the last record.

Parameters

iter	The iterator object.

Returns

True on success or false on failure.

Even if there's no record, the operation doesn't fail. This method is suppoerted only by ordered databases.

tkrzw_dbm_iter_jump()

bool tkrzw_dbm_iter_jump	(	TkrzwDBMIter *	iter,
		const char *	key_ptr,
		int32_t	key_size
	)

Initializes the iterator to indicate a specific record.

Parameters

iter	The iterator object.
key_ptr	The key pointer.
key_size	The key size. If it is negative, strlen(key_ptr) is used.

Returns

True on success or false on failure.

Ordered databases can support "lower bound" jump; If there's no record with the same key, the iterator refers to the first record whose key is greater than the given key. The operation fails with unordered databases if there's no record with the same key.

tkrzw_dbm_iter_jump_lower()

bool tkrzw_dbm_iter_jump_lower	(	TkrzwDBMIter *	iter,
		const char *	key_ptr,
		int32_t	key_size,
		bool	inclusive
	)

Initializes the iterator to indicate the last record whose key is lower than a given key.

Parameters

iter	The iterator object.
key_ptr	The key pointer.
key_size	The key size. If it is negative, strlen(key_ptr) is used.
inclusive	If true, the condition is inclusive: equal to or lower than the key.

Returns

True on success or false on failure.

Even if there's no matching record, the operation doesn't fail. This method is suppoerted only by ordered databases.

tkrzw_dbm_iter_jump_upper()

bool tkrzw_dbm_iter_jump_upper	(	TkrzwDBMIter *	iter,
		const char *	key_ptr,
		int32_t	key_size,
		bool	inclusive
	)

Initializes the iterator to indicate the first record whose key is upper than a given key.

Parameters

iter	The iterator object.
key_ptr	The key pointer.
key_size	The key size. If it is negative, strlen(key_ptr) is used.
inclusive	If true, the condition is inclusive: equal to or upper than the key.

Returns

True on success or false on failure.

Even if there's no matching record, the operation doesn't fail. This method is suppoerted only by ordered databases.

tkrzw_dbm_iter_next()

bool tkrzw_dbm_iter_next

(

TkrzwDBMIter *

iter

)

Moves the iterator to the next record.

Parameters

iter	The iterator object.

Returns

True on success or false on failure.

If the current record is missing, the operation fails. Even if there's no next record, the operation doesn't fail.

tkrzw_dbm_iter_previous()

bool tkrzw_dbm_iter_previous

(

TkrzwDBMIter *

iter

)

Moves the iterator to the previous record.

Parameters

iter	The iterator object.

Returns

True on success or false on failure.

If the current record is missing, the operation fails. Even if there's no previous record, the operation doesn't fail. This method is suppoerted only by ordered databases.

tkrzw_dbm_iter_process()

bool tkrzw_dbm_iter_process	(	TkrzwDBMIter *	iter,
		tkrzw_record_processor	proc,
		void *	proc_arg,
		bool	writable
	)

Processes the current record with a processor.

Parameters

iter	The iterator object.
proc	The callback function to process the record.
proc_arg	An arbitrary data which is given to the callback function.
writable	True if the processor can edit the record.

Returns

True on success or false on failure.

If the current record exists, the callback function is called. Otherwise, this method fails and the callback is not called. The callback function returns TKRZW_REC_PROC_NOOP to keep the current value, TKRZW_REC_PROC_REMOVE to remove the record, or a string pointer to a new value to set. The ownership of the return value is not taken. If the current record is removed, the iterator is moved to the next record.

tkrzw_dbm_iter_get()

bool tkrzw_dbm_iter_get	(	TkrzwDBMIter *	iter,
		char **	key_ptr,
		int32_t *	key_size,
		char **	value_ptr,
		int32_t *	value_size
	)

Gets the key and the value of the current record of the iterator.

Parameters

iter	The iterator object.
key_ptr	The pointer to a variable which points to the region containing the record key. If this function returns true, the region should be released by the free function. If it is NULL, it is not used.
key_size	The pointer to a variable which stores the size of the region containing the record key. If it is NULL, it is not used.
value_ptr	The pointer to a variable which points to the region containing the record value. If this function returns true, the region should be released by the free function. If it is NULL, it is not used.
value_size	The pointer to a variable which stores the size of the region containing the record value. If it is NULL, it is not used.

Returns

True on success or false on failure. If theres no record to fetch, false is returned.

tkrzw_dbm_iter_get_key()

char* tkrzw_dbm_iter_get_key	(	TkrzwDBMIter *	iter,
		int32_t *	key_size
	)

Gets the key of the current record, in a simple way.

Parameters

iter	The iterator object.
key_size	The pointer to the variable to store the key size. If it is NULL, it is not used.

Returns

The pointer to the key data, which should be released by the free function. NULL is returned on failure.

tkrzw_dbm_iter_get_value()

char* tkrzw_dbm_iter_get_value	(	TkrzwDBMIter *	iter,
		int32_t *	value_size
	)

Gets the key of the current record, in a simple way.

Parameters

iter	The iterator object.
value_size	The pointer to the variable to store the value size. If it is NULL, it is not used.

Returns

The pointer to the key data, which should be released by the free function. NULL is returned on failure.

tkrzw_dbm_iter_set()

bool tkrzw_dbm_iter_set	(	TkrzwDBMIter *	iter,
		const char *	value_ptr,
		int32_t	value_size
	)

Sets the value of the current record.

Parameters

iter	The iterator object.
value_ptr	The value pointer.
value_size	The value size. If it is negative, strlen(value_ptr) is used.

Returns

True on success or false on failure.

tkrzw_dbm_iter_remove()

bool tkrzw_dbm_iter_remove

(

TkrzwDBMIter *

iter

)

Removes the current record.

Returns

True on success or false on failure.

If possible, the iterator moves to the next record.

tkrzw_dbm_iter_step()

bool tkrzw_dbm_iter_step	(	TkrzwDBMIter *	iter,
		char **	key_ptr,
		int32_t *	key_size,
		char **	value_ptr,
		int32_t *	value_size
	)

Gets the current record and moves the iterator to the next record.

Parameters

iter	The iterator object.
key_ptr	The pointer to a variable which points to the region containing the record key. If this function returns true, the region should be released by the free function. If it is NULL, it is not used.
key_size	The pointer to a variable which stores the size of the region containing the record key. If it is NULL, it is not used.
value_ptr	The pointer to a variable which points to the region containing the record value. If this function returns true, the region should be released by the free function. If it is NULL, it is not used.
value_size	The pointer to a variable which stores the size of the region containing the record value. If it is NULL, it is not used.

tkrzw_dbm_restore_database()

bool tkrzw_dbm_restore_database	(	const char *	old_file_path,
		const char *	new_file_path,
		const char *	class_name,
		int64_t	end_offset,
		const char *	cipher_key
	)

Restores a broken database as a new healthy database.

Parameters

old_file_path	The path of the broken database.
new_file_path	The path of the new database to be created.
class_name	The name of the database class. If it is NULL or empty, the class is guessed from the file extension.
end_offset	The exclusive end offset of records to read. Negative means unlimited. 0 means the size when the database is synched or closed properly. Using a positive value is not meaningful if the number of shards is more than one.
cipher_key	The encryption key for cipher compressors. If it is NULL, an empty key is used.

Returns

True on success or false on failure.

tkrzw_async_dbm_new()

TkrzwAsyncDBM* tkrzw_async_dbm_new	(	TkrzwDBM *	dbm,
		int32_t	num_worker_threads
	)

Creates an asynchronous database adapter.

Parameters

dbm	A database object which has been opened. The ownership is not taken.
num_worker_threads	The number of threads in the internal thread pool.

Returns

The new database object, which should be released by the tkrzw_async_dbm_destruct function.

This class is a wrapper of DBM for asynchronous operations. A task queue with a thread pool is used inside. Every methods except for the constructor and the destructor are run by a thread in the thread pool and the result is set in the future oject of the return value. While the caller should release the returned future object, it can omit evaluation of the result status if it is not interesting. The destructor of this asynchronous database manager waits for all tasks to be done. Therefore, the destructor should be called before the database is closed. Asynchronous functions which take pointers to C-strings copies the regions of them so the caller doesn't have to expand the lifetime of them.

tkrzw_async_dbm_free()

void tkrzw_async_dbm_free

(

TkrzwAsyncDBM *

async

)

Releases the asynchronous database adapter.

Parameters

async

the asynchronous database adapter.

tkrzw_async_dbm_get()

TkrzwFuture* tkrzw_async_dbm_get	(	TkrzwAsyncDBM *	async,
		const char *	key_ptr,
		int32_t	key_size
	)

Gets the value of a record of a key asynchronously.

Parameters

async	the asynchronous database adapter.
key_ptr	The key pointer.
key_size	The key size. If it is negative, strlen(key_ptr) is used.

Returns

The future object to monitor the result. The future object should be released by the tkrzw_future_free function. The result should be gotten by the tkrzw_future_get_str function.

If there's no matching record, NOT_FOUND_ERROR status code is set.

tkrzw_async_dbm_get_multi()

TkrzwFuture* tkrzw_async_dbm_get_multi	(	TkrzwAsyncDBM *	async,
		const TkrzwStr *	keys,
		int32_t	num_keys
	)

Gets the values of multiple records of keys asynchronously.

Parameters

async	the asynchronous database adapter.
keys	An array of the keys of records to retrieve.
num_keys	The number of elements of the key array.

Returns

The future object to monitor the result. The future object should be released by the tkrzw_future_free function. The result should be gotten by the tkrzw_future_get_str_map function.

tkrzw_async_dbm_set()

TkrzwFuture* tkrzw_async_dbm_set	(	TkrzwAsyncDBM *	async,
		const char *	key_ptr,
		int32_t	key_size,
		const char *	value_ptr,
		int32_t	value_size,
		bool	overwrite
	)

Sets a record of a key and a value asynchronously.

Parameters

async	the asynchronous database adapter.
key_ptr	The key pointer.
key_size	The key size. If it is negative, strlen(key_ptr) is used.
value_ptr	The value pointer.
value_size	The value size. If it is negative, strlen(value_ptr) is used.
overwrite	Whether to overwrite the existing value if there's a record with the same key. If true, the existing value is overwritten by the new value. If false, the operation is given up and an error status is set.

Returns

The future object to monitor the result. The future object should be released by the tkrzw_future_free function. The result should be gotten by the tkrzw_future_get function.

If overwriting is abandoned, DUPLICATION_ERROR status code is set.

tkrzw_async_dbm_set_multi()

TkrzwFuture* tkrzw_async_dbm_set_multi	(	TkrzwAsyncDBM *	async,
		const TkrzwKeyValuePair *	records,
		int32_t	num_records,
		bool	overwrite
	)

Sets multiple records asynchronously.

Parameters

async	the asynchronous database adapter.
records	An array of the key-value pairs of records to store.
num_records	The number of elements of the record array.
overwrite	Whether to overwrite the existing value if there's a record with the same key. If true, the existing value is overwritten by the new value. If false, the operation is given up and an error status is set.

Returns

The future object to monitor the result. The future object should be released by the tkrzw_future_free function. The result should be gotten by the tkrzw_future_get function.

If overwriting is abandoned, DUPLICATION_ERROR status code is set.

tkrzw_async_dbm_remove()

TkrzwFuture* tkrzw_async_dbm_remove	(	TkrzwAsyncDBM *	async,
		const char *	key_ptr,
		int32_t	key_size
	)

Removes a record of a key asynchronously.

Parameters

async	the asynchronous database adapter.
key_ptr	The key pointer.
key_size	The key size. If it is negative, strlen(key_ptr) is used.

Returns

The future object to monitor the result. The future object should be released by the tkrzw_future_free function. The result should be gotten by the tkrzw_future_get function.

If there's no matching record, NOT_FOUND_ERROR status code is set.

tkrzw_async_dbm_remove_multi()

TkrzwFuture* tkrzw_async_dbm_remove_multi	(	TkrzwAsyncDBM *	async,
		const TkrzwStr *	keys,
		int32_t	num_keys
	)

Removes records of keys asynchronously.

Parameters

async	the asynchronous database adapter.
keys	An array of the keys of records to retrieve.
num_keys	The number of elements of the key array.

Returns

The future object to monitor the result. The future object should be released by the tkrzw_future_free function. The result should be gotten by the tkrzw_future_get function.

If there are missing records, NOT_FOUND_ERROR status code is set.

tkrzw_async_dbm_append()

TkrzwFuture* tkrzw_async_dbm_append	(	TkrzwAsyncDBM *	async,
		const char *	key_ptr,
		int32_t	key_size,
		const char *	value_ptr,
		int32_t	value_size,
		const char *	delim_ptr,
		int32_t	delim_size
	)

Appends data at the end of a record of a key asynchronously.

Parameters

async	the asynchronous database adapter.
key_ptr	The key pointer.
key_size	The key size. If it is negative, strlen(key_ptr) is used.
value_ptr	The value pointer.
value_size	The value size. If it is negative, strlen(value_ptr) is used.
delim_ptr	The delimiter pointer.
delim_size	The delimiter size. If it is negative, strlen(delim_ptr) is used.

Returns

The future object to monitor the result. The future object should be released by the tkrzw_future_free function. The result should be gotten by the tkrzw_future_get function.

If there's no existing record, the value is set without the delimiter.

tkrzw_async_dbm_append_multi()

TkrzwFuture* tkrzw_async_dbm_append_multi	(	TkrzwAsyncDBM *	async,
		const TkrzwKeyValuePair *	records,
		int32_t	num_records,
		const char *	delim_ptr,
		int32_t	delim_size
	)

Appends data to multiple records asynchronously.

Parameters

async	the asynchronous database adapter.
records	An array of the key-value pairs of records to append.
num_records	The number of elements of the record array.
delim_ptr	The delimiter pointer.
delim_size	The delimiter size. If it is negative, strlen(delim_ptr) is used.

Returns

The future object to monitor the result. The future object should be released by the tkrzw_future_free function. The result should be gotten by the tkrzw_future_get function.

If there's no existing record, the value is set without the delimiter.

tkrzw_async_dbm_compare_exchange()

TkrzwFuture* tkrzw_async_dbm_compare_exchange	(	TkrzwAsyncDBM *	async,
		const char *	key_ptr,
		int32_t	key_size,
		const char *	expected_ptr,
		int32_t	expected_size,
		const char *	desired_ptr,
		int32_t	desired_size
	)

Compares the value of a record and exchanges if the condition meets asynchronously.

Parameters

async	the asynchronous database adapter.
key_ptr	The key pointer.
key_size	The key size. If it is negative, strlen(key_ptr) is used.
expected_ptr	The expected value pointer. If it is NULL, no existing record is expected. If it is TKRZW_ANY_DATA, an existing record with any value is expacted.
expected_size	The expected value size. If it is negative, strlen(expected_ptr) is used.
desired_ptr	The desired value pointer. If it is NULL, the record is to be removed. expected. If it is TKRZW_ANY_DATA, no update is done.
desired_size	The desired value size. If it is negative, strlen(desired_ptr) is used.

Returns

The future object to monitor the result. The future object should be released by the tkrzw_future_free function. The result should be gotten by the tkrzw_future_get function.

If the condition doesn't meet, INFEASIBLE_ERROR status code is set.

tkrzw_async_dbm_increment()

TkrzwFuture* tkrzw_async_dbm_increment	(	TkrzwAsyncDBM *	async,
		const char *	key_ptr,
		int32_t	key_size,
		int64_t	increment,
		int64_t	initial
	)

Increments the numeric value of a record asynchronously.

Parameters

async	the asynchronous database adapter.
key_ptr	The key pointer.
key_size	The key size. If it is negative, strlen(key_ptr) is used.
increment	The incremental value. If it is TKRZW_INT64MIN, the current value is not changed and a new record is not created.
initial	The initial value.

Returns

The future object to monitor the result. The future object should be released by the tkrzw_future_free function. The result should be gotten by the tkrzw_future_get_int function.

The record value is stored as an 8-byte big-endian integer. Negative is also supported.

tkrzw_async_dbm_compare_exchange_multi()

TkrzwFuture* tkrzw_async_dbm_compare_exchange_multi	(	TkrzwAsyncDBM *	async,
		const TkrzwKeyValuePair *	expected,
		int32_t	num_expected,
		const TkrzwKeyValuePair *	desired,
		int32_t	num_desired
	)

Compares the values of records and exchanges if the condition meets asynchronously.

Parameters

async	the asynchronous database adapter.
expected	An array of the record keys and their expected values. If the value is NULL, no existing record is expected. If the value is TKRZW_ANY_DATA, an existing record with any value is expacted.
num_expected	The number of the expected array.
desired	An array of the record keys and their desired values. If the value is NULL, the record is to be removed.
num_desired	The number of the desired array.

Returns

The future object to monitor the result. The future object should be released by the tkrzw_future_free function. The result should be gotten by the tkrzw_future_get function.

If the condition doesn't meet, INFEASIBLE_ERROR is returned.

tkrzw_async_dbm_rekey()

TkrzwFuture* tkrzw_async_dbm_rekey	(	TkrzwAsyncDBM *	async,
		const char *	old_key_ptr,
		int32_t	old_key_size,
		const char *	new_key_ptr,
		int32_t	new_key_size,
		bool	overwrite,
		bool	copying
	)

Changes the key of a record asynchronously.

Parameters

async	the asynchronous database adapter.
old_key_ptr	The old key pointer.
old_key_size	The old key size. If it is negative, strlen(old_key_ptr) is used.
new_key_ptr	The new key pointer.
new_key_size	The new key size. If it is negative, strlen(new_key_ptr) is used.
overwrite	Whether to overwrite the existing record of the new key.
copying	Whether to retain the record of the old key.

Returns

The future object to monitor the result. The future object should be released by the tkrzw_future_free function. The result should be gotten by the tkrzw_future_get function.

If there's no matching record to the old key, NOT_FOUND_ERROR is set. If the overwrite flag is false and there is an existing record of the new key, DUPLICATION ERROR is set. This method is done atomically by ProcessMulti. The other threads observe that the record has either the old key or the new key. No intermediate states are observed.

tkrzw_async_dbm_pop_first()

TkrzwFuture* tkrzw_async_dbm_pop_first

(

TkrzwAsyncDBM *

async

)

Gets the first record and removes it asynchronously.

Parameters

async

the asynchronous database adapter.

Returns

The future object to monitor the result. The future object should be released by the tkrzw_future_free function. The result should be gotten by the tkrzw_future_get_str_pair function.

tkrzw_async_dbm_push_last()

TkrzwFuture* tkrzw_async_dbm_push_last	(	TkrzwAsyncDBM *	async,
		const char *	value_ptr,
		int32_t	value_size,
		double	wtime
	)

Adds a record with a key of the current timestamp.

Parameters

async	the asynchronous database adapter.
value_ptr	The value pointer.
value_size	The value size. If it is negative, strlen(value_ptr) is used.
wtime	The current wall time used to generate the key. If it is negative, the system clock is used.

Returns

The future object to monitor the result. The future object should be released by the tkrzw_future_free function. The result should be gotten by the tkrzw_future_get function.

The key is generated as an 8-bite big-endian binary string of the timestamp. If there is an existing record matching the generated key, the key is regenerated and the attempt is repeated until it succeeds.

tkrzw_async_dbm_clear()

TkrzwFuture* tkrzw_async_dbm_clear

(

TkrzwAsyncDBM *

async

)

Removes all records asynchronously.

Parameters

async

the asynchronous database adapter.

Returns

The future object to monitor the result. The future object should be released by the tkrzw_future_free function. The result should be gotten by the tkrzw_future_get function.

tkrzw_async_dbm_rebuild()

TkrzwFuture* tkrzw_async_dbm_rebuild	(	TkrzwAsyncDBM *	async,
		const char *	params
	)

Rebuilds the entire database asynchronously.

Parameters

async	the asynchronous database adapter.
params	Optional parameters in "key=value,key=value" format. The parameters work in the same way as with PolyDBM::RebuildAdvanced.

Returns

The future object to monitor the result. The future object should be released by the tkrzw_future_free function. The result should be gotten by the tkrzw_future_get function.

tkrzw_async_dbm_synchronize()

TkrzwFuture* tkrzw_async_dbm_synchronize	(	TkrzwAsyncDBM *	async,
		bool	hard,
		const char *	params
	)

Synchronizes the content of the database to the file system asynchronously.

Parameters

async	the asynchronous database adapter.
hard	True to do physical synchronization with the hardware or false to do only logical synchronization with the file system.
params	Optional parameters in "key=value,key=value" format. The parameters work in the same way as with PolyDBM::OpenAdvanced.

Returns

The future object to monitor the result. The future object should be released by the tkrzw_future_free function. The result should be gotten by the tkrzw_future_get function.

tkrzw_async_dbm_copy_file_data()

TkrzwFuture* tkrzw_async_dbm_copy_file_data	(	TkrzwAsyncDBM *	async,
		const char *	dest_path,
		bool	sync_hard
	)

Copies the content of the database files to other files.

Parameters

async	the asynchronous database adapter.
dest_path	The path prefix to the destination files.
sync_hard	True to do physical synchronization with the hardware.

Returns

The future object to monitor the result. The future object should be released by the tkrzw_future_free function. The result should be gotten by the tkrzw_future_get function.

Copying is done while the content is synchronized and stable. So, this method is suitable for making a backup file while running a database service.

tkrzw_async_dbm_export()

TkrzwFuture* tkrzw_async_dbm_export	(	TkrzwAsyncDBM *	async,
		TkrzwDBM *	dest_dbm
	)

Exports all records to another database.

Parameters

async	the asynchronous database adapter.
dest_dbm	The destination database object. The lefetime of the database object must last until the task finishes.

Returns

The future object to monitor the result. The future object should be released by the tkrzw_future_free function. The result should be gotten by the tkrzw_future_get function.

tkrzw_async_dbm_export_to_flat_records()

TkrzwFuture* tkrzw_async_dbm_export_to_flat_records	(	TkrzwAsyncDBM *	async,
		TkrzwFile *	dest_file
	)

Exports all records of a database to a flat record file.

Parameters

async	the asynchronous database adapter.
dest_file	The file object to write records in. The lefetime of the file object must last until the task finishes.

Returns

The future object to monitor the result. The future object should be released by the tkrzw_future_free function. The result should be gotten by the tkrzw_future_get function.

tkrzw_async_dbm_import_from_flat_records()

TkrzwFuture* tkrzw_async_dbm_import_from_flat_records	(	TkrzwAsyncDBM *	async,
		TkrzwFile *	src_file
	)

Imports records to a database from a flat record file.

Parameters

async	the asynchronous database adapter.
src_file	The file object to read records from. The lefetime of the file object must last until the task finishes.

Returns

The future object to monitor the result. The future object should be released by the tkrzw_future_free function. The result should be gotten by the tkrzw_future_get function.

tkrzw_async_dbm_search()

TkrzwFuture* tkrzw_async_dbm_search	(	TkrzwAsyncDBM *	async,
		const char *	mode,
		const char *	pattern_ptr,
		int32_t	pattern_size,
		int32_t	capacity
	)

Searches a database and get keys asynchronously.

Parameters

async	the asynchronous database adapter.
mode	The search mode. "contain" extracts keys containing the pattern. "begin" extracts keys beginning with the pattern. "end" extracts keys ending with the pattern. "regex" extracts keys partially matches the pattern of a regular expression. "edit" extracts keys whose edit distance to the pattern is the least. Ordered databases support "upper" and "lower" which extract keys whose positions are equal to or upper/lower than the pattern. "upperex" and "lowerex" are their exclusive versions.
pattern_ptr	The pattern pointer.
pattern_size	The pattern size. If it is negative, strlen(pattern_ptr) is used.
capacity	The maximum records to obtain. 0 means unlimited.

Returns

The future object to monitor the result. The future object should be released by the tkrzw_future_free function. The result should be gotten by the tkrzw_future_get_str_array function.

tkrzw_file_open()

TkrzwFile* tkrzw_file_open	(	const char *	path,
		bool	writable,
		const char *	params
	)

Opens a file.

Parameters

path	A path of the file.
writable	If true, the file is writable. If false, it is read-only.
params	Optional parameters in "key=value,key=value" format.

Returns

The new file object, which should be released by the tkrzw_dbm_close function. NULL is returned on failure.

The optional parameters can include options for the file opening operation.

• truncate (bool): True to truncate the file.
• no_create (bool): True to omit file creation.
• no_wait (bool): True to fail if the file is locked by another process.
• no_lock (bool): True to omit file locking.

• sync_hard (bool): True to do physical synchronization when closing.

  The optional parameter "file" specifies the internal file implementation class. The default file class is "MemoryMapAtomicFile". The other supported classes are "StdFile", "MemoryMapAtomicFile", "PositionalParallelFile", and "PositionalAtomicFile".

  For the file "PositionalParallelFile" and "PositionalAtomicFile", these optional parameters are supported.

• block_size (int): The block size to which all blocks should be aligned.
• access_options (str): Values separated by colon. "direct" for direct I/O. "sync" for synchrnizing I/O, "padding" for file size alignment by padding, "pagecache" for the mini page cache in the process.

tkrzw_file_close()

bool tkrzw_file_close

(

TkrzwFile *

file

)

Closes the file.

Parameters

file	The file object.

Returns

True on success or false on failure.

tkrzw_file_read()

bool tkrzw_file_read	(	TkrzwFile *	file,
		int64_t	off,
		void *	buf,
		size_t	size
	)

Reads data.

Parameters

file	The file object.
off	The offset of a source region.
buf	The pointer to the destination buffer.
size	The size of the data to be read.

Returns

True on success or false on failure.

tkrzw_file_write()

bool tkrzw_file_write	(	TkrzwFile *	file,
		int64_t	off,
		const void *	buf,
		size_t	size
	)

Writes data.

Parameters

file	The file object.
off	The offset of the destination region.
buf	The pointer to the source buffer.
size	The size of the data to be written.

Returns

True on success or false on failure.

tkrzw_file_append()

bool tkrzw_file_append	(	TkrzwFile *	file,
		const void *	buf,
		size_t	size,
		int64_t *	off
	)

Appends data at the end of the file.

Parameters

file	The file object.
buf	The pointer to the source buffer.
size	The size of the data to be written.
off	The pointer to an integer object to contain the offset at which the data has been put. If it is nullptr, it is ignored.

Returns

True on success or false on failure.

tkrzw_file_truncate()

bool tkrzw_file_truncate	(	TkrzwFile *	file,
		int64_t	size
	)

Truncates the file.

Parameters

file	The file object.
size	The new size of the file.

Returns

True on success or false on failure.

If the file is shrunk, data after the new file end is discarded. If the file is expanded, null codes are filled after the old file end.

tkrzw_file_synchronize()

bool tkrzw_file_synchronize	(	TkrzwFile *	file,
		bool	hard,
		int64_t	off,
		int64_t	size
	)

Synchronizes the content of the file to the file system.

Parameters

file	The file object.
hard	True to do physical synchronization with the hardware or false to do only logical synchronization with the file system.
off	The offset of the region to be synchronized.
size	The size of the region to be synchronized. If it is zero, the length to the end of file is specified.

Returns

True on success or false on failure.

The pysical file size can be larger than the logical size in order to improve performance by reducing frequency of allocation. Thus, you should call this function before accessing the file with external tools.

tkrzw_file_get_size()

int64_t tkrzw_file_get_size

(

TkrzwFile *

file

)

Gets the size of the file.

Parameters

file	The file object.

Returns

The size of the on success, or -1 on failure.

tkrzw_file_get_path()

char* tkrzw_file_get_path

(

TkrzwFile *

file

)

Gets the path of the file.

Parameters

file	The file object.

Returns

The pointer to the path data, which should be released by the free function. NULL is returned on failure.

tkrzw_file_search()

TkrzwStr* tkrzw_file_search	(	TkrzwFile *	file,
		const char *	mode,
		const char *	pattern_ptr,
		int32_t	pattern_size,
		int32_t	capacity,
		int32_t *	num_matched
	)

Searches the file and get lines which match a pattern, according to a mode expression.

Parameters

file	The file object.
mode	The search mode. "contain" extracts keys containing the pattern. "begin" extracts keys beginning with the pattern. "end" extracts keys ending with the pattern. "regex" extracts keys partially matches the pattern of a regular expression. "edit" extracts keys whose edit distance to the UTF-8 pattern is the least. "editbin" extracts keys whose edit distance to the binary pattern is the least.
pattern_ptr	The key pointer.
pattern_size	The key size. If it is negative, strlen(pattern_ptr) is used.
capacity	The maximum records to obtain. 0 means unlimited.
num_matched	The pointer to the variable to store the number of the element of the return value.

Returns

The pointer to an array of matched keys or NULL on failure. If not NULL, the array and its elements are allocated dynamically so they should be released by the tkrzw_free_str_array function.

tkrzw_index_open()

TkrzwIndex* tkrzw_index_open	(	const char *	path,
		bool	writable,
		const char *	params
	)

Opens an index file and makes an index object.

Parameters

path	A path of the file.
writable	If true, the file is writable. If false, it is read-only.
params	Optional parameters in "key=value,key=value" format. The options for the file opening operation are set by "truncate", "no_create", "no_wait", "no_lock", and "sync_hard". Other options are the same as PolyIndex::Open.

Returns

The new database object, which should be released by the tkrzw_index_close function. NULL is returned on failure.

If the path is empty, BabyDBM is used internally, which is equivalent to using the MemIndex class. If the path ends with ".tkt", TreeDBM is used internally, which is equivalent to using the FileIndex class. If the key comparator of the tuning parameter is not set, PairLexicalKeyComparator is set implicitly. Other compatible key comparators are PairLexicalCaseKeyComparator, PairDecimalKeyComparator, PairHexadecimalKeyComparator, and PairRealNumberKeyComparator.

tkrzw_index_close()

bool tkrzw_index_close

(

TkrzwIndex *

index

)

Closes the index file and releases the index object.

Parameters

index

The index object.

Returns

True on success or false on failure.

tkrzw_index_check()

bool tkrzw_index_check	(	TkrzwIndex *	index,
		const char *	key_ptr,
		int32_t	key_size,
		const char *	value_ptr,
		int32_t	value_size
	)

Checks whether a record exists in the index.

Parameters

index	The index object.
key_ptr	The key pointer.
key_size	The key size. If it is negative, strlen(key_ptr) is used.
value_ptr	The value pointer.
value_size	The value size. If it is negative, strlen(value_ptr) is used.

Returns

True if the record exists, or false if not.

tkrzw_index_get_values()

TkrzwStr* tkrzw_index_get_values	(	TkrzwIndex *	index,
		const char *	key_ptr,
		int32_t	key_size,
		int32_t	max,
		int32_t *	num_elems
	)

Gets all values of records of a key.

Parameters

index	The index object.
key_ptr	The key pointer.
key_size	The key size. If it is negative, strlen(key_ptr) is used.
max	The maximum number of values to get. 0 means unlimited.
num_elems	The pointer to the variable to store the number of elements of the extra string array.

Returns

The pointer to an array of all values of the key, which should be released by the tkrzw_free_str_array function. An empty array is returned on failure.

tkrzw_index_add()

bool tkrzw_index_add	(	TkrzwIndex *	index,
		const char *	key_ptr,
		int32_t	key_size,
		const char *	value_ptr,
		int32_t	value_size
	)

Adds a record.

Parameters

index	The index object.
key_ptr	The key pointer. This can be an arbitrary expression to search the index.
key_size	The key size. If it is negative, strlen(key_ptr) is used.
value_ptr	The value pointer. This should be a primary value of another database.
value_size	The value size. If it is negative, strlen(value_ptr) is used.

Returns

True on success or false on failure.

tkrzw_index_remove()

bool tkrzw_index_remove	(	TkrzwIndex *	index,
		const char *	key_ptr,
		int32_t	key_size,
		const char *	value_ptr,
		int32_t	value_size
	)

Remove a record.

Parameters

index	The index object.
key_ptr	The key pointer. This can be an arbitrary expression to search the index.
key_size	The key size. If it is negative, strlen(key_ptr) is used.
value_ptr	The value pointer. This should be a primary value of another database.
value_size	The value size. If it is negative, strlen(value_ptr) is used.

Returns

True on success or false on failure.

tkrzw_index_count()

int32_t tkrzw_index_count

(

TkrzwIndex *

index

)

Gets the number of records.

Parameters

index

The index object.

Returns

The number of records, or -1 on failure.

tkrzw_index_get_file_path()

char* tkrzw_index_get_file_path

(

TkrzwIndex *

index

)

Gets the path of the index file.

Parameters

index

The index object.

Returns

The pointer to the path data, which should be released by the free function. An empty string is returned on failure.

tkrzw_index_clear()

bool tkrzw_index_clear

(

TkrzwIndex *

index

)

Removes all records.

Parameters

index

The index object.

Returns

True on success or false on failure.

tkrzw_index_rebuild()

bool tkrzw_index_rebuild

(

TkrzwIndex *

index

)

Rebuilds the entire database.

Parameters

index

The index object.

Returns

True on success or false on failure.

tkrzw_index_synchronize()

bool tkrzw_index_synchronize	(	TkrzwIndex *	index,
		bool	hard
	)

Synchronizes the content of the database to the file system.

Parameters

index	The index object.
hard	True to do physical synchronization with the hardware or false to do only logical synchronization with the file system.

Returns

True on success or false on failure.

tkrzw_index_is_writable()

bool tkrzw_index_is_writable

(

TkrzwIndex *

index

)

Checks whether the database is writable.

Parameters

index

The index object.

Returns

True if the database is writable, or false if not.

tkrzw_index_make_iterator()

TkrzwIndexIter* tkrzw_index_make_iterator

(

TkrzwIndex *

index

)

Makes an iterator for each record.

Parameters

index

The index object.

Returns

The new iterator object, which should be released by the tkrzw_index_iter_free function.

tkrzw_index_iter_free()

void tkrzw_index_iter_free

(

TkrzwIndexIter *

iter

)

Releases the iterator object.

Parameters

iter	The iterator object.

tkrzw_index_iter_first()

void tkrzw_index_iter_first

(

TkrzwIndexIter *

iter

)

Initializes the iterator to indicate the first record.

Parameters

iter	The iterator object.

tkrzw_index_iter_last()

void tkrzw_index_iter_last

(

TkrzwIndexIter *

iter

)

Initializes the iterator to indicate the last record.

Parameters

iter	The iterator object.

tkrzw_index_iter_jump()

void tkrzw_index_iter_jump	(	TkrzwIndexIter *	iter,
		const char *	key_ptr,
		int32_t	key_size,
		const char *	value_ptr,
		int32_t	value_size
	)

Initializes the iterator to indicate a specific range.

Parameters

iter	The iterator object.
key_ptr	The key pointer of the lower bound.
key_size	The key size. If it is negative, strlen(key_ptr) is used.
value_ptr	The value pointer of the lower bound.
value_size	The value size. If it is negative, strlen(value_ptr) is used.

tkrzw_index_iter_next()

void tkrzw_index_iter_next

(

TkrzwIndexIter *

iter

)

Moves the iterator to the next record.

Parameters

iter	The iterator object.

tkrzw_index_iter_previous()

void tkrzw_index_iter_previous

(

TkrzwIndexIter *

iter

)

Moves the iterator to the previous record.

Parameters

iter	The iterator object.

tkrzw_index_iter_get()

bool tkrzw_index_iter_get	(	TkrzwIndexIter *	iter,
		char **	key_ptr,
		int32_t *	key_size,
		char **	value_ptr,
		int32_t *	value_size
	)

Gets the key and the value of the current record of the iterator.

Parameters

iter	The iterator object.
key_ptr	The pointer to a variable which points to the region containing the record key. If this function returns true, the region should be released by the free function. If it is NULL, it is not used.
key_size	The pointer to a variable which stores the size of the region containing the record key. If it is NULL, it is not used.
value_ptr	The pointer to a variable which points to the region containing the record value. If this function returns true, the region should be released by the free function. If it is NULL, it is not used.
value_size	The pointer to a variable which stores the size of the region containing the record value. If it is NULL, it is not used.

Returns

True on success or false on failure. If theres no record to fetch, false is returned.

Variable Documentation

TKRZW_PACKAGE_VERSION

const char* const TKRZW_PACKAGE_VERSION

extern

The string expression of the package version.

TKRZW_LIBRARY_VERSION

const char* const TKRZW_LIBRARY_VERSION

extern

The string expression of the library version.

TKRZW_OS_NAME

const char* const TKRZW_OS_NAME

extern

The recognized OS name.

TKRZW_PAGE_SIZE

const int32_t TKRZW_PAGE_SIZE

extern

The size of a memory page on the OS.

TKRZW_INT64MIN

const int64_t TKRZW_INT64MIN

extern

The minimum value of int64_t.

TKRZW_INT64MAX

const int64_t TKRZW_INT64MAX

extern

The maximum value of int64_t.

TKRZW_ANY_DATA

const char* const TKRZW_ANY_DATA

extern

The special string_view value to represent any data.

TKRZW_REC_PROC_NOOP

const char* const TKRZW_REC_PROC_NOOP

extern

The special string indicating no operation.

TKRZW_REC_PROC_REMOVE

const char* const TKRZW_REC_PROC_REMOVE

extern

The special string indicating removing operation.