sync0sync.h 16.6 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38
/******************************************************
Mutex, the basic synchronization primitive

(c) 1995 Innobase Oy

Created 9/5/1995 Heikki Tuuri
*******************************************************/

#ifndef sync0sync_h
#define sync0sync_h

#include "univ.i"
#include "sync0types.h"
#include "ut0lst.h"
#include "ut0mem.h"
#include "os0thread.h"
#include "os0sync.h"
#include "sync0arr.h"

/**********************************************************************
Initializes the synchronization data structures. */

void
sync_init(void);
/*===========*/
/**********************************************************************
Frees the resources in synchronization data structures. */

void
sync_close(void);
/*===========*/
/**********************************************************************
Creates, or rather, initializes a mutex object to a specified memory
location (which must be appropriately aligned). The mutex is initialized
in the reset state. Explicit freeing of the mutex with mutex_free is
necessary only if the memory block containing it is freed. */


39
#define mutex_create(M)	mutex_create_func((M), __FILE__, __LINE__)
40 41 42 43 44 45 46 47 48 49 50
/*===================*/
/**********************************************************************
Creates, or rather, initializes a mutex object in a specified memory
location (which must be appropriately aligned). The mutex is initialized
in the reset state. Explicit freeing of the mutex with mutex_free is
necessary only if the memory block containing it is freed. */

void
mutex_create_func(
/*==============*/
	mutex_t*	mutex,		/* in: pointer to memory */
51
	const char*	cfile_name,	/* in: file name where created */
52 53 54 55 56 57
	ulint		cline);		/* in: file line where created */
/**********************************************************************
Calling this function is obligatory only if the memory buffer containing
the mutex is freed. Removes a mutex object from the mutex list. The mutex
is checked to be in the reset state. */

unknown's avatar
unknown committed
58
#undef mutex_free			/* Fix for MacOS X */
59 60 61 62 63 64 65 66
void
mutex_free(
/*=======*/
	mutex_t*	mutex);	/* in: mutex */
/******************************************************************
NOTE! The following macro should be used in mutex locking, not the
corresponding function. */

67
#define mutex_enter(M)    mutex_enter_func((M), __FILE__, __LINE__)
68 69 70 71 72 73 74 75 76
/**********************************************************************
A noninlined function that reserves a mutex. In ha_innodb.cc we have disabled
inlining of InnoDB functions, and no inlined functions should be called from
there. That is why we need to duplicate the inlined function here. */

void
mutex_enter_noninline(
/*==================*/
	mutex_t*	mutex);	/* in: mutex */
77 78 79 80 81 82
/******************************************************************
NOTE! The following macro should be used in mutex locking, not the
corresponding function. */

/* NOTE! currently same as mutex_enter! */

83
#define mutex_enter_fast(M)    	mutex_enter_func((M), __FILE__, __LINE__)
84
#define mutex_enter_fast_func  	mutex_enter_func;
85 86 87 88 89 90 91 92 93
/**********************************************************************
NOTE! Use the corresponding macro in the header file, not this function
directly. Locks a mutex for the current thread. If the mutex is reserved
the function spins a preset time (controlled by SYNC_SPIN_ROUNDS) waiting
for the mutex before suspending the thread. */
UNIV_INLINE
void
mutex_enter_func(
/*=============*/
94
	mutex_t*	mutex,		/* in: pointer to mutex */
95
	const char*	file_name, 	/* in: file name where locked */
96
	ulint		line);		/* in: line where locked */
97 98 99 100 101 102 103
/************************************************************************
Tries to lock the mutex for the current thread. If the lock is not acquired
immediately, returns with return value 1. */

ulint
mutex_enter_nowait(
/*===============*/
104 105
					/* out: 0 if succeed, 1 if not */
	mutex_t*	mutex,		/* in: pointer to mutex */
106
	const char*	file_name,	/* in: file name where mutex
107
					requested */
108
	ulint		line);		/* in: line where requested */
109 110 111 112 113 114 115 116
/**********************************************************************
Unlocks a mutex owned by the current thread. */
UNIV_INLINE
void
mutex_exit(
/*=======*/
	mutex_t*	mutex);	/* in: pointer to mutex */
/**********************************************************************
117 118 119 120 121 122 123
Releases a mutex. */

void
mutex_exit_noninline(
/*=================*/
	mutex_t*	mutex);	/* in: mutex */
/**********************************************************************
124 125 126 127 128 129 130 131 132 133 134 135
Returns TRUE if no mutex or rw-lock is currently locked.
Works only in the debug version. */

