Man Linux: Main Page and Category List

NAME

       pmLoopRegisterChild,      pmLoopRegisterIdle,      pmLoopRegisterInput,
       pmLoopRegisterSignal,   pmLoopRegisterTimeout,   pmLoopUnregisterChild,
       pmLoopUnregisterIdle,   pmLoopUnregisterInput,  pmLoopUnregisterSignal,
       pmLoopUnregisterTimeout, pmLoopStop, pmLoopMain - PMAPI  functions  for
       implementing application main loop

C SYNOPSIS

       #include <pcp/pmapi.h>

       int pmLoopRegisterChild(pid_t pid,
           int (*callback)(pid_t pid, int status, const struct rusage *rusage, void *closure),
           void *closure);
       int pmLoopRegisterIdle(
           int (*callback)(void *closure),
           void *closure);
       int pmLoopRegisterInput(int fd, int flags,
           int (*callback)(int fd, int flags, void *closure),
           void *closure, int priority);
       int pmLoopRegisterSignal(int sig,
           int (*callback)(int sig, void *closure),
           void *closure);
       int pmLoopRegisterTimeout(int delay_msec,
           int (*callback)(void *closure),
           void *closure);

       int pmLoopUnregisterChild(int tag);
       int pmLoopUnregisterIdle(int tag);
       int pmLoopUnregisterInput(int tag);
       int pmLoopUnregisterSignal(int tag);
       int pmLoopUnregisterTimeout(int tag);

       void pmLoopStop(void);
       void pmLoopMain(void);

       cc ... -lpcp

