Ruby: include/ruby/ractor.h File Reference

Ruby 3.4.6p54 (2025-09-16 revision dbd83256b1cec76c69756ecb8758b9e1079833de)

Data Structures | Macros | Typedefs | Functions | Variables
ractor.h File Reference
`#include "internal/dllexport.h"`
`#include "internal/fl_type.h"`
`#include "internal/special_consts.h"`
`#include "internal/stdbool.h"`
`#include "internal/value.h"`

Go to the source code of this file.

## Data Structures
struct | rb_ractor_local_storage_type
| Type that defines a ractor-local storage. More...

## Macros
#define | RB_RACTOR_LOCAL_STORAGE_TYPE_FREE (&rb_ractor_local_storage_type_free)
| Just another name of rb_ractor_local_storage_type_free.
#define | RB_OBJ_SHAREABLE_P(obj)
| Queries if the passed object has previously classified as shareable or not.

## Typedefs
typedef struct rb_ractor_local_key_struct * | rb_ractor_local_key_t
| (Opaque) struct that holds a ractor-local storage key.

## Functions
VALUE | rb_ractor_stdin (void)
| Queries the standard input of the current Ractor that is calling this function.
VALUE | rb_ractor_stdout (void)
| Queries the standard output of the current Ractor that is calling this function.
VALUE | rb_ractor_stderr (void)
| Queries the standard error of the current Ractor that is calling this function.
void | rb_ractor_stdin_set (VALUE io)
| Assigns an IO to the standard input of the Ractor that is calling this function.
void | rb_ractor_stdout_set (VALUE io)
| Assigns an IO to the standard output of the Ractor that is calling this function.
void | rb_ractor_stderr_set (VALUE io)
| Assigns an IO to the standard error of the Ractor that is calling this function.
rb_ractor_local_key_t | rb_ractor_local_storage_value_newkey (void)
| Issues a new key.
VALUE | rb_ractor_local_storage_value (rb_ractor_local_key_t key)
| Queries the key.
bool | rb_ractor_local_storage_value_lookup (rb_ractor_local_key_t key, VALUE *val)
| Queries the key.
void | rb_ractor_local_storage_value_set (rb_ractor_local_key_t key, VALUE val)
| Associates the passed value to the passed key.
rb_ractor_local_key_t | rb_ractor_local_storage_ptr_newkey (const struct rb_ractor_local_storage_type *type)
| Extended version of rb_ractor_local_storage_value_newkey().
void * | rb_ractor_local_storage_ptr (rb_ractor_local_key_t key)
| Identical to rb_ractor_local_storage_value() except the return type.
void | rb_ractor_local_storage_ptr_set (rb_ractor_local_key_t key, void *ptr)
| Identical to rb_ractor_local_storage_value_set() except the parameter type.
VALUE | rb_ractor_make_shareable (VALUE obj)
| Destructively transforms the passed object so that multiple Ractors can share it.
VALUE | rb_ractor_make_shareable_copy (VALUE obj)
| Identical to rb_ractor_make_shareable(), except it returns a (deep) copy of the passed one instead of modifying it in-place.
static bool | rb_ractor_shareable_p (VALUE obj)
| Queries if multiple Ractors can share the passed object or not.

## Variables
VALUE | rb_cRactor
| Ractor class.
const struct rb_ractor_local_storage_type | rb_ractor_local_storage_type_free
| A type of ractor-local storage that destructs itself using ruby_xfree.

## Detailed Description

Author
  Koichi Sasada

Date
  Tue Nov 17 16:39:15 2020

Copyright
  Copyright (C) 2020 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 ractor.h.

## Macro Definition Documentation

## ◆ RB_OBJ_SHAREABLE_P

#define RB_OBJ_SHAREABLE_P | ( |  | obj | ) |

Value:
FL_TEST_RAW((obj), RUBY_FL_SHAREABLE)
RUBY_FL_SHAREABLE
@ RUBY_FL_SHAREABLE
This flag has something to do with Ractor.
Definition fl_type.h:266
FL_TEST_RAW
#define FL_TEST_RAW
Old name of RB_FL_TEST_RAW.
Definition fl_type.h:132

Queries if the passed object has previously classified as shareable or not.

