transaction.c File Reference

#include "asterisk.h"
#include "asterisk/astobj2.h"
#include "asterisk/sched.h"
#include "asterisk/utils.h"
#include "asterisk/res_aeap.h"
#include "asterisk/res_aeap_message.h"
#include "general.h"
#include "logger.h"
#include "transaction.h"

Include dependency graph for transaction.c:

Go to the source code of this file.

Data Structures
struct	aeap_transaction

Macros
#define	AEAP_TRANSACTION_BUCKETS   11
	Number of transaction buckets. More...

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...
	AO2_STRING_FIELD_CMP_FN (aeap_transaction, id)
	AO2_STRING_FIELD_HASH_FN (aeap_transaction, id)
static struct aeap_transaction *	transaction_create (const char *id, struct ast_aeap_tsx_params *params, struct ast_aeap *aeap)
static void	transaction_destructor (void *obj)
static void	transaction_end (struct aeap_transaction *tsx, int timed_out, int result)
static int	transaction_raise_timeout (const void *data)
static int	transaction_sched_timer (struct aeap_transaction *tsx)
static void	transaction_wait (struct aeap_transaction *tsx)

Macro Definition Documentation

AEAP_TRANSACTION_BUCKETS

#define AEAP_TRANSACTION_BUCKETS   11

Number of transaction buckets.

Definition at line 52 of file transaction.c.

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().

AO2_STRING_FIELD_CMP_FN()

AO2_STRING_FIELD_CMP_FN	(	aeap_transaction	,
		id
	)

AO2_STRING_FIELD_HASH_FN()

AO2_STRING_FIELD_HASH_FN	(	aeap_transaction	,
		id
	)

transaction_create()

static struct aeap_transaction * transaction_create ( const char *  id, struct ast_aeap_tsx_params *  params, struct ast_aeap *  aeap  )

static

Definition at line 88 of file transaction.c.

{
    struct aeap_transaction *tsx;
 
    if (!id) {
        aeap_error(aeap, "transaction", "missing transaction id");
        aeap_transaction_params_cleanup(params);
        return NULL;
    }
 
    tsx = ao2_alloc(sizeof(*tsx) + strlen(id) + 1, transaction_destructor);
    if (!tsx) {
        aeap_error(aeap, "transaction", "unable to create for '%s'", id);
        aeap_transaction_params_cleanup(params);
        return NULL;
    }
 
    strcpy(tsx->id, id); /* safe */
    tsx->sched_id = -1;
 
    ast_cond_init(&tsx->handled_cond, NULL);
 
    /*
     * Currently, transactions, and their lifetimes are fully managed by the given 'aeap'
     * object, so do not bump its reference here as we want the 'aeap' object to stop
     * transactions and not transactions potentially stopping the 'aeap' object.
     */
    tsx->aeap = aeap;
    tsx->params = *params;
 
    return tsx;
}

References aeap_transaction::aeap, aeap_error, aeap_transaction_params_cleanup(), ao2_alloc, ast_cond_init, aeap_transaction::handled_cond, aeap_transaction::id, NULL, aeap_transaction::params, aeap_transaction::sched_id, and transaction_destructor().

Referenced by aeap_transaction_create_and_add().

transaction_destructor()

static void transaction_destructor ( void *  obj )

static

Definition at line 76 of file transaction.c.

{
    struct aeap_transaction *tsx = obj;
 
    /* Ensure timer is canceled */
    aeap_transaction_cancel_timer(tsx);
 
    aeap_transaction_params_cleanup(&tsx->params);
 
    ast_cond_destroy(&tsx->handled_cond);
}

References aeap_transaction_cancel_timer(), aeap_transaction_params_cleanup(), ast_cond_destroy, aeap_transaction::handled_cond, and aeap_transaction::params.

Referenced by transaction_create().

transaction_end()

static void transaction_end ( struct aeap_transaction *  tsx, int  timed_out, int  result  )

static

Definition at line 122 of file transaction.c.

{
    if (!tsx) {
        return;
    }
 
    ao2_lock(tsx);
 
    tsx->result = result;
 
    if (tsx->container) {
        ao2_unlink(tsx->container, tsx);
        tsx->container = NULL;
    }
 
    if (!timed_out) {
        aeap_transaction_cancel_timer(tsx);
    } else if (tsx->sched_id != -1) {
        tsx->sched_id = -1;
    }
 
    if (!tsx->handled) {
        if (timed_out) {
            if (tsx->params.on_timeout) {
                tsx->params.on_timeout(tsx->aeap, tsx->params.msg, tsx->params.obj);
            } else {
                aeap_error(tsx->aeap, "transaction", "message '%s' timed out",
                    ast_aeap_message_name(tsx->params.msg));
            }
        }
 
        tsx->handled = 1;
        ast_cond_signal(&tsx->handled_cond);
    }
 
    ao2_unlock(tsx);
 
    ao2_ref(tsx, -1);
}

References aeap_transaction::aeap, aeap_error, aeap_transaction_cancel_timer(), ao2_lock, ao2_ref, ao2_unlink, ao2_unlock, ast_aeap_message_name(), ast_cond_signal, aeap_transaction::container, aeap_transaction::handled, aeap_transaction::handled_cond, ast_aeap_tsx_params::msg, NULL, ast_aeap_tsx_params::obj, ast_aeap_tsx_params::on_timeout, aeap_transaction::params, result, aeap_transaction::result, and aeap_transaction::sched_id.

Referenced by aeap_transaction_end(), and transaction_raise_timeout().

transaction_raise_timeout()

static int transaction_raise_timeout ( const void *  data )

static

Definition at line 162 of file transaction.c.

{
    /* Ref added added at timer creation removed in end call */
    transaction_end((struct aeap_transaction *)data, 1, -1);
 
    return 0;
}

References transaction_end().

Referenced by transaction_sched_timer().

transaction_sched_timer()

static int transaction_sched_timer ( struct aeap_transaction *  tsx )

static

Definition at line 170 of file transaction.c.

{
    if (tsx->params.timeout <= 0 || tsx->sched_id != -1) {
        return 0;
    }
 
    tsx->sched_id = ast_sched_add(aeap_sched_context(), tsx->params.timeout,
            transaction_raise_timeout, ao2_bump(tsx));
    if (tsx->sched_id == -1) {
        aeap_error(tsx->aeap, "transaction", "unable to schedule timeout for '%s'", tsx->id);
        ao2_ref(tsx, -1);
        return -1;
    }
 
    return 0;
}

References aeap_transaction::aeap, aeap_error, aeap_sched_context(), ao2_bump, ao2_ref, ast_sched_add(), aeap_transaction::id, aeap_transaction::params, aeap_transaction::sched_id, ast_aeap_tsx_params::timeout, and transaction_raise_timeout().

Referenced by aeap_transaction_start().

transaction_wait()

static void transaction_wait ( struct aeap_transaction *  tsx )

static

Definition at line 187 of file transaction.c.

{
    ao2_lock(tsx);
 
    while (!tsx->handled) {
        ast_cond_wait(&tsx->handled_cond, ao2_object_get_lockaddr(tsx));
    }
 
    ao2_unlock(tsx);
}

References ao2_lock, ao2_object_get_lockaddr(), ao2_unlock, ast_cond_wait, aeap_transaction::handled, and aeap_transaction::handled_cond.

Referenced by aeap_transaction_start().