DESCRIPTION

       These functions implement a generic UNIX main poll(2) loop which can be
       found at the heart of many UNIX daemon processes and a  number  of  the
       associated features which the UNIX process model requires the same code
       to  handle,  for  example  timers  and  safe   delivery   of   signals.
       Inspiration  for  this  module  came  from (in chronological order) the
       SunView notifier library, the X Intrinsics Toolkit main loop,  and  the
       GTK+/libglib main loop feature.

       The module supports the following features:

       *      callback to application code from main loop when input or output
              is possible on a file descriptor

       *      callback when a (catchable) signal is delivered

       *      callback on a timeout, including recurring timeouts

       *      callback when a  child  process  has  died  (or  its  status  is
              otherwise notified via wait3(2)).

       *      callback when the main loop is idle

       *      all  callbacks  occur at safe times, e.g. signal callback occurs
              when main loop is idle and not partway through another callback.

       *      a   callback  is  automatically  unregisted  if  the  callback’s
              function returns non-zero value.

       *      application code can call a subsidiary main loop, to handle  and
              dispatch   all   registered  callbacks  for  some  time  without
              returning to the main loop.

       int pmLoopRegisterInput(int fd, int flags,
            int (*callback)(int fd, int flags, void *closure),
            void *closure, int priority);

              Register callback to be called  when  input  or  output  becomes
              possible  on  file  descriptor  fd.   The flags are a bitmask of
              poll(2) flags, e.g. POLLIN will cause the callback to be  called
              when  input  is  available on the file descriptor and POLLOUT is
              for when output becomes possible.  The closure  pointer  is  not
              interpreted  in  any  way,  but  is  passed to the callback; the
              application may use this to pass around a pointer to any data it
              needs.   Priority  may be used to force the order of dispatch of
              callbacks when multiple file descriptors become available at the
              same time; callbacks are dispatched in increasing order of their
              priority number.  The return value is  a  tag  which  is  unique
              amongst  all  registered  callbacks  (e.g.  registering the same
              callback twice gives two different tags) and which can  be  used
              to remove the callback using pmLoopUnregisterInput().

       void pmLoopUnregisterInput(int tag);

              Unregisters   a   file   descriptor  input  callback  previously
              registered  with  pmLoopRegisterInput().   This  can  safely  be
              called from within the callback being deregistered.

       int pmLoopRegisterSignal(int sig,
           int (*callback)(int sig, void *closure),
           void *closure);

              Register  callback  to be called when signal sig is delivered to
              the process.  Some signals cannot be caught, see  the  signal(7)
              manpage  for  details.  Catching SIGCHLD is not recommended, see
              pmLoopRegisterChild() for a better way to detect  child  process
              status  changes.   The closure pointer is not interpreted in any
              way, but is passed to the callback; the application may use this
              to pass around a pointer to any data it needs.  The return value
              is a tag which is unique amongst all registered callbacks  (e.g.
              registering  the  same  callback twice gives two different tags)
              and  which  can  be  used   to   remove   the   callback   using
              pmLoopUnregisterSignal().   Once  registered,  a  callback stays
              registered     unless     explicitly      unregistered      with
              pmLoopUnregisterSignal(),  and does not need to be re-registered
              after a signal is delivered.  Note that two  or  more  callbacks
              can  be  registered  for the same signal; they are dispatched in
              the reverse of the order in which they were registered.

       void pmLoopUnregisterSignal(int tag);

              Unregisters  a  signal  callback  previously   registered   with
              pmLoopRegisterSignal().   This  can safely be called from within
              the callback being deregistered.

       int pmLoopRegisterTimeout(int delay_msec,
           int (*callback)(void *closure),
           void *closure);

              Register callback to be  called  after  delay_msec  milliseconds
              have   elapsed.    If   delay  is  0,  the  callback  is  called
              immediately.  The closure pointer is not interpreted in any way,
              but  is  passed to the callback; the application may use this to
              pass around a pointer to any data it needs.  The return value is
              a  tag  which  is  unique amongst all registered callbacks (e.g.
              registering the same callback twice gives  two  different  tags)
              and   which   can   be   used   to  remove  the  callback  using
              pmLoopUnregisterTimeout().  Once registered,  a  callback  stays
              registered  until  it  is  either  explictly  unregisterd or the
              callback function returns non-zero value.

       void pmLoopUnregisterTimeout(int tag);

              Unregisters  a  timeout  callback  previously  registered   with
              pmLoopRegisterTimeout().   This can safely be called from within
              the callback being deregistered.

       int pmLoopRegisterChild(pid_t pid,
           int (*callback)(pid_t pid, int status, const struct rusage *rusage, void * closure),
           void *closure);

              Register callback to  be  called  when  the  child  process  pid
              changes  status in a way which triggers a wait3(2) notification.
              Normally, this means the process has called exit()  or  died  in
              some  other  manner, but see the wait3(2) manpage.  Waiting on a
              process group (e.g. by passing a negative pid) is not supported.
              All  descendant  processes started by the process will be reaped
              by the module, regardless of whether a  child  process  callback
              has  been  registered  for  them  or not.  The status and rusage
              argument to the callback are from the wait3(2) system call,  see
              the  wait3(2)  manpage for how to use the macros WIFSTOPPED() et
              al to interpret these.  The closure pointer is  not  interpreted
              in  any  way, but is passed to the callback; the application may
              use this to pass around a pointer to any  data  it  needs.   The
              return  value  is  a  tag which is unique amongst all registered
              callbacks (e.g. registering the same callback  twice  gives  two
              different  tags)  and  which  can be used to remove the callback
              using pmLoopUnregisterChild().  Once registered, a  callback  is
              automatically  unregistered if status indicates that the process
              has  died  (this  is  the  usual  case),  otherwise   it   stays
              registered.

       void pmLoopUnregisterChild(int tag);

              Unregisters  a child process callback previously registered with
              pmLoopRegisterChild().  This can safely be  called  from  within
              the callback being deregistered.

       int pmLoopRegisterIdle(
           int (*callback)(void *closure),
           void *closure);

              Register callback to be called whenever the loop module is idle,
              i.e. no other callbacks are pending.  This is useful  for  doing
              background  processing  while  still responding to other events.
              Note that the callback function can be called many thousands  of
              times per second, so this feature should be used with care.  The
              closure pointer is not interpreted in any way, but is passed  to
              the  callback;  the  application  may  use this to pass around a
              pointer to any data it needs.  The return value is a  tag  which
              is unique amongst all registered callbacks (e.g. registering the
              same callback twice gives two different tags) and which  can  be
              used  to remove the callback using pmLoopUnregisterIdle().  Once
              registered, a callback stays registered.

       void pmLoopUnregisterIdle(int tag);

              Unregisters a child process callback previously registered  with
              pmLoopRegisterIdle().  This can safely be called from within the
              callback being deregistered.

       void pmLoopMain(void);

              This function starts  the  main  loop  of  an  application.   It
              handles various UNIX events and dispatches registered callbacks,
              not returning until pmLoopStop() is called.

              Note that pmLoopMain() may be called in an callback,  which  has
              the  effect  of running a subsidiary loop, i.e. loop for a while
              handling events and dispatching callbacks as the main loop would
              do,  but  without  returning  control  to  the  main loop.  Such
              subsidiary loops can be nested.

       void pmLoopStop(void);

              Causes the innermost pmLoopMain() to  return  when  it  is  next
              idle, i.e. as soon as the current callback has returned.

SEE ALSO

       poll(2), wait3(2), signal(7)