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