diff options
Diffstat (limited to 'storage/xtradb/include/sync0arr.h')
| -rw-r--r-- | storage/xtradb/include/sync0arr.h | 74 |
1 files changed, 39 insertions, 35 deletions
diff --git a/storage/xtradb/include/sync0arr.h b/storage/xtradb/include/sync0arr.h index cc01c9ac5c8..5f1280f5e28 100644 --- a/storage/xtradb/include/sync0arr.h +++ b/storage/xtradb/include/sync0arr.h @@ -16,7 +16,8 @@ Place, Suite 330, Boston, MA 02111-1307 USA *****************************************************************************/ -/****************************************************** +/**************************************************//** +@file include/sync0arr.h The wait array used in synchronization primitives Created 9/5/1995 Heikki Tuuri @@ -30,47 +31,51 @@ Created 9/5/1995 Heikki Tuuri #include "ut0mem.h" #include "os0thread.h" +/** Synchronization wait array cell */ typedef struct sync_cell_struct sync_cell_t; +/** Synchronization wait array */ typedef struct sync_array_struct sync_array_t; -#define SYNC_ARRAY_OS_MUTEX 1 -#define SYNC_ARRAY_MUTEX 2 +/** Parameters for sync_array_create() @{ */ +#define SYNC_ARRAY_OS_MUTEX 1 /*!< protected by os_mutex_t */ +#define SYNC_ARRAY_MUTEX 2 /*!< protected by mutex_t */ +/* @} */ -/*********************************************************************** +/*******************************************************************//** Creates a synchronization wait array. It is protected by a mutex which is automatically reserved when the functions operating on it -are called. */ +are called. +@return own: created wait array */ UNIV_INTERN sync_array_t* sync_array_create( /*==============*/ - /* out, own: created wait array */ - ulint n_cells, /* in: number of cells in the array + ulint n_cells, /*!< in: number of cells in the array to create */ - ulint protection); /* in: either SYNC_ARRAY_OS_MUTEX or + ulint protection); /*!< in: either SYNC_ARRAY_OS_MUTEX or SYNC_ARRAY_MUTEX: determines the type of mutex protecting the data structure */ -/********************************************************************** +/******************************************************************//** Frees the resources in a wait array. */ UNIV_INTERN void sync_array_free( /*============*/ - sync_array_t* arr); /* in, own: sync wait array */ -/********************************************************************** + sync_array_t* arr); /*!< in, own: sync wait array */ +/******************************************************************//** Reserves a wait array cell for waiting for an object. The event of the cell is reset to nonsignalled state. */ UNIV_INTERN void sync_array_reserve_cell( /*====================*/ - sync_array_t* arr, /* in: wait array */ - void* object, /* in: pointer to the object to wait for */ - ulint type, /* in: lock request type */ - const char* file, /* in: file where requested */ - ulint line, /* in: line where requested */ - ulint* index); /* out: index of the reserved cell */ -/********************************************************************** + sync_array_t* arr, /*!< in: wait array */ + void* object, /*!< in: pointer to the object to wait for */ + ulint type, /*!< in: lock request type */ + const char* file, /*!< in: file where requested */ + ulint line, /*!< in: line where requested */ + ulint* index); /*!< out: index of the reserved cell */ +/******************************************************************//** This function should be called when a thread starts to wait on a wait array cell. In the debug version this function checks if the wait for a semaphore will result in a deadlock, in which @@ -79,25 +84,25 @@ UNIV_INTERN void sync_array_wait_event( /*==================*/ - sync_array_t* arr, /* in: wait array */ - ulint index); /* in: index of the reserved cell */ -/********************************************************************** + sync_array_t* arr, /*!< in: wait array */ + ulint index); /*!< in: index of the reserved cell */ +/******************************************************************//** Frees the cell. NOTE! sync_array_wait_event frees the cell automatically! */ UNIV_INTERN void sync_array_free_cell( /*=================*/ - sync_array_t* arr, /* in: wait array */ - ulint index); /* in: index of the cell in array */ -/************************************************************************** + sync_array_t* arr, /*!< in: wait array */ + ulint index); /*!< in: index of the cell in array */ +/**********************************************************************//** Note that one of the wait objects was signalled. */ UNIV_INTERN void sync_array_object_signalled( /*========================*/ - sync_array_t* arr); /* in: wait array */ -/************************************************************************** + sync_array_t* arr); /*!< in: wait array */ +/**********************************************************************//** If the wakeup algorithm does not work perfectly at semaphore relases, this function will do the waking (see the comment in mutex_exit). This function should be called about every 1 second in the server. */ @@ -105,30 +110,29 @@ UNIV_INTERN void sync_arr_wake_threads_if_sema_free(void); /*====================================*/ -/************************************************************************** -Prints warnings of long semaphore waits to stderr. */ +/**********************************************************************//** +Prints warnings of long semaphore waits to stderr. +@return TRUE if fatal semaphore wait threshold was exceeded */ UNIV_INTERN ibool sync_array_print_long_waits(void); /*=============================*/ - /* out: TRUE if fatal semaphore wait threshold - was exceeded */ -/************************************************************************ +/********************************************************************//** Validates the integrity of the wait array. Checks that the number of reserved cells equals the count variable. */ UNIV_INTERN void sync_array_validate( /*================*/ - sync_array_t* arr); /* in: sync wait array */ -/************************************************************************** + sync_array_t* arr); /*!< in: sync wait array */ +/**********************************************************************//** Prints info of the wait array. */ UNIV_INTERN void sync_array_print_info( /*==================*/ - FILE* file, /* in: file where to print */ - sync_array_t* arr); /* in: wait array */ + FILE* file, /*!< in: file where to print */ + sync_array_t* arr); /*!< in: wait array */ #ifndef UNIV_NONINL |