NAME

       pmSearchSetup,     pmSearchSetSlots,    pmSearchSetEventLoop,    pmSearchSetConfiguration,
       pmSearchSetMetricRegistry, pmSearchClose - fast, scalable  and  full-text  capable  search
       services

C SYNOPSIS

       #include <pcp/pmwebapi.h>

       int pmSearchSetup(pmSearchModule *module, void *arg);

       int pmSearchSetSlots(pmSearchModule *module, void *slots);
       int pmSearchSetEventLoop(pmSearchModule *module, void *events);
       int pmSearchSetConfiguration(pmSearchModule *module, struct dict *config);
       int pmSearchSetMetricRegistry(pmSearchModule *module, struct mmv_registry *registry);

       int pmSearchClose(pmSearchModule *module);

       cc ... -lpcp_web

DESCRIPTION

       The  pmSearchSetup and related API functions prepare an application for accessing the fast
       and  scalable  metric,  instance  and  instance  domain,  full-text   capable,   searching
       functionality of the Performance Co-Pilot (PCP).

       This  functionality  is  provided trough asynchronous APIs, which function in event-driven
       fashion. The interface described here prepare  a  given  search  module  which  associates
       callback  routines with certain asynchronous events that occur as part of servicing search
       requests.

       As a general pattern, all interfaces in these APIs that need to invoke callbacks  provided
       by  the  calling program will take an opaque (void * pointer) arg parameter.  This pointer
       will be passed through unchanged  and  is  typically  used  to  access  a  data  structure
       maintaining state within the calling program.

       Where  asynchronous  setup  is  required by pmSearchSetup its completion will be indicated
       through use of the on_setup callback, which  is  part  of  the  passed  in  pmSearchModule
       structure.  This  structure  also  provides  for  custom diagnostics handling, through the
       on_info callback. These are  self-explanatory,  see  <pcp/pmwebapi.h>  for  exact  calling
       conventions.

       The callbacks registered by pmSearchSetup to handle events are as follows:

       pmSearchTextResultCallBack on_text_result
            Callback  is  called  once  for each item of search result that matches a given query
            passed by pmSearchTextInDom(3), pmSearchTextQuery(3), pmSearchTextSuggest(3).

       pmSearchMetricsCallBack on_metrics
            Callback is called for results of a call to pmSearchInfo(3).

       pmSearchDoneCallBack on_done
            On completion of all asynchronous interfaces that return success (zero return  code),
            this  callback  will be called.  It provides a status code indicating overall success
            (zero) or failure (negative PMAPI code) of the operation.

       The helper functions pmSearchSetSlots (key-value  server),  pmSearchSetEventLoop  (libuv),
       pmSearchSetConfiguration   (configuration   file)   and   pmSearchSetMetricRegistry   (MMV
       instrumentation) interfaces provide a mechanism for passing  in  state  for  each  of  the
       associated subsystems.

       Finally,  a  call  to pmSearchClose is used to end services available from a search module
       previously established through pmSearchSetup.

       Within PCP, the pmproxy(1)  and  pmsearch(1)  utilities  are  the  primary  users  of  the
       interfaces, providing REST API and command line search services respectively.

DIAGNOSTICS

       Where  these functions return a status code, this is always zero on success.  On failure a
       negative PMAPI error code is returned.

SEE ALSO

       pmproxy(1),    pmlogger(1),    pmsearch(1),    mmv_stats_registry(3),     pmSearchInfo(3),
       pmSearchTextInDom(3),    pmSearchTextQuery(3),    pmSearchTextSuggest(3),   PMAPI(3)   and
       PMWEBAPI(3).