NAME

       pmWebTimerRegister,  pmWebTimerRelease,  pmWebTimerSetMetricRegistry  -  thread-safe timer
       list management

C SYNOPSIS

       #include <pcp/pmwebapi.h>

       typedef void (*pmWebTimerCallBack)(void *data);
       int pmWebTimerRegister(pmWebTimerCallBack callback, void *data);

       int pmWebTimerRelease(int seq);
       int pmWebTimerSetMetricRegistry(struct mmv_registry *registry);
       cc ... -lpcp_web

DESCRIPTION

       The pmWebTimerRegister and related API functions provide a convenient thread-safe API  for
       applications  to  manage  a  list  of  timer  driven  callbacks.   On  the  first  call to
       pmWebTimerRegister or  pmWebTimerSetMetricRegistry,  an  internal  timer  is  set  up  and
       initialized  to  fire  every  1.0  seconds.   Each  time  the  timer  fires, all currently
       registered callback functions will be called serially with the opaque  data  pointer  that
       was supplied when each function was registered.  The pmWebTimerCallBack typedef provides a
       suitable callback function prototype.

       All  registered  callback  functions  should  be  non-blocking  and  execute  quickly  and
       synchronously.  Typical callback functions include refreshing instrumentation, calculating
       and updating performance metric values, periodic garbage collection and  any  other  local
       function that requires regular execution.

       The  pmWebTimerSetMetricRegistry  function provides a convenient way for an application to
       pass in a pointer to an libpcp_mmv(3) registry that has been suitably initialized  by  the
       calling application.  This registry will be used to dynamically create six server resource
       metrics   named   NAME.mem.datasz,    NAME.mem.maxrss,    NAME.cpu.total,    NAME.cpu.sys,
       NAME.cpu.user  and NAME.pid, where NAME is the root PCP PMNS(5) name set up by the calling
       application.  These metrics should be reasonably self explanatory; they  provide  resource
       usage  metrics  from  the  calling application / server and use getrusage(2), times(2) and
       getpid(2).

RETURN VALUE

       The pmWebTimerRegister function returns a positive integer handle that may be subsequently
       used  in a call to pmWebTimerRelease to remove a timer from the internal timer list.  When
       a timer is removed with a call to pmWebTimerRelease,  the  internal  data  structures  are
       freed.   The  caller however, is responsible for freeing the associated data (since it may
       or may not be dynamically allocated).

DIAGNOSTICS

       On failure a negative PMAPI error code is returned in all cases.

SEE ALSO

       pmproxy(1), mmv_stats_registry(3), PMAPI(3) and PMWEBAPI(3).