NAME

       IV_SIGNAL_INIT, iv_signal_register, iv_signal_unregister - ivykis signal handling

SYNOPSIS

       #include <iv_signal.h>

       struct iv_signal {
               int             signum;
               unsigned int    flags;
               void            *cookie;
               void            (*handler)(void *);
       };

       void IV_SIGNAL_INIT(struct iv_signal *this);
       int iv_signal_register(struct iv_signal *this);
       void iv_signal_unregister(struct iv_signal *this);

DESCRIPTION

       iv_signal  provides  a  way  for  ivykis(3)  applications  to  handle  POSIX  signals,  by
       integrating them with the ivykis event loop.

       An ivykis application desiring signal notification registers a struct iv_signal object  by
       calling   iv_signal_register,   after   having  initialised  it  with  IV_SIGNAL_INIT  and
       subsequently having filled in the ->signum, ->cookie and ->handler members.

       Once the signal indicated by ->signum is delivered to any thread in the  current  process,
       the  callback  specified  by  ->handler  is  scheduled to be called in the thread that the
       struct iv_signal object was registered in, with ->cookie as its sole argument.

       If the same signal arrives again  while  the  callback  function  is  still  running,  the
       callback function is guaranteed to be called again after it returns.

       It  is permitted to register multiple struct iv_signal objects for the same signal number.
       If all such objects are registered with IV_SIGNAL_FLAG_EXCLUSIVE in  ->flags  unset,  then
       all  objects  will  have their callback functions called upon arrival of the signal, in no
       guaranteed order.

       Invoking  callback  functions  stops  at  the   first   struct   iv_signal   object   with
       IV_SIGNAL_FLAG_EXCLUSIVE    in    ->flags    set,    so   that   if   all   objects   have
       IV_SIGNAL_FLAG_EXCLUSIVE set, only one callback function will be invoked.

       To deinitialize a struct iv_signal object, call iv_signal_unregister from the same  thread
       that iv_signal_register was called from on that object.

       It  is permitted to unregister a struct iv_signal object from any ivykis callback function
       in the thread it was registered in, including from a callback function triggered  by  this
       object,  and  it  is  permitted to free the memory corresponding to an unregistered object
       from its own callback function.

       It is guaranteed that signals delivered to child processes that were  created  by  fork(2)
       but that have not yet called execve(2) will not cause iv_signal callbacks to be invoked in
       the parent process.

       Internally, iv_signal is implemented using iv_event_raw(3).

SEE ALSO

       ivykis(3), iv_event_raw(3), sigaction(2)