transaction.h File Reference

#include "asterisk/res_aeap.h"

Include dependency graph for transaction.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
int	aeap_transaction_cancel_timer (struct aeap_transaction *tsx)
	Cancel the transaction timer. More...
struct aeap_transaction *	aeap_transaction_create_and_add (struct ao2_container *transactions, const char *id, struct ast_aeap_tsx_params *params, struct ast_aeap *aeap)
	Create a transaction object, and add it to the given container. More...
void	aeap_transaction_end (struct aeap_transaction *tsx, int result)
	End a transaction, and remove it from the given container. More...
struct aeap_transaction *	aeap_transaction_get (struct ao2_container *transactions, const char *id)
	Retrieve a transaction for the id from the container. More...
void	aeap_transaction_params_cleanup (struct ast_aeap_tsx_params *params)
	Clean up parameter references, and possibly call optional user object cleanup. More...
int	aeap_transaction_result (struct aeap_transaction *tsx)
	Get a transaction's result. More...
int	aeap_transaction_start (struct aeap_transaction *tsx)
	Start the transaction. More...
void *	aeap_transaction_user_obj (struct aeap_transaction *tsx)
	Retrieve the user object associated with the transaction. More...
struct ao2_container *	aeap_transactions_create (void)
	Create an Asterisk external application transactions container. More...

Function Documentation

aeap_transaction_cancel_timer()

int aeap_transaction_cancel_timer

(

struct aeap_transaction *

tsx

)

Cancel the transaction timer.

Stops the transaction timer, but does not end/stop the transaction itself

Parameters

tsx	A transaction to cancel the timer on

Returns

0 if canceled, non zero otherwise

Definition at line 57 of file transaction.c.

{
    if (tsx && tsx->sched_id != -1) {
        AST_SCHED_DEL_UNREF(aeap_sched_context(), tsx->sched_id, ao2_ref(tsx, -1));
        return tsx->sched_id != -1;
    }
 
    return 0;
}

References aeap_sched_context(), ao2_ref, AST_SCHED_DEL_UNREF, and aeap_transaction::sched_id.

Referenced by raise_msg(), transaction_destructor(), and transaction_end().

aeap_transaction_create_and_add()

struct aeap_transaction * aeap_transaction_create_and_add	(	struct ao2_container *	transactions,
		const char *	id,
		struct ast_aeap_tsx_params *	params,
		struct ast_aeap *	aeap
	)

Create a transaction object, and add it to the given container.

Parameters

transactions	A transactions container
id	An id to use for the transaction
params	Transaction parameters
aeap	The aeap object that "owns" this transaction

Returns

0 if successfully create and added, -1 on error

Definition at line 232 of file transaction.c.

{
    struct aeap_transaction *tsx;
 
    tsx = transaction_create(id, params, aeap);
    if (!tsx) {
        return NULL;
    }
 
    if (!ao2_link(transactions, tsx)) {
        aeap_error(tsx->aeap, "transaction", "unable to add '%s' to container", id);
        ao2_ref(tsx, -1);
        return NULL;
    }
 
    /*
     * Yes, this creates a circular reference. This reference is removed though
     * upon transaction end. It's assumed here that the given transactions container
     * takes "ownership", and ultimate responsibility of its contained transactions.
     * Thus when the given container needs to be unref'ed/freed it must call
     * aeap_transaction_end for each transaction prior to doing so.
     */
    /* tsx->container = ao2_bump(transactions); */
 
    /*
     * The transaction needs to know what container manages it, so it can remove
     * itself from the given container under certain conditions (e.g. transaction
     * timeout).
     *
     * It's expected that the given container will out live any contained transaction
     * (i.e. the container will not itself be destroyed before ensuring all contained
     * transactions are ended, and removed). Thus there is no reason to bump the given
     * container's reference here.
     */
    tsx->container = transactions;
 
    return tsx;
}

References aeap_transaction::aeap, aeap_error, ao2_link, ao2_ref, aeap_transaction::container, NULL, aeap_transaction::params, and transaction_create().

Referenced by ast_aeap_send_msg_tsx(), and exec().

aeap_transaction_end()

void aeap_transaction_end	(	struct aeap_transaction *	tsx,
		int	result
	)

End a transaction, and remove it from the given container.

