All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Typedefs | Functions
Turbulence Db List: common abstract interface to store list of items (flushed to the storage device).

Typedefs

typedef struct _TurbulenceDbList TurbulenceDbList
 

Functions

axl_bool turbulence_db_list_add (TurbulenceDbList *list, const char *value)
 
void turbulence_db_list_cleanup (TurbulenceCtx *ctx)
 
axl_bool turbulence_db_list_close (TurbulenceDbList *list)
 
axl_bool turbulence_db_list_count (TurbulenceDbList *list)
 
axl_bool turbulence_db_list_edit (TurbulenceDbList *list, const char *oldValue, const char *newValue)
 
axl_bool turbulence_db_list_exists (TurbulenceDbList *list, const char *value)
 
axl_bool turbulence_db_list_flush (TurbulenceDbList *list)
 
axlList * turbulence_db_list_get (TurbulenceDbList *list)
 
axl_bool turbulence_db_list_init (TurbulenceCtx *ctx)
 
TurbulenceDbListturbulence_db_list_open (TurbulenceCtx *ctx, axlError **error, const char *token,...)
 
axl_bool turbulence_db_list_reload (TurbulenceDbList *list)
 
axl_bool turbulence_db_list_remove (TurbulenceDbList *list, const char *value)
 
axl_bool turbulence_db_list_remove_by_func (TurbulenceDbList *list, TurbulenceDbListRemoveFunc func, axlPointer user_data)
 
axl_bool turbulence_db_list_unload (TurbulenceDbList *list)
 

Detailed Description

Typedef Documentation

typedef struct _TurbulenceDbList TurbulenceDbList

Type definition for an opened turbulence db list: an abstraction that provides easy access to an item list automatically stored.

Function Documentation

axl_bool turbulence_db_list_add ( TurbulenceDbList list,
const char *  value 
)

Allows to add the content provided to the db list.

The function doesn't check if the value to be added already exists. After the function finish, the content provided will be added to the in memory representation and the storage device.

Parameters
listThe db list where the content will be added.
valueThe value to add to the list.
Returns
axl_true if the item was properly added, axl_false if an error was found.

References turbulence_db_list_flush(), and turbulence_db_list_reload().

void turbulence_db_list_cleanup ( TurbulenceCtx ctx)

Allows to cleanup the turbulence db-list module.

This call is usually done from the turbulence_init function, but it may be used directly from those modules that only makes use from the db-list by only calling to turbulence_db_list_init.

Parameters
ctxThe context to cleanup.

References msg.

Referenced by turbulence_exit().

axl_bool turbulence_db_list_close ( TurbulenceDbList list)

Allows to close the db list opened.

Parameters
listThe list to close.
Returns
axl_true if the list was properly close, otherwise axl_false is returned.

Referenced by turbulence_db_list_open().

axl_bool turbulence_db_list_count ( TurbulenceDbList list)

Allows to get the number of items stored on the provided turbulence db list.

Parameters
listTurbulence db-list that is being requested to return the number of items stored.
Returns
The number or items stored or -1 it if fails.
axl_bool turbulence_db_list_edit ( TurbulenceDbList list,
const char *  oldValue,
const char *  newValue 
)

Allows to implement an edit operation on the provided dblist in an atomic way.

This function could be replaced by a call to turbulence_db_list_remove followed by a call to turbulence_db_list_add. However, there is a race condition between those two calls, which is avoided by this function. This function also allows to conserve position of the previous item edited, which is likely to be lost by an remove/add pattern is used.

Parameters
listThe list to be edited.
oldValueThe element to be edited. This element will be searched and edited/replaced with the value provided as newValue.
newValueThe new value to place in exchange for oldValue.
Returns
axl_true if the operation was properly completed, otherwise axl_false is returned.

References turbulence_db_list_flush(), and turbulence_db_list_reload().

axl_bool turbulence_db_list_exists ( TurbulenceDbList list,
const char *  value 
)

Allows to check if the provided value is already added in the provided db list.

Parameters
listThe list where the value will be checked.
valueThe value to be checked. The list can't contain null values, so requesting with NULL will always return axl_false. However empty values are supported ("").
Returns
axl_true if the list contains the value provided (first reference), otherwise axl_false is returned.

References turbulence_db_list_reload().

axl_bool turbulence_db_list_flush ( TurbulenceDbList list)

Allows to force a "flush" operation for the provided db list reference.

The function will take the content of the in memory representation saving it into the storage device. This operation is done automatically by the TurbulenceDbList API, however it can be forced by calling to this function.

Parameters
listThe db list to be flush.
Returns
axl_true if the flush operation was properly done, otherwise axl_false is returned.

References error, and turbulence_last_modification().

