Notification service

Introduction

The Performance Schema Notification service provides a means to register user-defined callback functions for the following thread and session events:

• thread create
• thread destroy
• session connect
• session disconnect
• session change user

This is a synchronous, low-level API designed to impose minimal performance overhead.

Callback Function Definition

Callback functions are of the type PSI_notification_cb:

typedef void (*PSI_notification_cb)(const PSI_thread_attrs *thread_attrs);

For example:

void callback_thread_create(const PSI_thread_attrs *thread_attrs)
{
  set_thread_resource_group(...)
}

When the callback is invoked, the PSI_thread_attrs structure will contain the system attributes of the thread.

Registering Events

To register for one or more events, set the corresponding callback function pointers in the PSI_notification structure, leaving the function pointer NULL for unused callbacks.

Use the service function register_notification() to register the callbacks with the server

int register_notification(PSI_notification *callbacks,
                          bool with_ref_count);

where

• callbacks is the callback function set
• with_ref_count determines whether a reference count is used for the callbacks. Set TRUE for callback functions in dynamically loaded modules. Set FALSE for callback functions in static or unloadable modules.

For example:

PSI_notification my_callbacks;
 
my_callbacks.thread_create   = &thread_create_callback;
my_callbacks.thread_destroy  = &thread_destroy_callback;
my_callbacks.session_connect = &session_connect_callback;
my_callbacks.session_disconnect  = &session_disconnect_callback;
my_callbacks.session_change_user = nullptr;
 
int my_handle =
 mysql_service_pfs_notification->register_notification(&my_callbacks, true);

A non-zero handle is returned if the registration is successful. This handle is used to unregister the callback set.

A callback set can be registered more than once. No error is returned for calling register_notification() more than once for a given callback set. Callbacks are invoked once for each time they are registered.

For callback functions that reside in dynamically loaded modules, set

with_ref_count = TRUE 

so that the module can be safely unloaded after the callbacks are unregistered.

For callback functions that reside in static, built-in or otherwise unloadable modules, set

with_ref_count = FALSE 

to optimize callback performance in high-concurrency environments.

Callbacks that reside in a dynamically loaded module such as a server plugin, must be successfully unregistered before the module is unloaded.

For callbacks in static or unloadable modules, unregister_notification() will disable the callback functions, but the function pointers will remain.

Unregistering Events

To unregister callback functions from the Notification service, use the handle returned from register_notification(). For example:

  int ret =
mysql_service_pfs_notification->unregister_notification(my_handle);
 
  if (ret == 0)
  {
    // unload component
  }
  else
  {
    // error
  }

Callbacks that reside in a dynamically loaded module such as a server plugin or component must be successfully unregistered before the module is unloaded.

If unregister_notification() returns an error, then the module should not be unloaded.

If the callbacks were registered with

with_ref_count = TRUE

then unregister_notification() will return an error if any of the functions are in use and fail to return after 2 seconds.

If the callbacks were registered with

with_ref_count = FALSE

then unregister_notification() will disable the callback functions, but the callback function pointers will be assumed to be valid until the server is shutdown.

unregister_callback() can be called multiple times for the same handle.

Failing to unregister all callback functions from a dynamically loaded plugin or component may result in a undocumented behavior during server shutdown.