Ruby: include/ruby/ractor.h File Reference

Ruby 3.2.5p208 (2024-07-26 revision 31d0f1a2e7dbfb60731d1f05b868e1d578cda493)

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:298
FL_TEST_RAW
#define FL_TEST_RAW
Old name of RB_FL_TEST_RAW.
Definition fl_type.h:140

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 3265 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 3167 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 3277 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 3236 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 3248 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 3176 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 3259 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 2522 of file ractor.c.

Referenced by rb_ractor_make_shareable().

## ◆ 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 2531 of file ractor.c.

Referenced by rb_ractor_make_shareable_copy().

## ◆ rb_ractor_shareable_p()

static 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 2148 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 2184 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 2124 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 2160 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 2136 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 2172 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 3156 of file ractor.c.