The "result" parameter is a value representing the state (success/failure, perhaps even something else) of transactional processing upon ending.

Parameters

tsx	A transaction to end
result	A result to give to the transaction

Definition at line 217 of file transaction.c.

{
    transaction_end(tsx, 0, result);
}

References result, and transaction_end().

Referenced by ast_aeap_send_msg_tsx(), end_transaction(), exec(), raise_msg(), and tsx_end().

aeap_transaction_get()

struct aeap_transaction * aeap_transaction_get	(	struct ao2_container *	transactions,
		const char *	id
	)

Retrieve a transaction for the id from the container.

Parameters

transactions	A transactions container
id	A transaction id

Returns

an AEAP transaction object, NULL if no transaction is found

Definition at line 212 of file transaction.c.

{
    return ao2_find(transactions, id, OBJ_SEARCH_KEY);
}

References ao2_find, and OBJ_SEARCH_KEY.

Referenced by raise_msg().

aeap_transaction_params_cleanup()

void aeap_transaction_params_cleanup

(

struct ast_aeap_tsx_params *

params

)

Clean up parameter references, and possibly call optional user object cleanup.

Parameters

params

Transaction parameters

Definition at line 67 of file transaction.c.

{
    ao2_cleanup(params->msg);
 
    if (params->obj_cleanup) {
        params->obj_cleanup(params->obj);
    }
}

References ao2_cleanup, ast_aeap_tsx_params::msg, ast_aeap_tsx_params::obj, and ast_aeap_tsx_params::obj_cleanup.

Referenced by ast_aeap_send_msg_tsx(), transaction_create(), and transaction_destructor().

aeap_transaction_result()

int aeap_transaction_result

(

struct aeap_transaction *

tsx

)

Get a transaction's result.

A transaction's result is a value that represents the relative success (0), or failure (-1) of a transaction. For example, a timeout is considered a failure and will elicit a -1.

This value though is also dependent upon the result of the message handler associated with the transaction. Meaning if an associated message is handled, then its result is stored as the transaction result and returned here.

Parameters

tsx	A transaction object

Returns

The transaction result

Definition at line 222 of file transaction.c.

{
    return tsx->result;
}

References aeap_transaction::result.

Referenced by ast_aeap_send_msg_tsx().

aeap_transaction_start()

int aeap_transaction_start

(

struct aeap_transaction *

tsx

)

Start the transaction.

Parameters

tsx	The transaction to initiate

Returns

0 if successfully raised, and handled. Otherwise non zero.

Definition at line 198 of file transaction.c.

{
    if (transaction_sched_timer(tsx)) {
        return -1;
    }
 
    if (tsx->params.wait) {
        /* Wait until transaction completes, or times out */
        transaction_wait(tsx);
    }
 
    return 0;
}

References aeap_transaction::params, transaction_sched_timer(), transaction_wait(), and ast_aeap_tsx_params::wait.

Referenced by ast_aeap_send_msg_tsx(), and exec().

aeap_transaction_user_obj()

void * aeap_transaction_user_obj

(

struct aeap_transaction *

tsx

)

Retrieve the user object associated with the transaction.

Parameters

tsx	A transaction object

Returns

A user object, or NULL if non associated

Definition at line 227 of file transaction.c.

{
    return tsx->params.obj;
}

References ast_aeap_tsx_params::obj, and aeap_transaction::params.

Referenced by end_transaction(), and raise_msg().

aeap_transactions_create()

struct ao2_container * aeap_transactions_create

(

void

)

Create an Asterisk external application transactions container.

Returns

A transaction object, or NULL on error

Definition at line 272 of file transaction.c.

{
    struct ao2_container *transactions;
 
    transactions = ao2_container_alloc_hash(AO2_ALLOC_OPT_LOCK_MUTEX, 0, AEAP_TRANSACTION_BUCKETS,
        aeap_transaction_hash_fn, NULL, aeap_transaction_cmp_fn);
    if (!transactions) {
        ast_log(LOG_ERROR, "AEAP transaction: unable to create container\n");
        return NULL;
    }
 
    return transactions;
}

References AEAP_TRANSACTION_BUCKETS, AO2_ALLOC_OPT_LOCK_MUTEX, ao2_container_alloc_hash, ast_log, LOG_ERROR, and NULL.

Referenced by ast_aeap_create(), and exec().