/src/mysql-server/include/mysql/psi/mysql_thread.h

Source
/* Copyright (c) 2008, 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 MYSQL_THREAD_H
#define MYSQL_THREAD_H

/**
  @file include/mysql/psi/mysql_thread.h
  Instrumentation helpers for mysys threads.
  This header file provides the necessary declarations
  to use the mysys thread API with the performance schema instrumentation.
  In some compilers (SunStudio), 'static inline' functions, when declared
  but not used, are not optimized away (because they are unused) by default,
  so that including a static inline function from a header file does
  create unwanted dependencies, causing unresolved symbols at link time.
  Other compilers, like gcc, optimize these dependencies by default.

  Since the instrumented APIs declared here are wrapper on top
  of my_thread / safemutex / etc APIs,
  including mysql/psi/mysql_thread.h assumes that
  the dependency on my_thread and safemutex already exists.
*/

/* HAVE_PSI_*_INTERFACE */
#include "my_psi_config.h"  // IWYU pragma: keep

#include "my_thread.h"
#include "my_thread_local.h"
#include "mysql/psi/psi_thread.h"

#if defined(MYSQL_SERVER) || defined(PFS_DIRECT_CALL)
/* PSI_THREAD_CALL() as direct call. */
#include "pfs_thread_provider.h"  // IWYU pragma: keep
#endif

#ifndef PSI_THREAD_CALL
#define PSI_THREAD_CALL(M) psi_thread_service->M
#endif

/**
  @defgroup psi_api_thread Thread Instrumentation (API)
  @ingroup psi_api
  @{
*/

/**
  @def mysql_thread_register(P1, P2, P3)
  Thread registration.
*/
#define mysql_thread_register(P1, P2, P3) \
  inline_mysql_thread_register(P1, P2, P3)

/**
  @def mysql_thread_create(K, P1, P2, P3, P4)
  Instrumented my_thread_create.
  This function creates both the thread instrumentation and a thread.
  @c mysql_thread_create is a replacement for @c my_thread_create.
  The parameter P4 (or, if it is NULL, P1) will be used as the
  instrumented thread "identity".
  Providing a P1 / P4 parameter with a different value for each call
  will on average improve performances, since this thread identity value
  is used internally to randomize access to data and prevent contention.
  This is optional, and the improvement is not guaranteed, only statistical.
  @param K The PSI_thread_key for this instrumented thread
  @param P1 my_thread_create parameter 1
  @param P2 my_thread_create parameter 2
  @param P3 my_thread_create parameter 3
  @param P4 my_thread_create parameter 4
*/
#define mysql_thread_create(K, P1, P2, P3, P4) \
  inline_mysql_thread_create(K, 0, P1, P2, P3, P4)

/**
  @def mysql_thread_create_seq(K, S, P1, P2, P3, P4)
  Instrumented my_thread_create.
  @see mysql_thread_create.
  This forms takes an additional sequence number parameter,
  used to name threads "name-N" in the operating system.

  @param K The PSI_thread_key for this instrumented thread
  @param S The sequence number for this instrumented thread
  @param P1 my_thread_create parameter 1
  @param P2 my_thread_create parameter 2
  @param P3 my_thread_create parameter 3
  @param P4 my_thread_create parameter 4
*/
#define mysql_thread_create_seq(K, S, P1, P2, P3, P4) \
  inline_mysql_thread_create(K, S, P1, P2, P3, P4)

/**
  @def mysql_thread_set_psi_id(I)
  Set the thread identifier for the instrumentation.
  @param I The thread identifier
*/
#define mysql_thread_set_psi_id(I) inline_mysql_thread_set_psi_id(I)

/**
  @def mysql_thread_set_psi_THD(T)
  Set the thread sql session for the instrumentation.
  @param T The thread sql session
*/
#define mysql_thread_set_psi_THD(T) inline_mysql_thread_set_psi_THD(T)

static inline void inline_mysql_thread_register(const char *category
                                                [[maybe_unused]],
                                                PSI_thread_info *info
                                                [[maybe_unused]],
                                                int count [[maybe_unused]]) {
#ifdef HAVE_PSI_THREAD_INTERFACE
  PSI_THREAD_CALL(register_thread)(category, info, count);
#endif
}

