User data t

The user_data_t data structure is used to pass custom information to callback functions, such as read, write, flush, notification, log callbacks. The struct contains a void pointer to the actual data and a function pointer. If the function pointer is not NULL, it will be used to free the user data when the callback is not longer used.

Write plugins which use the `user_data' pointer usually need the same data available to the flush callback. If this is the case, set the free_function to NULL when registering the flush callback and to the real free function when registering the write callback. This way the data isn't freed twice.

Definition of the struct

The structure is defined in src/plugin.h as follows:

 struct user_data_s
 {
   void *data;
   void (*free_func) (void *);
 };
 typedef struct user_data_s user_data_t;

Example

 static int my_config (oconfig_item_t *ci)
 {
   my_config_t *my_cfg;
   …
   /* configure and fill in "my_cfg" */
   …
   if (all_went_well)
   {
     user_data_t ud;

     memset (&ud, 0, sizeof (ud));
     ud.data = (void *) my_cfg;
     ud.free_func = my_config_free;

     plugin_register_complex_read ("my_read",
         /* callback = */ my_read,
         /* interval = */ NULL,
         /* userdata = */ &ud);
   } /* if (all_went_well) */

   return (0);
 } /* int my_config */

This example shows how to pass a pointer my_cfg to the callback function my_read. If the callback is deleted or callback registration is failed, the struct is freed using the my_config_free function.

Example for registering both write and flush

...
        user_data_t user_data;

        memset (&user_data, 0, sizeof (user_data));
        user_data.data = my_config;
        user_data.free_func = NULL;  /* Note this */
        plugin_register_flush ("my_plugin", my_flush, &user_data);

        user_data.free_func = my_config_free;
        plugin_register_write ("my_plugin", my_write, &user_data);
...

This example shows how to use common `user_data' in write and flush callbacks.

For real-world examples take a look at src/mysql.c and src/netapp.c.