PMSEARCHSETUP(3)           Library Functions Manual           PMSEARCHSETUP(3)

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 (redis), 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), redis-server(1),
       mmv_stats_registry(3), pmSearchInfo(3), pmSearchTextInDom(3),
       pmSearchTextQuery(3), pmSearchTextSuggest(3), PMAPI(3) and PMWEBAPI(3).


Performance Co-Pilot                  PCP                     PMSEARCHSETUP(3)