Signals

Collaboration diagram for Signals:

Data Structures
struct	_amxp_signal
	Structure containing the signal information. More...

Typedefs
typedef struct _amxp_signal	amxp_signal_t
	Structure containing the signal information. More...

Functions
int	amxp_sigmngr_emit_signal (const amxp_signal_mngr_t *const sig_mngr, const char *name, const amxc_var_t *const data)
	Emits a signal. More...
int	amxp_sigmngr_deferred_call (amxp_signal_mngr_t *const sig_mngr, amxp_deferred_fn_t fn, const amxc_var_t *const data, void *priv)
	Defers a function call. More...
int	amxp_sigmngr_enable (amxp_signal_mngr_t *const sig_mngr, bool enable)
	Enables or disables the signal manager. More...
int	amxp_sigmngr_suspend (amxp_signal_mngr_t *const sig_mngr)
	Suspends the handling of signals for the signal manager. More...
int	amxp_sigmngr_resume (amxp_signal_mngr_t *const sig_mngr)
	Resumes the handling of signals for the signal manager. More...
int	amxp_signal_new (amxp_signal_mngr_t *sig_mngr, amxp_signal_t **signal, const char *name)
	Constructor function, creates a new signal. More...
int	amxp_signal_delete (amxp_signal_t **signal)
	Destructor function, deletes a signal. More...
void	amxp_signal_trigger (amxp_signal_t *const signal, const amxc_var_t *const data)
	Triggers a signal. More...
int	amxp_signal_emit (const amxp_signal_t *const signal, const amxc_var_t *const data)
	Emits a signal. More...
int	amxp_signal_read (void)
	Reads from the amxp signal file descriptor. More...
int	amxp_signal_fd (void)
	Gets the amxp signal file descriptor. More...
int	amxp_signal_disconnect_all (amxp_signal_t *const signal)
	Disconnects all slots from the signal. More...
const char *	amxp_signal_name (const amxp_signal_t *const signal)
	Gets the name of the signal. More...
bool	amxp_signal_has_slots (const amxp_signal_t *const signal)
	Checks if the signal has slots conencted. More...

Detailed Description

When a signal is triggered, all callback functions (slots) that are connected are called immediately. When a signal is emitted, it will be triggered after reading from the amxp signal file descriptor. It is recommended to implement an eventloop.

A signal is a name to which slots (callback functions) can connect.

Typedef Documentation

amxp_signal_t

typedef struct _amxp_signal amxp_signal_t

Structure containing the signal information.

Function Documentation

amxp_sigmngr_deferred_call()

int amxp_sigmngr_deferred_call	(	amxp_signal_mngr_t *const	sig_mngr,
		amxp_deferred_fn_t	fn,
		const amxc_var_t *const	data,
		void *	priv
	)

Defers a function call.

Adds a function call to the singal queue. This function will be called at the moment the queue is being handled. Using deferred function calls it is possible to make synchronous functions behave asynchronously.

When sig_mngr is NULL, the function call is added to the queue of global signal manager.

The function will be called when reading the amxp signal file descriptor using function amxp_signal_read.

To be able to use this method it is recommended to implement an eventloop.

Parameters

sig_mngr	pointer to the sig_mngr pointer. Will be set to NULL
fn	the deferred function
data	the data that is passed to the function.
priv	some pointer to private data

Returns

0 when successful, otherwise an error code

Definition at line 536 of file amxp_signal.c.

                                           {
    int retval = -1;
    int write_length = 0;
    amxp_signal_mngr_t* mngr = (sig_mngr == NULL) ? &amxp_sigmngr : sig_mngr;
 
    when_null(fn, exit);
 
    amxp_signal_queue_lock();
 
    if(!mngr->suspended) {
        write_length = write(amxp_sigctrl.sigpipe[1], "S", 1);
        when_true_status(write_length != 1, exit, amxp_signal_queue_unlock());
    }
 
    retval = amxp_deferred_queue(mngr, fn, data, priv);
 
    amxp_signal_queue_unlock();
 
exit:
    return retval;
}

amxp_sigmngr_emit_signal()

int amxp_sigmngr_emit_signal	(	const amxp_signal_mngr_t *const	sig_mngr,
		const char *	name,
		const amxc_var_t *const	data
	)

Emits a signal.

Searches the signal manager for the given signal and emits the signal. This function is basically the same as calling amxp_sigmngr_find_signal and amxp_signal_emit in sequence.

When sig_mngr is NULL, the signal is searched in the global signal manager.

When no signal is found with the given name, this function fails.

The signal will be triggered when reading the amxp signal file descriptor using function amxp_signal_read.

To be able to use this method it is recommended to implement an eventloop.

Parameters

