MySQL  8.0.20
Source Code Documentation
psi_thread_bits.h
Go to the documentation of this file.
1 /* Copyright (c) 2008, 2020, 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 COMPONENTS_SERVICES_PSI_THREAD_BITS_H
24 #define COMPONENTS_SERVICES_PSI_THREAD_BITS_H
25 
26 #ifndef MYSQL_ABI_CHECK
27 #include <stddef.h> /* size_t */
28 #endif
29 
30 #include <mysql/components/services/my_io_bits.h> /* sockaddr_storage */
31 #include <mysql/components/services/my_thread_bits.h> /* my_thread_handle */
32 
33 /**
34  @file
35  Performance schema instrumentation interface.
36 
37  @defgroup psi_abi_thread Thread Instrumentation (ABI)
38  @ingroup psi_abi
39  @{
40 */
41 
42 /**
43  Instrumented thread key.
44  To instrument a thread, a thread key must be obtained
45  using @c register_thread.
46  Using a zero key always disable the instrumentation.
47 */
48 typedef unsigned int PSI_thread_key;
49 
50 #ifdef __cplusplus
51 class THD;
52 #else
53 /*
54  Phony declaration when compiling C code.
55  This is ok, because the C code will never have a THD anyway.
56 */
57 struct opaque_THD {
58  int dummy;
59 };
60 typedef struct opaque_THD THD;
61 #endif
62 
63 /** @sa enum_vio_type. */
64 typedef int opaque_vio_type;
65 
66 /**
67  Interface for an instrumented thread.
68  This is an opaque structure.
69 */
70 struct PSI_thread;
71 typedef struct PSI_thread PSI_thread;
72 
73 /**
74  Thread instrument information.
75  @since PSI_THREAD_VERSION_1
76  This structure is used to register an instrumented thread.
77 */
79  /**
80  Pointer to the key assigned to the registered thread.
81  */
83  /**
84  The name of the thread instrument to register.
85  */
86  const char *m_name;
87  /**
88  The flags of the thread to register.
89  @sa PSI_FLAG_SINGLETON
90  @sa PSI_FLAG_USER
91  */
92  unsigned int m_flags;
93  /** Volatility index. */
95  /** Documentation. */
96  const char *m_documentation;
97 };
99 
100 /**
101  Thread registration API.
102  @param category a category name (typically a plugin name)
103  @param info an array of thread info to register
104  @param count the size of the info array
105 */
106 typedef void (*register_thread_v1_t)(const char *category,
107  struct PSI_thread_info_v1 *info,
108  int count);
109 
110 /**
111  Spawn a thread.
112  This method creates a new thread, with instrumentation.
113  @param key the instrumentation key for this thread
114  @param thread the resulting thread
115  @param attr the thread attributes
116  @param start_routine the thread start routine
117  @param arg the thread start routine argument
118 */
120  const my_thread_attr_t *attr,
121  void *(*start_routine)(void *), void *arg);
122 
123 /**
124  Create instrumentation for a thread.
125  @param key the registered key
126  @param identity an address typical of the thread
127  @param thread_id PROCESSLIST_ID of the thread
128  @return an instrumented thread
129 */
130 typedef struct PSI_thread *(*new_thread_v1_t)(PSI_thread_key key,
131  const void *identity,
132  unsigned long long thread_id);
133 
134 /**
135  Assign a THD to an instrumented thread.
136  @param thread the instrumented thread
137  @param thd the sql layer THD to assign
138 */
139 typedef void (*set_thread_THD_v1_t)(struct PSI_thread *thread, THD *thd);
140 
141 /**
142  Assign an id to an instrumented thread.
143  @param thread the instrumented thread
144  @param id the PROCESSLIST_ID to assign
145 */
146 typedef void (*set_thread_id_v1_t)(struct PSI_thread *thread,
147  unsigned long long id);
148 /**
149  Read the THREAD_ID of the current thread.
150  @return the id of the instrumented thread
151 */
152 typedef unsigned long long (*get_current_thread_internal_id_v2_t)();
153 
154 /**
155  Read the THREAD_ID of an instrumented thread.
156  @param thread the instrumented thread
157  @return the id of the instrumented thread
158 */
159 typedef unsigned long long (*get_thread_internal_id_v2_t)(
160  struct PSI_thread *thread);
161 
162 /**
163  Get the instrumentation for the thread of given PROCESSLIST_ID.
164  @param processlist_id the thread id
165  @return the instrumented thread
166 */
167 typedef struct PSI_thread *(*get_thread_by_id_v2_t)(
168  unsigned long long processlist_id);
169 
170 /**
171  Assign the current operating system thread id to an instrumented thread.
172  The operating system task id is obtained from @c gettid()
173  @param thread the instrumented thread
174 */
175 typedef void (*set_thread_os_id_v1_t)(struct PSI_thread *thread);
176 
177 /**
178  Get the instrumentation for the running thread.
179  For this function to return a result,
180  the thread instrumentation must have been attached to the
181  running thread using @c set_thread()
182  @return the instrumentation for the running thread
183 */
184 typedef struct PSI_thread *(*get_thread_v1_t)(void);
185 
186 /**
187  Assign a user name to the instrumented thread.
188  @param user the user name
189  @param user_len the user name length
190 */
191 typedef void (*set_thread_user_v1_t)(const char *user, int user_len);
192 
193 /**
194  Assign a user name and host name to the instrumented thread.
195  @param user the user name
196  @param user_len the user name length
197  @param host the host name
198  @param host_len the host name length
199 */
200 typedef void (*set_thread_account_v1_t)(const char *user, int user_len,
201  const char *host, int host_len);
202 
203 /**
204  Assign a current database to the instrumented thread.
205  @param db the database name
206  @param db_len the database name length
207 */
208 typedef void (*set_thread_db_v1_t)(const char *db, int db_len);
209 
210 /**
211  Assign a current command to the instrumented thread.
212  @param command the current command
213 */
214 typedef void (*set_thread_command_v1_t)(int command);
215 
216 /**
217  Assign a connection type to the instrumented thread.
218  @param conn_type the connection type
219 */
220 typedef void (*set_connection_type_v1_t)(opaque_vio_type conn_type);
221 
222 /**
223  Assign a start time to the instrumented thread.
224  @param start_time the thread start time
225 */
226 typedef void (*set_thread_start_time_v1_t)(time_t start_time);
227 
228 /**
229  Assign a state to the instrumented thread.
230  @param state the thread state
231 */
232 typedef void (*set_thread_state_v1_t)(const char *state);
233 
234 /**
235  Assign a process info to the instrumented thread.
236  @param info the process into string
237  @param info_len the process into string length
238 */
239 typedef void (*set_thread_info_v1_t)(const char *info, unsigned int info_len);
240 
241 /**
242  Assign a resource group name to the current thread.
243 
244  @param group_name resource group name string
245  @param group_name_len resource group name string length
246  @param user_data user-defined data
247  return 0 if successful, 1 otherwise
248 */
249 typedef int (*set_thread_resource_group_v1_t)(const char *group_name,
250  int group_name_len,
251  void *user_data);
252 
253 /**
254  Assign a resource group name to an instrumented thread, identified either by
255  the thread instrumentation or Performance Schema thread id.
256 
257  @param thread pointer to the thread instrumentation. Ignored if NULL.
258  @param thread_id thread id of the target thread. Only used if thread is NULL.
259  @param group_name resource group name string
260  @param group_name_len resource group name string length
261  @param user_data user-defined data
262  return 0 if successful, 1 otherwise
263 */
265  PSI_thread *thread, unsigned long long thread_id, const char *group_name,
266  int group_name_len, void *user_data);
267 
268 /**
269  Attach a thread instrumentation to the running thread.
270  In case of thread pools, this method should be called when
271  a worker thread picks a work item and runs it.
272  Also, this method should be called if the instrumented code does not
273  keep the pointer returned by @c new_thread() and relies on @c get_thread()
274  instead.
275  @param thread the thread instrumentation
276 */
277 typedef void (*set_thread_v1_t)(struct PSI_thread *thread);
278 
279 /** Aggregate the thread status variables. */
280 typedef void (*aggregate_thread_status_v2_t)(struct PSI_thread *thread);
281 
282 /** Delete the current thread instrumentation. */
283 typedef void (*delete_current_thread_v1_t)(void);
284 
285 /** Delete a thread instrumentation. */
286 typedef void (*delete_thread_v1_t)(struct PSI_thread *thread);
287 
288 /**
289  Stores an array of connection attributes
290  @param buffer char array of length encoded connection attributes
291  in network format
292  @param length length of the data in buffer
293  @param from_cs charset in which @c buffer is encoded
294  @return state
295  @retval non_0 attributes truncated
296  @retval 0 stored the attribute
297 */
298 typedef int (*set_thread_connect_attrs_v1_t)(const char *buffer,
299  unsigned int length,
300  const void *from_cs);
301 
302 /**
303  Get the current thread current event.
304  @param [out] thread_internal_id The thread internal id
305  @param [out] event_id The per thread event id.
306 */
308  unsigned long long *thread_internal_id, unsigned long long *event_id);
309 
310 /**
311  Get the thread current event.
312  @deprecated
313  @param [out] thread_internal_id The thread internal id
314  @param [out] event_id The per thread event id.
315 */
316 typedef void (*get_thread_event_id_v1_t)(unsigned long long *thread_internal_id,
317  unsigned long long *event_id);
318 
319 /**
320  Get the thread current event.
321  @param psi the instrumented thread
322  @param [out] thread_internal_id The thread internal id
323  @param [out] event_id The per thread event id.
324 */
325 typedef void (*get_thread_event_id_v2_t)(struct PSI_thread *psi,
326  unsigned long long *thread_internal_id,
327  unsigned long long *event_id);
328 
329 /* Duplicate definitions to avoid dependency on mysql_com.h */
330 #define PSI_USERNAME_LENGTH (32 * 3)
331 #define PSI_NAME_LEN (64 * 3)
332 #define PSI_HOSTNAME_LENGTH (255)
333 
334 /**
335  Performance Schema thread type: user/foreground or system/background.
336  @sa get_thread_system_attrs
337 */
339  /* PFS internal thread id, unique. */
340  unsigned long long m_thread_internal_id;
341 
342  /* SHOW PROCESSLIST thread id, not unique. */
343  unsigned long m_processlist_id;
344 
345  /* Operating system thread id, if any. */
346  unsigned long long m_thread_os_id;
347 
348  /* User-defined data. */
349  void *m_user_data;
350 
351  /* User name. */
352  char m_username[PSI_USERNAME_LENGTH];
353 
354  /* User name length. */
356 
357  /* Host name. */
358  char m_hostname[PSI_HOSTNAME_LENGTH];
359 
360  /* Host name length. */
362 
363  /* Resource group name. */
364  char m_groupname[PSI_NAME_LEN];
365 
366  /* Resource group name length. */
368 
369  /** Raw socket address */
370  struct sockaddr_storage m_sock_addr;
371 
372  /** Length of address */
374 
375  /* True if system/background thread, false if user/foreground thread. */
377 };
378 
380 
381 /**
382  Callback for the pfs_notification service.
383  @param thread_attrs system attributes of the current thread.
384 */
385 typedef void (*PSI_notification_cb_v3)(const PSI_thread_attrs_v3 *thread_attrs);
386 
387 /**
388  Registration structure for the pfs_notification service.
389  @sa register_notification_v3_t
390 */
397 };
398 
400 
401 /**
402  Get system attributes for the current thread.
403 
404  @param thread_attrs pointer to pfs_thread_attr struct
405  @return 0 if successful, 1 otherwise
406 */
407 typedef int (*get_thread_system_attrs_v3_t)(PSI_thread_attrs_v3 *thread_attrs);
408 
409 /**
410  Get system attributes for an instrumented thread, identified either by the
411  thread instrumentation or Performance Schema thread id.
412 
413  @param thread pointer to the thread instrumentation. Ignored if NULL.
414  @param thread_id thread id of the target thread. Only used if thread is NULL.
415  @param thread_attrs pointer to pfs_thread_attr struct
416  @return 0 if successful, 1 otherwise
417 */
419  PSI_thread *thread, unsigned long long thread_id,
420  PSI_thread_attrs_v3 *thread_attrs);
421 
422 /**
423  Register callback functions for the Notification service.
424  For best performance, set with_ref_count = false.
425 
426  @param callbacks structure of user-defined callback functions
427  @param with_ref_count true if callbacks can be unregistered
428  @sa unregister_notification
429  @return registration handle on success, 0 if failure
430 */
432  bool with_ref_count);
433 
434 /**
435  Unregister callback functions for the Notification service.
436 
437  @param handle registration handle returned by register_notification()
438  @sa register_notification
439  @return 0 if successful, non-zero otherwise
440 */
442 
443 /**
444  Invoke the callback function registered for a session connect event.
445 
446  @param thread the thread instrumentation
447 */
448 typedef void (*notify_session_connect_v1_t)(PSI_thread *thread);
449 
450 /**
451  Invoke the callback function registered for a session disconnect event.
452 
453  @param thread the thread instrumentation
454 */
456 
457 /**
458  Invoke the callback function registered for a changer user event.
459 
460  @param thread the thread instrumentation
461 */
463 
465 
466 /** @} (end of group psi_abi_thread) */
467 
468 #endif /* COMPONENTS_SERVICES_PSI_THREAD_BITS_H */
PSI_notification_cb_v3 thread_destroy
Definition: psi_thread_bits.h:393
void(* delete_current_thread_v1_t)(void)
Delete the current thread instrumentation.
Definition: psi_thread_bits.h:283
void(* set_thread_command_v1_t)(int command)
Assign a current command to the instrumented thread.
Definition: psi_thread_bits.h:214
int(* get_thread_system_attrs_by_id_v3_t)(PSI_thread *thread, unsigned long long thread_id, PSI_thread_attrs_v3 *thread_attrs)
Get system attributes for an instrumented thread, identified either by the thread instrumentation or ...
Definition: psi_thread_bits.h:418
void(* set_thread_user_v1_t)(const char *user, int user_len)
Assign a user name to the instrumented thread.
Definition: psi_thread_bits.h:191
void(* register_thread_v1_t)(const char *category, struct PSI_thread_info_v1 *info, int count)
Thread registration API.
Definition: psi_thread_bits.h:106
const char * m_name
The name of the thread instrument to register.
Definition: psi_thread_bits.h:86
char * user
Definition: mysqladmin.cc:59
int(* spawn_thread_v1_t)(PSI_thread_key key, my_thread_handle *thread, const my_thread_attr_t *attr, void *(*start_routine)(void *), void *arg)
Spawn a thread.
Definition: psi_thread_bits.h:119
int opaque_vio_type
Definition: psi_thread_bits.h:51
#define PSI_HOSTNAME_LENGTH
Definition: psi_thread_bits.h:332
ssize_t count
Definition: memcached.c:386
void * handle
Definition: engine_loader.c:19
#define PSI_USERNAME_LENGTH
Definition: psi_thread_bits.h:330
char buffer[STRING_BUFFER]
Definition: test_sql_9_sessions.cc:57
void(* get_thread_event_id_v1_t)(unsigned long long *thread_internal_id, unsigned long long *event_id)
Get the thread current event.
Definition: psi_thread_bits.h:316
void(* aggregate_thread_status_v2_t)(struct PSI_thread *thread)
Aggregate the thread status variables.
Definition: psi_thread_bits.h:280
unsigned long long(* get_current_thread_internal_id_v2_t)()
Read the THREAD_ID of the current thread.
Definition: psi_thread_bits.h:152
int(* set_thread_resource_group_v1_t)(const char *group_name, int group_name_len, void *user_data)
Assign a resource group name to the current thread.
Definition: psi_thread_bits.h:249
unsigned int m_flags
The flags of the thread to register.
Definition: psi_thread_bits.h:92
void * m_user_data
Definition: psi_thread_bits.h:349
int(* unregister_notification_v1_t)(int handle)
Unregister callback functions for the Notification service.
Definition: psi_thread_bits.h:441
#define PSI_NAME_LEN
Definition: psi_thread_bits.h:331
const char * host
Definition: mysqladmin.cc:58
PSI_notification_cb_v3 session_change_user
Definition: psi_thread_bits.h:396
unsigned long id[MAX_DEAD]
Definition: xcom_base.c:426
Types to make different thread packages compatible.
void(* set_thread_info_v1_t)(const char *info, unsigned int info_len)
Assign a process info to the instrumented thread.
Definition: psi_thread_bits.h:239
size_t m_username_length
Definition: psi_thread_bits.h:355
const char * m_documentation
Documentation.
Definition: psi_thread_bits.h:96
unsigned long m_processlist_id
Definition: psi_thread_bits.h:343
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
void(* set_thread_db_v1_t)(const char *db, int db_len)
Assign a current database to the instrumented thread.
Definition: psi_thread_bits.h:208
void(* set_thread_v1_t)(struct PSI_thread *thread)
Attach a thread instrumentation to the running thread.
Definition: psi_thread_bits.h:277
void(* notify_session_change_user_v1_t)(PSI_thread *thread)
Invoke the callback function registered for a changer user event.
Definition: psi_thread_bits.h:462
void(* get_thread_event_id_v2_t)(struct PSI_thread *psi, unsigned long long *thread_internal_id, unsigned long long *event_id)
Get the thread current event.
Definition: psi_thread_bits.h:325
PSI_thread_key * m_key
Pointer to the key assigned to the registered thread.
Definition: psi_thread_bits.h:82
void(* set_thread_os_id_v1_t)(struct PSI_thread *thread)
Assign the current operating system thread id to an instrumented thread.
Definition: psi_thread_bits.h:175
unsigned long long m_thread_os_id
Definition: psi_thread_bits.h:346
socklen_t m_sock_addr_length
Length of address.
Definition: psi_thread_bits.h:373
void(* set_thread_state_v1_t)(const char *state)
Assign a state to the instrumented thread.
Definition: psi_thread_bits.h:232
PSI_notification_cb_v3 thread_create
Definition: psi_thread_bits.h:392
PSI_notification_cb_v3 session_connect
Definition: psi_thread_bits.h:394
void(* PSI_notification_cb_v3)(const PSI_thread_attrs_v3 *thread_attrs)
Callback for the pfs_notification service.
Definition: psi_thread_bits.h:385
int m_volatility
Volatility index.
Definition: psi_thread_bits.h:94
size_t m_hostname_length
Definition: psi_thread_bits.h:361
void(* notify_session_connect_v1_t)(PSI_thread *thread)
Invoke the callback function registered for a session connect event.
Definition: psi_thread_bits.h:448
void(* set_thread_account_v1_t)(const char *user, int user_len, const char *host, int host_len)
Assign a user name and host name to the instrumented thread.
Definition: psi_thread_bits.h:200
PSI_notification_cb_v3 session_disconnect
Definition: psi_thread_bits.h:395
void(* delete_thread_v1_t)(struct PSI_thread *thread)
Delete a thread instrumentation.
Definition: psi_thread_bits.h:286
Definition: my_thread_bits.h:51
void(* get_current_thread_event_id_v2_t)(unsigned long long *thread_internal_id, unsigned long long *event_id)
Get the current thread current event.
Definition: psi_thread_bits.h:307
void(* notify_session_disconnect_v1_t)(PSI_thread *thread)
Invoke the callback function registered for a session disconnect event.
Definition: psi_thread_bits.h:455
void(* set_thread_start_time_v1_t)(time_t start_time)
Assign a start time to the instrumented thread.
Definition: psi_thread_bits.h:226
static const char * key
Definition: suite_stubs.c:14
static const char * category
Definition: sha2_password.cc:167
command
Definition: version_token.cc:278
Performance Schema thread type: user/foreground or system/background.
Definition: psi_thread_bits.h:338
Thread instrument information.
Definition: psi_thread_bits.h:78
unsigned int PSI_thread_key
Instrumented thread key.
Definition: psi_thread_bits.h:48
pthread_attr_t my_thread_attr_t
Definition: my_thread_bits.h:48
int(* get_thread_system_attrs_v3_t)(PSI_thread_attrs_v3 *thread_attrs)
Get system attributes for the current thread.
Definition: psi_thread_bits.h:407
void(* set_connection_type_v1_t)(opaque_vio_type conn_type)
Assign a connection type to the instrumented thread.
Definition: psi_thread_bits.h:220
int(* set_thread_resource_group_by_id_v1_t)(PSI_thread *thread, unsigned long long thread_id, const char *group_name, int group_name_len, void *user_data)
Assign a resource group name to an instrumented thread, identified either by the thread instrumentati...
Definition: psi_thread_bits.h:264
void(* set_thread_id_v1_t)(struct PSI_thread *thread, unsigned long long id)
Assign an id to an instrumented thread.
Definition: psi_thread_bits.h:146
unsigned long long m_thread_internal_id
Definition: psi_thread_bits.h:340
Types to make file and socket I/O compatible.
std::decay_t< T > identity
Definition: string_view.h:176
Log info(cout, "NOTE")
Registration structure for the pfs_notification service.
Definition: psi_thread_bits.h:391
unsigned long long(* get_thread_internal_id_v2_t)(struct PSI_thread *thread)
Read the THREAD_ID of an instrumented thread.
Definition: psi_thread_bits.h:159
bool m_system_thread
Definition: psi_thread_bits.h:376
static const sasl_callback_t callbacks[]
Definition: auth_ldap_sasl_client.h:44
size_t m_groupname_length
Definition: psi_thread_bits.h:367
void(* set_thread_THD_v1_t)(struct PSI_thread *thread, THD *thd)
Assign a THD to an instrumented thread.
Definition: psi_thread_bits.h:139
struct PSI_thread PSI_thread
Definition: psi_thread_bits.h:71
bool length(const dd::Spatial_reference_system *srs, const Geometry *g1, double *length, bool *null) noexcept
Computes the length of linestrings and multilinestrings.
Definition: length.cc:75
int(* set_thread_connect_attrs_v1_t)(const char *buffer, unsigned int length, const void *from_cs)
Stores an array of connection attributes.
Definition: psi_thread_bits.h:298
static my_thread_id thread_id
Definition: my_thr_init.cc:62
For each client connection we create a separate thread with THD serving as a thread/connection descri...
Definition: sql_class.h:765