Ruby 3.2.2p53 (2023-03-30 revision e51014f9c05aa65cbf203442d37fef7c12390015)
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.

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 /** thread started */
 
#define RUBY_INTERNAL_THREAD_EVENT_READY   1 << 1 /** acquiring GVL */
 
#define RUBY_INTERNAL_THREAD_EVENT_RESUMED   1 << 2 /** acquired GVL */
 
#define RUBY_INTERNAL_THREAD_EVENT_SUSPENDED   1 << 3 /** released GVL */
 
#define RUBY_INTERNAL_THREAD_EVENT_EXITED   1 << 4 /** thread terminated */
 
#define RUBY_INTERNAL_THREAD_EVENT_MASK   0xff /** All Thread events */
 
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.
 

Typedefs

typedef void 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
 

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

Detailed Description

Author
Author
matz
Date
Tue Jul 10 17:35:43 JST 2012

Definition in file thread.h.

Macro Definition Documentation

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

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

◆ 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 191 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 185 of file thread.h.

◆ RUBY_INTERNAL_THREAD_EVENT_EXITED

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

Definition at line 197 of file thread.h.

◆ RUBY_INTERNAL_THREAD_EVENT_MASK

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

Definition at line 198 of file thread.h.

◆ RUBY_INTERNAL_THREAD_EVENT_READY

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

Definition at line 194 of file thread.h.

◆ RUBY_INTERNAL_THREAD_EVENT_RESUMED

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

Definition at line 195 of file thread.h.

◆ RUBY_INTERNAL_THREAD_EVENT_STARTED

#define RUBY_INTERNAL_THREAD_EVENT_STARTED   1 << 0 /** thread started */

Definition at line 193 of file thread.h.

◆ RUBY_INTERNAL_THREAD_EVENT_SUSPENDED

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

Definition at line 196 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 202 of file thread.h.

◆ rb_internal_thread_event_data_t

typedef void rb_internal_thread_event_data_t

Definition at line 200 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 205 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]funcA callback.
[in]eventsA set of events that func should run.
[in]dataPassed as-is to func.
Returns
An opaque pointer to the hook, to unregister it later.
Note
This functionality is a noop on Windows.
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
Wether the hook was found and unregistered.
Note
This functionality is a noop on Windows.
Warning
This function MUST not be called from a thread event callback.

◆ rb_nogvl()

void * rb_nogvl ( void *(*)(void *)  func,
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]funcA function to call without GVL.
[in,out]data1Passed as-is to func.
[in]ubfAn UBF to cancel func.
[in,out]data2Passed as-is to ubf.
[in]flagsFlags.
Returns
What func returned, or 0 in case func did not return.

Definition at line 1523 of file thread.c.

Referenced by rb_thread_call_without_gvl2().

◆ rb_thread_call_with_gvl()

void * rb_thread_call_with_gvl ( void *(*)(void *)  func,
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]funcWhat to call with GVL.
[in,out]data1Passed 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 1756 of file thread.c.

Referenced by rb_thread_call_with_gvl().

◆ rb_thread_call_without_gvl()

void * rb_thread_call_without_gvl ( void *(*)(void *)  func,
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]funcA function to call without GVL.
[in,out]data1Passed as-is to func.
[in]ubfAn UBF to cancel func.
[in,out]data2Passed 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.

◆ rb_thread_call_without_gvl2()

void * rb_thread_call_without_gvl2 ( void *(*)(void *)  func,
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]funcA function to call without GVL.
[in,out]data1Passed as-is to func.
[in]ubfAn UBF to cancel func.
[in,out]data2Passed as-is to ubf.
Returns
What func returned, or 0 in case func did not return.

Definition at line 1654 of file thread.c.