Ruby: include/ruby/thread_native.h File Reference

Ruby 3.3.4p94 (2024-07-09 revision be1089c8ec5ba40e09b1553e36b3174bf4014d9d)

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.

## ◆ 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.

## ◆ 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.

## ◆ 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.

## ◆ 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 | `ErrnoETIMEDOUT` for timeout.

Precondition
  `mutex` is owned by the current thread.

Postcondition
  `mutex` is owned by the current thread.

Note
  This can wake up spuriously.

## ◆ 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.

## ◆ 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_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_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_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.

## ◆ 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_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 292 of file thread.c.

Referenced by rb_nativethread_lock_destroy().

## ◆ 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 286 of file thread.c.

Referenced by rb_nativethread_lock_initialize().

## ◆ 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 298 of file thread.c.

Referenced by rb_nativethread_lock_lock().

## ◆ 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 304 of file thread.c.

Referenced by rb_nativethread_lock_unlock().

## ◆ 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.