MySQL 9.0.0
Source Code Documentation
psi_mutex_bits.h
Go to the documentation of this file.
1/* Copyright (c) 2008, 2024, 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 COMPONENTS_SERVICES_BITS_PSI_MUTEX_BITS_H
25#define COMPONENTS_SERVICES_BITS_PSI_MUTEX_BITS_H
26
28
29/**
30 @file mysql/components/services/bits/psi_mutex_bits.h
31 Instrumentation helpers for mutexes.
32 This header file provides the necessary declarations
33 to use the mutex API with the performance schema instrumentation.
34 In some compilers (SunStudio), 'static inline' functions, when declared
35 but not used, are not optimized away (because they are unused) by default,
36 so that including a static inline function from a header file does
37 create unwanted dependencies, causing unresolved symbols at link time.
38 Other compilers, like gcc, optimize these dependencies by default.
39*/
40
41/**
42 @defgroup psi_abi_mutex Mutex Instrumentation (ABI)
43 @ingroup psi_abi
44 @{
45*/
46
47/**
48 Instrumented mutex key.
49 To instrument a mutex, a mutex key must be obtained using @c register_mutex.
50 Using a zero key always disable the instrumentation.
51*/
52typedef unsigned int PSI_mutex_key;
53
54/**
55 @def PSI_MUTEX_VERSION_1
56 Performance Schema Mutex Interface number for version 1.
57 This version is supported.
58*/
59#define PSI_MUTEX_VERSION_1 1
60
61/**
62 @def PSI_CURRENT_MUTEX_VERSION
63 Performance Schema Mutex Interface number for the most recent version.
64 The most current version is @c PSI_MUTEX_VERSION_1
65*/
66#define PSI_CURRENT_MUTEX_VERSION 1
67
68/**
69 Mutex information.
70 @since PSI_MUTEX_VERSION_1
71 This structure is used to register an instrumented mutex.
72*/
74 /**
75 Pointer to the key assigned to the registered mutex.
76 */
78 /**
79 The name of the mutex to register.
80 */
81 const char *m_name;
82 /**
83 The flags of the mutex to register.
84 @sa PSI_FLAG_SINGLETON
85 */
86 unsigned int m_flags;
87 /** Volatility index. */
89 /** Documentation. */
90 const char *m_documentation;
91};
92
93/**
94 Interface for an instrumented mutex.
95 This is an opaque structure.
96*/
97struct PSI_mutex : PSI_instr {};
98typedef struct PSI_mutex PSI_mutex;
99
100/**
101 Interface for an instrumented mutex operation.
102 This is an opaque structure.
103*/
104struct PSI_mutex_locker;
106
107/** Operation performed on an instrumented mutex. */
109 /** Lock. */
111 /** Lock attempt. */
115
116/**
117 State data storage for @c start_mutex_wait_v1_t.
118 This structure provide temporary storage to a mutex locker.
119 The content of this structure is considered opaque,
120 the fields are only hints of what an implementation
121 of the psi interface can use.
122 This memory is provided by the instrumented code for performance reasons.
123 @sa start_mutex_wait_v1_t
124*/
126 /** Internal state. */
127 unsigned int m_flags;
128 /** Current operation. */
130 /** Current mutex. */
132 /** Current thread. */
134 /** Timer start. */
135 unsigned long long m_timer_start{0};
136 /** Timer function. */
137 unsigned long long (*m_timer)(void);
138 /** Internal data. */
139 void *m_wait{nullptr};
140};
142
143/**
144 Mutex registration API.
145 @param category a category name (typically a plugin name)
146 @param info an array of mutex info to register
147 @param count the size of the info array
148*/
149typedef void (*register_mutex_v1_t)(const char *category,
150 struct PSI_mutex_info_v1 *info, int count);
151
152/**
153 Mutex instrumentation initialization API.
154 @param key the registered mutex key
155 @param identity the address of the mutex itself
156 @return an instrumented mutex
157*/
158typedef struct PSI_mutex *(*init_mutex_v1_t)(PSI_mutex_key key,
159 const void *identity);
160
161/**
162 Mutex instrumentation destruction API.
163 @param mutex the mutex to destroy
164*/
165typedef void (*destroy_mutex_v1_t)(struct PSI_mutex *mutex);
166
167/**
168 Record a mutex instrumentation unlock event.
169 @param mutex the mutex instrumentation
170*/
171typedef void (*unlock_mutex_v1_t)(struct PSI_mutex *mutex);
172
173/**
174 Record a mutex instrumentation wait start event.
175 @param state data storage for the locker
176 @param mutex the instrumented mutex to lock
177 @param op the operation to perform
178 @param src_file the source file name
179 @param src_line the source line number
180 @return a mutex locker, or NULL
181*/
182typedef struct PSI_mutex_locker *(*start_mutex_wait_v1_t)(
183 struct PSI_mutex_locker_state_v1 *state, struct PSI_mutex *mutex,
184 enum PSI_mutex_operation op, const char *src_file, unsigned int src_line);
185
186/**
187 Record a mutex instrumentation wait end event.
188 @param locker a thread locker for the running thread
189 @param rc the wait operation return code
190*/
191typedef void (*end_mutex_wait_v1_t)(struct PSI_mutex_locker *locker, int rc);
192
196
197/** @} (end of group psi_abi_mutex) */
198
199#endif /* COMPONENTS_SERVICES_BITS_PSI_MUTEX_BITS_H */
PSI_mutex_operation
Operation performed on an instrumented mutex.
Definition: psi_mutex_bits.h:108
void(* end_mutex_wait_v1_t)(struct PSI_mutex_locker *locker, int rc)
Record a mutex instrumentation wait end event.
Definition: psi_mutex_bits.h:191
struct PSI_mutex_locker PSI_mutex_locker
Definition: psi_mutex_bits.h:105
unsigned int PSI_mutex_key
Instrumented mutex key.
Definition: psi_mutex_bits.h:52
void(* destroy_mutex_v1_t)(struct PSI_mutex *mutex)
Mutex instrumentation destruction API.
Definition: psi_mutex_bits.h:165
void(* register_mutex_v1_t)(const char *category, struct PSI_mutex_info_v1 *info, int count)
Mutex registration API.
Definition: psi_mutex_bits.h:149
void(* unlock_mutex_v1_t)(struct PSI_mutex *mutex)
Record a mutex instrumentation unlock event.
Definition: psi_mutex_bits.h:171
PSI_mutex_info_v1 PSI_mutex_info
Definition: psi_mutex_bits.h:194
@ PSI_MUTEX_TRYLOCK
Lock attempt.
Definition: psi_mutex_bits.h:112
@ PSI_MUTEX_LOCK
Lock.
Definition: psi_mutex_bits.h:110
struct PSI_thread PSI_thread
Definition: psi_thread_bits.h:82
static int count
Definition: myisam_ftdump.cc:45
static const char * category
Definition: sha2_password.cc:170
Performance schema instrumentation interface.
required string key
Definition: replication_asynchronous_connection_failover.proto:60
Instrumented artifact.
Definition: psi_bits.h:177
Mutex information.
Definition: psi_mutex_bits.h:73
unsigned int m_flags
The flags of the mutex to register.
Definition: psi_mutex_bits.h:86
int m_volatility
Volatility index.
Definition: psi_mutex_bits.h:88
const char * m_name
The name of the mutex to register.
Definition: psi_mutex_bits.h:81
const char * m_documentation
Documentation.
Definition: psi_mutex_bits.h:90
PSI_mutex_key * m_key
Pointer to the key assigned to the registered mutex.
Definition: psi_mutex_bits.h:77
State data storage for start_mutex_wait_v1_t.
Definition: psi_mutex_bits.h:125
unsigned int m_flags
Internal state.
Definition: psi_mutex_bits.h:127
enum PSI_mutex_operation m_operation
Current operation.
Definition: psi_mutex_bits.h:129
struct PSI_mutex * m_mutex
Current mutex.
Definition: psi_mutex_bits.h:131
void * m_wait
Internal data.
Definition: psi_mutex_bits.h:139
struct PSI_thread * m_thread
Current thread.
Definition: psi_mutex_bits.h:133
unsigned long long(* m_timer)(void)
Timer function.
Definition: psi_mutex_bits.h:137
unsigned long long m_timer_start
Timer start.
Definition: psi_mutex_bits.h:135
Interface for an instrumented mutex.
Definition: psi_mutex_bits.h:97