Transactions

A transaction is a sequence of actions that needs to be performed on one or more objects. More...

Macros
#define	amxd_trans_set_value(type, trans, name, value)    amxd_trans_set_ ## type(trans, name, value)
	Helper macro for setting a value. More...

Typedefs
typedef enum _amxd_tattr_id	amxd_tattr_id_t
	Transaction attributes. More...

Enumerations
enum	_amxd_tattr_id { amxd_tattr_change_ro , amxd_tattr_change_pub , amxd_tattr_change_prot , amxd_tattr_change_priv }
	Transaction attributes. More...

Functions
amxd_status_t	amxd_trans_init (amxd_trans_t *const trans)
	Initializes a transaction object. More...
void	amxd_trans_clean (amxd_trans_t *const trans)
	Cleans the transaction object. More...
amxd_status_t	amxd_trans_new (amxd_trans_t **trans)
	Allocates a transaction object on the heap and initializes it. More...
void	amxd_trans_delete (amxd_trans_t **trans)
	Frees the memory previously allocated for a transaction object. More...
amxd_status_t	amxd_trans_set_attr (amxd_trans_t *trans, amxd_tattr_id_t attr, bool enable)
	Set the transaction attributes. More...
amxd_status_t	amxd_trans_add_action (amxd_trans_t *const trans, const amxd_action_t reason, const amxc_var_t *data)
	Adds an action to a transaction. More...