static inline int inline_mysql_thread_create(
    PSI_thread_key key [[maybe_unused]],
    unsigned int sequence_number [[maybe_unused]], my_thread_handle *thread,
    const my_thread_attr_t *attr, my_start_routine start_routine, void *arg) {
  int result;
#ifdef HAVE_PSI_THREAD_INTERFACE
  result = PSI_THREAD_CALL(spawn_thread)(key, sequence_number, thread, attr,
                                         start_routine, arg);
#else
  result = my_thread_create(thread, attr, start_routine, arg);
#endif
  return result;
}

static inline void inline_mysql_thread_set_psi_id(my_thread_id id
                                                  [[maybe_unused]]) {
#ifdef HAVE_PSI_THREAD_INTERFACE
  struct PSI_thread *psi = PSI_THREAD_CALL(get_thread)();
  PSI_THREAD_CALL(set_thread_id)(psi, id);
#endif
}

#ifdef __cplusplus
class THD;
static inline void inline_mysql_thread_set_psi_THD(THD *thd [[maybe_unused]]) {
#ifdef HAVE_PSI_THREAD_INTERFACE
  struct PSI_thread *psi = PSI_THREAD_CALL(get_thread)();
  PSI_THREAD_CALL(set_thread_THD)(psi, thd);
#endif
}
#endif /* __cplusplus */

/**
  @def mysql_thread_set_peer_port()
  Set the remote (peer) port for the thread instrumentation.
  @param port peer port number
*/
static inline void mysql_thread_set_peer_port(uint port [[maybe_unused]]) {
#ifdef HAVE_PSI_THREAD_INTERFACE
  struct PSI_thread *psi = PSI_THREAD_CALL(get_thread)();
  PSI_THREAD_CALL(set_thread_peer_port)(psi, port);
#endif
}

/**
  @def mysql_thread_set_secondary_engine()
  Set the EXECUTION_ENGINE attribute for the thread instrumentation.
  @param secondary True for SECONDARY, false for PRIMARY.
*/
static inline void mysql_thread_set_secondary_engine(bool secondary
                                                     [[maybe_unused]]) {
#ifdef HAVE_PSI_THREAD_INTERFACE
  PSI_THREAD_CALL(set_thread_secondary_engine)(secondary);
#endif
}

/**
  Set the INFO attribute in the thread instrumentation.
  @param str query string
  @param len query length
*/
static inline void mysql_thread_set_info(const char *str [[maybe_unused]],
                                         int len [[maybe_unused]]) {
#ifdef HAVE_PSI_THREAD_INTERFACE
  PSI_THREAD_CALL(set_thread_info)(str, len);
#endif
}

/** @} (end of group psi_api_thread) */

#endif

Coverage Report

Created: 2025-11-16 07:11

