~ubuntu-branches/ubuntu/utopic/glame/utopic

@comment $Id: glsignal.texi,v 1.5 2001/08/03 12:54:16 richi Exp $

 

@node GLAME Signal Interface, Function and Type Index, GLAME Database Interface, Top

@chapter GLAME Signal Interface

 

Generic signals via callbacks (@code{glsig_handler_t}), issuable from a

glsig_emitter. Signal masks are supported, as is a hierarchy of the

signal emitters.

 

WARNING! No explicit threading support is included, i.e. do your own

locking (you have to protect the emitter against concurrent addition and

removal of handlers and emit of signals). Also a handler will be invoked

in the thread context of the emitter, not in the one which added the

handler. If you want to emit signals from real signal handlers you have

to ensure yourself that your handlers are signal safe - also they should

be reentrant as parallel invocation from different threads is not

protected against.

 

Brief description of the available API follows: 

 

@deftp void {(glsig_callb_t)} (glsig_handler_t *, long, va_list)

  The type of the used callback functions through which signals

  are supposed to be handled.

@end deftp

 

@tindex glsig_emitter_t

@deftypefun {} INIT_GLSIG_EMITTER ( glsig_emitter_t *@var{emitter})

  Inits an emitter. No signal handlers are attached initially.

@end deftypefun

 

@tindex glsig_emitter_t

@tindex glsig_handler_t

@tindex glsig_callb_t

@deftypefun {glsig_handler_t *} glsig_add_handler ( glsig_emitter_t *@var{emitter}, long @var{sigmask}, glsig_callb_t *@var{cb}, void *@var{priv})

  Adds a signal handler to the emitter using the specified sigmask

  and the callback handler. The priv data is stored in the handlers

  ->priv field which you should access using @code{glsig_handler_private()}.

@end deftypefun

 

@tindex glsig_emitter_t

@tindex glsig_handler_t

@deftypefun {glsig_handler_t *} glsig_add_redirector ( glsig_emitter_t *@var{emitter}, long @var{sigmask}, glsig_emitter_t *@var{dest})

  Adds a redirector to the emitter. All signals raised from the emitter

  matching the specified signal mask will be raised again from the dest emitt

@end deftypefun

 

@tindex glsig_emitter_t

@deftypefun void glsig_emit ( glsig_emitter_t *@var{emitter}, int @var{sig}, ...)

  Emits the signal sig from the emitter and provides the varargs

  to the callbacks. Signals are emitted bottom to top in the hierarchy.

  It is safe to remove your signal handler during execution.

@end deftypefun

 

@tindex glsig_emitter_t

@deftypefun int glsig_copy_handlers ( glsig_emitter_t *@var{dest}, glsig_emitter_t *@var{source})

  Copies all handlers from one emitter to another - same "private"

  data, of course. Can return -1 on memory shortage. Redirectors are

  not copied.

@end deftypefun

 

@tindex glsig_emitter_t

@deftypefun int glsig_copy_redirectors ( glsig_emitter_t *@var{dest}, glsig_emitter_t *@var{source})

  Copies all redirectors from one emitter to another - same "private"

  data, of course. Can return -1 on memory shortage. Normal handlers

  are not copied.

@end deftypefun

 

@tindex glsig_handler_t

@deftypefun void glsig_delete_handler ( glsig_handler_t *@var{handler})

  Removes and destroyes the specified handler from its emitter.

@end deftypefun

 

@tindex glsig_emitter_t

@deftypefun void glsig_delete_all ( glsig_emitter_t *@var{emitter})

  Removes and destroyes all signal handlers from the specified emitter.

  Use with care.

@end deftypefun

 

@tindex glsig_handler_t

@deftypefun void glsig_handler_exec ( glsig_handler_t *@var{h}, int @var{sig}, ...)

  Executes the specified signal handler. Usually you dont want to use

  this, instead use @code{glsig_emit()}.

@end deftypefun

 

 

Inside signal handlers you may access the passed parameters (which you

should know by type and count) with the following macros.

 

@deftypefun void GLSIGH_GETARGS1 ( va_list @var{va}, type1 @var{var1})

@deftypefunx void GLSIGH_GETARGS2 ( va_list @var{va}, type1 @var{var1}, type2 @var{var2})

@deftypefunx void GLSIGH_GETARGS3 ( va_list @var{va}, type1 @var{var1}, type2 @var{var2}, type3 @var{var3})

@deftypefunx void GLSIGH_GETARGS4 ( va_list @var{va}, type1 @var{var1}, type2 @var{var2}, type3 @var{var3}, type4 @var{var4})

These macros initialize the provided variables with the passed parameters.

Beware that passing types with @code{sizeof(type)} not equal to

@code{sizeof(void *)} is not safe on compilers other than gcc.

@end deftypefun