ibool
sync_all_freed(void);
/*================*/
/*#####################################################################
FUNCTION PROTOTYPES FOR DEBUGGING */
/***********************************************************************
Prints wait info of the sync system. */

void
unknown's avatar
unknown committed
136 137
sync_print_wait_info(
/*=================*/
138
	FILE*	file);		/* in: file where to print */
139 140 141 142
/***********************************************************************
Prints info of the sync system. */

void
unknown's avatar
unknown committed
143 144
sync_print(
/*=======*/
145
	FILE*	file);		/* in: file where to print */
146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201
/**********************************************************************
Checks that the mutex has been initialized. */

ibool
mutex_validate(
/*===========*/
	mutex_t*	mutex);
/**********************************************************************
Sets the mutex latching level field. */

void
mutex_set_level(
/*============*/
	mutex_t*	mutex,	/* in: mutex */
	ulint		level);	/* in: level */
/**********************************************************************
Adds a latch and its level in the thread level array. Allocates the memory
for the array if called first time for this OS thread. Makes the checks
against other latch levels stored in the array for this thread. */

void
sync_thread_add_level(
/*==================*/
	void*	latch,	/* in: pointer to a mutex or an rw-lock */
	ulint	level);	/* in: level in the latching order; if SYNC_LEVEL_NONE,
			nothing is done */			
/**********************************************************************
Removes a latch from the thread level array if it is found there. */

ibool
sync_thread_reset_level(
/*====================*/
			/* out: TRUE if found from the array; it is no error
			if the latch is not found, as we presently are not
			able to determine the level for every latch
			reservation the program does */
	void*	latch);	/* in: pointer to a mutex or an rw-lock */
/**********************************************************************
Checks that the level array for the current thread is empty. */

ibool
sync_thread_levels_empty(void);
/*==========================*/
			/* out: TRUE if empty */
/**********************************************************************
Checks that the level array for the current thread is empty. */

ibool
sync_thread_levels_empty_gen(
/*=========================*/
					/* out: TRUE if empty except the
					exceptions specified below */
	ibool	dict_mutex_allowed);	/* in: TRUE if dictionary mutex is
					allowed to be owned by the thread,
					also purge_is_running mutex is
					allowed */
202
#ifdef UNIV_SYNC_DEBUG
203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218
/**********************************************************************
Checks that the current thread owns the mutex. Works only
in the debug version. */

ibool
mutex_own(
/*======*/
				/* out: TRUE if owns */
	mutex_t*	mutex);	/* in: mutex */
/**********************************************************************
Gets the debug information for a reserved mutex. */

void
mutex_get_debug_info(
/*=================*/
	mutex_t*	mutex,		/* in: mutex */
219
	const char**	file_name,	/* out: file where requested */
220 221 222 223 224 225 226 227 228 229 230 231 232 233 234
	ulint*		line,		/* out: line where requested */
	os_thread_id_t* thread_id);	/* out: id of the thread which owns
					the mutex */
/**********************************************************************
Counts currently reserved mutexes. Works only in the debug version. */

ulint
mutex_n_reserved(void);
/*==================*/
/**********************************************************************
Prints debug info of currently reserved mutexes. */

void
mutex_list_print_info(void);
/*========================*/
235
#endif /* UNIV_SYNC_DEBUG */
236 237 238 239 240 241 242 243
/**********************************************************************
NOT to be used outside this module except in debugging! Gets the value
of the lock word. */
UNIV_INLINE
ulint
mutex_get_lock_word(
/*================*/
	mutex_t*	mutex);	/* in: mutex */
244
#ifdef UNIV_SYNC_DEBUG
245 246 247 248 249 250 251 252 253
/**********************************************************************
NOT to be used outside this module except in debugging! Gets the waiters
field in a mutex. */
UNIV_INLINE
ulint
mutex_get_waiters(
/*==============*/
				/* out: value to set */		
	mutex_t*	mutex);	/* in: mutex */
254
#endif /* UNIV_SYNC_DEBUG */
255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374