sig_mngr	ponter to the sig_mngr pointer. Will be set to NULL
name	the name of the signal
data	the data that is passed to all the slots.

Returns

0 when successful, otherwise an error code

Definition at line 514 of file amxp_signal.c.

                                                           {
 
    int retval = -1;
    amxp_signal_t* signal = NULL;
    const amxp_signal_mngr_t* mngr = (sig_mngr == NULL) ? &amxp_sigmngr : sig_mngr;
    amxc_htable_it_t* hit = NULL;
 
    when_null(name, exit);
    when_true(*name == 0, exit)
 
    hit = amxc_htable_get(&mngr->signals, name);
    when_null(hit, exit);
 
    signal = amxc_htable_it_get_data(hit, amxp_signal_t, hit);
    retval = amxp_signal_emit(signal, data);
 
exit:
    return retval;
}

amxp_sigmngr_enable()

int amxp_sigmngr_enable	(	amxp_signal_mngr_t *const	sig_mngr,
		bool	enable
	)

Enables or disables the signal manager.

When a signal manager is disabled, all emitted signals or triggered signals are discarded, including the signal data.

Parameters

sig_mngr	pointer to the signal manager. Use NULL for the global signal manager.
enable	when true signal emitting and triggering is enabled, when false emitting and triggering of signals is blocked for this signal manager.

Returns

0 when successful, otherwise an error code

Definition at line 561 of file amxp_signal.c.

                                     {
    int retval = 0;
    amxp_signal_mngr_t* mngr = (sig_mngr == NULL) ? &amxp_sigmngr : sig_mngr;
 
    mngr->enabled = enable;
 
    return retval;
}

amxp_sigmngr_resume()

int amxp_sigmngr_resume

(

amxp_signal_mngr_t *const

sig_mngr

)

Resumes the handling of signals for the signal manager.

When a signal manager is resumed, all queued signals will be handled by the eventloop.

After resuming a signal manager it will be possible to trigger signals again.

When the signal manager was not suspended this functions returns a none-zero value.

Parameters

sig_mngr

pointer to the signal manager. Use NULL for the global signal manager.

Returns

0 when successful, otherwise an error code

Definition at line 595 of file amxp_signal.c.

                                                            {
    int retval = -1;
    int write_length = 0;
    amxp_signal_mngr_t* mngr = (sig_mngr == NULL) ? &amxp_sigmngr : sig_mngr;
 
    when_false(mngr->suspended, exit);
    mngr->suspended = false;
 
    amxp_signal_queue_lock();
 
    amxc_llist_iterate(it, &mngr->signal_queue) {
        write_length = write(amxp_sigctrl.sigpipe[1], "S", 1);
        when_true_status(write_length != 1, exit, amxp_signal_queue_unlock());
    }
 
    amxc_llist_append(&amxp_sigctrl.pending_sigmngrs, &mngr->it);
 
    amxp_signal_queue_unlock();
 
    retval = 0;
 
exit:
    return retval;
}

amxp_sigmngr_suspend()

int amxp_sigmngr_suspend

(

amxp_signal_mngr_t *const

sig_mngr

)

Suspends the handling of signals for the signal manager.

When a signal manager is suspended, all emitted signals are queued but not handled until the signal manager is resumed with amxp_sigmngr_resume.

When a signal manager is suspended, all triggered signals are dropped including the signal data.

When the signal manager was already suspended this functions returns a none-zero value.

Parameters

sig_mngr

pointer to the signal manager. Use NULL for the global signal manager.

Returns

0 when successful, otherwise an error code

Definition at line 571 of file amxp_signal.c.

                                                             {
    int retval = -1;
    char buffer[1];
    amxp_signal_mngr_t* mngr = (sig_mngr == NULL) ? &amxp_sigmngr : sig_mngr;
 
    when_true(mngr->suspended, exit);
 
    amxp_signal_queue_lock();
 
    amxc_llist_iterate(it, &mngr->signal_queue) {
        when_true_status(read(amxp_sigctrl.sigpipe[0], buffer, 1) == -1, exit, amxp_signal_queue_unlock());
    }
 
    amxc_llist_append(&amxp_sigctrl.sigmngrs, &mngr->it);
    mngr->suspended = true;
 
    amxp_signal_queue_unlock();
 
    retval = 0;
 
exit:
    return retval;
}

amxp_signal_delete()

int amxp_signal_delete

(

amxp_signal_t **

signal

)

Destructor function, deletes a signal.

All connected slots will be automatically disconnected.

The signal is removed from the signal manager it was added to.

Note

It is not safe to delete a signal from within a slot callback function.

Parameters

signal

pointer to the pointer that wil point to the new allocated signal.

Returns

0 when successful, otherwise an error code

