MySQL  8.0.19
Source Code Documentation
pfs_notification.h
Go to the documentation of this file.
1 /* Copyright (c) 2017, 2019, Oracle and/or its affiliates. All rights reserved.
2 
3 This program is free software; you can redistribute it and/or modify
4 it under the terms of the GNU General Public License, version 2.0,
5 as published by the Free Software Foundation.
6 
7 This program is also distributed with certain software (including
8 but not limited to OpenSSL) that is licensed under separate terms,
9 as designated in a particular file or component or in included license
10 documentation. The authors of MySQL hereby grant you an additional
11 permission to link the program and your derivative works with the
12 separately licensed software that they have included with MySQL.
13 
14 This program is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 GNU General Public License, version 2.0, for more details.
18 
19 You should have received a copy of the GNU General Public License
20 along with this program; if not, write to the Free Software
21 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
22 
23 #ifndef PFS_NOTIFY_SERVICE_H
24 #define PFS_NOTIFY_SERVICE_H
25 
27 #include <mysql/psi/mysql_thread.h>
28 
29 /**
30  @page PAGE_PFS_NOTIFICATION_SERVICE Notification service
31 
32  @section PFS_NOTIFICATION_INTRO Introduction
33  The Performance Schema Notification service provides a means to register
34  user-defined callback functions for the following thread and session events:
35 
36  - thread create
37  - thread destroy
38  - session connect
39  - session disconnect
40  - session change user
41 
42  This is a synchronous, low-level API designed to impose minimal performance
43  overhead.
44 
45  @section PFS_NOTIFICATION_CALLBACKS Callback Function Definition
46 
47  Callback functions are of the type #PSI_notification_cb:
48 
49  @code
50  typedef void (*PSI_notification_cb)(const PSI_thread_attrs *thread_attrs);
51  @endcode
52 
53  For example:
54  @code
55  void callback_thread_create(const PSI_thread_attrs *thread_attrs)
56  {
57  set_thread_resource_group(...)
58  }
59  @endcode
60 
61  When the callback is invoked, the #PSI_thread_attrs structure will contain the
62  system attributes of the thread.
63 
64  @section PFS_NOTIFICATION_REGISTER Registering Events
65 
66  To register for one or more events, set the corresponding callback function
67  pointers in the #PSI_notification structure, leaving the function pointer
68  NULL for unused callbacks.
69 
70  Use the service function @c register_notification() to register the callbacks
71  with the server
72 
73  @code
74  int register_notification(PSI_notification *callbacks,
75  bool with_ref_count);
76  @endcode
77 
78  where
79  - @c callbacks is the callback function set
80  - @c with_ref_count determines whether a reference count is used for the
81  callbacks. Set TRUE for callback functions in
82  dynamically loaded modules. Set FALSE for callback
83  functions in static or unloadable modules.
84 
85  For example:
86  @code
87  PSI_notification_cb my_callbacks;
88 
89  my_callbacks.thread_create = &thread_create_callback;
90  my_callbacks.thread_destroy = &thread_destroy_callback;
91  my_callbacks.session_connect = &session_connect_callback;
92  my_callbacks.session_disconnect = &session_disconnect_callback;
93  my_callbacks.session_change_user = nullptr;
94 
95  int my_handle =
96  mysql_service_pfs_notification->register_notification(&my_callbacks, true);
97  @endcode
98 
99  A non-zero handle is returned if the registration is successful. This handle
100  is used to unregister the callback set.
101 
102  A callback set can be registered more than once. No error is returned
103  for calling @c register_notification() more than once for a given callback
104  set. Callbacks are invoked once for each time they are registered.
105 
106  For callback functions that reside in dynamically loaded modules, set
107  @verbatim with_ref_count = TRUE @endverbatim so that the module can be safely
108  unloaded after the callbacks are unregistered.
109 
110  For callback functions that reside in static, built-in or otherwise unloadable
111  modules, set @verbatim with_ref_count = FALSE @endverbatim to optimize
112  callback performance in high-concurrency environments.
113 
114  Callbacks that reside in a dynamically loaded module such as a server plugin,
115  must be successfully unregistered before the module is unloaded.
116 
117  For callbacks in static or unloadable modules, @c unregister_notification()
118  will disable the callback functions, but the function pointers will remain.
119 
120  @section PFS_NOTIFICATION_UNREGISTER Unregistering Events
121 
122  To unregister callback functions from the Notification service, use the handle
123  returned from @c register_notification(). For example:
124 
125  @code
126  int ret =
127  mysql_service_pfs_notification->unregister_notification(my_handle);
128 
129  if (ret == 0)
130  {
131  // unload component
132  }
133  else
134  {
135  // error
136  }
137  @endcode
138 
139  Callbacks that reside in a dynamically loaded module such as a server plugin
140  or component must be successfully unregistered before the module is unloaded.
141 
142  If @c unregister_notification() returns an error, then the module should not
143  be unloaded.
144 
145  If the callbacks were registered with @verbatim with_ref_count = TRUE
146  @endverbatim then
147  @c unregister_notification() will return an error if any of the functions are
148  in use and fail to return after 2 seconds.
149 
150  If the callbacks were registered with @verbatim with_ref_count = FALSE
151  @endverbatim then
152  @c unregister_notification() will disable the callback functions, but the
153  callback function pointers will be assumed to be valid until the server is
154  shutdown.
155 
156  @c unregister_callback() can be called multiple times for the same handle.
157 
158  Failing to unregister all callback functions from a dynamically loaded plugin
159  or component may result in a undocumented behavior during server shutdown.
160 
161 */
162 
163 /*
164  SERVICE_DEFINITION(pfs_notification)
165  Introduced in MySQL 8.0.2
166  Removed in MySQL 8.0.17
167  Status: Removed, use version 3 instead.
168 */
169 
170 /*
171  Version 3.
172  Introduced in MySQL 8.0.17
173  Status: active
174 */
175 
176 BEGIN_SERVICE_DEFINITION(pfs_notification_v3)
177 register_notification_v3_t register_notification;
178 unregister_notification_v1_t unregister_notification;
179 END_SERVICE_DEFINITION(pfs_notification_v3)
180 
181 #define REQUIRES_PFS_NOTIFICATION_SERVICE REQUIRES_SERVICE(pfs_notification_v3)
182 
183 #endif
END_SERVICE_DEFINITION
#define END_SERVICE_DEFINITION(name)
A macro to end the last Service definition started with the BEGIN_SERVICE_DEFINITION macro.
Definition: service.h:90
BEGIN_SERVICE_DEFINITION
#define BEGIN_SERVICE_DEFINITION(name)
Declares a new Service.
Definition: service.h:85
service.h
register_notification_v3_t
int(* register_notification_v3_t)(const PSI_notification_v3 *callbacks, bool with_ref_count)
Register callback functions for the Notification service.
Definition: psi_thread_bits.h:431
unregister_notification_v1_t
int(* unregister_notification_v1_t)(int handle)
Unregister callback functions for the Notification service.
Definition: psi_thread_bits.h:441
mysql_thread.h