/*
		LATCHING ORDER WITHIN THE DATABASE
		==================================

The mutex or latch in the central memory object, for instance, a rollback
segment object, must be acquired before acquiring the latch or latches to
the corresponding file data structure. In the latching order below, these
file page object latches are placed immediately below the corresponding
central memory object latch or mutex.

Synchronization object			Notes
----------------------			-----
		
Dictionary mutex			If we have a pointer to a dictionary
|					object, e.g., a table, it can be
|					accessed without reserving the
|					dictionary mutex. We must have a
|					reservation, a memoryfix, to the
|					appropriate table object in this case,
|					and the table must be explicitly
|					released later.
V
Dictionary header
|
V					
Secondary index tree latch		The tree latch protects also all
|					the B-tree non-leaf pages. These
V					can be read with the page only
Secondary index non-leaf		bufferfixed to save CPU time,
|					no s-latch is needed on the page.
|					Modification of a page requires an
|					x-latch on the page, however. If a
|					thread owns an x-latch to the tree,
|					it is allowed to latch non-leaf pages
|					even after it has acquired the fsp
|					latch.
V					
Secondary index leaf			The latch on the secondary index leaf
|					can be kept while accessing the
|					clustered index, to save CPU time.
V
Clustered index tree latch		To increase concurrency, the tree
|					latch is usually released when the
|					leaf page latch has been acquired.
V					
Clustered index non-leaf
|
V
Clustered index leaf
|
V
Transaction system header
|
V
Transaction undo mutex			The undo log entry must be written
|					before any index page is modified.
|					Transaction undo mutex is for the undo
|					logs the analogue of the tree latch
|					for a B-tree. If a thread has the
|					trx undo mutex reserved, it is allowed
|					to latch the undo log pages in any
|					order, and also after it has acquired
|					the fsp latch. 
V
Rollback segment mutex			The rollback segment mutex must be
|					reserved, if, e.g., a new page must
|					be added to an undo log. The rollback
|					segment and the undo logs in its
|					history list can be seen as an
|					analogue of a B-tree, and the latches
|					reserved similarly, using a version of
|					lock-coupling. If an undo log must be
|					extended by a page when inserting an
|					undo log record, this corresponds to
|					a pessimistic insert in a B-tree.
V
Rollback segment header
|
V
Purge system latch
|
V
Undo log pages				If a thread owns the trx undo mutex,
|					or for a log in the history list, the
|					rseg mutex, it is allowed to latch
|					undo log pages in any order, and even
|					after it has acquired the fsp latch.
|					If a thread does not have the
|					appropriate mutex, it is allowed to
|					latch only a single undo log page in
|					a mini-transaction.
V
File space management latch		If a mini-transaction must allocate
|					several file pages, it can do that,
|					because it keeps the x-latch to the
|					file space management in its memo.
V
File system pages
|
V
Kernel mutex				If a kernel operation needs a file
|					page allocation, it must reserve the
|					fsp x-latch before acquiring the kernel
|					mutex.
V
Search system mutex
|
V
Buffer pool mutex
|
V
Log mutex
|
Any other latch
|
V
Memory pool mutex */

/* Latching order levels */
unknown's avatar
unknown committed
375 376 377 378 379

/* User transaction locks are higher than any of the latch levels below:
no latches are allowed when a thread goes to wait for a normal table
or row lock! */
#define SYNC_USER_TRX_LOCK	9999
380 381 382
#define SYNC_NO_ORDER_CHECK	3000	/* this can be used to suppress
					latching order checking */
#define	SYNC_LEVEL_NONE		2000	/* default: level not defined */
unknown's avatar
unknown committed
383 384 385 386
#define	SYNC_DICT_OPERATION	1001	/* table create, drop, etc. reserve
					this in X-mode, implicit or backround
					operations purge, rollback, foreign
					key checks reserve this in S-mode */
387
#define SYNC_DICT		1000
388
#define SYNC_DICT_AUTOINC_MUTEX	999
389 390 391 392
#define SYNC_DICT_HEADER	995
#define SYNC_IBUF_HEADER	914
#define SYNC_IBUF_PESS_INSERT_MUTEX 912
#define SYNC_IBUF_MUTEX		910	/* ibuf mutex is really below
unknown's avatar
unknown committed
393 394
					SYNC_FSP_PAGE: we assign a value this
					high only to make the program to pass
395 396 397 398 399 400 401 402 403 404 405 406 407
					the debug checks */
