MySQL  8.0.27
Source Code Documentation
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);
Performance Schema thread type: user/foreground or system/background.
Definition: psi_thread_bits.h:463

For example:

void callback_thread_create(const PSI_thread_attrs *thread_attrs)
{
}
int set_thread_resource_group(PFS_thread *pfs, const char *group_name, int group_name_len, void *user_data)
Set the resource group name for a given thread.
Definition: pfs.cc:3326

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);
static const sasl_callback_t callbacks[]
Definition: auth_ldap_sasl_client.h:44
Registration structure for the pfs_notification service.
Definition: psi_thread_bits.h:516

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_cb 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);
void thread_create_callback(const PSI_thread_attrs *thread_attrs)
Definition: resource_group_mgr.cc:71
void session_disconnect_callback(const PSI_thread_attrs *)
Definition: resource_group_mgr.cc:86

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.