This doesn't mean anything in practice... Objects can be shared later. Always use rb_ractor_shareable_p() instead.

Parameters

  [in] | obj | Object in question.

Return values

  RUBY_FL_SHAREABLE | It once was shareable before.
  0 | Otherwise.

Definition at line 235 of file ractor.h.

Referenced by rb_ractor_shareable_p().

## ◆ RB_RACTOR_LOCAL_STORAGE_TYPE_FREE

#define RB_RACTOR_LOCAL_STORAGE_TYPE_FREE (&rb_ractor_local_storage_type_free)

Just another name of rb_ractor_local_storage_type_free.

Definition at line 164 of file ractor.h.

## Typedef Documentation

## ◆ rb_ractor_local_key_t

typedef struct rb_ractor_local_key_struct* rb_ractor_local_key_t

(Opaque) struct that holds a ractor-local storage key.

Definition at line 42 of file ractor.h.

## Function Documentation

## ◆ rb_ractor_local_storage_ptr()

void * rb_ractor_local_storage_ptr | ( | rb_ractor_local_key_t | key | ) |

Identical to rb_ractor_local_storage_value() except the return type.

Parameters

  [in] | key | A ractor-local storage key to lookup.

Return values

  NULL | No such key.
  otherwise | A value corresponds to key in the current Ractor.

Definition at line 3869 of file ractor.c.

## ◆ rb_ractor_local_storage_ptr_newkey()

rb_ractor_local_key_t rb_ractor_local_storage_ptr_newkey | ( | const struct rb_ractor_local_storage_type * | type | ) |

Extended version of rb_ractor_local_storage_value_newkey().

It additionally takes the type of the issuing key.

Parameters

  [in] | type | How the value associated with the issuing key should behave.

Returns
  A newly issued ractor-local storage key, of type type.

Definition at line 3771 of file ractor.c.

Referenced by rb_ractor_local_storage_value_newkey().

## ◆ rb_ractor_local_storage_ptr_set()

void rb_ractor_local_storage_ptr_set | ( | rb_ractor_local_key_t | key,
|  | void * | ptr )

Identical to rb_ractor_local_storage_value_set() except the parameter type.

Parameters

  [in] | key | A ractor-local storage key.
  [in] | ptr | A pointer that conforms key's type.

Postcondition
  ptr corresponds to key in the current Ractor.

Definition at line 3881 of file ractor.c.

## ◆ rb_ractor_local_storage_value()

VALUE rb_ractor_local_storage_value | ( | rb_ractor_local_key_t | key | ) |

Queries the key.

Parameters

  [in] | key | A ractor-local storage key to lookup.

Return values

  RUBY_Qnil | No such key.
  otherwise | A value corresponds to key in the current Ractor.

Note
  This cannot distinguish between a nonexistent key and a key exists and corresponds to RUBY_Qnil.

Definition at line 3840 of file ractor.c.

## ◆ rb_ractor_local_storage_value_lookup()

bool rb_ractor_local_storage_value_lookup | ( | rb_ractor_local_key_t | key,
|  | VALUE * | val )

Queries the key.

Parameters

  [in] | key | A ractor-local storage key to lookup.
  [out] | val | Return value buffer.

Return values

  false | key not found.
  true | key found.

Postcondition
  val is updated so that it has the value corresponds to key in the current Ractor.

Definition at line 3852 of file ractor.c.

## ◆ rb_ractor_local_storage_value_newkey()

rb_ractor_local_key_t rb_ractor_local_storage_value_newkey | ( | void |  | ) |

Issues a new key.

Returns
  A newly issued ractor-local storage key. Keys issued using this key can be associated to a Ruby object per Ractor.

Definition at line 3780 of file ractor.c.

## ◆ rb_ractor_local_storage_value_set()

void rb_ractor_local_storage_value_set | ( | rb_ractor_local_key_t | key,
|  | VALUE | val )

Associates the passed value to the passed key.

Parameters

  [in] | key | A ractor-local storage key.
  [in] | val | Arbitrary ruby object.

Postcondition
  val corresponds to key in the current Ractor.

Definition at line 3863 of file ractor.c.

## ◆ rb_ractor_make_shareable()

VALUE rb_ractor_make_shareable | ( | VALUE | obj | ) |