/*-------------------------------*/
#define	SYNC_INDEX_TREE		900
#define SYNC_TREE_NODE_NEW	892
#define SYNC_TREE_NODE_FROM_HASH 891
#define SYNC_TREE_NODE		890
#define	SYNC_PURGE_SYS		810
#define	SYNC_PURGE_LATCH	800
#define	SYNC_TRX_UNDO		700
#define SYNC_RSEG		600
#define SYNC_RSEG_HEADER_NEW	591
#define SYNC_RSEG_HEADER	590
#define SYNC_TRX_UNDO_PAGE	570
408
#define SYNC_EXTERN_STORAGE	500
409 410 411 412
#define	SYNC_FSP		400
#define	SYNC_FSP_PAGE		395
/*------------------------------------- Insert buffer headers */ 
/*------------------------------------- ibuf_mutex */
unknown's avatar
unknown committed
413
/*------------------------------------- Insert buffer tree */
414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430
#define	SYNC_IBUF_BITMAP_MUTEX	351
#define	SYNC_IBUF_BITMAP	350
/*-------------------------------*/
#define	SYNC_KERNEL		300
#define SYNC_REC_LOCK		299
#define	SYNC_TRX_LOCK_HEAP	298
#define SYNC_TRX_SYS_HEADER	290
#define SYNC_LOG		170
#define SYNC_RECV		168
#define	SYNC_SEARCH_SYS		160	/* NOTE that if we have a memory
					heap that can be extended to the
					buffer pool, its logical level is
					SYNC_SEARCH_SYS, as memory allocation
					can call routines there! Otherwise
					the level is SYNC_MEM_HASH. */
#define	SYNC_BUF_POOL		150
#define	SYNC_BUF_BLOCK		149
431
#define SYNC_DOUBLEWRITE	140
432
#define	SYNC_ANY_LATCH		135
433
#define SYNC_THR_LOCAL		133
434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449
#define	SYNC_MEM_HASH		131
#define	SYNC_MEM_POOL		130

/* Codes used to designate lock operations */
#define RW_LOCK_NOT_LOCKED 	350
#define RW_LOCK_EX		351
#define RW_LOCK_EXCLUSIVE	351
#define RW_LOCK_SHARED		352
#define RW_LOCK_WAIT_EX		353
#define SYNC_MUTEX		354

/* NOTE! The structure appears here only for the compiler to know its size.
Do not use its fields directly! The structure used in the spin lock
implementation of a mutual exclusion semaphore. */

struct mutex_struct {
unknown's avatar
unknown committed
450
	os_event_t	event;	/* Used by sync0arr.c for the wait queue */
451 452
	ulint	lock_word;	/* This ulint is the target of the atomic
				test-and-set instruction in Win32 */
unknown's avatar
unknown committed
453
#if !defined(_WIN32) || !defined(UNIV_CAN_USE_X86_ASSEMBLER)
454 455 456 457 458 459 460 461 462 463
	os_fast_mutex_t
		os_fast_mutex;	/* In other systems we use this OS mutex
				in place of lock_word */
#endif
	ulint	waiters;	/* This ulint is set to 1 if there are (or
				may be) threads waiting in the global wait
				array for this mutex to be released.
				Otherwise, this is 0. */
	UT_LIST_NODE_T(mutex_t)	list; /* All allocated mutexes are put into
				a list.	Pointers to the next and prev. */
464 465 466
#ifdef UNIV_SYNC_DEBUG
	const char*	file_name;	/* File where the mutex was locked */
	ulint	line;		/* Line where the mutex was locked */
467 468
	os_thread_id_t thread_id; /* Debug version: The thread id of the
				thread which locked the mutex. */
469 470
#endif /* UNIV_SYNC_DEBUG */
	ulint	level;		/* Level in the global latching
471
				order; default SYNC_LEVEL_NONE */
472
	const char*	cfile_name;/* File name where mutex created */
473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512
	ulint	cline;		/* Line where created */
	ulint	magic_n;
};

#define MUTEX_MAGIC_N	(ulint)979585

/* The global array of wait cells for implementation of the databases own
mutexes and read-write locks. Appears here for debugging purposes only! */

extern sync_array_t*	sync_primary_wait_array;

/* Constant determining how long spin wait is continued before suspending
the thread. A value 600 rounds on a 1995 100 MHz Pentium seems to correspond
to 20 microseconds. */

#define	SYNC_SPIN_ROUNDS	srv_n_spin_wait_rounds

#define SYNC_INFINITE_TIME	((ulint)(-1))

/* Means that a timeout elapsed when waiting */

#define SYNC_TIME_EXCEEDED	(ulint)1

/* The number of system calls made in this module. Intended for performance
monitoring. */

extern 	ulint	mutex_system_call_count;
extern	ulint	mutex_exit_count;

/* Latching order checks start when this is set TRUE */
extern ibool	sync_order_checks_on;

/* This variable is set to TRUE when sync_init is called */
extern ibool	sync_initialized;

#ifndef UNIV_NONINL
#include "sync0sync.ic"
#endif

#endif