diff --git a/libretro-common/include/rthreads/rthreads.h b/libretro-common/include/rthreads/rthreads.h index 8176092a670c..7e30c85cd3fd 100644 --- a/libretro-common/include/rthreads/rthreads.h +++ b/libretro-common/include/rthreads/rthreads.h @@ -192,85 +192,97 @@ scond_t *scond_new(void); void scond_free(scond_t *cond); /** - * scond_wait: - * @cond : pointer to condition variable object - * @lock : pointer to mutex object + * Blocks until the given condition variable is signaled or broadcast. * - * Block on a condition variable (i.e. wait on a condition). - **/ + * @param cond Condition variable to wait on. + * This function blocks until another thread + * calls \c scond_signal or \c scond_broadcast with this condition variable. + * @param lock Mutex to lock while waiting. + * + * @see scond_signal + * @see scond_broadcast + * @see scond_wait_timeout + */ void scond_wait(scond_t *cond, slock_t *lock); /** - * scond_wait_timeout: - * @cond : pointer to condition variable object - * @lock : pointer to mutex object - * @timeout_us : timeout (in microseconds) + * Blocks until the given condition variable is signaled or broadcast, + * or until the specified time has passed. * - * Try to block on a condition variable (i.e. wait on a condition) until - * @timeout_us elapses. + * @param cond Condition variable to wait on. + * This function blocks until another thread + * calls \c scond_signal or \c scond_broadcast with this condition variable. + * @param lock Mutex to lock while waiting. + * @param timeout_us Time to wait for a signal, in microseconds. * - * Returns: false (0) if timeout elapses before condition variable is - * signaled or broadcast, otherwise true (1). - **/ + * @return \c false if \c timeout_us elapses + * before \c cond is signaled or broadcast, otherwise \c true. + */ bool scond_wait_timeout(scond_t *cond, slock_t *lock, int64_t timeout_us); /** - * scond_broadcast: - * @cond : pointer to condition variable object + * Unblocks all threads waiting on the specified condition variable. * - * Broadcast a condition. Unblocks all threads currently blocked - * on the specified condition variable @cond. - **/ + * @param cond Condition variable to broadcast. + * @return 0 on success, non-zero on failure. + */ int scond_broadcast(scond_t *cond); /** - * scond_signal: - * @cond : pointer to condition variable object + * Unblocks at least one thread waiting on the specified condition variable. * - * Signal a condition. Unblocks at least one of the threads currently blocked - * on the specified condition variable @cond. - **/ + * @param cond Condition variable to signal. + */ void scond_signal(scond_t *cond); #ifdef HAVE_THREAD_STORAGE /** - * @brief Creates a thread-local storage key. + * Creates a thread-local storage key. * - * This function shall create thread-specific data key visible to all threads in - * the process. The same key can be used by multiple threads to store - * thread-local data. + * Thread-local storage keys have a single value associated with them + * that is unique to the thread that uses them. * - * When the key is created NULL shall be associated with it in all active - * threads. Whenever a new thread is spawned the all defined keys will be - * associated with NULL on that thread. + * New thread-local storage keys have a value of \c NULL for all threads, + * and new threads initialize all existing thread-local storage to \c NULL. * - * @param tls Pointer to the thread local storage key that will be initialized. + * @param tls[in,out] Pointer to the thread local storage key that will be initialized. + * Must be cleaned up with \c sthread_tls_delete. * Behavior is undefined if \c NULL. * @return \c true if the operation succeeded, \c false otherwise. + * @see sthread_tls_delete */ bool sthread_tls_create(sthread_tls_t *tls); /** - * @brief Deletes a thread local storage - * @param tls - * @return whether the operation suceeded or not + * Deletes a thread local storage key. + * + * The value must be cleaned up separately \em before calling this function, + * if necessary. + * + * @param tls The thread local storage key to delete. + * Behavior is undefined if \c NULL. + * @return \c true if the operation succeeded, \c false otherwise. */ bool sthread_tls_delete(sthread_tls_t *tls); /** - * @brief Retrieves thread specific data associated with a key + * Gets the calling thread's local data for the given key. * - * There is no way to tell whether this function failed. - * - * @param tls - * @return + * @param tls The thread-local storage key to get the data for. + * @return The calling thread's local data associated with \c tls, + * which should previously have been set with \c sthread_tls_set. + * Will be \c NULL if this thread has not set a value or if there was an error. */ void *sthread_tls_get(sthread_tls_t *tls); /** - * @brief Binds thread specific data to a key - * @param tls - * @return Whether the operation suceeded or not + * Sets the calling thread's local data for the given key. + * + * @param tls The thread-local storage key to set the data for. + * @param data Pointer to the data that will be associated with \c tls. + * May be \c NULL. + * @return \c true if \c data was successfully assigned to \c tls, + * \c false if there was an error. */ bool sthread_tls_set(sthread_tls_t *tls, const void *data); #endif diff --git a/libretro-common/rthreads/rthreads.c b/libretro-common/rthreads/rthreads.c index c34bf2ff48f3..da9a29159509 100644 --- a/libretro-common/rthreads/rthreads.c +++ b/libretro-common/rthreads/rthreads.c @@ -202,7 +202,7 @@ sthread_t *sthread_create_with_priority(void (*thread_func)(void*), void *userda pthread_attr_setstacksize(&thread_attr , 0x10000 ); thread_attr_needed = true; #elif defined(__APPLE__) - /* Default stack size on Apple is 512Kb; + /* Default stack size on Apple is 512Kb; * for PS2 disc scanning and other reasons, we'd like 2MB. */ pthread_attr_setstacksize(&thread_attr , 0x200000 ); thread_attr_needed = true; @@ -325,15 +325,6 @@ void slock_unlock(slock_t *lock) #endif } -/** - * scond_new: - * - * Creates and initializes a condition variable. Must - * be manually freed. - * - * Returns: pointer to new condition variable on success, - * otherwise NULL. - **/ scond_t *scond_new(void) { scond_t *cond = (scond_t*)calloc(1, sizeof(*cond)); @@ -609,13 +600,6 @@ static bool _scond_wait_win32(scond_t *cond, slock_t *lock, DWORD dwMilliseconds } #endif -/** - * scond_wait: - * @cond : pointer to condition variable object - * @lock : pointer to mutex object - * - * Block on a condition variable (i.e. wait on a condition). - **/ void scond_wait(scond_t *cond, slock_t *lock) { #ifdef USE_WIN32_THREADS @@ -625,13 +609,6 @@ void scond_wait(scond_t *cond, slock_t *lock) #endif } -/** - * scond_broadcast: - * @cond : pointer to condition variable object - * - * Broadcast a condition. Unblocks all threads currently blocked - * on the specified condition variable @cond. - **/ int scond_broadcast(scond_t *cond) { #ifdef USE_WIN32_THREADS @@ -652,13 +629,6 @@ int scond_broadcast(scond_t *cond) #endif } -/** - * scond_signal: - * @cond : pointer to condition variable object - * - * Signal a condition. Unblocks at least one of the threads currently blocked - * on the specified condition variable @cond. - **/ void scond_signal(scond_t *cond) { #ifdef USE_WIN32_THREADS @@ -698,18 +668,6 @@ void scond_signal(scond_t *cond) #endif } -/** - * scond_wait_timeout: - * @cond : pointer to condition variable object - * @lock : pointer to mutex object - * @timeout_us : timeout (in microseconds) - * - * Try to block on a condition variable (i.e. wait on a condition) until - * @timeout_us elapses. - * - * Returns: false (0) if timeout elapses before condition variable is - * signaled or broadcast, otherwise true (1). - **/ bool scond_wait_timeout(scond_t *cond, slock_t *lock, int64_t timeout_us) { #ifdef USE_WIN32_THREADS