MySQL 9.0.0
Source Code Documentation
psi_rwlock_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_RWLOCK_BITS_H
25#define COMPONENTS_SERVICES_BITS_PSI_RWLOCK_BITS_H
26
28
29/**
30 @file mysql/components/services/bits/psi_rwlock_bits.h
31 Performance schema instrumentation interface.
32
33 @defgroup psi_abi_rwlock Rwlock Instrumentation (ABI)
34 @ingroup psi_abi
35 @{
36*/
37
38/**
39 Instrumented rwlock key.
40 To instrument a rwlock, a rwlock key must be obtained
41 using @c register_rwlock.
42 Using a zero key always disable the instrumentation.
43*/
44typedef unsigned int PSI_rwlock_key;
45
46/**
47 @def PSI_RWLOCK_VERSION_1
48 Performance Schema Rwlock Interface number for version 1.
49 This version is obsolete.
50*/
51#define PSI_RWLOCK_VERSION_1 1
52
53/**
54 @def PSI_RWLOCK_VERSION_2
55 Performance Schema Rwlock Interface number for version 2.
56 This version is supported.
57*/
58#define PSI_RWLOCK_VERSION_2 2
59
60/**
61 @def PSI_CURRENT_RWLOCK_VERSION
62 Performance Schema Rwlock Interface number for the most recent version.
63 The most current version is @c PSI_RWLOCK_VERSION_2
64*/
65#define PSI_CURRENT_RWLOCK_VERSION 2
66
67/**
68 Interface for an instrumented rwlock.
69 This is an opaque structure.
70*/
72typedef struct PSI_rwlock PSI_rwlock;
73
74/**
75 Interface for an instrumented rwlock operation.
76 This is an opaque structure.
77*/
80
81#if 0
82/*
83 Keeping the original version 1 definition in the source,
84 in case we ever need to provide support for version 1.
85*/
86
87/**
88 Operation performed on an instrumented rwlock.
89 For basic READ / WRITE lock,
90 operations are "READ" or "WRITE".
91 For SX-locks, operations are "SHARED", "SHARED-EXCLUSIVE" or "EXCLUSIVE".
92*/
94 /** Read lock. */
96 /** Write lock. */
98 /** Read lock attempt. */
100 /** Write lock attempt. */
102
103 /** Shared lock. */
105 /** Shared Exclusive lock. */
107 /** Exclusive lock. */
109 /** Shared lock attempt. */
111 /** Shared Exclusive lock attempt. */
113 /** Exclusive lock attempt. */
115};
116#endif
117
118/**
119 Operation performed on an instrumented rwlock.
120 For basic READ / WRITE lock,
121 operations are "READ" or "WRITE".
122 For SX-locks, operations are "SHARED", "SHARED-EXCLUSIVE" or "EXCLUSIVE".
123*/
125 /** Read lock. */
127 /** Write lock. */
129 /** Read lock attempt. */
131 /** Write lock attempt. */
133 /** Unlock (Read or Write). */
135
136 /** Shared lock. */
138 /** Shared Exclusive lock. */
140 /** Exclusive lock. */
142 /** Shared lock attempt. */
144 /** Shared Exclusive lock attempt. */
146 /** Exclusive lock attempt. */
148 /** Unlock a shared lock. */
150 /** Unlock a shared exclusive lock. */
152 /** Unlock an exclusive lock. */
156
157/**
158 Rwlock information.
159 @since PSI_RWLOCK_VERSION_1
160 This structure is used to register an instrumented rwlock.
161*/
163 /**
164 Pointer to the key assigned to the registered rwlock.
165 */
167 /**
168 The name of the rwlock to register.
169 */
170 const char *m_name;
171 /**
172 The flags of the rwlock to register.
173 @sa PSI_FLAG_SINGLETON
174 */
175 unsigned int m_flags;
176 /** Volatility index. */
178 /** Documentation. */
179 const char *m_documentation;
180};
182
183/**
184 State data storage for @c start_rwlock_rdwait_v1_t, @c
185 start_rwlock_wrwait_v1_t.
186 This structure provide temporary storage to a rwlock locker.
187 The content of this structure is considered opaque,
188 the fields are only hints of what an implementation
189 of the psi interface can use.
190 This memory is provided by the instrumented code for performance reasons.
191 @sa start_rwlock_rdwait_v1_t
192 @sa start_rwlock_wrwait_v1_t
193*/
195 /** Internal state. */
196 unsigned int m_flags;
197 /** Current operation. */
199 /** Current rwlock. */
201 /** Current thread. */
203 /** Timer start. */
204 unsigned long long m_timer_start{0};
205 /** Timer function. */
206 unsigned long long (*m_timer)(void);
207 /** Internal data. */
208 void *m_wait{nullptr};
209};
211
212/**
213 Rwlock registration API.
214 @param category a category name (typically a plugin name)
215 @param info an array of rwlock info to register
216 @param count the size of the info array
217*/
218typedef void (*register_rwlock_v1_t)(const char *category,
219 struct PSI_rwlock_info_v1 *info,
220 int count);
221
222/**
223 Rwlock instrumentation initialization API.
224 @param key the registered rwlock key
225 @param identity the address of the rwlock itself
226 @return an instrumented rwlock
227*/
228typedef struct PSI_rwlock *(*init_rwlock_v1_t)(PSI_rwlock_key key,
229 const void *identity);
230
231/**
232 Rwlock instrumentation destruction API.
233 @param rwlock the rwlock to destroy
234*/
235typedef void (*destroy_rwlock_v1_t)(struct PSI_rwlock *rwlock);
236
237/**
238 Record a rwlock instrumentation read wait start event.
239 @param state data storage for the locker
240 @param rwlock the instrumented rwlock to lock
241 @param op the operation to perform
242 @param src_file the source file name
243 @param src_line the source line number
244 @return a rwlock locker, or NULL
245*/
246typedef struct PSI_rwlock_locker *(*start_rwlock_rdwait_v1_t)(
247 struct PSI_rwlock_locker_state_v1 *state, struct PSI_rwlock *rwlock,
248 enum PSI_rwlock_operation op, const char *src_file, unsigned int src_line);
249
250/**
251 Record a rwlock instrumentation read wait end event.
252 @param locker a thread locker for the running thread
253 @param rc 0 if the lock was acquired, 1 if it was not
254*/
255typedef void (*end_rwlock_rdwait_v1_t)(struct PSI_rwlock_locker *locker,
256 int rc);
257
258/**
259 Record a rwlock instrumentation write wait start event.
260 @param state data storage for the locker
261 @param rwlock the instrumented rwlock to lock
262 @param op the operation to perform
263 @param src_file the source file name
264 @param src_line the source line number
265 @return a rwlock locker, or NULL
266*/
267typedef struct PSI_rwlock_locker *(*start_rwlock_wrwait_v1_t)(
268 struct PSI_rwlock_locker_state_v1 *state, struct PSI_rwlock *rwlock,
269 enum PSI_rwlock_operation op, const char *src_file, unsigned int src_line);
270
271/**
272 Record a rwlock instrumentation write wait end event.
273 @param locker a thread locker for the running thread
274 @param rc 0 if the lock was acquired, 1 if it was not
275*/
276typedef void (*end_rwlock_wrwait_v1_t)(struct PSI_rwlock_locker *locker,
277 int rc);
278
279/**
280 Record a rwlock instrumentation unlock event.
281 @param rwlock the rwlock instrumentation
282*/
283typedef void (*unlock_rwlock_v1_t)(struct PSI_rwlock *rwlock);
284
285/**
286 Record a rwlock instrumentation unlock event.
287 @param rwlock the rwlock instrumentation
288 @param op the unlock operation performed
289*/
290typedef void (*unlock_rwlock_v2_t)(struct PSI_rwlock *rwlock,
291 enum PSI_rwlock_operation op);
292
295
296/** @} (end of group psi_abi_rwlock) */
297
298#endif /* COMPONENTS_SERVICES_BITS_PSI_RWLOCK_BITS_H */
void(* unlock_rwlock_v1_t)(struct PSI_rwlock *rwlock)
Record a rwlock instrumentation unlock event.
Definition: psi_rwlock_bits.h:283
void(* end_rwlock_rdwait_v1_t)(struct PSI_rwlock_locker *locker, int rc)
Record a rwlock instrumentation read wait end event.
Definition: psi_rwlock_bits.h:255
unsigned int PSI_rwlock_key
Instrumented rwlock key.
Definition: psi_rwlock_bits.h:44
struct PSI_rwlock_locker PSI_rwlock_locker
Definition: psi_rwlock_bits.h:79
PSI_rwlock_operation
Operation performed on an instrumented rwlock.
Definition: psi_rwlock_bits.h:124
void(* destroy_rwlock_v1_t)(struct PSI_rwlock *rwlock)
Rwlock instrumentation destruction API.
Definition: psi_rwlock_bits.h:235
void(* end_rwlock_wrwait_v1_t)(struct PSI_rwlock_locker *locker, int rc)
Record a rwlock instrumentation write wait end event.
Definition: psi_rwlock_bits.h:276
void(* register_rwlock_v1_t)(const char *category, struct PSI_rwlock_info_v1 *info, int count)
Rwlock registration API.
Definition: psi_rwlock_bits.h:218
void(* unlock_rwlock_v2_t)(struct PSI_rwlock *rwlock, enum PSI_rwlock_operation op)
Record a rwlock instrumentation unlock event.
Definition: psi_rwlock_bits.h:290
@ PSI_RWLOCK_TRYWRITELOCK
Write lock attempt.
Definition: psi_rwlock_bits.h:132
@ PSI_RWLOCK_SHAREDEXCLUSIVEUNLOCK
Unlock a shared exclusive lock.
Definition: psi_rwlock_bits.h:151
@ PSI_RWLOCK_WRITELOCK
Write lock.
Definition: psi_rwlock_bits.h:128
@ PSI_RWLOCK_UNLOCK
Unlock (Read or Write).
Definition: psi_rwlock_bits.h:134
@ PSI_RWLOCK_SHAREDUNLOCK
Unlock a shared lock.
Definition: psi_rwlock_bits.h:149
@ PSI_RWLOCK_SHAREDLOCK
Shared lock.
Definition: psi_rwlock_bits.h:137
@ PSI_RWLOCK_SHAREDEXCLUSIVELOCK
Shared Exclusive lock.
Definition: psi_rwlock_bits.h:139
@ PSI_RWLOCK_EXCLUSIVEUNLOCK
Unlock an exclusive lock.
Definition: psi_rwlock_bits.h:153
@ PSI_RWLOCK_TRYSHAREDEXCLUSIVELOCK
Shared Exclusive lock attempt.
Definition: psi_rwlock_bits.h:145
@ PSI_RWLOCK_TRYSHAREDLOCK
Shared lock attempt.
Definition: psi_rwlock_bits.h:143
@ PSI_RWLOCK_TRYREADLOCK
Read lock attempt.
Definition: psi_rwlock_bits.h:130
@ PSI_RWLOCK_EXCLUSIVELOCK
Exclusive lock.
Definition: psi_rwlock_bits.h:141
@ PSI_RWLOCK_READLOCK
Read lock.
Definition: psi_rwlock_bits.h:126
@ PSI_RWLOCK_TRYEXCLUSIVELOCK
Exclusive lock attempt.
Definition: psi_rwlock_bits.h:147
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
Rwlock information.
Definition: psi_rwlock_bits.h:162
const char * m_name
The name of the rwlock to register.
Definition: psi_rwlock_bits.h:170
PSI_rwlock_key * m_key
Pointer to the key assigned to the registered rwlock.
Definition: psi_rwlock_bits.h:166
int m_volatility
Volatility index.
Definition: psi_rwlock_bits.h:177
unsigned int m_flags
The flags of the rwlock to register.
Definition: psi_rwlock_bits.h:175
const char * m_documentation
Documentation.
Definition: psi_rwlock_bits.h:179
State data storage for start_rwlock_rdwait_v1_t, start_rwlock_wrwait_v1_t.
Definition: psi_rwlock_bits.h:194
struct PSI_rwlock * m_rwlock
Current rwlock.
Definition: psi_rwlock_bits.h:200
enum PSI_rwlock_operation m_operation
Current operation.
Definition: psi_rwlock_bits.h:198
unsigned long long(* m_timer)(void)
Timer function.
Definition: psi_rwlock_bits.h:206
struct PSI_thread * m_thread
Current thread.
Definition: psi_rwlock_bits.h:202
unsigned long long m_timer_start
Timer start.
Definition: psi_rwlock_bits.h:204
void * m_wait
Internal data.
Definition: psi_rwlock_bits.h:208
unsigned int m_flags
Internal state.
Definition: psi_rwlock_bits.h:196
Interface for an instrumented rwlock.
Definition: psi_rwlock_bits.h:71