amxd_status_t	amxd_trans_select_pathf (amxd_trans_t *const trans, const char *path,...) __attribute__((format(printf
	Selects an object using a absolute or relative path. More...
amxd_status_t amxd_status_t	amxd_trans_select_object (amxd_trans_t *trans, const amxd_object_t *const object)
	Selects an object using an object pointer. More...
amxd_status_t	amxd_trans_set_param (amxd_trans_t *const trans, const char *param_name, amxc_var_t *const value)
	Adds a set value action to a transaction. More...
amxd_status_t	amxd_trans_add_inst (amxd_trans_t *const trans, const uint32_t index, const char *name)
	Adds an instance add action to a transaction. More...
amxd_status_t	amxd_trans_del_inst (amxd_trans_t *const trans, const uint32_t index, const char *name)
	Adds an instance delete action to a transaction. More...
amxd_status_t	amxd_trans_apply (amxd_trans_t *const trans, amxd_dm_t *const dm)
	Applies all previously added actions. More...
void	amxd_trans_dump (const amxd_trans_t *const trans, const int fd, const bool reverse)
	Dumps the transaction to a file descriptor. More...

Detailed Description

A transaction is a sequence of actions that needs to be performed on one or more objects.

The squence of actions (transaction) can be considered as an atomic operation. Either all actions succeed or none is applied.

Typically an object is selected to work on with amxd_trans_select_pathf or amxd_trans_select_object, and the a set of actions is added.

Adding action to a transaction have no effect immediatly. The actions are executed as soon as amxd_trans_apply is called.

When amxd_trans_apply fails no changes are done. When amxd_trans_apply succeeds all changes are applied and events are send.

In one transaction it is possible to change many objects.

Macro Definition Documentation

amxd_trans_set_value

#define amxd_trans_set_value	(		type,
			trans,
			name,
			value
	)		amxd_trans_set_ ## type(trans, name, value)

Helper macro for setting a value.

This helper macro sets a value, using a type indicator

Parameters

type	the data type, must be a valid parameter type, or must be convertable to a valid parameter type
trans	pointer to a transaction object
name	parameter name of the current selected object
value	the new value, must match the type

Definition at line 144 of file amxd_transaction.h.

Typedef Documentation

amxd_tattr_id_t

typedef enum _amxd_tattr_id amxd_tattr_id_t

Transaction attributes.

Transaction attributes can be set using amxd_trans_set_attr

Enumeration Type Documentation

_amxd_tattr_id

enum _amxd_tattr_id

Transaction attributes.

Transaction attributes can be set using amxd_trans_set_attr

Enumerator
amxd_tattr_change_ro	When set transaction can change read-only params or object
amxd_tattr_change_pub	Set transaction access level to public
amxd_tattr_change_prot	Set transaction access level to protected
amxd_tattr_change_priv	Set transaction access level to private

Definition at line 102 of file amxd_transaction.h.

                            {
    amxd_tattr_change_ro,           
    amxd_tattr_change_pub,          
    amxd_tattr_change_prot,         
    amxd_tattr_change_priv,         
} amxd_tattr_id_t;

Function Documentation

amxd_trans_add_action()

amxd_status_t amxd_trans_add_action	(	amxd_trans_t *const	trans,
		const amxd_action_t	reason,
		const amxc_var_t *	data
	)

Adds an action to a transaction.

Adds an action to a transaction, providing the action data.

This function is mostly no called directly, some convience wrapper functions are provide to make it easier to add an action to a transaction.

Use one of these methods instead

• amxd_trans_select_pathf
• amxd_trans_select_object
• amxd_trans_set_param or amxd_trans_set_value
• amxd_trans_add_inst
• amxd_trans_del_inst

Parameters

trans	pointer to a transaction object
reason	the action identifier
data	the action data

Returns

amxd_status_ok when the atcion is added to the transaction.

Definition at line 597 of file amxd_transaction.c.

                                                            {
    amxd_status_t status = amxd_status_unknown_error;
    amxd_trans_action_t* action = NULL;
 
    when_null(trans, exit);
    when_true_status(reason != action_any &&
                     reason != action_object_write &&
                     reason != action_object_add_inst &&
                     reason != action_object_del_inst,
                     exit,
                     status = amxd_status_invalid_action);
 
    action = amxd_trans_new_action(trans, reason);
    when_null(action, exit);
    amxc_var_copy(&action->data, data);
    status = amxd_status_ok;
 
exit:
    if(trans != NULL) {
        trans->status = status;
    }
    return status;
}

amxd_trans_add_inst()

amxd_status_t amxd_trans_add_inst	(	amxd_trans_t *const	trans,
		const uint32_t	index,
		const char *	name
	)

Adds an instance add action to a transaction.

The instance add action works on the currently selected object. The currently selected object must be a multi-instance object.

The newly added instance will become the currently selected object.

Parameters

trans	pointer to a transaction object
index	the index for the instance, no other instance should exist with this index, or 0 to automatically assing an index
name	name of the instance or NULL. If the multi-instance object contains a "Alias" parameter the name is stored in that parameter. No other instance of the selected multi-instance object should have the same name. When no names need to be set, use a NULL pointer for this argument

Returns

amxd_status_ok when the instance add atcion is added to the transaction.

Definition at line 738 of file amxd_transaction.c.

                                                    {
    amxd_status_t status = amxd_status_unknown_error;
    amxd_trans_action_t* action = NULL;
 
    when_null(trans, exit);
 
    action = amxd_trans_new_action(trans, action_object_add_inst);
    when_null(action, exit);
 
    when_null(amxc_var_add_key(bool,
                               &action->data,
                               "set_read_only",
                               trans->attr.read_only == 1),
              exit);
    when_null(amxc_var_add_key(uint32_t,
                               &action->data,
                               "access",
                               trans->access),
              exit);
    when_null(amxc_var_add_key(uint32_t, &action->data, "index", index),
              exit);
    when_null(amxc_var_add_key(cstring_t,
                               &action->data,
                               "name",
                               name == NULL ? "" : name),
              exit);
 
    status = amxd_status_ok;
 
exit:
    if(trans != NULL) {
        trans->status = status;
    }
    return status;
}

amxd_trans_apply()

amxd_status_t amxd_trans_apply	(	amxd_trans_t *const	trans,
		amxd_dm_t *const	dm
	)

Applies all previously added actions.

Executes all actions of the transaction in the order the actions were added. During execution, a reverse transaction is created. Whenever the execution of one of the actions fail, the reverse transaction is executed to restore the original state.

Either all actions of a transaction are applied, or none.

When the transaction succeeds (all actions executed) the transaction will send events for all changed/adds/deletes done.

Parameters

trans	pointer to a transaction object
dm	the data model the transaction needs to be applied on

Returns

amxd_status_ok when the all actions are applied, otherwise an other error code and no changes in the data model are done.

Definition at line 841 of file amxd_transaction.c.

                                                    {
    static bool trans_buzy = false;
    amxd_status_t status = amxd_status_unknown_error;
    amxd_trans_t rollback;
 
    amxd_trans_init(&rollback);
    when_true(trans_buzy, exit);
    when_null(trans, exit);
    when_null(dm, exit);
    when_failed_status(trans->status, exit, status = trans->status);
    trans_buzy = true;
    trans->fail_index = 0;
    amxc_var_clean(&trans->retvals);
    amxc_var_set_type(&trans->retvals, AMXC_VAR_ID_LIST);
    amxc_llist_for_each(it, (&trans->actions)) {
        amxd_trans_action_t* action =
            amxc_llist_it_get_data(it, amxd_trans_action_t, it);
        status = amxd_trans_invoke_action(trans, dm, action, &rollback);
        when_failed(status, exit);
        trans->fail_index++;
    }
    status = amxd_trans_validate_objects(trans, dm);
 
exit:
    if(trans != NULL) {
        trans->status = status;
        if(status != amxd_status_ok) {
            amxd_trans_select_object(&rollback, trans->current);
            amxd_trans_revert(&rollback, dm);
            amxc_llist_clean(&trans->garbage, amxc_string_list_it_free);
            trans->current = NULL;
        } else {
            amxc_llist_clean(&trans->actions, amxd_trans_free_action_it);
        }
        amxd_trans_clean(&rollback);
    }
    trans_buzy = false;
    return status;
}

amxd_trans_clean()

void amxd_trans_clean

(

amxd_trans_t *const

trans

)

Cleans the transaction object.

After cleaning the transaction obnject, it is ready to be re-used.

This function will reset all internal bookkeeping objects, but keeps the current selected object and the transaction attributes

Parameters

trans

pointer to a transaction object

Definition at line 529 of file amxd_transaction.c.

                                                 {
    when_null(trans, exit);
 
    amxc_llist_clean(&trans->actions, amxd_trans_free_action_it);
    amxc_llist_clean(&trans->garbage, amxc_string_list_it_free);
    amxc_llist_clean(&trans->validate, amxd_trans_free_validate_it);
    amxc_var_clean(&trans->retvals);
 
    trans->status = amxd_status_ok;
    trans->fail_index = -1;
 
exit:
    return;
}

amxd_trans_del_inst()

amxd_status_t amxd_trans_del_inst	(	amxd_trans_t *const	trans,
		const uint32_t	index,
		const char *	name
	)

Adds an instance delete action to a transaction.

The instance delete action works on the currently selected object. The currently selected object must be a multi-instance object.

The deleted instance is selected by index or by name. When both are specified, the index takes precedence over the name. At least one of them should be specified.

The transaction will fail if no instance is found with the index or name specified.

Note

The instance is added to the garbage collector and is really deleted when all actions of the transaction are applied successful. The reason for this implementation is that it would otherwise not be possible to rollback the executed actions when on failure.

Parameters

trans	pointer to a transaction object
index	the index for the instance that will be deleted or 0
name	name of the instance that will be deleted or NULL.

Returns

amxd_status_ok when the instance add atcion is added to the transaction.

Definition at line 776 of file amxd_transaction.c.

                                                    {
    amxd_status_t status = amxd_status_unknown_error;
    amxd_trans_action_t* action = NULL;
 
    when_null(trans, exit);
 
    action = amxd_trans_new_action(trans, action_object_del_inst);
    when_null(action, exit);
    when_true((index == 0 && (name == NULL || *name == 0)), exit);
 
    when_null(amxc_var_add_key(bool,
                               &action->data,
                               "set_read_only",
                               trans->attr.read_only == 1),
              exit);
    when_null(amxc_var_add_key(uint32_t,
                               &action->data,
                               "access",
                               trans->access),
              exit);
    when_null(amxc_var_add_key(uint32_t, &action->data, "index", index),
              exit);
    when_null(amxc_var_add_key(cstring_t,
                               &action->data,
                               "name",
                               name == NULL ? "" : name),
              exit);
 
    status = amxd_status_ok;
 
exit:
    if(trans != NULL) {
        trans->status = status;
    }
    return status;
}

amxd_trans_delete()

void amxd_trans_delete

(

amxd_trans_t **

trans

)

Frees the memory previously allocated for a transaction object.

First calls amxd_trans_clean and then frees the memory allocated for the transaction object.

Note

Only call this function on transaction objects previously allocated with amxd_trans_new

Parameters

trans

pointer to pointer to a transaction object

Definition at line 557 of file amxd_transaction.c.

                                             {
    when_null(trans, exit);
    when_null((*trans), exit);
 
    amxd_trans_clean(*trans);
 
    free(*trans);
    *trans = NULL;
 
exit:
    return;
}

amxd_trans_dump()

void amxd_trans_dump	(	const amxd_trans_t *const	trans,
		const int	fd,
		const bool	reverse
	)

Dumps the transaction to a file descriptor.

Dumps in human readable text format all actions of a transaction in the order the actions were added.

This function can be used for debugging purposes.

Parameters

trans	pointer to a transaction object
fd	a valid file descriptor
reverse	when set to true, dumps the action in reverse order

Definition at line 882 of file amxd_transaction.c.

                                         {
    if(reverse) {
        amxc_llist_for_each_reverse(it, (&trans->actions)) {
            amxd_trans_action_t* action =
                amxc_llist_it_get_data(it, amxd_trans_action_t, it);
            amxd_trans_dump_action(action, fd);
        }
    } else {
        amxc_llist_for_each(it, (&trans->actions)) {
            amxd_trans_action_t* action =
                amxc_llist_it_get_data(it, amxd_trans_action_t, it);
            amxd_trans_dump_action(action, fd);
        }
    }
}

amxd_trans_init()

amxd_status_t amxd_trans_init

(

amxd_trans_t *const

trans

)

Initializes a transaction object.

Sets the internal transaction fields to a default value:

• Sets current object to NULL
• Transaction can not change read-only parameters
• The transaction can change public and protected parameters
• Initializes internal bookkeeping objects (garbage collection, rollback info, ...)

Parameters

trans

pointer to a transaction object

Returns

amxd_status_ok if the transaction object is correctly initialized.

Definition at line 507 of file amxd_transaction.c.

                                                         {
    amxd_status_t status = amxd_status_unknown_error;
    when_null(trans, exit);
 
    amxc_llist_init(&trans->actions);
    amxc_llist_init(&trans->garbage);
    amxc_llist_init(&trans->validate);
    amxc_var_init(&trans->retvals);
    amxc_var_set_type(&trans->retvals, AMXC_VAR_ID_LIST);
 
    trans->current = NULL;
    trans->status = amxd_status_ok;
    trans->fail_index = -1;
    trans->attr.read_only = 0;
    trans->access = amxd_dm_access_protected;
 
    status = amxd_status_ok;
 
exit:
    return status;
}

amxd_trans_new()

amxd_status_t amxd_trans_new

(

amxd_trans_t **

trans

)

Allocates a transaction object on the heap and initializes it.

Allocates memory for a transaction object and then calls amxd_trans_init

Note

A transaction object allocated on the heap must be freed using amxd_trans_delete

Parameters

trans

pointer to pointer to a transaction object

Returns

amxd_status_ok if the transaction object is allocated and correctly initialized.

Definition at line 544 of file amxd_transaction.c.

                                                   {
    amxd_status_t status = amxd_status_unknown_error;
    when_null(trans, exit);
 
    *trans = (amxd_trans_t*) calloc(1, sizeof(amxd_trans_t));
    when_null((*trans), exit);
 
    status = amxd_trans_init(*trans);
 
exit:
    return status;
}

amxd_trans_select_object()

amxd_status_t amxd_status_t amxd_trans_select_object	(	amxd_trans_t *	trans,
		const amxd_object_t *const	object
	)

Selects an object using an object pointer.

Selects an object on which the next actions must be applied.

The path of the object is stored in the select action, not the object itself.

Parameters

trans	pointer to a transaction object
object	pointer to an object in the data model

Returns

amxd_status_ok when the select atcion is added to the transaction.

Definition at line 666 of file amxd_transaction.c.

                                                                          {
    amxd_status_t status = amxd_status_unknown_error;
    char* full_path = NULL;
    amxd_trans_action_t* action = NULL;
 
    when_null(trans, exit);
 
    full_path = amxd_object_get_path(object, AMXD_OBJECT_INDEXED | AMXD_OBJECT_TERMINATE);
    action = amxd_trans_new_action(trans, action_any);
    when_null(action, exit);
    when_null(amxc_var_add_key(cstring_t,
                               &action->data,
                               "path",
                               full_path),
              exit);
 
    when_null(object, exit);
 
    status = amxd_status_ok;
 
exit:
    if(trans != NULL) {
        trans->status = status;
    }
    free(full_path);
    return status;
}

amxd_trans_select_pathf()

amxd_status_t amxd_trans_select_pathf	(	amxd_trans_t *const	trans,
		const char *	path,
			...
	)

Selects an object using a absolute or relative path.

Selects an object on which the next actions must be applied. The object is selected using a path. This path can be absolute or relative.

A relative path must start with a '.' and is relative to the currently selected object in the transaction.

The path may be a search path. The search path must only return one object.

This function supports printf formatting.

To go up in the hierarchy of objects, relative from the current object the symbol '^' can be used.

Parameters

trans	pointer to a transaction object
path	relative or abosule path, can be a search path

Returns

amxd_status_ok when the select atcion is added to the transaction.

amxd_trans_set_attr()

amxd_status_t amxd_trans_set_attr	(	amxd_trans_t *	trans,
		amxd_tattr_id_t	attr,
		bool	enable
	)

Set the transaction attributes.

Using the transaction attributes it is possible to change the behavior of a transaction.

By default a transaction can not change or update read-only parameters or objects and only works on public or protected parameters and objects.

The following attributes can be set:

• amxd_tattr_change_ro, enables changing of read-only parameters and objects
• amxd_tattr_change_pub, only change public parameters or objects
• amxd_tattr_change_prot, can change public or protected parameters and objects
• amxd_tattr_change_priv, can change public, protected and private parameters and objects

Note

• Set the transaction attributes before adding actions
• amxd_tattr_change_pub, amxd_tattr_change_prot, amxd_tattr_change_priv are mutually exclusive, only set one of these, by default amxd_tattr_change_prot is set.
• when specifying amxd_tattr_change_pub, the enable flag has no effect
• when specifying amxd_tattr_change_prot or amxd_tattr_change_priv with enable equal to false, amxd_tattr_change_pub is set.

Parameters

trans	pointer to a transaction object
attr	one of amxd_tattr_id_t
enable	enable or disables the attrivbute

Returns

amxd_status_ok if the attribute is set or unset.

Definition at line 570 of file amxd_transaction.c.

                                               {
    amxd_status_t retval = amxd_status_unknown_error;
    when_null(trans, exit);
 
    switch(attr) {
    case amxd_tattr_change_ro:
        trans->attr.read_only = enable;
        break;
    case amxd_tattr_change_pub:
        trans->access = amxd_dm_access_public;
        break;
    case amxd_tattr_change_prot:
        trans->access = enable ? amxd_dm_access_protected : amxd_dm_access_public;
        break;
    case amxd_tattr_change_priv:
        trans->access = enable ? amxd_dm_access_private : amxd_dm_access_public;
        break;
    }
 
    retval = amxd_status_ok;
 
exit:
    return retval;
}

amxd_trans_set_param()

amxd_status_t amxd_trans_set_param	(	amxd_trans_t *const	trans,
		const char *	param_name,
		amxc_var_t *const	value
	)

Adds a set value action to a transaction.

The set action works on the currently selected object.

When mutiple set actions are added to the transaction in sequence, the transaction will combine these as one write action on the selected object.

Parameters

trans	pointer to a transaction object
param_name	name of the parameter
value	the new value

Returns

amxd_status_ok when the set atcion is added to the transaction.

Definition at line 695 of file amxd_transaction.c.

                                                            {
    amxd_status_t status = amxd_status_unknown_error;
    amxd_trans_action_t* action = NULL;
    amxc_var_t* params = NULL;
 
    when_null(trans, exit);
    when_str_empty(param_name, exit);
    when_null(value, exit);
 
    action = amxd_trans_find_write_action(trans);
    if(action == NULL) {
        action = amxd_trans_new_action(trans, action_object_write);
        when_null(action, exit);
        when_null(amxc_var_add_key(bool, &action->data, "set_read_only",
                                   trans->attr.read_only == 1),
                  exit);
        when_null(amxc_var_add_key(uint32_t, &action->data, "access", trans->access),
                  exit);
    }
 
    params = amxc_var_get_key(&action->data, "parameters",
                              AMXC_VAR_FLAG_DEFAULT);
    if(params == NULL) {
        params = amxc_var_add_key(amxc_htable_t, (&action->data), "parameters",
                                  NULL);
        when_null(params, exit);
    }
 
    when_failed(amxc_var_set_key(params, param_name, value,
                                 AMXC_VAR_FLAG_UPDATE | AMXC_VAR_FLAG_COPY),
                exit);
 
    status = amxd_status_ok;
 
exit:
    if(trans != NULL) {
        trans->status = status;
    }
    return status;
}