Referenced by turbulence_db_list_add(), turbulence_db_list_edit(), and turbulence_db_list_remove().

axlList * turbulence_db_list_get ( TurbulenceDbList list)

Allows to get a copy translated into a axlList from the current content held by the TurbulenceDbList.

The function is useful to get a list with the content inside the db list, especially for view operations. The list returned have the content at the particular time the call was done, and any modification to the list have no effect on the stored data.

Parameters
listThe db list requested to return its content.
Returns
A reference to a newly allocated axlList, containing strings representing the content hold by the provided db list. The reference returned is owned by the caller and a call to axl_list_free is required when no longer needed the data returned.

References turbulence_db_list_reload().

axl_bool turbulence_db_list_init ( TurbulenceCtx ctx)

Service used to start the turbulence db list module.

Returns
axl_true if the module was properly started, otherwise axl_false is returned.

References msg2.

Referenced by turbulence_init().

TurbulenceDbList * turbulence_db_list_open ( TurbulenceCtx ctx,
axlError **  error,
const char *  token,
  ... 
)

Allows to open the provide db list, containing a list of tokens that follows the format provided by the module.

Once the db list is opened, a reference to its handler is provided. This handler is used to access and modify the content with functions like:

The reference returned will be automatically managed by Turbulence. This means:

  • It is not required to close the handler at the module close. This is done by turbulence at the termination process, closing and flushing all data to its proper destination. All resources allocated are also freed.
  • It is not required to perform a reloading operation to ensure the data loaded in memory is in sync with the storage device. Turbulence will take care about file changes, reloading them if necessary.

It is possible to force a reload operation by calling to: turbulence_db_list_reload. It is also possible to explicitly close the handler opened by calling: turbulence_db_list_close.

The common case while using TurbulenceDbList is to open the db file at the module init function as:

axlError * err;
// open the db list, providing a reference to an axlError to get
// textual dianogtic error reporting and a list of tokens configuring
// the full path to the file to be opened, ended by a NULL decl.
list = turbulence_db_list_open (ctx, &err, SYSCONFDIR,
"turbulence",
"your-module",
"db-file.xml", NULL);
if (list == NULL) {
error ("Something have failed: %s", axl_error_get (err));
return axl_false;
}

If the file provided to be opened doesn't exists, the function will load an empty db list into memory that will be dumped to the storage device once the db list is closed.

The path to the db list must exist. The function will create all directories in the path that doesn't exists.

Parameters
ctxTurbulence context where the operation will take place.
errorAn optional user pointer to an axlError reference.
tokenFirst token of a list of tokens configuring the full path to the db list. This list must be terminated with a NULL decl.
Returns
A referece to the TurbulenceDbList handler. It is not required to perform a close operation when no longer needed. This is already done by Turbulence.

References error, msg, msg2, turbulence_create_dir(), turbulence_db_list_close(), and turbulence_last_modification().

axl_bool turbulence_db_list_reload ( TurbulenceDbList list)

Performs a reload operation, checking if the data in the storage device have differences with actual memory loaded data.

Parameters
listThe reference to reload.
Returns
axl_true if the reload operation was done, otherwise axl_false is returned.

References error, turbulence_file_test_v(), and turbulence_last_modification().

Referenced by turbulence_db_list_add(), turbulence_db_list_edit(), turbulence_db_list_exists(), turbulence_db_list_get(), turbulence_db_list_remove(), and turbulence_db_list_remove_by_func().

axl_bool turbulence_db_list_remove ( TurbulenceDbList list,
const char *  value 
)

Allows to remove the provided content (first reference) on the provided db list.

Parameters
listThe reference of the db list where the item will be deleted.
valueThe string value to be removed from the db list.
Returns
axl_true if the item was removed, otherwise axl_false is returned.

References turbulence_db_list_flush(), and turbulence_db_list_reload().

axl_bool turbulence_db_list_remove_by_func ( TurbulenceDbList list,
TurbulenceDbListRemoveFunc  func,
axlPointer  user_data 
)

Allows to produce a remove operation (or several remove operation) using an external function which is called to check if the item should be removed or not.

Parameters
listThe list to be filtered by removing all items selected by the provided function.
funcA handler configure to check if an item must be removed or not. If the function returns axl_true the item will be removed. Otherwise it will remain.
user_dataUser defined pointer which is passed to the filter (remove) function.
Returns
axl_true if the operation was fully completed, otherwise axl_false is returned.

References turbulence_db_list_reload().

axl_bool turbulence_db_list_unload ( TurbulenceDbList list)

Allows to close the db list opened by removing it from memory (without dumping content).

Parameters
listThe list to unload.
Returns
axl_true if the list was properly close, otherwise axl_false is returned.