Destructively transforms the passed object so that multiple Ractors can share it.

What is a shareable object and what is not is a nuanced concept, and @ko1 says the definition can still change. However extension library authors might interest to learn how to use #RUBY_TYPED_FROZEN_SHAREABLE.

Parameters

  [out] | obj | Arbitrary ruby object to modify.

Exceptions

  rb_eRactorError | Ractors cannot share `obj` by nature.

Returns
  Passed obj.

Postcondition
  Multiple Ractors can share obj.

Definition at line 3116 of file ractor.c.

Referenced by rb_ractor_make_shareable(), and rb_ractor_make_shareable_copy().

## ◆ rb_ractor_make_shareable_copy()

VALUE rb_ractor_make_shareable_copy | ( | VALUE | obj | ) |

Identical to rb_ractor_make_shareable(), except it returns a (deep) copy of the passed one instead of modifying it in-place.

Parameters

  [in] | obj | Arbitrary ruby object to duplicate.

Exceptions

  rb_eRactorError | Ractors cannot share `obj` by nature.

Returns
  A deep copy of obj which is sharable among Ractors.

Definition at line 3125 of file ractor.c.

Referenced by rb_ractor_make_shareable_copy().

## ◆ rb_ractor_shareable_p()

bool rb_ractor_shareable_p | ( | VALUE | obj | ) |
| inlinestatic

Queries if multiple Ractors can share the passed object or not.

Ractors run without protecting each other. Sharing an object among them is basically dangerous, disabled by default. However there are objects that are extremely carefully implemented to be Ractor-safe; for instance integers have such property. This function can classify that.

Parameters

  [in] | obj | Arbitrary ruby object.

Return values

  true | obj is capable of shared across ractors.
  false | obj cannot travel across ractor boundaries.

Definition at line 249 of file ractor.h.

## ◆ rb_ractor_stderr()

VALUE rb_ractor_stderr | ( | void |  | ) |

Queries the standard error of the current Ractor that is calling this function.

Returns
  An IO.

Note
  This can be different from the process-global one.

Definition at line 2761 of file ractor.c.

Referenced by rb_f_abort(), and rb_write_error2().

## ◆ rb_ractor_stderr_set()

void rb_ractor_stderr_set | ( | VALUE | io | ) |

Assigns an IO to the standard error of the Ractor that is calling this function.

Parameters

  [in] | io | An IO.

Postcondition
  io is the standard input of the current ractor.
  In case the calling Ractor is the main Ractor, it also updates the process global rb_stderr.

Definition at line 2797 of file ractor.c.

## ◆ rb_ractor_stdin()

VALUE rb_ractor_stdin | ( | void |  | ) |

Queries the standard input of the current Ractor that is calling this function.

Returns
  An IO.

Note
  This can be different from the process-global one.

Definition at line 2737 of file ractor.c.

## ◆ rb_ractor_stdin_set()

void rb_ractor_stdin_set | ( | VALUE | io | ) |

Assigns an IO to the standard input of the Ractor that is calling this function.

Parameters

  [in] | io | An IO.

Postcondition
  io is the standard input of the current ractor.
  In case the calling Ractor is the main Ractor, it also updates the process global rb_stdin.

Definition at line 2773 of file ractor.c.

## ◆ rb_ractor_stdout()

VALUE rb_ractor_stdout | ( | void |  | ) |

Queries the standard output of the current Ractor that is calling this function.

Returns
  An IO.

Note
  This can be different from the process-global one.

Definition at line 2749 of file ractor.c.

Referenced by rb_io_getbyte().

## ◆ rb_ractor_stdout_set()

void rb_ractor_stdout_set | ( | VALUE | io | ) |

Assigns an IO to the standard output of the Ractor that is calling this function.

Parameters

  [in] | io | An IO.

Postcondition
  io is the standard input of the current ractor.
  In case the calling Ractor is the main Ractor, it also updates the process global rb_stdout.

Definition at line 2785 of file ractor.c.

## Variable Documentation

## ◆ rb_ractor_local_storage_type_free

const struct rb_ractor_local_storage_type rb_ractor_local_storage_type_free
| extern

A type of ractor-local storage that destructs itself using ruby_xfree.

Definition at line 3760 of file ractor.c.