diff options
Diffstat (limited to 'src/anydb.h')
| -rw-r--r-- | src/anydb.h | 213 |
1 files changed, 185 insertions, 28 deletions
diff --git a/src/anydb.h b/src/anydb.h index 843ef29..64f86bd 100644 --- a/src/anydb.h +++ b/src/anydb.h @@ -14,8 +14,12 @@ * See the License for the specific language governing permissions and * limitations under the License. */ - #pragma once +/******************************************************************************/ +/******************************************************************************/ +/* HIGH LEVEL ABSTRACTION OF THE DATABASES */ +/******************************************************************************/ +/******************************************************************************/ /** * An index is an integer @@ -29,10 +33,16 @@ typedef uint32_t anydb_idx_t; /** The invalid index */ #define AnyIdx_Invalid ((anydb_idx_t)0xffffffffu) -/** */ +/** The index for ANY */ #define AnyIdx_Any ((anydb_idx_t)0xfffffffeu) + +/** The index for WIDE */ #define AnyIdx_Wide ((anydb_idx_t)0xfffffffdu) + +/** The index for NONE */ #define AnyIdx_None ((anydb_idx_t)0xfffffffcu) + +/** The maximum value for indexes */ #define AnyIdx_Max ((anydb_idx_t)0xfffffff7u) /** @@ -67,45 +77,155 @@ struct anydb_value typedef struct anydb_value anydb_value_t; /** + * Operation of the transaction */ -enum anydb_action -{ - Anydb_Action_Stop, - Anydb_Action_Continue, - Anydb_Action_Update_And_Stop, - Anydb_Action_Remove_And_Continue -}; -typedef enum anydb_action anydb_action_t; - enum anydb_transaction { + /** + * Operation: Start a cancelable transaction + */ Anydb_Transaction_Start = 0, + + /** + * Operation: Terminate the started transaction and commit its changes + */ Anydb_Transaction_Commit = 1, + + /** + * Operation: Terminate the started transaction and cancel its changes + */ Anydb_Transaction_Cancel = 2 }; typedef enum anydb_transaction anydb_transaction_t; +/** + * Actions to perform in response to anydb_applycb_t callbacks. + */ +enum anydb_action +{ + /** Continue to apply with the next element of the database */ + Anydb_Action_Continue = 0, + + /** Stop to apply */ + Anydb_Action_Stop = 1, + + /** Update the current element (implicitly, also continue) */ + Anydb_Action_Update = 2, + + /** Remove the current element (implicitly, also continue) */ + Anydb_Action_Remove = 4, + + /** Update the current element and stop to apply */ + Anydb_Action_Update_And_Stop = Anydb_Action_Update | Anydb_Action_Stop, + + /** Update the current element and continue to apply */ + Anydb_Action_Update_And_Continue = Anydb_Action_Update | Anydb_Action_Continue, + + /** Remove the current element and stop to apply */ + Anydb_Action_Remove_And_Stop = Anydb_Action_Remove | Anydb_Action_Stop, + + /** Remove the current element and continue to apply */ + Anydb_Action_Remove_And_Continue = Anydb_Action_Remove | Anydb_Action_Continue +}; +typedef enum anydb_action anydb_action_t; + +/** + * Callback of apply method. This callback is called for any item of + * the database and it tells through its return what the anydb has + * to do: see anydb_action_t. + * The 'closure' is the closure given by the caller of 'apply' method. + * 'key' is the iterated key of the anydb. It can not be changed. + * 'value' is the value stored in the database for the key. + */ +typedef anydb_action_t anydb_applycb_t(void *closure, const anydb_key_t *key, anydb_value_t *value); + +/** + * Interface to any database implementation + */ struct anydb_itf { + /** + * Get the index of the 'name' in 'idx'. If the name is found + * then its index is returned. If the name is not found, the + * database backend has to create it if 'create' is not zero. + * 'clodb' is the database's closure. + * Returns 0 in case of success (*idx filled with the index) + * or return a negative error code in -errno like form. + */ int (*index)(void *clodb, anydb_idx_t *idx, const char *name, bool create); + + /** + * Get the string for the index 'idx'. idx MUST be valid. + * 'clodb' is the database's closure. + */ const char *(*string)(void *clodb, anydb_idx_t idx); + + /** + * Start, Commit or Cancel a cancellable transaction. The operation + * to perform is given by 'op'. + * 'clodb' is the database's closure. + * Returns 0 in case of success or return a negative error code + * in -errno like form. + */ int (*transaction)(void *clodb, anydb_transaction_t atomic_op); - void (*apply)(void *clodb, anydb_action_t (*oper)(void *closure, const anydb_key_t *key, anydb_value_t *value), void *closure); + + /** + * Iterate over the database items and apply the operator 'oper'. + * The callback operator 'oper' is called with the given 'closure' + * and the key and value for the item. It can modify or delete the item. + * 'clodb' is the database's closure. + */ + void (*apply)(void *clodb, anydb_applycb_t *oper, void *closure); + + /** + * Add the item of 'key' and 'value'. + * 'clodb' is the database's closure. + * Returns 0 in case of success or return a negative error code + * in -errno like form. + */ int (*add)(void *clodb, const anydb_key_t *key, const anydb_value_t *value); + + /** + * Garbage collection of unused items. + * 'clodb' is the database's closure. + */ void (*gc)(void *clodb); + + /** + * Synchronize the database and its longterm support (file) + * 'clodb' is the database's closure. + * Returns 0 in case of success or return a negative error code + * in -errno like form. + */ int (*sync)(void *clodb); + + /** + * Destroys the database + * 'clodb' is the database's closure. + */ void (*destroy)(void *clodb); }; typedef struct anydb_itf anydb_itf_t; +/** + * The structure for abstracting backend databases + */ struct anydb { + /** the closure */ void *clodb; + + /** the implementation methods */ anydb_itf_t itf; }; typedef struct anydb anydb_t; -/** manage atomicity of operations */ +/** + * Manage atomicity of modifications by enabling cancellation + * @param db database to manage + * @param oper operation to perform + * @return 0 in case of success or a negative error code in -errno like form. + */ extern int anydb_transaction( @@ -113,28 +233,44 @@ anydb_transaction( anydb_transaction_t oper ); -/** enumerate */ +/** + * Enumerate items of the database matching the given key + * @param db database to enumerate + * @param callback callback function receiving the item that matches the key + * @param closure closure for the callback + * @param key key to restrict enumeration can't be NULL + */ extern void anydb_for_all( anydb_t *db, - void *closure, void (*callback)( void *closure, const data_key_t *key, const data_value_t *value), + void *closure, const data_key_t *key ); -/** drop rules */ +/** + * Drop any rule that matches the key + * @param db database to modify + * @param key the key that select items to be dropped + */ extern -int +void anydb_drop( anydb_t *db, const data_key_t *key ); -/** set a rules */ +/** + * Set the rule described by key and value + * @param db the database to set + * @param key the key of the rule + * @param value the value of the rule + * @return 0 on success or a negative error code + */ extern int anydb_set( @@ -143,39 +279,60 @@ anydb_set( const data_value_t *value ); -/** test a rule, returns 0 or the score: count of exact keys */ +/** + * Test a rule and return its score and the value + * @param db the database + * @param key key to be matched by rules + * @param value value found for the key, filled only if a key matched + * @return 0 if no rule matched or a positive integer when the rule matched + * The higher the integer is, the more accurate is the rule found. + */ extern -int +unsigned anydb_test( anydb_t *db, const data_key_t *key, data_value_t *value ); -/** drop rules */ +/** + * Drop any expired rule + * @param db the database to clean + */ extern void anydb_cleanup( anydb_t *db ); -/** is the database empty? */ +/** + * Is the database empty? + * @param db the database to test + * @return true if the database is empty or otherwise false + */ extern bool anydb_is_empty( anydb_t *db ); -/** destroy the database */ +/** + * Synchronize the database if needed + * @param db the database to + * @return 0 on success or a negative -errno like code + */ extern -void -anydb_destroy( +int +anydb_sync( anydb_t *db ); -/** synchronize database */ +/** + * Destroy the database + * @param db the database to destroy + */ extern -int -anydb_sync( +void +anydb_destroy( anydb_t *db ); |