MySQL  8.0.27
Source Code Documentation
psi_mutex_bits.h
Go to the documentation of this file.
1 /* Copyright (c) 2008, 2021, 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_PSI_MUTEX_BITS_H
24 #define COMPONENTS_SERVICES_PSI_MUTEX_BITS_H
25 
27 
28 /**
29  @file
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 */
51 typedef 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 */
96 struct PSI_mutex : PSI_instr {};
97 typedef struct PSI_mutex PSI_mutex;
98 
99 /**
100  Interface for an instrumented mutex operation.
101  This is an opaque structure.
102 */
103 struct PSI_mutex_locker;
104 typedef struct PSI_mutex_locker PSI_mutex_locker;
105 
106 /** Operation performed on an instrumented mutex. */
108  /** Lock. */
110  /** Lock attempt. */
112 };
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 */
148 typedef 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 */
157 typedef 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 */
164 typedef 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 */
170 typedef 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 */
181 typedef 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 */
190 typedef void (*end_mutex_wait_v1_t)(struct PSI_mutex_locker *locker, int rc);
191 
192 typedef struct PSI_mutex_info_v1 PSI_mutex_info_v1;
195 
196 /** @} (end of group psi_abi_mutex) */
197 
198 #endif /* COMPONENTS_SERVICES_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:161
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