MySQL 8.3.0
Source Code Documentation
sync0policy.h
Go to the documentation of this file.
1/*****************************************************************************
2
3Copyright (c) 2012, 2023, Oracle and/or its affiliates.
4
5This program is free software; you can redistribute it and/or modify it under
6the terms of the GNU General Public License, version 2.0, as published by the
7Free Software Foundation.
8
9This program is also distributed with certain software (including but not
10limited to OpenSSL) that is licensed under separate terms, as designated in a
11particular file or component or in included license documentation. The authors
12of MySQL hereby grant you an additional permission to link the program and
13your derivative works with the separately licensed software that they have
14included with MySQL.
15
16This program is distributed in the hope that it will be useful, but WITHOUT
17ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
18FOR A PARTICULAR PURPOSE. See the GNU General Public License, version 2.0,
19for more details.
20
21You should have received a copy of the GNU General Public License along with
22this program; if not, write to the Free Software Foundation, Inc.,
2351 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
24
25*****************************************************************************/
26
27/** @file include/sync0policy.h
28 Policies for mutexes.
29
30 Created 2012-08-21 Sunny Bains.
31 ***********************************************************************/
32
33#ifndef sync0policy_h
34#define sync0policy_h
35
36#include <string>
37#include <thread>
38
39#include "srv0mon.h"
40#include "sync0types.h"
41#include "univ.i"
42#include "ut0rnd.h"
43
44#ifndef UNIV_LIBRARY
45#ifdef UNIV_DEBUG
46
47constexpr uint32_t MUTEX_MAGIC_N{0xb251b04bU};
48
49template <typename Mutex>
51 public:
52 /** For passing context to SyncDebug */
53 struct Context : public latch_t {
54 /** Constructor */
56 : m_mutex(), m_filename(), m_line(), m_thread_id(std::thread::id{}) {
57 /* No op */
58 }
59
60 /** Create the context for SyncDebug
61 @param[in] id ID of the latch to track */
62 Context(latch_id_t id) : latch_t(id) { /* No op */
63 }
64
65 /** Set to locked state
66 @param[in] mutex The mutex to acquire
67 @param[in] filename File name from where to acquire
68 @param[in] line Line number in filename */
69 void locked(const Mutex *mutex, const char *filename,
70 ulint line) UNIV_NOTHROW {
71 m_mutex = mutex;
72
74
76
77 m_line = line;
78 }
79
80 /** Reset to unlock state */
82 m_mutex = nullptr;
83
85
86 m_filename = nullptr;
87
89 }
90
91 /** Print information about the latch
92 @return the string representation */
93 std::string to_string() const override UNIV_NOTHROW {
95
96 msg << m_mutex->policy().to_string();
97
99 msg << " addr: " << m_mutex << " acquired: " << locked_from().c_str();
100
101 } else {
102 msg << "Not locked";
103 }
104
105 return (msg.str());
106 }
107
108 /** @return the name of the file and line number in the file
109 from where the mutex was acquired "filename:line" */
110 virtual std::string locked_from() const override {
112
113 msg << sync_basename(m_filename) << ":" << m_line;
114
115 return (std::string(msg.str()));
116 }
117
118 /** Mutex to check for lock order violation */
119 const Mutex *m_mutex;
120
121 /** Filename from where enter was called */
122 const char *m_filename;
123
124 /** Line number in filename */
126
127 /** Thread ID of the thread that own(ed) the mutex */
129 };
130
131 /** Constructor. */
133 }
134
135 /* Destructor */
136 virtual ~MutexDebug() = default;
137
138 /** Mutex is being destroyed. */
142
143 m_magic_n = 0;
144
146 }
147
148 /** Called when the mutex is "created". Note: Not from the constructor
149 but when the mutex is initialised.
150 @param[in] id Mutex ID */
152
153 /** Called when an attempt is made to lock the mutex
154 @param[in] mutex Mutex instance to be locked
155 @param[in] filename Filename from where it was called
156 @param[in] line Line number from where it was called */
157 void enter(const Mutex *mutex, const char *filename, ulint line) UNIV_NOTHROW;
158
159 /** Called when the mutex is locked
160 @param[in] mutex Mutex instance that was locked
161 @param[in] filename Filename from where it was called
162 @param[in] line Line number from where it was called */
163 void locked(const Mutex *mutex, const char *filename,
164 ulint line) UNIV_NOTHROW;
165
166 /** Called when the mutex is released
167 @param[in] mutex Mutex that was released */
168 void release(const Mutex *mutex) UNIV_NOTHROW;
169
170 /** @return true if thread owns the mutex */
171 bool is_owned() const UNIV_NOTHROW {
173 }
174
175 /** @return the name of the file from the mutex was acquired */
176 const char *get_enter_filename() const UNIV_NOTHROW {
177 return m_context.m_filename;
178 }
179
180 /** @return the name of the file from the mutex was acquired */
182
183 /** @return id of the thread that was trying to acquire the mutex */
185 return m_context.m_thread_id;
186 }
187
188 /** Magic number to check for memory corruption. */
189 uint32_t m_magic_n;
190
191 /** Latch state of the mutex owner */
193};
194#endif /* UNIV_DEBUG */
195
196/* Do nothing */
197template <typename Mutex>
198struct NoPolicy {
199 /** Default constructor. */
200 NoPolicy() = default;
201
202 void init(const Mutex &, latch_id_t, const char *, uint32_t) UNIV_NOTHROW {}
204 void enter(const Mutex &, const char *, ulint line) UNIV_NOTHROW {}
205 void add(uint32_t, uint32_t) UNIV_NOTHROW {}
206 void locked(const Mutex &, const char *, ulint) UNIV_NOTHROW {}
207 void release(const Mutex &) UNIV_NOTHROW {}
208 std::string to_string() const { return (""); }
210};
211
212/** Collect the metrics per mutex instance, no aggregation. */
213template <typename Mutex>
215#ifdef UNIV_DEBUG
216 : public MutexDebug<Mutex>
217#endif /* UNIV_DEBUG */
218{
219 public:
220 typedef Mutex MutexType;
221
222 /** Constructor. */
224#ifdef UNIV_DEBUG
226#endif /* UNIV_DEBUG */
227 m_count(),
228 m_id() {
229 }
230
231 /** Destructor */
232 ~GenericPolicy() = default;
233
234 /** Called when the mutex is "created". Note: Not from the constructor
235 but when the mutex is initialised.
236 @param[in] mutex Mutex instance to track
237 @param[in] id Mutex ID
238 @param[in] filename File where mutex was created
239 @param[in] line Line in filename */
240 void init(const MutexType &mutex [[maybe_unused]], latch_id_t id,
241 const char *filename, uint32_t line) UNIV_NOTHROW {
242 m_id = id;
243
245
246 ut_ad(meta.get_id() == id);
247
248 meta.get_counter()->single_register(&m_count);
249
251
253 }
254
255 /** Called when the mutex is destroyed. */
258
259 meta.get_counter()->single_deregister(&m_count);
260
262
264 }
265
266 /** Called after a successful mutex acquire.
267 @param[in] n_spins Number of times the thread did
268 spins while trying to acquire the mutex
269 @param[in] n_waits Number of times the thread waited
270 in some type of OS queue */
271 void add(uint32_t n_spins, uint32_t n_waits) UNIV_NOTHROW {
272 /* Currently global on/off. Keeps things simple and fast */
273
274 if (!m_count.m_enabled) {
275 return;
276 }
277
278 m_count.m_spins += n_spins;
279 m_count.m_waits += n_waits;
280
281 ++m_count.m_calls;
282 }
283
284 /** Called when an attempt is made to lock the mutex
285 @param[in] mutex Mutex instance to be locked
286 @param[in] filename Filename from where it was called
287 @param[in] line Line number from where it was called */
288 void enter(const MutexType &IF_DEBUG(mutex), const char *IF_DEBUG(filename),
291 }
292
293 /** Called when the mutex is locked
294 @param[in] mutex Mutex instance that is locked
295 @param[in] filename Filename from where it was called
296 @param[in] line Line number from where it was called */
297 void locked(const MutexType &IF_DEBUG(mutex), const char *IF_DEBUG(filename),
300 }
301
302 /** Called when the mutex is released
303 @param[in] mutex Mutex instance that is released */
306 }
307
308 /** Print the information about the latch
309 @return the string representation */
310 std::string print() const UNIV_NOTHROW;
311
312 /** @return the latch ID */
313 latch_id_t get_id() const UNIV_NOTHROW { return (m_id); }
314
315 /** @return the string representation */
316 std::string to_string() const;
317
318 private:
320
321 /** The user visible counters, registered with the meta-data. */
322 Counter::Count m_count;
323
324 /** Latch meta data ID */
326};
327
328/** Track aggregate metrics policy, used by the page mutex. There are just
329too many of them to count individually. */
330template <typename Mutex>
332#ifdef UNIV_DEBUG
333 : public MutexDebug<Mutex>
334#endif /* UNIV_DEBUG */
335{
336 public:
337 typedef Mutex MutexType;
338 typedef typename latch_meta_t::CounterType::Count Count;
339
340 /** Default constructor. */
342 :
343#ifdef UNIV_DEBUG
345#endif /* UNIV_DEBUG */
346 m_count(),
347 m_id() {
348 /* Do nothing */
349 }
350
351 /** Destructor */
352 ~BlockMutexPolicy() = default;
353
354 /** Called when the mutex is "created". Note: Not from the constructor
355 but when the mutex is initialised.
356 @param[in] mutex Mutex instance to track
357 @param[in] id Mutex ID
358 @param[in] filename File where mutex was created
359 @param[in] line Line in filename */
360 void init(const MutexType &mutex [[maybe_unused]], latch_id_t id,
361 const char *filename [[maybe_unused]],
362 uint32_t line [[maybe_unused]]) UNIV_NOTHROW {
363 /* It can be LATCH_ID_BUF_BLOCK_MUTEX or
364 LATCH_ID_BUF_POOL_ZIP. Unfortunately, they
365 are mapped to the same mutex type in the
366 buffer pool code. */
367
368 m_id = id;
369
371
372 ut_ad(meta.get_id() == id);
373
374 m_count = meta.get_counter()->sum_register();
375
377 }
378
379 /** Called when the mutex is destroyed. */
382
383 ut_ad(meta.get_id() == m_id);
384
385 meta.get_counter()->sum_deregister(m_count);
386
387 m_count = nullptr;
388
390 }
391
392 /** Called after a successful mutex acquire.
393 @param[in] n_spins Number of times the thread did
394 spins while trying to acquire the mutex
395 @param[in] n_waits Number of times the thread waited
396 in some type of OS queue */
397 void add(uint32_t n_spins, uint32_t n_waits) UNIV_NOTHROW {
398 if (!m_count->m_enabled) {
399 return;
400 }
401
402 m_count->m_spins += n_spins;
403 m_count->m_waits += n_waits;
404
405 ++m_count->m_calls;
406 }
407
408 /** Called when the mutex is locked
409 @param[in] mutex Mutex instance that is locked
410 @param[in] filename Filename from where it was called
411 @param[in] line Line number from where it was called */
412 void locked(const MutexType &IF_DEBUG(mutex), const char *IF_DEBUG(filename),
415 }
416
417 /** Called when the mutex is released
418 @param[in] mutex Mutex instance that is released */
421 }
422
423 /** Called when an attempt is made to lock the mutex
424 @param[in] mutex Mutex instance to be locked
425 @param[in] filename Filename from where it was called
426 @param[in] line Line number from where it was called */
427 void enter(const MutexType &IF_DEBUG(mutex), const char *IF_DEBUG(filename),
430 }
431
432 /** Print the information about the latch
433 @return the string representation */
434 std::string print() const UNIV_NOTHROW;
435
436 /** @return the latch ID */
437 latch_id_t get_id() const { return (m_id); }
438
439 /** @return the string representation */
440 std::string to_string() const;
441
442 private:
444
445 /** The user visible counters, registered with the meta-data. */
446 Counter::Count *m_count;
447
448 /** Latch meta data ID */
450};
451
452#include "sync0policy.ic"
453
454#endif /* !UNIV_LIBRARY */
455#endif /* sync0policy_h */
Track aggregate metrics policy, used by the page mutex.
Definition: sync0policy.h:335
void init(const MutexType &mutex, latch_id_t id, const char *filename, uint32_t line) 1
Called when the mutex is "created".
Definition: sync0policy.h:360
latch_meta_t::CounterType Counter
Definition: sync0policy.h:443
void locked(const MutexType &mutex, const char *filename, ulint line) 1
Called when the mutex is locked.
Definition: sync0policy.h:412
void add(uint32_t n_spins, uint32_t n_waits) 1
Called after a successful mutex acquire.
Definition: sync0policy.h:397
void destroy() 1
Called when the mutex is destroyed.
Definition: sync0policy.h:380
std::string to_string() const
Definition: sync0policy.ic:41
std::string print() const 1
Print the information about the latch.
latch_meta_t::CounterType::Count Count
Definition: sync0policy.h:338
void enter(const MutexType &mutex, const char *filename, ulint line) 1
Called when an attempt is made to lock the mutex.
Definition: sync0policy.h:427
Counter::Count * m_count
The user visible counters, registered with the meta-data.
Definition: sync0policy.h:446
void release(const MutexType &mutex) 1
Called when the mutex is released.
Definition: sync0policy.h:419
Mutex MutexType
Definition: sync0policy.h:337
BlockMutexPolicy()
Default constructor.
Definition: sync0policy.h:341
~BlockMutexPolicy()=default
Destructor.
latch_id_t m_id
Latch meta data ID.
Definition: sync0policy.h:449
latch_id_t get_id() const
Definition: sync0policy.h:437
Latch meta data.
Definition: sync0types.h:772
Counter * get_counter()
Definition: sync0types.h:846
Counter CounterType
Definition: sync0types.h:774
latch_id_t get_id() const
Definition: sync0types.h:829
Definition: sync0policy.h:50
const char * get_enter_filename() const 1
Definition: sync0policy.h:176
bool is_owned() const 1
Definition: sync0policy.h:171
ulint get_enter_line() const 1
Definition: sync0policy.h:181
uint32_t m_magic_n
Magic number to check for memory corruption.
Definition: sync0policy.h:189
std::thread::id get_thread_id() const 1
Definition: sync0policy.h:184
void destroy() 1
Mutex is being destroyed.
Definition: sync0policy.h:139
Context m_context
Latch state of the mutex owner.
Definition: sync0policy.h:192
void enter(const Mutex *mutex, const char *filename, ulint line) 1
Called when an attempt is made to lock the mutex.
Definition: sync0policy.ic:60
void release(const Mutex *mutex) 1
Called when the mutex is released.
Definition: sync0policy.ic:86
void locked(const Mutex *mutex, const char *filename, ulint line) 1
Called when the mutex is locked.
Definition: sync0policy.ic:75
void init(latch_id_t id) 1
Called when the mutex is "created".
Definition: sync0policy.ic:51
MutexDebug()
Constructor.
Definition: sync0policy.h:132
Definition: varlen_sort.h:174
pid_type get_id()
Definition: process.h:47
std::basic_ostringstream< char, std::char_traits< char >, ut::allocator< char > > ostringstream
Specialization of basic_ostringstream which uses ut::allocator.
Definition: ut0new.h:2869
const char * filename
Definition: pfs_example_component_population.cc:66
Server monitor counter related defines.
Collect the metrics per mutex instance, no aggregation.
Definition: sync0policy.h:218
void locked(const MutexType &mutex, const char *filename, ulint line) 1
Called when the mutex is locked.
Definition: sync0policy.h:297
void destroy() 1
Called when the mutex is destroyed.
Definition: sync0policy.h:256
std::string print() const 1
Print the information about the latch.
~GenericPolicy()=default
Destructor.
latch_id_t get_id() const 1
Definition: sync0policy.h:313
void enter(const MutexType &mutex, const char *filename, ulint line) 1
Called when an attempt is made to lock the mutex.
Definition: sync0policy.h:288
Counter::Count m_count
The user visible counters, registered with the meta-data.
Definition: sync0policy.h:322
void add(uint32_t n_spins, uint32_t n_waits) 1
Called after a successful mutex acquire.
Definition: sync0policy.h:271
void release(const MutexType &mutex) 1
Called when the mutex is released.
Definition: sync0policy.h:304
latch_id_t m_id
Latch meta data ID.
Definition: sync0policy.h:325
Mutex MutexType
Definition: sync0policy.h:220
std::string to_string() const
Definition: sync0policy.ic:36
latch_meta_t::CounterType Counter
Definition: sync0policy.h:319
void init(const MutexType &mutex, latch_id_t id, const char *filename, uint32_t line) 1
Called when the mutex is "created".
Definition: sync0policy.h:240
GenericPolicy() 1
Constructor.
Definition: sync0policy.h:223
For passing context to SyncDebug.
Definition: sync0policy.h:53
std::thread::id m_thread_id
Thread ID of the thread that own(ed) the mutex.
Definition: sync0policy.h:128
std::string to_string() const override 1
Print information about the latch.
Definition: sync0policy.h:93
virtual std::string locked_from() const override
Definition: sync0policy.h:110
Context()
Constructor.
Definition: sync0policy.h:55
void release() 1
Reset to unlock state.
Definition: sync0policy.h:81
const Mutex * m_mutex
Mutex to check for lock order violation.
Definition: sync0policy.h:119
ulint m_line
Line number in filename.
Definition: sync0policy.h:125
Context(latch_id_t id)
Create the context for SyncDebug.
Definition: sync0policy.h:62
void locked(const Mutex *mutex, const char *filename, ulint line) 1
Set to locked state.
Definition: sync0policy.h:69
const char * m_filename
Filename from where enter was called.
Definition: sync0policy.h:122
Definition: sync0policy.h:198
std::string to_string() const
Definition: sync0policy.h:208
void add(uint32_t, uint32_t) 1
Definition: sync0policy.h:205
void init(const Mutex &, latch_id_t, const char *, uint32_t) 1
Definition: sync0policy.h:202
void enter(const Mutex &, const char *, ulint line) 1
Definition: sync0policy.h:204
NoPolicy()=default
Default constructor.
latch_id_t get_id() const
void release(const Mutex &) 1
Definition: sync0policy.h:207
void destroy() 1
Definition: sync0policy.h:203
void locked(const Mutex &, const char *, ulint) 1
Definition: sync0policy.h:206
All (ordered) latches, used in debugging, must derive from this class.
Definition: sync0types.h:961
constexpr uint32_t MUTEX_MAGIC_N
Definition: sync0policy.h:47
Policy for mutexes.
Global types for sync.
void sync_file_created_register(const void *ptr, const char *filename, uint16_t line)
Register a latch, called when it is created.
Definition: sync0debug.cc:1645
latch_meta_t & sync_latch_get_meta(latch_id_t id)
Get the latch meta-data from the latch ID.
Definition: sync0types.h:882
latch_id_t
Each latch has an ID.
Definition: sync0types.h:342
const char * sync_basename(const char *filename)
Print the filename "basename".
Definition: sync0sync.cc:217
void sync_file_created_deregister(const void *ptr)
Deregister a latch, called when it is destroyed.
Definition: sync0debug.cc:1652
Version control for database, common definitions, and include files.
#define IF_DEBUG(...)
Definition: univ.i:673
#define UNIV_NOTHROW
Definition: univ.i:455
unsigned long int ulint
Definition: univ.i:405
constexpr ulint ULINT_UNDEFINED
The 'undefined' value for a ulint.
Definition: univ.i:419
#define ut_ad(EXPR)
Debug assertion.
Definition: ut0dbg.h:104
#define ut_d(EXPR)
Debug statement.
Definition: ut0dbg.h:106
Random numbers and hashing.
unsigned long id[MAX_DEAD]
Definition: xcom_base.cc:509