diff options
Diffstat (limited to 'include/ruby/thread_native.h')
| -rw-r--r-- | include/ruby/thread_native.h | 152 |
1 files changed, 145 insertions, 7 deletions
diff --git a/include/ruby/thread_native.h b/include/ruby/thread_native.h index 343c02c30d..8217a67514 100644 --- a/include/ruby/thread_native.h +++ b/include/ruby/thread_native.h @@ -9,9 +9,7 @@ * Permission is hereby granted, to either redistribute and/or * modify this file, provided that the conditions mentioned in the * file COPYING are met. Consult the file for details. - */ - -/* + * * This file contains wrapper APIs for native thread primitives * which Ruby interpreter uses. * @@ -21,7 +19,6 @@ * please use Mutex directly. */ - #if defined(_WIN32) #include <windows.h> typedef HANDLE rb_nativethread_id_t; @@ -31,6 +28,11 @@ typedef union rb_thread_lock_union { CRITICAL_SECTION crit; } rb_nativethread_lock_t; +struct rb_thread_cond_struct { + struct cond_event_entry *next; + struct cond_event_entry *prev; +}; + typedef struct rb_thread_cond_struct rb_nativethread_cond_t; #elif defined(HAVE_PTHREAD_H) @@ -40,33 +42,169 @@ typedef pthread_t rb_nativethread_id_t; typedef pthread_mutex_t rb_nativethread_lock_t; typedef pthread_cond_t rb_nativethread_cond_t; +#elif defined(__wasi__) // no-thread platforms + +typedef struct rb_nativethread_id_t *rb_nativethread_id_t; +typedef struct rb_nativethread_lock_t *rb_nativethread_lock_t; +typedef struct rb_nativethread_cond_t *rb_nativethread_cond_t; + +#elif defined(__DOXYGEN__) + +/** Opaque type that holds an ID of a native thread. */ +struct rb_nativethread_id_t; + +/** Opaque type that holds a lock. */ +struct rb_nativethread_lock_t; + +/** Opaque type that holds a condition variable. */ +struct rb_nativethread_cond_t; + #else #error "unsupported thread type" #endif -RUBY_SYMBOL_EXPORT_BEGIN +RBIMPL_SYMBOL_EXPORT_BEGIN() +/** + * Queries the ID of the native thread that is calling this function. + * + * @return The caller thread's native ID. + */ rb_nativethread_id_t rb_nativethread_self(void); +/** + * Fills the passed lock with an initial value. + * + * @param[out] lock A mutex to initialise. + * @post `lock` is updated to its initial state. + * + * @internal + * + * There is no data structure that analogous to pthread_once_t in ruby. It is + * pretty much tricky (if not impossible) to properly initialise a mutex + * exactly once. + */ void rb_nativethread_lock_initialize(rb_nativethread_lock_t *lock); + +/** + * Destroys the passed mutex. + * + * @param[out] lock A mutex to kill. + * @post `lock` is no longer eligible for other functions. + * + * @internal + * + * It is an undefined behaviour (see `pthread_mutex_destroy(3posix)`) to + * destroy a locked mutex. So it has to be unlocked. But an unlocked mutex + * can of course be locked by another thread. That's the ultimate reason why + * we do mutex. There is an inevitable race condition here. 2017 edition of + * IEEE 1003.1 issue 7 says in its rationale that "care must be taken". Care? + * How? + * + * @shyouhei thinks that POSIX is broken by design. + */ void rb_nativethread_lock_destroy(rb_nativethread_lock_t *lock); + +/** + * Blocks until the current thread obtains a lock. + * + * @param[out] lock A mutex to lock. + * @post `lock` is owned by the current native thread. + */ void rb_nativethread_lock_lock(rb_nativethread_lock_t *lock); + +/** + * Releases a lock. + * + * @param[out] lock A mutex to unlock. + * @pre `lock` is owned by the current native thread. + * @post `lock` is not owned by the current native thread. + */ void rb_nativethread_lock_unlock(rb_nativethread_lock_t *lock); +/** @alias{rb_nativethread_lock_lock} */ void rb_native_mutex_lock(rb_nativethread_lock_t *lock); + +/** + * Identical to rb_native_mutex_lock(), except it doesn't block in case + * rb_native_mutex_lock() would. + * + * @param[out] lock A mutex to lock. + * @retval 0 `lock` is successfully owned by the current thread. + * @retval EBUSY `lock` is owned by someone else. + */ int rb_native_mutex_trylock(rb_nativethread_lock_t *lock); + +/** @alias{rb_nativethread_lock_unlock} */ void rb_native_mutex_unlock(rb_nativethread_lock_t *lock); + +/** @alias{rb_nativethread_lock_initialize} */ void rb_native_mutex_initialize(rb_nativethread_lock_t *lock); + +/** @alias{rb_nativethread_lock_destroy} */ void rb_native_mutex_destroy(rb_nativethread_lock_t *lock); +/** + * Signals a condition variable. + * + * @param[out] cond A condition variable to ping. + * @post More than one threads waiting for `cond` gets signalled. + * @note This function can spuriously wake multiple threads up. + * `pthread_cond_signal(3posix)` says it can even be "impossible + * to avoid the unblocking of more than one thread blocked on a + * condition variable". Just brace spurious wakeups. + */ void rb_native_cond_signal(rb_nativethread_cond_t *cond); + +/** + * Signals a condition variable. + * + * @param[out] cond A condition variable to ping. + * @post All threads waiting for `cond` gets signalled. + */ void rb_native_cond_broadcast(rb_nativethread_cond_t *cond); + +/** + * Waits for the passed condition variable to be signalled. + * + * @param[out] cond A condition variable to wait. + * @param[out] mutex A mutex. + * @pre `mutex` is owned by the current thread. + * @post `mutex` is owned by the current thread. + * @note This can wake up spuriously. + */ void rb_native_cond_wait(rb_nativethread_cond_t *cond, rb_nativethread_lock_t *mutex); + +/** + * Identical to rb_native_cond_wait(), except it additionally takes timeout in + * msec resolution. Timeouts can be detected by catching exceptions. + * + * @param[out] cond A condition variable to wait. + * @param[out] mutex A mutex. + * @param[in] msec Timeout. + * @exception rb_eSystemCallError `Errno::ETIMEDOUT` for timeout. + * @pre `mutex` is owned by the current thread. + * @post `mutex` is owned by the current thread. + * @note This can wake up spuriously. + */ void rb_native_cond_timedwait(rb_nativethread_cond_t *cond, rb_nativethread_lock_t *mutex, unsigned long msec); + +/** + * Fills the passed condition variable with an initial value. + * + * @param[out] cond A condition variable to initialise. + * @post `cond` is updated to its initial state. + */ void rb_native_cond_initialize(rb_nativethread_cond_t *cond); -void rb_native_cond_destroy(rb_nativethread_cond_t *cond); -RUBY_SYMBOL_EXPORT_END +/** + * Destroys the passed condition variable. + * + * @param[out] cond A condition variable to kill. + * @post `cond` is no longer eligible for other functions. + */ +void rb_native_cond_destroy(rb_nativethread_cond_t *cond); +RBIMPL_SYMBOL_EXPORT_END() #endif |