Signal class - an ooc signal / slot mechanism. More...

#include "list.h"

Include dependency graph for signal.h:

Typedefs
typedef void(*	SignalHandler )(void target, void source, void *param)
	Signal handler prototype. More...

Functions
void	signal_connect (void source, SignalPGetter getter, void target, SignalHandler handler)
	Connects a signal to a signal handler. More...

void	signal_disconnect (void source, SignalPGetter getter, void target, SignalHandler handler)
	Disconnects a signal handler from a signal. More...

void	signal_emit (Signal, void *parameter, ooc_destroyer param_destroy_fn)
	Emits a signal asynchronuosly. More...

void	signal_emit_sync (Signal, void *parameter, ooc_destroyer param_destroy_fn)
	Emits a signal synchronously. More...

void	signal_destroy_notify (Object object)
	Object destroy notifier for the signaling system. More...

void	signal_process_signals (void)
	Processes all asynchronously emitted signals. More...

int	signal_process_next (void)
	Processes the next asynchronously emitted signals. More...

Detailed Description

Signal class - an ooc signal / slot mechanism.

A signal / slot mechanism implemented for the ooc object manager.

The use of the Signal class is optimized for the user's convenience, therefore it is a bit different from other ooc classes. There are some rules that must be considered using Signals. The signaling system must be initilaized at the start and released at the end of your application.

int main( int argc, char argv[] )
{
    ooc_init_class( Signal );
    ...  Your staff here 
    ooc_finalize_all();
    return 0;
}

Todo:: Desrcibing the use of the signaling system

Note: Signal implementation is thread safe. Any thread can emit a signal at any time. However the initialization of the Signal class must be done before any fork in the program.

See Also: signal_process_signals() for blocking behavior!

Typedef Documentation

typedef void(* SignalHandler)(void *target, void *source, void *param)

Signal handler prototype.

The signal handler is a function that has three parameters. In Object oriented manner it is a member function of the target object.

Parameters

target	The Object that has been assigned to the handler.
source	The source Object that has activated the signal.
param	The parameter the has been passed at the time of signal emittion.

See Also: signal_connect(), signal_emit(), signal_emit_sync()

Warning: The signal handler can throw an exception, but this exception will not be propagated! The signal emittion routines will return as if everything went normal.

Function Documentation

void signal_connect	(	void *	source,
		SignalPGetter	getter,
		void *	target,
		SignalHandler	handler
	)

Connects a signal to a signal handler.

The connected signal handler will be executed when the signal is emitted.

Parameters

source	The source Object of the signal (the Object that holds the Signal as a member).
getter	The getter function, that returns address of the Signal of the source Object.
target	The target Object (the object that is passed as the first parameter of the signal handler).
handler	The signal handler.

See Also: signal_disconnect()

Note: Multiple handlers can be connected to a signal, they are called in the order of connections in the case of signal emittion.; For user's convenience there is no new operator for Signals! No need to create new signals, just connect them. Never call ooc_new( Signal, NULL )!;

void signal_destroy_notify ( Object object )

Object destroy notifier for the signaling system.

Every Object that can be signal source or a signal target, must call this notifier in their destructor. This notifier disconnects all signals that are related to the Object under destruction.

Parameters

object The Object that is being deleted.

void signal_disconnect	(	void *	source,
		SignalPGetter	getter,
		void *	target,
		SignalHandler	handler
	)

Disconnects a signal handler from a signal.

The connected signal handler will be disconnected.

Parameters

source	The source Object of the signal.
getter	The getter function, that returns address of the Signal of the source Object.
target	The target Object.
handler	The signal handler.

See Also: signal_connect()

Note: If the same signal handler was connected multiple times to the same source and target objects (meaningless but possible) only the first one will be disconnected!

Warning: Already buffered async emitted signals will be executed even if they have been disconnected!

void signal_emit	(	Signal	signal,
		void *	parameter,
		ooc_destroyer	param_destroy_fn
	)

Emits a signal asynchronuosly.

Asynchronuos signal emittion means, that the signal_emit() function returns immadiately, and the signal is buffered in the signal queue. Signal is executed when the main eventloop reaches the signal emittion section.

Parameters

signal	The signal that must be emitted.
parameter	The parameter to be passed to the connected signal handler. The signaling system takes over the ownership of this memory block or Object if param_destroy_fn != NULL, so you must not destroy it!
param_destroy_fn	The destroy function for freeing up the memory occupied by the parameter. The signalimg system automatically destroys the parameter when all connected signal handler has been executed. For constant parameters you should pass NULL (no demolition is required at the end).

See Also: signal_emit_sync()

void signal_emit_sync	(	Signal	signal,
		void *	parameter,
		ooc_destroyer	param_destroy_fn
	)

Emits a signal synchronously.

Synchronous signal emittion means, that the signal handlers are called immediately, and the signal_emit_sync() function returns only, when all connected signal handlers has been executed.

Parameters

signal	The signal that must be emitted.
parameter	The parameter to be passed to the connected signal handler. The signaling system takes over the ownership of this memory block or Object if param_destroy_fn != NULL, so you must not destroy it!
param_destroy_fn	The destroy function for freeing up the memory occupied by the parameter. The signalimg system automatically destroys the parameter when all connected signal handler has been executed. For constant parameters you should pass NULL (no demolition is required at the end). If you would like to take care of the lifecycle of the parameter object instaed of the signaling system then you can pass NULL as well.

See Also: signal_emit()

int signal_process_next ( void )

Processes the next asynchronously emitted signals.

Must be called from the eventloop. Processes the next buffered async signal in the signal queue. Only one emitted signal is processed.

Returns: TRUE is signal was processed, FALSE if there was no signal in the queue.

Note: This opeartion is thread safe, can be called parallely.

See Also: signal_process_signals()

void signal_process_signals ( void )

Processes all asynchronously emitted signals.

Must be called from the eventloop. Processes all buffered async signals.

Warning: The async signals emitted by the called handlers will be executed as well before return.

Note: The signals are processed in a single thread.

Warning: This is a blocking operation! Only one thread is used for emitting the signals. If an other thread attempts to call signal_process_signals() parallely then that thread will be blocked.

Note: If you want to process the signals in threads, use signal_process_next() instead.

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation