libds/libds.c File Reference

#include <search.h>
#include <stdlib.h>
#include <string.h>
#include <pthread.h>
#include "libds.h"

Data Structures
struct	datastore_entry_t
Functions
void	datastore_init (datastore_t *ds)
	Initializes the data store.
unsigned long	datastore_put (datastore_t *ds, const char *key, const char *value)
	Adds the key-value pair (key, value) to the data store, if and only if the key does not already exist in the data store.
const char *	datastore_get (datastore_t *ds, const char *key, unsigned long *revision)
	Retrieves the current value, and its revision number, for a specific key.
unsigned long	datastore_update (datastore_t *ds, const char *key, const char *value, unsigned long known_revision)
	Updates the specific key in the data store if and only if the key exists in the data store and the key's revision in the data store matches the knwon_revision specified.
unsigned long	datastore_delete (datastore_t *ds, const char *key, unsigned long known_revision)
	Deletes a specific key from the data store.
void	datastore_destroy (datastore_t *ds)
	Destroys the data store, freeing any memory that is in use by the data store.

---

Detailed Description

---

Function Documentation

unsigned long datastore_delete	(	datastore_t *	ds,
		const char *	key,
		unsigned long	known_revision
	)

Deletes a specific key from the data store.

This function is thread-safe.

Parameters:

ds	An initialized data store.
key	The specific key to update in the data store.
known_revision	The revision number for the key specified that is expected to be found in the data store. If the revision number specified in calling the function does not match the revision number in the data store, this function will not update the data store.

Return values:

0	The revision number specified did not match the revision number in the data store or the key was not found in the data store. If the key is in the data store, this indicates that the data has been modified since you last performed a datastore_get() operation. You should get an updated value from the data store.
non-zero	The key was deleted from the data store.

void datastore_destroy

(

datastore_t *

ds

)

Destroys the data store, freeing any memory that is in use by the data store.

Parameters:

ds	An initialized data store.

const char* datastore_get	(	datastore_t *	ds,
		const char *	key,
		unsigned long *	revision
	)

Retrieves the current value, and its revision number, for a specific key.

This function is thread-safe.

Parameters:

ds	An initialized data store.
key	The specific key to retrieve the value.
revision	If non-NULL, the revision number of the returned value will be written to the address pointed to by revision.

Returns:

If the data store contains the key, a new string containing the value will be returned. It is the responsibility of the user of the data store to free the value returned. If the data store does not contain the key, NULL will be returned and revision will be unmodified.

void datastore_init

(

datastore_t *

ds

)

Initializes the data store.

Parameters:

ds	An uninitialized data store.

unsigned long datastore_put	(	datastore_t *	ds,
		const char *	key,
		const char *	value
	)

Adds the key-value pair (key, value) to the data store, if and only if the key does not already exist in the data store.

The data store will make an internal copy key and value, if necessary, so the user of the data store may free these strings if necessary.

This function is thread-safe.

Parameters:

ds	An initialized data store.
key	The key to be added to the data store.
value	The value to associated with the new key.

Return values:

0	The key already exists in the data store.
non-zero	The revision number assigned to the specific value for the given key.

unsigned long datastore_update	(	datastore_t *	ds,
		const char *	key,
		const char *	value,
		unsigned long	known_revision
	)

Updates the specific key in the data store if and only if the key exists in the data store and the key's revision in the data store matches the knwon_revision specified.

The data store will make an internal copy key and value, if necessary, so the user of the data store may free these strings if necessary.

This function is thread-safe.

Parameters:

ds	An initialized data store.
key	The specific key to update in the data store.
value	The updated value to the key in the data store.
known_revision	The revision number for the key specified that is expected to be found in the data store. If the revision number specified in calling the function does not match the revision number in the data store, this function will not update the data store.

Return values:

0	The revision number specified did not match the revision number in the data store or the key was not found in the data store. If the key is in the data store, this indicates that the data has been modified since you last performed a datastore_get() operation. You should get an updated value from the data store.
non-zero	The new revision number for the key, now associated with the new value.