ruby--ruby/include/ruby/thread_native.h

#ifndef RUBY_THREAD_NATIVE_H                         /*-*-C++-*-vi:se ft=cpp:*/
#define RUBY_THREAD_NATIVE_H 1
/**
 * @file
 * @author     $Author: ko1 $
 * @date       Wed May 14 19:37:31 2014
 * @copyright  Copyright (C) 2014 Yukihiro Matsumoto
 * @copyright  This  file  is   a  part  of  the   programming  language  Ruby.
 *             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.
 *
 * Now, we only support pthread and Windows threads.
 *
 * If you want to use Ruby's Mutex and so on to synchronize Ruby Threads,
 * please use Mutex directly.
 */

#if defined(_WIN32)
#include <windows.h>
typedef HANDLE rb_nativethread_id_t;

typedef union rb_thread_lock_union {
    HANDLE mutex;
    CRITICAL_SECTION crit;
} rb_nativethread_lock_t;

typedef struct rb_thread_cond_struct rb_nativethread_cond_t;

#elif defined(HAVE_PTHREAD_H)

#include <pthread.h>
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(__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

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);

/**
 * 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