From 14d410fc8695049691bfb5e70e881020625f7a85 Mon Sep 17 00:00:00 2001 From: Haru Date: Sun, 13 Mar 2016 20:50:19 +0100 Subject: Various changes to the mutex interface Mostly stylistic changes. Cleaned up documentation. Signed-off-by: Haru --- src/common/mutex.c | 95 ++++++++++++++++++++++++++++++------------------------ src/common/mutex.h | 26 ++++++++++----- 2 files changed, 70 insertions(+), 51 deletions(-) (limited to 'src/common') diff --git a/src/common/mutex.c b/src/common/mutex.c index a3f0fd4e5..bdc2fb4dc 100644 --- a/src/common/mutex.c +++ b/src/common/mutex.c @@ -34,6 +34,10 @@ #include #endif +/** @file + * Implementation of the mutex interface. + */ + struct mutex_interface mutex_s; struct mutex_interface *mutex; @@ -57,13 +61,10 @@ struct cond_data { #endif }; -//////////////////// -// Mutex -// -// Implementation: -// +/* Mutex */ -struct mutex_data *ramutex_create(void) +/// @copydoc mutex_interface::create() +struct mutex_data *mutex_create(void) { struct mutex_data *m = aMalloc(sizeof(struct mutex_data)); if (m == NULL) { @@ -78,9 +79,10 @@ struct mutex_data *ramutex_create(void) #endif return m; -}//end: ramutex_create() +} -void ramutex_destroy(struct mutex_data *m) +/// @copydoc mutex_interface::destroy() +void mutex_destroy(struct mutex_data *m) { #ifdef WIN32 DeleteCriticalSection(&m->hMutex); @@ -89,18 +91,20 @@ void ramutex_destroy(struct mutex_data *m) #endif aFree(m); -}//end: ramutex_destroy() +} -void ramutex_lock(struct mutex_data *m) +/// @copydoc mutex_interface::lock() +void mutex_lock(struct mutex_data *m) { #ifdef WIN32 EnterCriticalSection(&m->hMutex); #else pthread_mutex_lock(&m->hMutex); #endif -}//end: ramutex_lock +} -bool ramutex_trylock(struct mutex_data *m) +/// @copydoc mutex_interface::trylock() +bool mutex_trylock(struct mutex_data *m) { #ifdef WIN32 if (TryEnterCriticalSection(&m->hMutex) != FALSE) @@ -110,24 +114,22 @@ bool ramutex_trylock(struct mutex_data *m) return true; #endif return false; -}//end: ramutex_trylock() +} -void ramutex_unlock(struct mutex_data *m) +/// @copydoc mutex_interface::unlock() +void mutex_unlock(struct mutex_data *m) { #ifdef WIN32 LeaveCriticalSection(&m->hMutex); #else pthread_mutex_unlock(&m->hMutex); #endif -}//end: ramutex_unlock() +} -/////////////// -// Condition Variables -// -// Implementation: -// +/* Conditional variable */ -struct cond_data *racond_create(void) +/// @copydoc mutex_interface::cond_create() +struct cond_data *cond_create(void) { struct cond_data *c = aMalloc(sizeof(struct cond_data)); if (c == NULL) { @@ -145,9 +147,10 @@ struct cond_data *racond_create(void) #endif return c; -}//end: racond_create() +} -void racond_destroy(struct cond_data *c) +/// @copydoc mutex_interface::cond_destroy() +void cond_destroy(struct cond_data *c) { #ifdef WIN32 CloseHandle(c->events[EVENT_COND_SIGNAL]); @@ -158,9 +161,10 @@ void racond_destroy(struct cond_data *c) #endif aFree(c); -}//end: racond_destroy() +} -void racond_wait(struct cond_data *c, struct mutex_data *m, sysint timeout_ticks) +/// @copydoc mutex_interface::cond_wait() +void cond_wait(struct cond_data *c, struct mutex_data *m, sysint timeout_ticks) { #ifdef WIN32 register DWORD ms; @@ -209,9 +213,10 @@ void racond_wait(struct cond_data *c, struct mutex_data *m, sysint timeout_ticks pthread_cond_timedwait( &c->hCond, &m->hMutex, &wtime); } #endif -}//end: racond_wait() +} -void racond_signal(struct cond_data *c) +/// @copydoc mutex_interface::cond_signal() +void cond_signal(struct cond_data *c) { #ifdef WIN32 # if 0 @@ -223,13 +228,14 @@ void racond_signal(struct cond_data *c) if(has_waiters == true) # endif // 0 - SetEvent( c->events[ EVENT_COND_SIGNAL ] ); + SetEvent(c->events[EVENT_COND_SIGNAL]); #else pthread_cond_signal(&c->hCond); #endif -}//end: racond_signal() +} -void racond_broadcast(struct cond_data *c) +/// @copydoc mutex_interface::cond_broadcast() +void cond_broadcast(struct cond_data *c) { #ifdef WIN32 # if 0 @@ -241,24 +247,27 @@ void racond_broadcast(struct cond_data *c) if(has_waiters == true) # endif // 0 - SetEvent( c->events[ EVENT_COND_BROADCAST ] ); + SetEvent(c->events[EVENT_COND_BROADCAST]); #else pthread_cond_broadcast(&c->hCond); #endif -}//end: racond_broadcast() +} +/** + * Interface base initialization. + */ void mutex_defaults(void) { mutex = &mutex_s; - mutex->create = ramutex_create; - mutex->destroy = ramutex_destroy; - mutex->lock = ramutex_lock; - mutex->trylock = ramutex_trylock; - mutex->unlock = ramutex_unlock; - - mutex->cond_create = racond_create; - mutex->cond_destroy = racond_destroy; - mutex->cond_wait = racond_wait; - mutex->cond_signal = racond_signal; - mutex->cond_broadcast = racond_broadcast; + mutex->create = mutex_create; + mutex->destroy = mutex_destroy; + mutex->lock = mutex_lock; + mutex->trylock = mutex_trylock; + mutex->unlock = mutex_unlock; + + mutex->cond_create = cond_create; + mutex->cond_destroy = cond_destroy; + mutex->cond_wait = cond_wait; + mutex->cond_signal = cond_signal; + mutex->cond_broadcast = cond_broadcast; } diff --git a/src/common/mutex.h b/src/common/mutex.h index 2365cf4e9..0569fb0da 100644 --- a/src/common/mutex.h +++ b/src/common/mutex.h @@ -23,21 +23,28 @@ #include "common/hercules.h" +/** @file + * Mutex and conditional variables implementation for Hercules. + */ + /* Opaque types */ + struct mutex_data; ///< Mutex struct cond_data; ///< Conditional variable /* Interface */ + +/// The mutex interface. struct mutex_interface { /** - * Creates a Mutex + * Creates a mutex. * * @return The created mutex. */ struct mutex_data *(*create) (void); /** - * Destroys a Mutex. + * Destroys a mutex. * * @param m the mutex to destroy. */ @@ -46,6 +53,8 @@ struct mutex_interface { /** * Gets a lock. * + * This function blocks until the lock can be acquired. + * * @param m The mutex to lock. */ void (*lock) (struct mutex_data *m); @@ -53,6 +62,8 @@ struct mutex_interface { /** * Tries to get a lock. * + * This function returns immediately. + * * @param m The mutex to try to lock. * @return success status. * @retval true if the lock was acquired. @@ -67,18 +78,17 @@ struct mutex_interface { */ void (*unlock) (struct mutex_data *m); - /** - * Creates a Condition variable. + * Creates a conditional variable. * - * @return the created condition variable. + * @return the created conditional variable. */ struct cond_data *(*cond_create) (void); /** - * Destroys a Condition variable. + * Destroys a conditional variable. * - * @param c the condition variable to destroy. + * @param c the conditional variable to destroy. */ void (*cond_destroy) (struct cond_data *c); @@ -116,6 +126,6 @@ struct mutex_interface { void mutex_defaults(void); #endif // HERCULES_CORE -HPShared struct mutex_interface *mutex; +HPShared struct mutex_interface *mutex; ///< Pointer to the mutex interface. #endif /* COMMON_MUTEX_H */ -- cgit v1.2.3-70-g09d2