MySQL 8.0.31
Source Code Documentation
pfs_notification.h
Go to the documentation of this file.
1/* Copyright (c) 2017, 2022, Oracle and/or its affiliates.
2
3This program is free software; you can redistribute it and/or modify
4it under the terms of the GNU General Public License, version 2.0,
5as published by the Free Software Foundation.
6
7This program is also distributed with certain software (including
8but not limited to OpenSSL) that is licensed under separate terms,
9as designated in a particular file or component or in included license
10documentation. The authors of MySQL hereby grant you an additional
11permission to link the program and your derivative works with the
12separately licensed software that they have included with MySQL.
13
14This program is distributed in the hope that it will be useful,
15but WITHOUT ANY WARRANTY; without even the implied warranty of
16MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17GNU General Public License, version 2.0, for more details.
18
19You should have received a copy of the GNU General Public License
20along with this program; if not, write to the Free Software
21Foundation, 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
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 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
176BEGIN_SERVICE_DEFINITION(pfs_notification_v3)
177register_notification_v3_t register_notification;
178unregister_notification_v1_t unregister_notification;
179END_SERVICE_DEFINITION(pfs_notification_v3)
180
181#define REQUIRES_PFS_NOTIFICATION_SERVICE REQUIRES_SERVICE(pfs_notification_v3)
182
183#endif
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:562
int(* unregister_notification_v1_t)(int handle)
Unregister callback functions for the Notification service.
Definition: psi_thread_bits.h:572
Instrumentation helpers for mysys threads.
#define END_SERVICE_DEFINITION(name)
A macro to end the last Service definition started with the BEGIN_SERVICE_DEFINITION macro.
Definition: service.h:90
#define BEGIN_SERVICE_DEFINITION(name)
Declares a new Service.
Definition: service.h:85