pfs_notification.h

Go to the documentation of this file.

/* Copyright (c) 2017, 2025, Oracle and/or its affiliates.
 
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License, version 2.0,
as published by the Free Software Foundation.
 
This program is designed to work with certain software (including
but not limited to OpenSSL) that is licensed under separate terms,
as designated in a particular file or component or in included license
documentation.  The authors of MySQL hereby grant you an additional
permission to link the program and your derivative works with the
separately licensed software that they have either included with
the program or referenced in the documentation.
 
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License, version 2.0, for more details.
 
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA */
 
#ifndef PFS_NOTIFY_SERVICE_H
#define PFS_NOTIFY_SERVICE_H
 
#include <mysql/components/service.h>
#include <mysql/psi/mysql_thread.h>
 
/**
  @page PAGE_PFS_NOTIFICATION_SERVICE Notification service
 
  @section PFS_NOTIFICATION_INTRO 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.
 
  @section PFS_NOTIFICATION_CALLBACKS Callback Function Definition
 
  Callback functions are of the type #PSI_notification_cb:
 
  @code
    typedef void (*PSI_notification_cb)(const PSI_thread_attrs *thread_attrs);
  @endcode
 
  For example:
  @code
    void callback_thread_create(const PSI_thread_attrs *thread_attrs)
    {
      set_thread_resource_group(...)
    }
  @endcode
 
  When the callback is invoked, the #PSI_thread_attrs structure will contain the
  system attributes of the thread.
 
  @section PFS_NOTIFICATION_REGISTER 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 @c register_notification() to register the callbacks
  with the server
 
  @code
    int register_notification(PSI_notification *callbacks,
                              bool with_ref_count);
  @endcode
 
  where
  - @c callbacks is the callback function set
  - @c 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:
  @code
    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);
  @endcode
 
  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 @c 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
  @verbatim with_ref_count = TRUE @endverbatim 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 @verbatim with_ref_count = FALSE @endverbatim 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, @c unregister_notification()
  will disable the callback functions, but the function pointers will remain.
 
  @section PFS_NOTIFICATION_UNREGISTER Unregistering Events
 
  To unregister callback functions from the Notification service, use the handle
  returned from @c register_notification(). For example:
 
  @code
    int ret =
  mysql_service_pfs_notification->unregister_notification(my_handle);
 
    if (ret == 0)
    {
      // unload component
    }
    else
    {
      // error
    }
  @endcode
 
  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 @c unregister_notification() returns an error, then the module should not
  be unloaded.
 
  If the callbacks were registered with @verbatim with_ref_count = TRUE
  @endverbatim then
  @c 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 @verbatim with_ref_count = FALSE
  @endverbatim then
  @c unregister_notification() will disable the callback functions, but the
  callback function pointers will be assumed to be valid until the server is
  shutdown.
 
  @c 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.
 
*/
 
/*
  SERVICE_DEFINITION(pfs_notification)
  Introduced in MySQL 8.0.2
  Removed in MySQL 8.0.17
  Status: Removed, use version 3 instead.
*/
 
/*
  Version 3.
  Introduced in MySQL 8.0.17
  Status: active
*/
 
BEGIN_SERVICE_DEFINITION(pfs_notification_v3)
register_notification_v3_t register_notification;
unregister_notification_v1_t unregister_notification;
END_SERVICE_DEFINITION(pfs_notification_v3)
 
#define REQUIRES_PFS_NOTIFICATION_SERVICE REQUIRES_SERVICE(pfs_notification_v3)
 
#endif