nmsg 1.3.1
Data Structures | Macros | Typedefs
statsmod_plugin.h File Reference

Implementing statistics export modules. More...

Go to the source code of this file.

Data Structures

struct  nmsg_statsmod_plugin
 Structure exported by statistics modules. More...
 

Macros

#define NMSG_STATSMOD_VERSION   1
 Version number of the nmsg statsmod ABI.
 
#define NMSG_STATSMOD_REQUIRED_INIT    .statsmod_version = NMSG_STATSMOD_VERSION
 Convenience macro.
 

Typedefs

typedef nmsg_res(* nmsg_statsmod_module_init_fp) (const void *param, size_t len_param, void **mod_data)
 Initialize the stats module.
 
typedef void(* nmsg_statsmod_module_fini_fp) (void *mod_data)
 Destroy the filter module.
 
typedef nmsg_res(* nmsg_statsmod_add_io_fp) (void *mod_data, nmsg_io_t io, const char *name)
 Add an nmsg_io_t with the statistics module for instrumentation.
 
typedef nmsg_res(* nmsg_statsmod_remove_io_fp) (void *mod_data, nmsg_io_t io)
 Remove an nmsg_io_t with the filter module.
 

Detailed Description

Implementing statistics export modules.

This file defines the interface that developers of statistics export modules must implement. For the interface for loading and calling statistics modules, see nmsg/fltmod.h.

Statistics modules are dynamically loaded shared objects that must export a symbol called nmsg_statsmod_plugin_export. This is a structure of type nmsg_statsmod_plugin and is the sole entry point into the module.

The first field of the nmsg_statsmod_plugin structure is the version of the API/ABI between libnmsg and the statistics module. Module developers should assign this field the value NMSG_STATSMOD_VERSION, or they can add NMSG_STATSMOD_REQUIRED_INIT, to the initializer, which is a convenience macro that initializes required fields.

A statistics module (statsmod) needs to provide four functions:

  1. An initialization function function module_init,
  2. A finalization function module_fini,
  3. A function to add an nmsg_io to instrumentation io_add, and
  4. A function to remove an nmsg_io from instrumentation io_remove.

A statistics module is expected to call nmsg_io_get_stats() on any enrolled nmsg_io object and expose these stats appropriately.

Definition in file statsmod_plugin.h.

Macro Definition Documentation

◆ NMSG_STATSMOD_VERSION

#define NMSG_STATSMOD_VERSION   1

Version number of the nmsg statsmod ABI.

Definition at line 50 of file statsmod_plugin.h.

◆ NMSG_STATSMOD_REQUIRED_INIT

#define NMSG_STATSMOD_REQUIRED_INIT    .statsmod_version = NMSG_STATSMOD_VERSION

Convenience macro.

Definition at line 118 of file statsmod_plugin.h.

Typedef Documentation

◆ nmsg_statsmod_module_init_fp

typedef nmsg_res(* nmsg_statsmod_module_init_fp) (const void *param, size_t len_param, void **mod_data)

Initialize the stats module.

Data with module-defined meaning may be passed in via the 'param' and 'len_param' parameters. This can be used to, for example, configure module-specific statistics export parameters.

Parameters
[in]paramModule-defined data needed for the initialization of the module.
[in]len_paramLength of 'param'.
[out]mod_dataModule-defined, module-wide state, passed to other module functions that take a 'mod_data' parameter.
Returns
nmsg_res_success If the module was successfully initialized.
Any other result to indicate a fatal error.

Definition at line 74 of file statsmod_plugin.h.

◆ nmsg_statsmod_module_fini_fp

typedef void(* nmsg_statsmod_module_fini_fp) (void *mod_data)

Destroy the filter module.

Any module-wide resources acquired by the module must be released.

Parameters
[in]mod_dataModule-defined, module-wide state.

Definition at line 86 of file statsmod_plugin.h.

◆ nmsg_statsmod_add_io_fp

typedef nmsg_res(* nmsg_statsmod_add_io_fp) (void *mod_data, nmsg_io_t io, const char *name)

Add an nmsg_io_t with the statistics module for instrumentation.

Parameters
[in]mod_dataModule-defined, module-wide state.
[in]ioAn nmsg_io_t object.
[in]nameA name for the nmsg_io_t object to appear in stats reporting.

Definition at line 101 of file statsmod_plugin.h.

◆ nmsg_statsmod_remove_io_fp

typedef nmsg_res(* nmsg_statsmod_remove_io_fp) (void *mod_data, nmsg_io_t io)

Remove an nmsg_io_t with the filter module.

Must be called before nmsg_io_destroy() on the given io object.

Parameters
[in]mod_dataModule-defined, module-wide state.
[in]ioAn nmsg_io_t object.

Definition at line 114 of file statsmod_plugin.h.