Ruby: include/ruby/thread_native.h File Reference

Ruby 4.0.6p0 (2026-07-14 revision 03b6d3f8898a28604fe6cb00eae3226b821168f4)

Functions
thread_native.h File Reference

Go to the source code of this file.

## Functions
rb_nativethread_id_t | rb_nativethread_self (void)
| Queries the ID of the native thread that is calling this function.
void | rb_nativethread_lock_initialize (rb_nativethread_lock_t *lock)
| Fills the passed lock with an initial value.
void | rb_nativethread_lock_destroy (rb_nativethread_lock_t *lock)
| Destroys the passed mutex.
void | rb_nativethread_lock_lock (rb_nativethread_lock_t *lock)
| Blocks until the current thread obtains a lock.
void | rb_nativethread_lock_unlock (rb_nativethread_lock_t *lock)
| Releases a lock.
void | rb_native_mutex_lock (rb_nativethread_lock_t *lock)
| Just another name of rb_nativethread_lock_lock.
int | rb_native_mutex_trylock (rb_nativethread_lock_t *lock)
| Identical to rb_native_mutex_lock(), except it doesn't block in case rb_native_mutex_lock() would.
void | rb_native_mutex_unlock (rb_nativethread_lock_t *lock)
| Just another name of rb_nativethread_lock_unlock.
void | rb_native_mutex_initialize (rb_nativethread_lock_t *lock)
| Just another name of rb_nativethread_lock_initialize.
void | rb_native_mutex_destroy (rb_nativethread_lock_t *lock)
| Just another name of rb_nativethread_lock_destroy.
void | rb_native_cond_signal (rb_nativethread_cond_t *cond)
| Signals a condition variable.
void | rb_native_cond_broadcast (rb_nativethread_cond_t *cond)
| Signals a condition variable.
void | rb_native_cond_wait (rb_nativethread_cond_t *cond, rb_nativethread_lock_t *mutex)
| Waits for the passed condition variable to be signalled.
void | rb_native_cond_timedwait (rb_nativethread_cond_t *cond, rb_nativethread_lock_t *mutex, unsigned long msec)
| Identical to rb_native_cond_wait(), except it additionally takes timeout in msec resolution.
void | rb_native_cond_initialize (rb_nativethread_cond_t *cond)
| Fills the passed condition variable with an initial value.
void | rb_native_cond_destroy (rb_nativethread_cond_t *cond)
| Destroys the passed condition variable.

## Detailed Description

Author

Author
  ko1

Date
  Wed May 14 19:37:31 2014

Copyright
  Copyright (C) 2014 Yukihiro Matsumoto
  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.

Definition in file thread_native.h.

## Function Documentation

## ◆ rb_native_cond_broadcast()

void rb_native_cond_broadcast | ( | rb_nativethread_cond_t * | cond | ) |

Signals a condition variable.

Parameters

  [out] | cond | A condition variable to ping.

Postcondition
  All threads waiting for cond gets signalled.

Referenced by rb_native_cond_broadcast().

## ◆ rb_native_cond_destroy()

void rb_native_cond_destroy | ( | rb_nativethread_cond_t * | cond | ) |

Destroys the passed condition variable.

Parameters

  [out] | cond | A condition variable to kill.

Postcondition
  cond is no longer eligible for other functions.

Referenced by rb_native_cond_destroy().

## ◆ rb_native_cond_initialize()

void rb_native_cond_initialize | ( | rb_nativethread_cond_t * | cond | ) |

Fills the passed condition variable with an initial value.

Parameters

  [out] | cond | A condition variable to initialise.

Postcondition
  cond is updated to its initial state.

Referenced by rb_native_cond_initialize().

## ◆ rb_native_cond_signal()

void rb_native_cond_signal | ( | rb_nativethread_cond_t * | cond | ) |

Signals a condition variable.

Parameters

  [out] | cond | A condition variable to ping.

Postcondition
  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.

Referenced by rb_native_cond_signal().

## ◆ rb_native_cond_timedwait()

void rb_native_cond_timedwait | ( | rb_nativethread_cond_t * | cond,
|  | rb_nativethread_lock_t * | mutex,
|  | unsigned long | msec )

Identical to rb_native_cond_wait(), except it additionally takes timeout in msec resolution.

Timeouts can be detected by catching exceptions.

Parameters

  [out] | cond | A condition variable to wait.
  [out] | mutex | A mutex.
  [in] | msec | Timeout.

