'\"macro stdmacro
.\"
.\" Copyright (c) 2020 Red Hat.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\"
.TH PMSEARCHSETUP 3 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmSearchSetup\f1,
\f3pmSearchSetSlots\f1,
\f3pmSearchSetEventLoop\f1,
\f3pmSearchSetConfiguration\f1,
\f3pmSearchSetMetricRegistry\f1,
\f3pmSearchClose\f1 \- fast, scalable and fulltext capable search services
.SH "C SYNOPSIS"
.ft 3
#include <pcp/pmwebapi.h>
.sp
.ad l
.hy 0
.in +8n
.ti -8n
int pmSearchSetup(pmSearchModule *\fImodule\fP, void *\fIarg\fP);
.sp
.ti -8n
int pmSearchSetSlots(pmSearchModule *\fImodule\fP, void *\fIslots\fP);
.br
.ti -8n
int pmSearchSetEventLoop(pmSearchModule *\fImodule\fP, void *\fIevents\fP);
.br
.ti -8n
int pmSearchSetConfiguration(pmSearchModule *\fImodule\fP, struct dict *\fIconfig\fP);
.br
.ti -8n
int pmSearchSetMetricRegistry(pmSearchModule *\fImodule\fP, struct mmv_registry *\fIregistry\fP);
.sp
.ti -8n
int pmSearchClose(pmSearchModule *\fImodule\fP);
.sp
.in
.hy
.ad
cc ... \-lpcp_web
.ft 1
.SH DESCRIPTION
The
.B pmSearchSetup
and related API functions prepare an application for accessing the fast and scalable metric, instance and instance domain, fulltext capable, searching functionality of the Performance Co-Pilot (PCP).
.PP
This functionality is provided trough asynchronous APIs, which function in event-driven fashion. The interface described here prepare a given search
.IR module
which associates callback routines with certain asynchronous events that occur as part of servicing search requests.
.PP
As a general pattern, all interfaces in these APIs that need to invoke
.I callbacks
provided by the calling program will take an opaque (void * pointer)
.IR arg
parameter.
This pointer will be passed through unchanged and is typically used to access a data structure maintaining state within the calling program.
.PP
Where asynchronous setup is required by
.B pmSearchSetup
its completion will be indicated throught use of the
.I on_setup
callback, which is part of the passed in
.I pmSearchModule
structure. This structure also provides for custom diagnostics handling, through the
.I on_info
callback. These are self-explanatory, see
.I <pcp/pmwebapi.h>
for exact calling conventions.
.PP
The
.I callbacks
registered by
.B pmSearchSetup
to handle events are as follows:
.TP 5
\fBpmSearchTextResultCallBack\fR \fIon_text_result\fR
Callback is called once for each item of search result that matches a given
.B query
passed by
.BR pmSearchTextInDom (3),
.BR pmSearchTextQuery (3),
.BR pmSearchTextSuggest (3).
.TP 5
\fBpmSearchMetricsCallBack\fR \fIon_metrics\fR
Callback is called for results of a call to
.BR pmSearchInfo (3).
.TP 5
\fBpmSearchDoneCallBack\fR \fIon_done\fR
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.
.PP
The helper functions
.B pmSearchSetSlots
(redis),
.B pmSearchSetEventLoop
(libuv),
.B pmSearchSetConfiguration
(configuration file)
and
.B pmSearchSetMetricRegistry
(MMV instrumentation)
interfaces provide a mechanism for passing in state for each of the associated subsystems.
.PP
Finally, a call to
.B pmSearchClose
is used to end services available from a search
.I module
previously enstablished through
.BR pmSearchSetup .
.PP
Within PCP, the
.BR pmproxy (1)
and
.BR pmsearch (1)
utilities are the primary users of the interfaces, providing REST API and command line search services respectively.
.SH DIAGNOSTICS
Where these functions return a status code, this is always zero on success.
On failure a negative PMAPI error code is returned.
.SH SEE ALSO
.BR pmproxy (1),
.BR pmlogger (1),
.BR pmsearch (1),
.BR redis-server (1),
.BR mmv_stats_registry (3),
.BR pmSearchInfo (3),
.BR pmSearchTextInDom (3),
.BR pmSearchTextQuery (3),
.BR pmSearchTextSuggest (3),
.BR PMAPI (3)
and
.BR PMWEBAPI (3).