Definition at line 669 of file amxp_signal.c.

                                                     {
    int retval = -1;
    when_null(signal, exit);
    when_null(*signal, exit);
 
    amxp_signal_queue_lock();
 
    if(!(*signal)->triggered) {
        amxc_htable_it_clean(&(*signal)->hit, amxp_free_signals);
    } else {
        (*signal)->mngr = NULL;
    }
    *signal = NULL;
 
    amxp_signal_queue_unlock();
 
    retval = 0;
 
exit:
    return retval;
}

amxp_signal_disconnect_all()

int amxp_signal_disconnect_all

(

amxp_signal_t *const

signal

)

Disconnects all slots from the signal.

Parameters

signal

pointer to the signal structure.

Returns

0 when successful, otherwise an error code

Definition at line 806 of file amxp_signal.c.

                                                            {
    int retval = -1;
    when_null(signal, exit);
 
    amxc_llist_clean(&signal->slots, amxp_free_slots);
    retval = 0;
 
exit:
    return retval;
}

amxp_signal_emit()

int amxp_signal_emit	(	const amxp_signal_t *const	signal,
		const amxc_var_t *const	data
	)

Emits a signal.

The signal will be triggered when reading the amxp signal file descriptor using function amxp_signal_read.

To be able to use this method it is recommended to implement an eventloop.

Parameters

signal	pointer to the signal structure.
data	the data that will be passed to all slots.

Returns

0 when successful, otherwise an error code

Definition at line 742 of file amxp_signal.c.

                                                   {
    int retval = -1;
    int write_length = 0;
    amxp_signal_mngr_t* sig_mngr = NULL;
    when_null(signal, exit);
    when_null(signal->mngr, exit);
    sig_mngr = signal->mngr;
 
    when_false(sig_mngr->enabled, exit);
    when_true(sig_mngr->deleted, exit);
 
    amxp_signal_queue_lock();
 
    if(!sig_mngr->suspended) {
        write_length = write(amxp_sigctrl.sigpipe[1], "S", 1);
        when_true_status(write_length != 1, exit, amxp_signal_queue_unlock());
    }
 
    retval = amxp_signal_queue(signal, data);
 
    amxp_signal_queue_unlock();
 
exit:
    return retval;
}

amxp_signal_fd()

int amxp_signal_fd

(

void

)

Gets the amxp signal file descriptor.

Returns

The amxp signal file descriptor

Definition at line 841 of file amxp_signal.c.

                         {
    return amxp_sigctrl.sigpipe[0];
}

amxp_signal_has_slots()

bool amxp_signal_has_slots

(

const amxp_signal_t *const

signal

)

Checks if the signal has slots conencted.

Parameters

signal

pointer to the signal structure.

Returns

True when at least one slot is connected, false when no slots are connected.

Definition at line 821 of file amxp_signal.c.

                                                              {
    bool retval = false;
 
    when_null(signal, exit);
    retval = !amxc_llist_is_empty(&signal->slots);
    when_false(retval, exit);
 
    retval = false;
    amxc_llist_iterate(it, &signal->slots) {
        amxp_slot_t* slot = amxc_container_of(it, amxp_slot_t, it);
        if(!slot->deleted) {
            retval = true;
            break;
        }
    }
 
exit:
    return retval;
}

amxp_signal_name()

const char* amxp_signal_name

(

const amxp_signal_t *const

signal

)

Gets the name of the signal.

Parameters

signal

pointer to the signal structure.

Returns

The name of the signal

Definition at line 817 of file amxp_signal.c.

                                                                {
    return signal ? signal->name : NULL;
}

amxp_signal_new()

int amxp_signal_new	(	amxp_signal_mngr_t *	sig_mngr,
		amxp_signal_t **	signal,
		const char *	name
	)

Constructor function, creates a new signal.

Creates a new signal and adds it to the given signal manager. If sig_mngr is NULL, the signal is added to the global signal manager.

Note

This function allocates memory, the free the allocated memory use the destruction function amxp_signal_delete

Parameters

sig_mngr	pointer to signal manager where the signal must be added
signal	pointer to the pointer that wil point to the new allocated signal
name	name of the signal

Returns

0 when successful, otherwise an error code

