# pmsearchsetup

## 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  Perfor‐
           mance 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 comple‐
           tion 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 ex‐
           act 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 suc‐
                cess (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), **pm‐**
           **SearchSetEventLoop**(libuv), **pmSearchSetConfiguration**(configura‐
           tion file) and **pmSearchSetMetricRegistry**(MMV instrumentation) in‐
           terfaces 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 pri‐
           mary 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.
    


* * *