Exceptions

  rb_eSystemCallError | `Errno::ETIMEDOUT` for timeout.

Precondition
  mutex is owned by the current thread.

Postcondition
  mutex is owned by the current thread.

Note
  This can wake up spuriously.

Referenced by rb_native_cond_timedwait().

## ◆ rb_native_cond_wait()

void rb_native_cond_wait | ( | rb_nativethread_cond_t * | cond,
|  | rb_nativethread_lock_t * | mutex )

Waits for the passed condition variable to be signalled.

Parameters

  [out] | cond | A condition variable to wait.
  [out] | mutex | A mutex.

Precondition
  mutex is owned by the current thread.

Postcondition
  mutex is owned by the current thread.

Note
  This can wake up spuriously.

Referenced by rb_native_cond_wait().

## ◆ rb_native_mutex_destroy()

void rb_native_mutex_destroy | ( | rb_nativethread_lock_t * | lock | ) |

Just another name of rb_nativethread_lock_destroy.

Referenced by rb_native_mutex_destroy(), rb_nativethread_lock_destroy(), and ruby_vm_destruct().

## ◆ rb_native_mutex_initialize()

void rb_native_mutex_initialize | ( | rb_nativethread_lock_t * | lock | ) |

Just another name of rb_nativethread_lock_initialize.

Referenced by rb_native_mutex_initialize(), and rb_nativethread_lock_initialize().

## ◆ rb_native_mutex_lock()

void rb_native_mutex_lock | ( | rb_nativethread_lock_t * | lock | ) |

Just another name of rb_nativethread_lock_lock.

Referenced by rb_native_mutex_lock(), and rb_nativethread_lock_lock().

## ◆ rb_native_mutex_trylock()

int rb_native_mutex_trylock | ( | rb_nativethread_lock_t * | lock | ) |

Identical to rb_native_mutex_lock(), except it doesn't block in case rb_native_mutex_lock() would.

Parameters

  [out] | lock | A mutex to lock.

Return values

  0 | lock is successfully owned by the current thread.
  EBUSY | lock is owned by someone else.

Referenced by rb_native_mutex_trylock().

## ◆ rb_native_mutex_unlock()

void rb_native_mutex_unlock | ( | rb_nativethread_lock_t * | lock | ) |

Just another name of rb_nativethread_lock_unlock.

Referenced by rb_native_mutex_unlock(), and rb_nativethread_lock_unlock().

## ◆ rb_nativethread_lock_destroy()

void rb_nativethread_lock_destroy | ( | rb_nativethread_lock_t * | lock | ) |

Destroys the passed mutex.

Parameters

  [out] | lock | A mutex to kill.

Postcondition
  lock is no longer eligible for other functions.

Definition at line 301 of file thread.c.

Referenced by rb_nativethread_lock_destroy(), and rb_nativethread_self().

## ◆ rb_nativethread_lock_initialize()

void rb_nativethread_lock_initialize | ( | rb_nativethread_lock_t * | lock | ) |

Fills the passed lock with an initial value.

Parameters

  [out] | lock | A mutex to initialise.

Postcondition
  lock is updated to its initial state.

Definition at line 295 of file thread.c.

Referenced by rb_nativethread_lock_initialize(), and rb_nativethread_self().

## ◆ rb_nativethread_lock_lock()

void rb_nativethread_lock_lock | ( | rb_nativethread_lock_t * | lock | ) |

Blocks until the current thread obtains a lock.

Parameters

  [out] | lock | A mutex to lock.

Postcondition
  lock is owned by the current native thread.

Definition at line 307 of file thread.c.

Referenced by rb_nativethread_lock_lock(), and rb_nativethread_self().

## ◆ rb_nativethread_lock_unlock()

void rb_nativethread_lock_unlock | ( | rb_nativethread_lock_t * | lock | ) |

Releases a lock.

Parameters

  [out] | lock | A mutex to unlock.

Precondition
  lock is owned by the current native thread.

Postcondition
  lock is not owned by the current native thread.

Definition at line 313 of file thread.c.

Referenced by rb_nativethread_lock_unlock(), and rb_nativethread_self().

## ◆ rb_nativethread_self()

rb_nativethread_id_t rb_nativethread_self | ( | void |  | ) |

Queries the ID of the native thread that is calling this function.

Returns
  The caller thread's native ID.

Referenced by rb_nativethread_self().