Line	Count	Source
1		/* Copyright (c) 2008, 2025, Oracle and/or its affiliates.
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 designed to work 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 either included with
13		the program or referenced in the documentation.
14
15		This program is distributed in the hope that it will be useful,
16		but WITHOUT ANY WARRANTY; without even the implied warranty of
17		MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18		GNU General Public License, version 2.0, for more details.
19
20		You should have received a copy of the GNU General Public License
21		along with this program; if not, write to the Free Software
22		Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
23
24		#ifndef MYSQL_THREAD_H
25		#define MYSQL_THREAD_H
26
27		/**
28		@file include/mysql/psi/mysql_thread.h
29		Instrumentation helpers for mysys threads.
30		This header file provides the necessary declarations
31		to use the mysys thread API with the performance schema instrumentation.
32		In some compilers (SunStudio), 'static inline' functions, when declared
33		but not used, are not optimized away (because they are unused) by default,
34		so that including a static inline function from a header file does
35		create unwanted dependencies, causing unresolved symbols at link time.
36		Other compilers, like gcc, optimize these dependencies by default.
37
38		Since the instrumented APIs declared here are wrapper on top
39		of my_thread / safemutex / etc APIs,
40		including mysql/psi/mysql_thread.h assumes that
41		the dependency on my_thread and safemutex already exists.
42		*/
43
44		/* HAVE_PSI__INTERFACE /
45		#include "my_psi_config.h" // IWYU pragma: keep
46
47		#include "my_thread.h"
48		#include "my_thread_local.h"
49		#include "mysql/psi/psi_thread.h"
50
51		#if defined(MYSQL_SERVER) \|\| defined(PFS_DIRECT_CALL)
52		/* PSI_THREAD_CALL() as direct call. */
53		#include "pfs_thread_provider.h" // IWYU pragma: keep
54		#endif
55
56		#ifndef PSI_THREAD_CALL
57	0	#define PSI_THREAD_CALL(M) psi_thread_service->M
58		#endif
59
60		/**
61		@defgroup psi_api_thread Thread Instrumentation (API)
62		@ingroup psi_api
63		@{
64		*/
65
66		/**
67		@def mysql_thread_register(P1, P2, P3)
68		Thread registration.
69		*/
70		#define mysql_thread_register(P1, P2, P3) \
71	0	inline_mysql_thread_register(P1, P2, P3)
72
73		/**
74		@def mysql_thread_create(K, P1, P2, P3, P4)
75		Instrumented my_thread_create.
76		This function creates both the thread instrumentation and a thread.
77		@c mysql_thread_create is a replacement for @c my_thread_create.
78		The parameter P4 (or, if it is NULL, P1) will be used as the
79		instrumented thread "identity".
80		Providing a P1 / P4 parameter with a different value for each call
81		will on average improve performances, since this thread identity value
82		is used internally to randomize access to data and prevent contention.
83		This is optional, and the improvement is not guaranteed, only statistical.
84		@param K The PSI_thread_key for this instrumented thread
85		@param P1 my_thread_create parameter 1
86		@param P2 my_thread_create parameter 2
87		@param P3 my_thread_create parameter 3
88		@param P4 my_thread_create parameter 4
89		*/
90		#define mysql_thread_create(K, P1, P2, P3, P4) \
91		inline_mysql_thread_create(K, 0, P1, P2, P3, P4)
92
93		/**
94		@def mysql_thread_create_seq(K, S, P1, P2, P3, P4)
95		Instrumented my_thread_create.
96		@see mysql_thread_create.
97		This forms takes an additional sequence number parameter,
98		used to name threads "name-N" in the operating system.
99
100		@param K The PSI_thread_key for this instrumented thread
101		@param S The sequence number for this instrumented thread
102		@param P1 my_thread_create parameter 1
103		@param P2 my_thread_create parameter 2
104		@param P3 my_thread_create parameter 3
105		@param P4 my_thread_create parameter 4
106		*/
107		#define mysql_thread_create_seq(K, S, P1, P2, P3, P4) \
108		inline_mysql_thread_create(K, S, P1, P2, P3, P4)
109
110		/**
111		@def mysql_thread_set_psi_id(I)
112		Set the thread identifier for the instrumentation.
113		@param I The thread identifier
114		*/
115		#define mysql_thread_set_psi_id(I) inline_mysql_thread_set_psi_id(I)
116
117		/**
118		@def mysql_thread_set_psi_THD(T)
119		Set the thread sql session for the instrumentation.
120		@param T The thread sql session
121		*/
122		#define mysql_thread_set_psi_THD(T) inline_mysql_thread_set_psi_THD(T)
123
124		static inline void inline_mysql_thread_register(const char *category
125		[[maybe_unused]],
126		PSI_thread_info *info
127		[[maybe_unused]],
128	0	int count [[maybe_unused]]) {
129	0	#ifdef HAVE_PSI_THREAD_INTERFACE
130	0	PSI_THREAD_CALL(register_thread)(category, info, count);
131	0	#endif
132	0	} Unexecuted instantiation: my_init.cc:inline_mysql_thread_register(char const, PSI_thread_info_v5, int) Unexecuted instantiation: my_thr_init.cc:inline_mysql_thread_register(char const, PSI_thread_info_v5, int)
133
134		static inline int inline_mysql_thread_create(
135		PSI_thread_key key [[maybe_unused]],
136		unsigned int sequence_number [[maybe_unused]], my_thread_handle *thread,
137	0	const my_thread_attr_t attr, my_start_routine start_routine, void arg) {
138	0	int result;
139	0	#ifdef HAVE_PSI_THREAD_INTERFACE
140	0	result = PSI_THREAD_CALL(spawn_thread)(key, sequence_number, thread, attr,
141	0	start_routine, arg);
142	0	#else
143	0	result = my_thread_create(thread, attr, start_routine, arg);
144	0	#endif
145	0	return result;
146	0	} Unexecuted instantiation: my_init.cc:inline_mysql_thread_create(unsigned int, unsigned int, my_thread_handle, pthread_attr_t const, void* ()(void), void) Unexecuted instantiation: my_thr_init.cc:inline_mysql_thread_create(unsigned int, unsigned int, my_thread_handle, pthread_attr_t const, void ()(void), void*)
147
148		static inline void inline_mysql_thread_set_psi_id(my_thread_id id
149	0	[[maybe_unused]]) {
150	0	#ifdef HAVE_PSI_THREAD_INTERFACE
151	0	struct PSI_thread *psi = PSI_THREAD_CALL(get_thread)();
152	0	PSI_THREAD_CALL(set_thread_id)(psi, id);
153	0	#endif
154	0	} Unexecuted instantiation: my_init.cc:inline_mysql_thread_set_psi_id(unsigned int) Unexecuted instantiation: my_thr_init.cc:inline_mysql_thread_set_psi_id(unsigned int)
155
156		#ifdef __cplusplus
157		class THD;
158	0	static inline void inline_mysql_thread_set_psi_THD(THD *thd [[maybe_unused]]) {
159	0	#ifdef HAVE_PSI_THREAD_INTERFACE
160	0	struct PSI_thread *psi = PSI_THREAD_CALL(get_thread)();
161	0	PSI_THREAD_CALL(set_thread_THD)(psi, thd);
162	0	#endif
163	0	} Unexecuted instantiation: my_init.cc:inline_mysql_thread_set_psi_THD(THD) Unexecuted instantiation: my_thr_init.cc:inline_mysql_thread_set_psi_THD(THD)
164		#endif /* __cplusplus */
165
166		/**
167		@def mysql_thread_set_peer_port()
168		Set the remote (peer) port for the thread instrumentation.
169		@param port peer port number
170		*/
171	0	static inline void mysql_thread_set_peer_port(uint port [[maybe_unused]]) {
172	0	#ifdef HAVE_PSI_THREAD_INTERFACE
173	0	struct PSI_thread *psi = PSI_THREAD_CALL(get_thread)();
174	0	PSI_THREAD_CALL(set_thread_peer_port)(psi, port);
175	0	#endif
176	0	} Unexecuted instantiation: my_init.cc:mysql_thread_set_peer_port(unsigned int) Unexecuted instantiation: my_thr_init.cc:mysql_thread_set_peer_port(unsigned int)
177
178		/**
179		@def mysql_thread_set_secondary_engine()
180		Set the EXECUTION_ENGINE attribute for the thread instrumentation.
181		@param secondary True for SECONDARY, false for PRIMARY.
182		*/
183		static inline void mysql_thread_set_secondary_engine(bool secondary
184	0	[[maybe_unused]]) {
185	0	#ifdef HAVE_PSI_THREAD_INTERFACE
186	0	PSI_THREAD_CALL(set_thread_secondary_engine)(secondary);
187	0	#endif
188	0	} Unexecuted instantiation: my_init.cc:mysql_thread_set_secondary_engine(bool) Unexecuted instantiation: my_thr_init.cc:mysql_thread_set_secondary_engine(bool)
189
190		/**
191		Set the INFO attribute in the thread instrumentation.
192		@param str query string
193		@param len query length
194		*/
195		static inline void mysql_thread_set_info(const char *str [[maybe_unused]],
196	0	int len [[maybe_unused]]) {
197	0	#ifdef HAVE_PSI_THREAD_INTERFACE
198	0	PSI_THREAD_CALL(set_thread_info)(str, len);
199	0	#endif
200	0	} Unexecuted instantiation: my_init.cc:mysql_thread_set_info(char const, int) Unexecuted instantiation: my_thr_init.cc:mysql_thread_set_info(char const, int)
201
202		/** @} (end of group psi_api_thread) */
203
204		#endif