@@ -53,7 +53,7 @@ extern "C" {
5353/// obx_version() or obx_version_is_at_least().
5454#define OBX_VERSION_MAJOR 4
5555#define OBX_VERSION_MINOR 0
56- #define OBX_VERSION_PATCH 0 // values >= 100 are reserved for dev releases leading to the next minor/major increase
56+ #define OBX_VERSION_PATCH 1 // values >= 100 are reserved for dev releases leading to the next minor/major increase
5757
5858//----------------------------------------------
5959// Common types
@@ -79,13 +79,19 @@ typedef struct OBX_id_score {
7979/// Error/success code returned by an obx_* function; see defines OBX_SUCCESS, OBX_NOT_FOUND, and OBX_ERROR_*
8080typedef int obx_err ;
8181
82- /// The callback for reading data one-by-one
82+ /// The callback for reading data (i.e. object bytes) one-by-one.
8383/// @param data is the read data buffer
8484/// @param size specifies the length of the read data
8585/// @param user_data is a pass-through argument passed to the called API
86- /// @return true to keep going, false to cancel.
86+ /// @return The visitor returns true to keep going or false to cancel.
8787typedef bool obx_data_visitor (const uint8_t * data , size_t size , void * user_data );
8888
89+ /// The callback for reading data (i.e. object bytes) with a search score one-by-one.
90+ /// @param data contains the current data with score element
91+ /// @param user_data is a pass-through argument passed to the called API
92+ /// @return The visitor returns true to keep going or false to cancel.
93+ typedef bool obx_data_score_visitor (const struct OBX_bytes_score * data , void * user_data );
94+
8995//----------------------------------------------
9096// Runtime library information
9197//
@@ -805,6 +811,15 @@ typedef enum {
805811 OBXBackupFlags_ExcludeSalt = 0x2 ,
806812} OBXBackupFlags ;
807813
814+ /// WAL flags control how the store handles WAL files.
815+ typedef enum {
816+ /// Enable Wal
817+ OBXWalFlags_EnableWal = 0x1 ,
818+
819+ /// Does not wait for the disk to acknowledge; faster but not ACID compliant (not generally recommended).
820+ OBXWalFlags_NoSyncFile = 0x2 ,
821+ } OBXWalFlags ;
822+
808823/// This bytes struct is an input/output wrapper used for a single data object (represented as FlatBuffers).
809824typedef struct OBX_bytes {
810825 const uint8_t * data ;
@@ -1087,6 +1102,23 @@ typedef enum {
10871102/// e.g., to overwrite all existing data in the database.
10881103OBX_C_API void obx_opt_backup_restore (OBX_store_options * opt , const char * backup_file , uint32_t flags );
10891104
1105+ /// Enables Write-ahead logging (WAL) if OBXWalFlags_EnableWal is given.
1106+ /// For now this is only supported for in-memory DBs.
1107+ /// @param flags OBXWalFlags_EnableWal with optional other flags (bitwise OR).
1108+ OBX_C_API void obx_opt_wal (OBX_store_options * opt , uint32_t flags );
1109+
1110+ /// The WAL file gets consolidated when it reached this size limit when opening the database.
1111+ /// This setting is meant for applications that prefer to consolidate on startup,
1112+ /// which may avoid consolidations on commits while the application is running.
1113+ /// The default is 4096 (4 MB).
1114+ OBX_C_API void obx_opt_wal_max_file_size_on_open_in_kb (OBX_store_options * opt , uint64_t size_in_kb );
1115+
1116+ /// The WAL file gets consolidated when it reaches this size limit after a commit.
1117+ /// As consolidation takes some time, it is a trade-off between accumulating enough data
1118+ /// and the time the consolidation takes (longer with more data).
1119+ /// The default is 16384 (16 MB).
1120+ OBX_C_API void obx_opt_wal_max_file_size_in_kb (OBX_store_options * opt , uint64_t size_in_kb );
1121+
10901122/// Gets the option for "directory"; this is either the default, or, the value set by obx_opt_directory().
10911123/// The returned value must not be modified and is only valid for the lifetime of the options or until the value is
10921124/// changed.
@@ -1235,7 +1267,10 @@ typedef enum {
12351267 OBXStoreTypeId_LMDB = 1 ,
12361268
12371269 /// Store type ID for in-memory database (non-persistent)
1238- OBXStoreTypeId_InMemory = 2
1270+ OBXStoreTypeId_InMemory = 2 ,
1271+
1272+ /// Store type ID for in-memory WAL-enabled (persistent)
1273+ OBXStoreTypeId_InMemoryWal = 3
12391274
12401275} OBXStoreTypeId ;
12411276
@@ -2053,10 +2088,14 @@ OBX_C_API obx_err obx_query_find_first(OBX_query* query, const uint8_t** data, s
20532088/// operation (e.g. put/remove) was executed. Accessing data after this is undefined behavior.
20542089OBX_C_API obx_err obx_query_find_unique (OBX_query * query , const uint8_t * * data , size_t * size );
20552090
2056- /// Walk over matching objects using the given data visitor.
2091+ /// Walk over matching objects one-by-one using the given data visitor (a callback function) .
20572092/// Note: if no order conditions is present, the order is arbitrary (sometimes ordered by ID, but never guaranteed to).
20582093OBX_C_API obx_err obx_query_visit (OBX_query * query , obx_data_visitor * visitor , void * user_data );
20592094
2095+ /// Walk over matching objects with their query score one-by-one using the given data visitor (a callback function).
2096+ /// Note: the elements are ordered by the score (ascending).
2097+ OBX_C_API obx_err obx_query_visit_with_score (OBX_query * query , obx_data_score_visitor * visitor , void * user_data );
2098+
20602099/// Return the IDs of all matching objects.
20612100/// Note: if no order conditions is present, the order is arbitrary (sometimes ordered by ID, but never guaranteed to).
20622101OBX_C_API OBX_id_array * obx_query_find_ids (OBX_query * query );
@@ -2492,6 +2531,29 @@ OBX_C_API obx_id obx_tree_leaves_info_id(OBX_tree_leaves_info* leaves_info, size
24922531/// Frees a leaves info reference.
24932532OBX_C_API void obx_tree_leaves_info_free (OBX_tree_leaves_info * leaves_info );
24942533
2534+ /// Callback for obx_tree_async_get_raw().
2535+ /// \note If the given status is an error, you can use functions like obx_last_error_message() to gather more info
2536+ /// during this callback (error state is thread bound and the callback uses an internal thread).
2537+ /// @param status The result status of the async operation
2538+ /// @param id If the operation was successful, the ID of the leaf, which was get (otherwise zero).
2539+ /// @param path The leafs path as string.
2540+ /// @param leaf_data The leafs data flatbuffer pointer.
2541+ /// @param leaf_data_size The leafs data flatbuffer size.
2542+ /// @param leaf_metadata The leafs metadata flatbuffer pointer.
2543+ /// @param leaf_metadata_size The leafs meatdata flatbuffer size.
2544+ /// @param user_data The data initially passed to the async function call is passed back.
2545+ typedef void obx_tree_async_get_callback (obx_err status , obx_id id , const char * path , const uint8_t * leaf_data ,
2546+ size_t leaf_data_size , const uint8_t * leaf_metadata , size_t leaf_metadata_size ,
2547+ void * user_data );
2548+
2549+ /// Like obx_tree_cursor_get_raw(), but asynchronous.
2550+ /// @param with_metadata Flag if the callback also wants to receive the metadata (also as raw FlatBuffers).
2551+ /// @param callback Optional (may be null) function that is called with results once the async operation completes.
2552+ /// @param callback_user_data Any value you can supply, which is passed on to the callback (e.g. to identify user
2553+ /// specific context).
2554+ OBX_C_API obx_err obx_tree_async_get_raw (OBX_tree * tree , const char * path , bool with_metadata ,
2555+ obx_tree_async_get_callback * callback , void * callback_user_data );
2556+
24952557/// Callback for obx_tree_async_put_raw().
24962558/// \note If the given status is an error, you can use functions like obx_last_error_message() to gather more info
24972559/// during this callback (error state is thread bound and the callback uses an internal thread).
0 commit comments