ooc 1.3
Object Oriented tollkit fo ANSI C

signal.h File Reference

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.

Functions

void signal_connect (void *source, SignalPGetter getter, void *target, SignalHandler handler)
 Connects a signal to a signal handler.
void signal_disconnect (void *source, SignalPGetter getter, void *target, SignalHandler handler)
 Disconnects a signal handler from a signal.
void signal_emit (Signal, void *parameter, ooc_destroyer param_destroy_fn)
 Emits a signal asynchronuosly.
void signal_emit_sync (Signal, void *parameter, ooc_destroyer param_destroy_fn)
 Emits a signal synchronously.
void signal_destroy_notify (Object object)
 Object destroy notifier for the signaling system.
void signal_process_signals (void)
 Processes all asynchronously emitted signals.
int signal_process_next (void)
 Processes the next asynchronously emitted signals.

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:
targetThe Object that has been assigned to the handler.
sourceThe source Object that has activated the signal.
paramThe 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:
sourceThe source Object of the signal (the Object that holds the Signal as a member).
getterThe getter function, that returns address of the Signal of the source Object.
targetThe target Object (the object that is passed as the first parameter of the signal handler).
handlerThe 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:
objectThe 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:
sourceThe source Object of the signal.
getterThe getter function, that returns address of the Signal of the source Object.
targetThe target Object.
handlerThe 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:
signalThe signal that must be emitted.
parameterThe 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_fnThe 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:
signalThe signal that must be emitted.
parameterThe 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_fnThe 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.
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines