Ruby: include/ruby/thread.h File Reference

Ruby 3.4.3p32 (2025-04-14 revision d0b7e5b6a04bde21ca483d20a1546b28b401c2d4)

Data Structures | Macros | Typedefs | Functions
thread.h File Reference
`#include "ruby/internal/attr/nonnull.h"`
`#include "ruby/internal/intern/thread.h"`
`#include "ruby/internal/dllexport.h"`

Go to the source code of this file.

## Data Structures
struct | rb_internal_thread_event_data

## Macros
#define | RUBY_CALL_WO_GVL_FLAG_SKIP_CHECK_INTS_AFTER 0x01
#define | RUBY_CALL_WO_GVL_FLAG_SKIP_CHECK_INTS_
#define | RUBY_INTERNAL_THREAD_EVENT_STARTED 1 << 0
| Triggered when a new thread is started.
#define | RUBY_INTERNAL_THREAD_EVENT_READY 1 << 1 /** acquiring GVL */
| Triggered when a thread attempt to acquire the GVL.
#define | RUBY_INTERNAL_THREAD_EVENT_RESUMED 1 << 2 /** acquired GVL */
| Triggered when a thread successfully acquired the GVL.
#define | RUBY_INTERNAL_THREAD_EVENT_SUSPENDED 1 << 3 /** released GVL */
| Triggered when a thread released the GVL.
#define | RUBY_INTERNAL_THREAD_EVENT_EXITED 1 << 4 /** thread terminated */
| Triggered when a thread exits.
#define | RUBY_INTERNAL_THREAD_EVENT_MASK 0xff /** All Thread events */
#define | RB_INTERNAL_THREAD_SPECIFIC_KEY_MAX 8
Flags for rb_nogvl()
#define | RB_NOGVL_INTR_FAIL (0x1)
| Passing this flag to rb_nogvl() prevents it from checking interrupts.
#define | RB_NOGVL_UBF_ASYNC_SAFE (0x2)
| Passing this flag to rb_nogvl() indicates that the passed UBF is async-signal-safe.
#define | RB_NOGVL_OFFLOAD_SAFE (0x4)
| Passing this flag to rb_nogvl() indicates that the passed function is safe to offload to a background thread or work pool.

## Typedefs
typedef struct rb_internal_thread_event_data | rb_internal_thread_event_data_t
typedef void(* | rb_internal_thread_event_callback) (rb_event_flag_t event, const rb_internal_thread_event_data_t *event_data, void *user_data)
typedef struct rb_internal_thread_event_hook | rb_internal_thread_event_hook_t
typedef int | rb_internal_thread_specific_key_t

## Functions
void * | rb_thread_call_with_gvl (void *(*func)(void *), void *data1)
| (Re-)acquires the GVL.
void * | rb_thread_call_without_gvl (void *(*func)(void *), void *data1, rb_unblock_function_t *ubf, void *data2)
| Allows the passed function to run in parallel with other Ruby threads.
void * | rb_thread_call_without_gvl2 (void *(*func)(void *), void *data1, rb_unblock_function_t *ubf, void *data2)
| Identical to rb_thread_call_without_gvl(), except it does not interface with signals etc.
void * | rb_nogvl (void *(*func)(void *), void *data1, rb_unblock_function_t *ubf, void *data2, int flags)
| Identical to rb_thread_call_without_gvl(), except it additionally takes "flags" that change the behaviour.
bool | rb_thread_lock_native_thread (void)
| Declare the current Ruby thread should acquire a dedicated native thread on M:N thread scheduler.
rb_internal_thread_event_hook_t * | rb_internal_thread_add_event_hook (rb_internal_thread_event_callback func, rb_event_flag_t events, void *data)
| Registers a thread event hook function.
bool | rb_internal_thread_remove_event_hook (rb_internal_thread_event_hook_t *hook)
| Unregister the passed hook.
rb_internal_thread_specific_key_t | rb_internal_thread_specific_key_create (void)
| Create a key to store thread specific data.
void * | rb_internal_thread_specific_get (VALUE thread_val, rb_internal_thread_specific_key_t key)
| Get thread and tool specific data.
void | rb_internal_thread_specific_set (VALUE thread_val, rb_internal_thread_specific_key_t key, void *data)
| Set thread and tool specific data.

## Detailed Description

Author

Author
  matz

Date
  Tue Jul 10 17:35:43 JST 2012

Copyright
  Copyright (C) 2007 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.

Definition in file thread.h.

## Macro Definition Documentation

## ◆ RB_INTERNAL_THREAD_SPECIFIC_KEY_MAX

#define RB_INTERNAL_THREAD_SPECIFIC_KEY_MAX 8

Definition at line 298 of file thread.h.

## ◆ RB_NOGVL_INTR_FAIL

#define RB_NOGVL_INTR_FAIL (0x1)

Passing this flag to rb_nogvl() prevents it from checking interrupts.

Interrupts can impact your program negatively. For instance consider following callback function:

static inline int fd; // set elsewhere.
static inline auto callback(auto buf) {
auto tmp = ruby_xmalloc(BUFSIZ);
auto ret = ruby_xmalloc(sizeof(ssize_t)); // (a)
auto n = read(fd, tmp, BUFSIZ); // (b)
memcpy(buf, tmp, n); // (c)
memcpy(ret, n, sizeof(n));
ruby_xfree(tmp);
return ret;
}

Here, if it gets interrupted at (a) or (b), `read(2)` is cancelled and this function leaks memory (which is not a good thing of course, but...). But if it gets interrupted at (c), where `read(2)` is already done, interruption is way more catastrophic because what was read gets lost. To reroute this kind of problem you should set this flag. And check interrupts elsewhere at your own risk.

Definition at line 48 of file thread.h.

Referenced by rb_nogvl(), and rb_thread_call_without_gvl2().

## ◆ RB_NOGVL_OFFLOAD_SAFE

#define RB_NOGVL_OFFLOAD_SAFE (0x4)

Passing this flag to rb_nogvl() indicates that the passed function is safe to offload to a background thread or work pool.

In other words, the function is safe to run using a fiber scheduler's `blocking_operation_wait`. hook.

If your function depends on thread-local storage, or thread-specific data operations/data structures, you should not set this flag, as these operations may behave differently (or fail) when run in a different thread/context (e.g. unlocking a mutex).

Definition at line 73 of file thread.h.

Referenced by rb_nogvl().

## ◆ RB_NOGVL_UBF_ASYNC_SAFE

#define RB_NOGVL_UBF_ASYNC_SAFE (0x2)

Passing this flag to rb_nogvl() indicates that the passed UBF is async-signal-safe.

An UBF could be async safe, and that makes things simpler. However async unsafe UBFs are just okay. If unsure, you can safely leave it unspecified.

Definition at line 60 of file thread.h.

Referenced by rb_nogvl().

## ◆ RUBY_CALL_WO_GVL_FLAG_SKIP_CHECK_INTS_

#define RUBY_CALL_WO_GVL_FLAG_SKIP_CHECK_INTS_

Deprecated
  It seems even in the old days it made no sense...?

Definition at line 204 of file thread.h.

## ◆ RUBY_CALL_WO_GVL_FLAG_SKIP_CHECK_INTS_AFTER

#define RUBY_CALL_WO_GVL_FLAG_SKIP_CHECK_INTS_AFTER 0x01

Deprecated
  This macro once was a thing in the old days, but makes no sense any longer today. Exists here for backwards compatibility only. You can safely forget about it.

Definition at line 198 of file thread.h.

## ◆ RUBY_INTERNAL_THREAD_EVENT_EXITED

#define RUBY_INTERNAL_THREAD_EVENT_EXITED 1 << 4 /** thread terminated */

Triggered when a thread exits.

Note
  The callback will be called without the GVL held.

Definition at line 252 of file thread.h.

## ◆ RUBY_INTERNAL_THREAD_EVENT_MASK

#define RUBY_INTERNAL_THREAD_EVENT_MASK 0xff /** All Thread events */

Definition at line 254 of file thread.h.

## ◆ RUBY_INTERNAL_THREAD_EVENT_READY

#define RUBY_INTERNAL_THREAD_EVENT_READY 1 << 1 /** acquiring GVL */

Triggered when a thread attempt to acquire the GVL.

Note
  The callback will be called without the GVL held.

Definition at line 231 of file thread.h.

## ◆ RUBY_INTERNAL_THREAD_EVENT_RESUMED

#define RUBY_INTERNAL_THREAD_EVENT_RESUMED 1 << 2 /** acquired GVL */

Triggered when a thread successfully acquired the GVL.

Note
  The callback will be called with the GVL held.

Definition at line 238 of file thread.h.

## ◆ RUBY_INTERNAL_THREAD_EVENT_STARTED

#define RUBY_INTERNAL_THREAD_EVENT_STARTED 1 << 0

Triggered when a new thread is started.

Note
  The callback will be called without the GVL held.

Definition at line 224 of file thread.h.

## ◆ RUBY_INTERNAL_THREAD_EVENT_SUSPENDED

#define RUBY_INTERNAL_THREAD_EVENT_SUSPENDED 1 << 3 /** released GVL */

Triggered when a thread released the GVL.

Note
  The callback will be called without the GVL held.

Definition at line 245 of file thread.h.

## Typedef Documentation

## ◆ rb_internal_thread_event_callback

typedef void(* rb_internal_thread_event_callback) (rb_event_flag_t event, const rb_internal_thread_event_data_t *event_data, void *user_data)

Definition at line 260 of file thread.h.

## ◆ rb_internal_thread_event_hook_t

typedef struct rb_internal_thread_event_hook rb_internal_thread_event_hook_t

Definition at line 263 of file thread.h.

## ◆ rb_internal_thread_specific_key_t

typedef int rb_internal_thread_specific_key_t

Definition at line 297 of file thread.h.

## Function Documentation

## ◆ rb_internal_thread_add_event_hook()

rb_internal_thread_event_hook_t * rb_internal_thread_add_event_hook | ( | rb_internal_thread_event_callback | func,
|  | rb_event_flag_t | events,
|  | void * | data )

Registers a thread event hook function.

Parameters

  [in] | func | A callback.
  [in] | events | A set of events that `func` should run.
  [in] | data | Passed as-is to `func`.

Returns
  An opaque pointer to the hook, to unregister it later.

Note
  This functionality is a noop on Windows and WebAssembly.
  The callback will be called without the GVL held, except for the RESUMED event.
  Callbacks are not guaranteed to be executed on the native threads that corresponds to the Ruby thread. To identify which Ruby thread the event refers to, you must use `event_data->thread`.

Warning
  This function MUST not be called from a thread event callback.

## ◆ rb_internal_thread_remove_event_hook()

bool rb_internal_thread_remove_event_hook | ( | rb_internal_thread_event_hook_t * | hook | ) |

Unregister the passed hook.

Parameters

  [in] | hook. | The hook to unregister.

Returns
  Whether the hook was found and unregistered.

Note
  This functionality is a noop on Windows and WebAssembly.

Warning
  This function MUST not be called from a thread event callback.

## ◆ rb_internal_thread_specific_get()

void * rb_internal_thread_specific_get | ( | VALUE | thread_val,
|  | rb_internal_thread_specific_key_t | key )

Get thread and tool specific data.

This function is async signal safe and thread safe.

Definition at line 5959 of file thread.c.

Referenced by rb_internal_thread_specific_get().

## ◆ rb_internal_thread_specific_key_create()

rb_internal_thread_specific_key_t rb_internal_thread_specific_key_create | ( | void |  | ) |

Create a key to store thread specific data.

These APIs are designed for tools using rb_internal_thread_event_hook APIs.

Note that only `RB_INTERNAL_THREAD_SPECIFIC_KEY_MAX` keys can be created. raises `ThreadError` if exceeded.

Usage: // at initialize time: int tool_key; // gvar Init_tool() { tool_key = rb_internal_thread_specific_key_create(); }

// at any timing: rb_internal_thread_specific_set(thread, tool_key, per_thread_data); ... per_thread_data = rb_internal_thread_specific_get(thread, tool_key);

Definition at line 5931 of file thread.c.

Referenced by rb_internal_thread_specific_key_create().

## ◆ rb_internal_thread_specific_set()

void rb_internal_thread_specific_set | ( | VALUE | thread_val,
|  | rb_internal_thread_specific_key_t | key,
|  | void * | data )

Set thread and tool specific data.

This function is async signal safe and thread safe.

Definition at line 5972 of file thread.c.

Referenced by rb_internal_thread_specific_set().

## ◆ rb_nogvl()

void * rb_nogvl | ( | void *(* | func )(void *),
|  | void * | data1,
|  | rb_unblock_function_t * | ubf,
|  | void * | data2,
|  | int | flags )

Identical to rb_thread_call_without_gvl(), except it additionally takes "flags" that change the behaviour.

Parameters

  [in] | func | A function to call without GVL.
  [in,out] | data1 | Passed as-is to `func`.
  [in] | ubf | An UBF to cancel `func`.
  [in,out] | data2 | Passed as-is to `ubf`.
  [in] | flags | Flags.

