oracular (3) pmWebTimerRelease.3.gz

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).