1
/*****************************************************************************
3
Copyright (c) 1995, 2009, Innobase Oy. All Rights Reserved.
4
Copyright (c) 2008, Google Inc.
6
Portions of this file contain modifications contributed and copyrighted by
7
Google, Inc. Those modifications are gratefully acknowledged and are described
8
briefly in the InnoDB documentation. The contributions by Google are
9
incorporated with their permission, and subject to the conditions contained in
10
the file COPYING.Google.
12
This program is free software; you can redistribute it and/or modify it under
13
the terms of the GNU General Public License as published by the Free Software
14
Foundation; version 2 of the License.
16
This program is distributed in the hope that it will be useful, but WITHOUT
17
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
18
FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
20
You should have received a copy of the GNU General Public License along with
21
this program; if not, write to the Free Software Foundation, Inc., 59 Temple
22
Place, Suite 330, Boston, MA 02111-1307 USA
24
*****************************************************************************/
26
/**************************************************//**
27
@file include/sync0sync.h
28
Mutex, the basic synchronization primitive
30
Created 9/5/1995 Heikki Tuuri
31
*******************************************************/
37
#include "sync0types.h"
40
#include "os0thread.h"
44
#if defined(UNIV_DEBUG) && !defined(UNIV_HOTBACKUP)
45
extern my_bool timed_mutexes;
46
#endif /* UNIV_DEBUG && !UNIV_HOTBACKUP */
48
#ifdef HAVE_WINDOWS_ATOMICS
49
typedef LONG lock_word_t; /*!< On Windows, InterlockedExchange operates
52
typedef byte lock_word_t;
55
/******************************************************************//**
56
Initializes the synchronization data structures. */
61
/******************************************************************//**
62
Frees the resources in synchronization data structures. */
67
/******************************************************************//**
68
Creates, or rather, initializes a mutex object to a specified memory
69
location (which must be appropriately aligned). The mutex is initialized
70
in the reset state. Explicit freeing of the mutex with mutex_free is
71
necessary only if the memory block containing it is freed. */
74
# ifdef UNIV_SYNC_DEBUG
75
# define mutex_create(M, level) \
76
mutex_create_func((M), #M, (level), __FILE__, __LINE__)
78
# define mutex_create(M, level) \
79
mutex_create_func((M), #M, __FILE__, __LINE__)
82
# define mutex_create(M, level) \
83
mutex_create_func((M), __FILE__, __LINE__)
86
/******************************************************************//**
87
Creates, or rather, initializes a mutex object in a specified memory
88
location (which must be appropriately aligned). The mutex is initialized
89
in the reset state. Explicit freeing of the mutex with mutex_free is
90
necessary only if the memory block containing it is freed. */
95
mutex_t* mutex, /*!< in: pointer to memory */
97
const char* cmutex_name, /*!< in: mutex name */
98
# ifdef UNIV_SYNC_DEBUG
99
ulint level, /*!< in: level */
100
# endif /* UNIV_SYNC_DEBUG */
101
#endif /* UNIV_DEBUG */
102
const char* cfile_name, /*!< in: file name where created */
103
ulint cline); /*!< in: file line where created */
105
#undef mutex_free /* Fix for MacOS X */
107
/******************************************************************//**
108
Calling this function is obligatory only if the memory buffer containing
109
the mutex is freed. Removes a mutex object from the mutex list. The mutex
110
is checked to be in the reset state. */
115
mutex_t* mutex); /*!< in: mutex */
116
/**************************************************************//**
117
NOTE! The following macro should be used in mutex locking, not the
118
corresponding function. */
120
#define mutex_enter(M) mutex_enter_func((M), __FILE__, __LINE__)
121
/**************************************************************//**
122
NOTE! The following macro should be used in mutex locking, not the
123
corresponding function. */
125
/* NOTE! currently same as mutex_enter! */
127
#define mutex_enter_fast(M) mutex_enter_func((M), __FILE__, __LINE__)
128
/******************************************************************//**
129
NOTE! Use the corresponding macro in the header file, not this function
130
directly. Locks a mutex for the current thread. If the mutex is reserved
131
the function spins a preset time (controlled by SYNC_SPIN_ROUNDS) waiting
132
for the mutex before suspending the thread. */
137
mutex_t* mutex, /*!< in: pointer to mutex */
138
const char* file_name, /*!< in: file name where locked */
139
ulint line); /*!< in: line where locked */
140
/**************************************************************//**
141
NOTE! The following macro should be used in mutex locking, not the
142
corresponding function. */
144
#define mutex_enter_nowait(M) \
145
mutex_enter_nowait_func((M), __FILE__, __LINE__)
146
/********************************************************************//**
147
NOTE! Use the corresponding macro in the header file, not this function
148
directly. Tries to lock the mutex for the current thread. If the lock is not
149
acquired immediately, returns with return value 1.
150
@return 0 if succeed, 1 if not */
153
mutex_enter_nowait_func(
154
/*====================*/
155
mutex_t* mutex, /*!< in: pointer to mutex */
156
const char* file_name, /*!< in: file name where mutex
158
ulint line); /*!< in: line where requested */
159
/******************************************************************//**
160
Unlocks a mutex owned by the current thread. */
165
mutex_t* mutex); /*!< in: pointer to mutex */
166
#ifdef UNIV_SYNC_DEBUG
167
/******************************************************************//**
168
Returns TRUE if no mutex or rw-lock is currently locked.
169
Works only in the debug version.
170
@return TRUE if no mutexes and rw-locks reserved */
173
sync_all_freed(void);
175
#endif /* UNIV_SYNC_DEBUG */
176
/*#####################################################################
177
FUNCTION PROTOTYPES FOR DEBUGGING */
178
/*******************************************************************//**
179
Prints wait info of the sync system. */
182
sync_print_wait_info(
183
/*=================*/
184
FILE* file); /*!< in: file where to print */
185
/*******************************************************************//**
186
Prints info of the sync system. */
191
FILE* file); /*!< in: file where to print */
193
/******************************************************************//**
194
Checks that the mutex has been initialized.
200
const mutex_t* mutex); /*!< in: mutex */
201
/******************************************************************//**
202
Checks that the current thread owns the mutex. Works only
203
in the debug version.
204
@return TRUE if owns */
209
const mutex_t* mutex); /*!< in: mutex */
210
#endif /* UNIV_DEBUG */
211
#ifdef UNIV_SYNC_DEBUG
212
/******************************************************************//**
213
Adds a latch and its level in the thread level array. Allocates the memory
214
for the array if called first time for this OS thread. Makes the checks
215
against other latch levels stored in the array for this thread. */
218
sync_thread_add_level(
219
/*==================*/
220
void* latch, /*!< in: pointer to a mutex or an rw-lock */
221
ulint level); /*!< in: level in the latching order; if
222
SYNC_LEVEL_VARYING, nothing is done */
223
/******************************************************************//**
224
Removes a latch from the thread level array if it is found there.
225
@return TRUE if found in the array; it is no error if the latch is
226
not found, as we presently are not able to determine the level for
227
every latch reservation the program does */
230
sync_thread_reset_level(
231
/*====================*/
232
void* latch); /*!< in: pointer to a mutex or an rw-lock */
233
/******************************************************************//**
234
Checks that the level array for the current thread is empty.
235
@return TRUE if empty */
238
sync_thread_levels_empty(void);
239
/*==========================*/
240
/******************************************************************//**
241
Checks that the level array for the current thread is empty.
242
@return TRUE if empty except the exceptions specified below */
245
sync_thread_levels_empty_gen(
246
/*=========================*/
247
ibool dict_mutex_allowed); /*!< in: TRUE if dictionary mutex is
248
allowed to be owned by the thread,
249
also purge_is_running mutex is
251
/******************************************************************//**
252
Gets the debug information for a reserved mutex. */
255
mutex_get_debug_info(
256
/*=================*/
257
mutex_t* mutex, /*!< in: mutex */
258
const char** file_name, /*!< out: file where requested */
259
ulint* line, /*!< out: line where requested */
260
os_thread_id_t* thread_id); /*!< out: id of the thread which owns
262
/******************************************************************//**
263
Counts currently reserved mutexes. Works only in the debug version.
264
@return number of reserved mutexes */
267
mutex_n_reserved(void);
268
/*==================*/
269
#endif /* UNIV_SYNC_DEBUG */
270
/******************************************************************//**
271
NOT to be used outside this module except in debugging! Gets the value
277
const mutex_t* mutex); /*!< in: mutex */
278
#ifdef UNIV_SYNC_DEBUG
279
/******************************************************************//**
280
NOT to be used outside this module except in debugging! Gets the waiters
282
@return value to set */
287
const mutex_t* mutex); /*!< in: mutex */
288
#endif /* UNIV_SYNC_DEBUG */
291
LATCHING ORDER WITHIN THE DATABASE
292
==================================
294
The mutex or latch in the central memory object, for instance, a rollback
295
segment object, must be acquired before acquiring the latch or latches to
296
the corresponding file data structure. In the latching order below, these
297
file page object latches are placed immediately below the corresponding
298
central memory object latch or mutex.
300
Synchronization object Notes
301
---------------------- -----
303
Dictionary mutex If we have a pointer to a dictionary
304
| object, e.g., a table, it can be
305
| accessed without reserving the
306
| dictionary mutex. We must have a
307
| reservation, a memoryfix, to the
308
| appropriate table object in this case,
309
| and the table must be explicitly
315
Secondary index tree latch The tree latch protects also all
316
| the B-tree non-leaf pages. These
317
V can be read with the page only
318
Secondary index non-leaf bufferfixed to save CPU time,
319
| no s-latch is needed on the page.
320
| Modification of a page requires an
321
| x-latch on the page, however. If a
322
| thread owns an x-latch to the tree,
323
| it is allowed to latch non-leaf pages
324
| even after it has acquired the fsp
327
Secondary index leaf The latch on the secondary index leaf
328
| can be kept while accessing the
329
| clustered index, to save CPU time.
331
Clustered index tree latch To increase concurrency, the tree
332
| latch is usually released when the
333
| leaf page latch has been acquired.
335
Clustered index non-leaf
341
Transaction system header
344
Transaction undo mutex The undo log entry must be written
345
| before any index page is modified.
346
| Transaction undo mutex is for the undo
347
| logs the analogue of the tree latch
348
| for a B-tree. If a thread has the
349
| trx undo mutex reserved, it is allowed
350
| to latch the undo log pages in any
351
| order, and also after it has acquired
354
Rollback segment mutex The rollback segment mutex must be
355
| reserved, if, e.g., a new page must
356
| be added to an undo log. The rollback
357
| segment and the undo logs in its
358
| history list can be seen as an
359
| analogue of a B-tree, and the latches
360
| reserved similarly, using a version of
361
| lock-coupling. If an undo log must be
362
| extended by a page when inserting an
363
| undo log record, this corresponds to
364
| a pessimistic insert in a B-tree.
366
Rollback segment header
372
Undo log pages If a thread owns the trx undo mutex,
373
| or for a log in the history list, the
374
| rseg mutex, it is allowed to latch
375
| undo log pages in any order, and even
376
| after it has acquired the fsp latch.
377
| If a thread does not have the
378
| appropriate mutex, it is allowed to
379
| latch only a single undo log page in
380
| a mini-transaction.
382
File space management latch If a mini-transaction must allocate
383
| several file pages, it can do that,
384
| because it keeps the x-latch to the
385
| file space management in its memo.
390
Kernel mutex If a kernel operation needs a file
391
| page allocation, it must reserve the
392
| fsp x-latch before acquiring the kernel
408
/* Latching order levels */
410
/* User transaction locks are higher than any of the latch levels below:
411
no latches are allowed when a thread goes to wait for a normal table
413
#define SYNC_USER_TRX_LOCK 9999
414
#define SYNC_NO_ORDER_CHECK 3000 /* this can be used to suppress
415
latching order checking */
416
#define SYNC_LEVEL_VARYING 2000 /* Level is varying. Only used with
417
buffer pool page locks, which do not
418
have a fixed level, but instead have
419
their level set after the page is
421
ibuf_bitmap_get_map_page(). */
422
#define SYNC_TRX_I_S_RWLOCK 1910 /* Used for
423
trx_i_s_cache_t::rw_lock */
424
#define SYNC_TRX_I_S_LAST_READ 1900 /* Used for
425
trx_i_s_cache_t::last_read_mutex */
426
#define SYNC_FILE_FORMAT_TAG 1200 /* Used to serialize access to the
428
#define SYNC_DICT_OPERATION 1001 /* table create, drop, etc. reserve
429
this in X-mode, implicit or backround
430
operations purge, rollback, foreign
431
key checks reserve this in S-mode */
432
#define SYNC_DICT 1000
433
#define SYNC_DICT_AUTOINC_MUTEX 999
434
#define SYNC_DICT_HEADER 995
435
#define SYNC_IBUF_HEADER 914
436
#define SYNC_IBUF_PESS_INSERT_MUTEX 912
437
#define SYNC_IBUF_MUTEX 910 /* ibuf mutex is really below
438
SYNC_FSP_PAGE: we assign a value this
439
high only to make the program to pass
441
/*-------------------------------*/
442
#define SYNC_INDEX_TREE 900
443
#define SYNC_TREE_NODE_NEW 892
444
#define SYNC_TREE_NODE_FROM_HASH 891
445
#define SYNC_TREE_NODE 890
446
#define SYNC_PURGE_SYS 810
447
#define SYNC_PURGE_LATCH 800
448
#define SYNC_TRX_UNDO 700
449
#define SYNC_RSEG 600
450
#define SYNC_RSEG_HEADER_NEW 591
451
#define SYNC_RSEG_HEADER 590
452
#define SYNC_TRX_UNDO_PAGE 570
453
#define SYNC_EXTERN_STORAGE 500
455
#define SYNC_FSP_PAGE 395
456
/*------------------------------------- Insert buffer headers */
457
/*------------------------------------- ibuf_mutex */
458
/*------------------------------------- Insert buffer tree */
459
#define SYNC_IBUF_BITMAP_MUTEX 351
460
#define SYNC_IBUF_BITMAP 350
461
/*------------------------------------- MySQL query cache mutex */
462
/*------------------------------------- MySQL binlog mutex */
463
/*-------------------------------*/
464
#define SYNC_KERNEL 300
465
#define SYNC_REC_LOCK 299
466
#define SYNC_TRX_LOCK_HEAP 298
467
#define SYNC_TRX_SYS_HEADER 290
469
#define SYNC_RECV 168
470
#define SYNC_WORK_QUEUE 162
471
#define SYNC_SEARCH_SYS_CONF 161 /* for assigning btr_search_enabled */
472
#define SYNC_SEARCH_SYS 160 /* NOTE that if we have a memory
473
heap that can be extended to the
474
buffer pool, its logical level is
475
SYNC_SEARCH_SYS, as memory allocation
476
can call routines there! Otherwise
477
the level is SYNC_MEM_HASH. */
478
#define SYNC_BUF_POOL 150
479
#define SYNC_BUF_BLOCK 149
480
#define SYNC_DOUBLEWRITE 140
481
#define SYNC_ANY_LATCH 135
482
#define SYNC_THR_LOCAL 133
483
#define SYNC_MEM_HASH 131
484
#define SYNC_MEM_POOL 130
486
/* Codes used to designate lock operations */
487
#define RW_LOCK_NOT_LOCKED 350
488
#define RW_LOCK_EX 351
489
#define RW_LOCK_EXCLUSIVE 351
490
#define RW_LOCK_SHARED 352
491
#define RW_LOCK_WAIT_EX 353
492
#define SYNC_MUTEX 354
494
/* NOTE! The structure appears here only for the compiler to know its size.
495
Do not use its fields directly! The structure used in the spin lock
496
implementation of a mutual exclusion semaphore. */
499
struct mutex_struct {
500
os_event_t event; /*!< Used by sync0arr.c for the wait queue */
501
volatile lock_word_t lock_word; /*!< lock_word is the target
502
of the atomic test-and-set instruction when
503
atomic operations are enabled. */
505
#if !defined(HAVE_ATOMIC_BUILTINS)
507
os_fast_mutex; /*!< We use this OS mutex in place of lock_word
508
when atomic operations are not enabled */
510
ulint waiters; /*!< This ulint is set to 1 if there are (or
511
may be) threads waiting in the global wait
512
array for this mutex to be released.
513
Otherwise, this is 0. */
514
UT_LIST_NODE_T(mutex_t) list; /*!< All allocated mutexes are put into
515
a list. Pointers to the next and prev. */
516
#ifdef UNIV_SYNC_DEBUG
517
const char* file_name; /*!< File where the mutex was locked */
518
ulint line; /*!< Line where the mutex was locked */
519
ulint level; /*!< Level in the global latching order */
520
#endif /* UNIV_SYNC_DEBUG */
521
const char* cfile_name;/*!< File name where mutex created */
522
ulint cline; /*!< Line where created */
524
os_thread_id_t thread_id; /*!< The thread id of the thread
525
which locked the mutex. */
526
ulint magic_n; /*!< MUTEX_MAGIC_N */
527
/** Value of mutex_struct::magic_n */
528
# define MUTEX_MAGIC_N (ulint)979585
529
#endif /* UNIV_DEBUG */
530
ulong count_os_wait; /*!< count of os_wait */
532
ulong count_using; /*!< count of times mutex used */
533
ulong count_spin_loop; /*!< count of spin loops */
534
ulong count_spin_rounds;/*!< count of spin rounds */
535
ulong count_os_yield; /*!< count of os_wait */
536
ulonglong lspent_time; /*!< mutex os_wait timer msec */
537
ulonglong lmax_spent_time;/*!< mutex os_wait timer msec */
538
const char* cmutex_name; /*!< mutex name */
539
ulint mutex_type; /*!< 0=usual mutex, 1=rw_lock mutex */
540
#endif /* UNIV_DEBUG */
543
/** The global array of wait cells for implementation of the databases own
544
mutexes and read-write locks. */
545
extern sync_array_t* sync_primary_wait_array;/* Appears here for
546
debugging purposes only! */
548
/** Constant determining how long spin wait is continued before suspending
549
the thread. A value 600 rounds on a 1995 100 MHz Pentium seems to correspond
550
to 20 microseconds. */
552
#define SYNC_SPIN_ROUNDS srv_n_spin_wait_rounds
554
/** The number of mutex_exit calls. Intended for performance monitoring. */
555
extern ib_int64_t mutex_exit_count;
557
#ifdef UNIV_SYNC_DEBUG
558
/** Latching order checks start when this is set TRUE */
559
extern ibool sync_order_checks_on;
560
#endif /* UNIV_SYNC_DEBUG */
562
/** This variable is set to TRUE when sync_init is called */
563
extern ibool sync_initialized;
565
/** Global list of database mutexes (not OS mutexes) created. */
566
typedef UT_LIST_BASE_NODE_T(mutex_t) ut_list_base_node_t;
567
/** Global list of database mutexes (not OS mutexes) created. */
568
extern ut_list_base_node_t mutex_list;
570
/** Mutex protecting the mutex_list variable */
571
extern mutex_t mutex_list_mutex;
575
#include "sync0sync.ic"
added
removed
plugin/innobase/include/sync0sync.h