Returns
  What `func` returned, or 0 in case `func` did not return.

Definition at line 1539 of file thread.c.

Referenced by rb_thread_call_without_gvl(), and rb_thread_call_without_gvl2().

## ◆ rb_thread_call_with_gvl()

void * rb_thread_call_with_gvl | ( | void *(* | func )(void *),
|  | void * | data1 )

(Re-)acquires the GVL.

This manoeuvre makes it possible for an out-of-GVL routine to one-shot call a ruby method.

What this function does:

1. Blocks until it acquires the GVL.
2. Calls the passed function.
3. Releases the GVL.
4. Returns what was returned form the passed function.

Parameters

  [in] | func | What to call with GVL.
  [in,out] | data1 | Passed as-is to `func`.

Returns
  What was returned from `func`.

Warning
  `func` must not return a Ruby object. If it did such return value would escape from GC's scope; would not be marked.
  Global escapes from this function just yield whatever fatal undefined behaviours. You must make sure that `func` does not raise, by properly rescuing everything using e.g. rb_protect().
  You cannot convert a non-Ruby thread into a Ruby thread using this API. This function makes sense only from inside of a rb_thread_call_without_gvl()'s callback.

Definition at line 1904 of file thread.c.

Referenced by rb_thread_call_with_gvl().

## ◆ rb_thread_call_without_gvl()

void * rb_thread_call_without_gvl | ( | void *(* | func )(void *),
|  | void * | data1,
|  | rb_unblock_function_t * | ubf,
|  | void * | data2 )

Allows the passed function to run in parallel with other Ruby threads.

What this function does:

1. Checks (and handles) pending interrupts.
2. Releases the GVL. (Others can run here in parallel...)
3. Calls the passed function.
4. Blocks until it re-acquires the GVL.
5. Checks interrupts that happened between 2 to 4.

In case other threads interfaced with this thread using rb_thread_kill() etc., the passed UBF is additionally called. See rb_unblock_function_t for details.

Unlike rb_thread_call_without_gvl2() this function also reacts to signals etc.

Parameters

  [in] | func | A function to call without GVL.
  [in,out] | data1 | Passed as-is to `func`.
  [in] | ubf | An UBF to cancel `func`.
  [in,out] | data2 | Passed as-is to `ubf`.

Returns
  What `func` returned, or 0 in case `ubf` cancelled `func`.

Warning
  You cannot use most of Ruby C APIs like calling methods or raising exceptions from any of the functions passed to it. If that is dead necessary use rb_thread_call_with_gvl() to re-acquire the GVL.
  In short, this API is difficult. @ko1 recommends you to use other ways if any. We lack experiences to use this API. If you find any corner cases etc., please report it to the devs.
  Releasing and re-acquiring the GVL are expensive operations. For a short-running `func`, it might be faster to just call `func` with blocking everything else. Be sure to benchmark your code to see if it is actually worth releasing the GVL.

Definition at line 1685 of file thread.c.

## ◆ rb_thread_call_without_gvl2()

void * rb_thread_call_without_gvl2 | ( | void *(* | func )(void *),
|  | void * | data1,
|  | rb_unblock_function_t * | ubf,
|  | void * | data2 )

Identical to rb_thread_call_without_gvl(), except it does not interface with signals etc.

As described in RB_NOGVL_INTR_FAIL, interrupts can hurt you. In case this function detects an interrupt, it returns immediately. You can record progress of your callback and check it after returning from this function.

What this function does:

1. Checks for pending interrupts and if any, just returns.
2. Releases the GVL. (Others can run here in parallel...)
3. Calls the passed function.
4. Blocks until it re-acquires the GVL.

Parameters

  [in] | func | A function to call without GVL.
  [in,out] | data1 | Passed as-is to `func`.
  [in] | ubf | An UBF to cancel `func`.
  [in,out] | data2 | Passed as-is to `ubf`.

Returns
  What `func` returned, or 0 in case `func` did not return.

Definition at line 1678 of file thread.c.

## ◆ rb_thread_lock_native_thread()

bool rb_thread_lock_native_thread | ( | void |  | ) |

Declare the current Ruby thread should acquire a dedicated native thread on M:N thread scheduler.

If a C extension (or a library which the extension relies on) should keep to run on a native thread (e.g. using thread-local-storage), this function allocates a dedicated native thread for the thread.

Returns
  `false` if the thread already running on a dedicated native thread. Otherwise `true`.