|
nmsg 1.1.2
|
Implementing message filter modules. More...
Go to the source code of this file.
Data Structures | |
| struct | nmsg_fltmod_plugin |
| Structure exported by filter modules. More... | |
Macros | |
| #define | NMSG_FLTMOD_VERSION 1 |
| Version number of the nmsg fltmod ABI. | |
| #define | NMSG_FLTMOD_REQUIRED_INIT .fltmod_version = NMSG_FLTMOD_VERSION |
| Convenience macro. | |
Typedefs | |
| typedef nmsg_res(* | nmsg_fltmod_module_init_fp) (const void *param, const size_t len_param, void **mod_data) |
| Initialize the filter module. | |
| typedef void(* | nmsg_fltmod_module_fini_fp) (void *mod_data) |
| Destroy the filter module. | |
| typedef nmsg_res(* | nmsg_fltmod_thread_init_fp) (void *mod_data, void **thr_data) |
| Initialize module-defined, thread-wide state. | |
| typedef nmsg_res(* | nmsg_fltmod_thread_fini_fp) (void *mod_data, void *thr_data) |
| Destroy thread-wide state. | |
| typedef nmsg_res(* | nmsg_fltmod_filter_message_fp) (nmsg_message_t *msg, void *mod_data, void *thr_data, nmsg_filter_message_verdict *vres) |
| Filter a message object and return the filter verdict. | |
Implementing message filter modules.
This file defines the interface that developers of message filter modules must implement. For the interface for loading and calling filter modules, see nmsg/fltmod.h.
Filter modules are dynamically loaded shared objects that must export a symbol called nmsg_fltmod_plugin_export. This is a structure of type nmsg_fltmod_plugin and is the sole entry point into the module.
The first field of the nmsg_fltmod_plugin structure is the version of the API/ABI between libnmsg and the filter module. Module developers should assign this field the value NMSG_FLTMOD_VERSION, or they can add NMSG_FLTMOD_REQUIRED_INIT, to the initializer, which is a convenience macro that initializes required fields.
A filter module needs to provide at least one function, the core message filtering function filter_message. This function must be thread-safe, since it may be called simultaneously from multiple threads.
Optionally, up to four more functions may be provided: a global module initializer and finalizer (module_init and module_fini), and a per-thread initializer and finalizer (thread_init and thread_fini). These functions can be used to acquire and release resources, generate debug messages, etc. The module and thread initializers may provide opaque data pointers. These pointers will be provided as parameters to the message filtering function.
The module_init function will only be called once, immediately after the plugin module has been loaded. It will be called before all other module functions. Therefore, it does not need to be thread-safe.
The module_fini function will only be called once, immediately before the plugin module will be unloaded from the process. It will be called after all other module functions. Therefore, it does not need to be thread-safe, either.
The thread_init and thread_fini functions may be called by a processing thread after the thread has started and before the thread exits. They need to be thread-safe, since they be called by independently executing threads. A thread may not call a module's filter_message function before it has called thread_init, and it may not call filter_message after it has called thread_fini.
For an example of a simple message filtering module, see the "sample" filter module in the fltmod/ directory of the nmsg distribution. The "sample" filter performs either systematic count-based or uniform probabilistic sampling of the message stream.
Definition in file fltmod_plugin.h.
| #define NMSG_FLTMOD_VERSION 1 |
Version number of the nmsg fltmod ABI.
Definition at line 74 of file fltmod_plugin.h.
| #define NMSG_FLTMOD_REQUIRED_INIT .fltmod_version = NMSG_FLTMOD_VERSION |
Convenience macro.
Definition at line 184 of file fltmod_plugin.h.
| typedef nmsg_res(* nmsg_fltmod_module_init_fp) (const void *param, const size_t len_param, void **mod_data) |
Initialize the filter 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 filtering parameters.
| [in] | param | Module-defined data needed for the initialization of the module. |
| [in] | len_param | Length of 'param'. |
| [out] | mod_data | Module-defined, module-wide state, passed to other module functions that take a 'mod_data' parameter. |
Definition at line 98 of file fltmod_plugin.h.
| typedef void(* nmsg_fltmod_module_fini_fp) (void *mod_data) |
Destroy the filter module.
Any module-wide resources acquired by the module must be released.
| [in] | mod_data | Module-defined, module-wide state. |
Definition at line 110 of file fltmod_plugin.h.
| typedef nmsg_res(* nmsg_fltmod_thread_init_fp) (void *mod_data, void **thr_data) |
Initialize module-defined, thread-wide state.
| [in] | mod_data | Module-defined, module-wide state. |
| [out] | thr_data | Module-defined, thread-wide state. |
Definition at line 127 of file fltmod_plugin.h.
| typedef nmsg_res(* nmsg_fltmod_thread_fini_fp) (void *mod_data, void *thr_data) |
Destroy thread-wide state.
Any thread-wide resources corresponding to the passed in 'thr_data' value that have been acquired by the module must be released.
| [in] | mod_data | Module-defined, module-wide state. |
| [in] | thr_data | Module-defined, thread-wide state. |
Definition at line 146 of file fltmod_plugin.h.
| typedef nmsg_res(* nmsg_fltmod_filter_message_fp) (nmsg_message_t *msg, void *mod_data, void *thr_data, nmsg_filter_message_verdict *vres) |
Filter a message object and return the filter verdict.
The filter function may alter the message object, or it may replace the message object with an entirely new message. If the filter function replaces the message object, it is responsible for disposing of the old message, for instance by calling nmsg_message_destroy().
| [in,out] | msg | Pointer to the message object to be filtered. The message object may optionally be altered, or it may be replaced with an entirely new message object. |
| [in] | mod_data | Module-defined, module-wide state. |
| [in] | thr_data | Module-defined, thread-wide state. |
| [out] | vres | The filter verdict. |
Definition at line 177 of file fltmod_plugin.h.
1.9.8