Definition at line 620 of file amxp_signal.c.

                                      {
    int retval = -1;
    amxc_htable_it_t* hit = NULL;
    when_null(signal, exit);
    when_not_null(*signal, exit);
    when_null(name, exit);
    when_true(*name == 0, exit)
 
    sig_mngr = (sig_mngr == NULL) ? &amxp_sigmngr : sig_mngr;
    when_null(sig_mngr->it.llist, exit);
 
    hit = amxc_htable_get(&sig_mngr->signals, name);
    when_not_null(hit, exit);
 
    *signal = (amxp_signal_t*) calloc(1, sizeof(amxp_signal_t));
    when_null(*signal, exit);
    (*signal)->mngr = sig_mngr;
 
    amxp_signal_queue_lock();
 
    amxc_htable_it_init(&(*signal)->hit);
    amxc_llist_init(&(*signal)->slots);
    if(amxc_htable_insert(&sig_mngr->signals, name, &(*signal)->hit) == 0) {
        const char* n = amxc_htable_it_get_key(&(*signal)->hit);
        when_null_status(n, exit, amxp_signal_queue_unlock());
        (*signal)->name = n;
        amxc_llist_for_each(it, (&amxp_sigctrl.sigall->slots)) {
            amxp_slot_t* slot = amxc_llist_it_get_data(it, amxp_slot_t, it);
            if(slot->deleted) {
                continue;
            }
            amxp_slot_connect(sig_mngr,
                              name,
                              slot->expr == NULL ? NULL : slot->expr->expression,
                              slot->fn,
                              slot->priv);
        }
 
        retval = 0;
    }
 
    amxp_signal_queue_unlock();
 
exit:
    return retval;
}

amxp_signal_read()

int amxp_signal_read

(

void

)

Reads from the amxp signal file descriptor.

Each signal that was emitted will be read from the file descriptor and triggered. This is usefull when you want to do a full stack unwind before triggering the slots.

To be able to use this method it is recommended to implement an eventloop.

Returns

0 when successful, otherwise an error code

Definition at line 769 of file amxp_signal.c.

                           {
    int retval = -1;
    int read_length = 0;
    char buffer[1];
    signal_queue_item_t* item = NULL;
    amxc_htable_it_t* hit = NULL;
    amxp_signal_t* signal = NULL;
 
    amxp_signal_queue_lock();
 
    read_length = read(amxp_sigctrl.sigpipe[0], buffer, 1);
    when_true_status(read_length < 1, exit, amxp_signal_queue_unlock());
    item = amxp_signal_dequeue();
    when_null_status(item, exit, amxp_signal_queue_unlock());
 
    amxp_signal_queue_unlock();
 
    if(item->sig_name != NULL) {
        hit = amxc_htable_get(&item->sig_mngr->signals, item->sig_name);
        signal = amxc_container_of(hit, amxp_signal_t, hit);
        when_null(signal, exit);
        amxp_signal_trigger(signal, &item->sig_data);
    } else if(item->fn != NULL) {
        item->fn(&item->sig_data, item->priv);
    }
 
    retval = 0;
 
exit:
    if(item != NULL) {
        amxc_var_clean(&item->sig_data);
        free(item->sig_name);
        free(item);
    }
    return retval;
}

amxp_signal_trigger()

void amxp_signal_trigger	(	amxp_signal_t *const	signal,
		const amxc_var_t *const	data
	)

Triggers a signal.

All slots connected to the signal will be called. When a private data pointer was given at the time of the connect, the private data is passed to the slot.

The signal name and the signal data are passed to all the connected slots as well.

Parameters

signal	pointer to the signal structure.
data	the data that will be passed to all slots.

Definition at line 691 of file amxp_signal.c.

                                                       {
    amxp_signal_mngr_t* sig_mngr = NULL;
    char* sig_name = NULL;
    static uint32_t recurse = 0;
 
    when_null(signal, exit);
    when_null(signal->mngr, exit);
    sig_mngr = signal->mngr;
    when_false(sig_mngr->enabled, exit);
    when_true(sig_mngr->deleted, exit);
    when_true(sig_mngr->suspended, exit);
 
    recurse++;
    sig_name = strdup(signal->name);
    sig_mngr->triggered = true;
    signal->triggered = true;
    amxc_llist_for_each(it, (&signal->slots)) {
        amxp_slot_t* slot = amxc_llist_it_get_data(it, amxp_slot_t, it);
        // slots that are marked for deletion should not be called anymore
        if(slot->deleted) {
            continue;
        }
        // always call the remaining slots (if not marked as deleted), even
        // if the signal is removed (signal->mngr == NULL)
        amxp_slot_trigger(slot, sig_name, data);
 
    }
    signal->triggered = false;
    sig_mngr->triggered = false;
 
    amxp_sigmngr_trigger_regexp(sig_mngr, sig_name, data);
    recurse--;
 
    if(recurse == 0) {
        // it is safe now to clean-up memory
        // garbage collect all deleted slots or the signal
        amxp_signal_garbage_collect(signal);
    }
 
    free(sig_name);
 
exit:
    if(recurse == 0) {
        // it is safe now to clean-up memory
        // garbage collect all deleted slots, signals or the signal manager
        amxp_sigmngr_garbage_collect(sig_mngr);
    }
    return;
}