(d568c610946b44722ffb51ab7b36edc2e779d306)

#include "internal/dllexport.h"
#include "internal/fl_type.h"
#include "internal/special_consts.h"
#include "internal/stdbool.h"
#include "internal/value.h"

Include dependency graph for ractor.h:

This graph shows which files directly or indirectly include this file:

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) FL_TEST_RAW((obj), RUBY_FL_SHAREABLE)
	Queries if the passed object has previously classified as shareable or not.

#define	RB_OBJ_SET_SHAREABLE(obj) rb_obj_set_shareable(obj)
	Wrapper of rb_obj_set_shareable().

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.

VALUE	rb_obj_set_shareable (VALUE obj)
	Marks the passed object as shareable, without any check.

static bool	rb_ractor_shareable_p (VALUE obj)
	Queries if multiple Ractors can share the passed object or not.

static VALUE	RB_OBJ_SET_FROZEN_SHAREABLE (VALUE obj)
	Freezes and marks the object as shareable.

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_SET_SHAREABLE

#define RB_OBJ_SET_SHAREABLE ( obj ) rb_obj_set_shareable(obj)

Wrapper of rb_obj_set_shareable().

Use this macro, not the function.

Definition at line 290 of file ractor.h.

◆ RB_OBJ_SHAREABLE_P

#define RB_OBJ_SHAREABLE_P ( obj ) FL_TEST_RAW((obj), RUBY_FL_SHAREABLE)

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 255 of file ractor.h.

◆ 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_OBJ_SET_FROZEN_SHAREABLE()

static VALUE RB_OBJ_SET_FROZEN_SHAREABLE ( VALUE obj )

inlinestatic

Freezes and marks the object as shareable.

The same warning and note as rb_obj_set_shareable() apply.

Parameters

[out] obj Arbitrary ruby object, except special constants.

Returns: Passed obj.

Definition at line 301 of file ractor.h.

◆ rb_obj_set_shareable()

VALUE rb_obj_set_shareable ( VALUE obj )

Marks the passed object as shareable, without any check.

This is for objects which the caller knows are safe to be shared among Ractors, for instance because they are frozen and only refer to shareable objects.

Parameters

[out] obj Arbitrary ruby object, except special constants.

Returns: Passed obj.

Postcondition: Multiple Ractors can share obj.

Warning: No check is done. Marking an unsafe object as shareable breaks the Ractor isolation.; Do not make objects shareable more than needed. A shareable object is out of the reach of a local GC, so it is not collected until a global GC runs. This is for the few objects which live as long as the process, typically internal constants, not for objects created per call.

Note: Do not call this directly; use RB_OBJ_SET_SHAREABLE, or RB_OBJ_SET_FROZEN_SHAREABLE to freeze at the same time.

Definition at line 1506 of file ractor.c.

◆ 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 3678 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 3582 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 3690 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 3649 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 3661 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 3591 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 3672 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 1911 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 shareable among Ractors.

Definition at line 1922 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 269 of file ractor.h.

Referenced by make_singleton_class().

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

◆ 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 1444 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 1375 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 1420 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 1390 of file ractor.c.

◆ 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 1432 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 3571 of file ractor.c.

(d568c610946b44722ffb51ab7b36edc2e779d306)

Data Structures

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ RB_OBJ_SET_SHAREABLE

◆ RB_OBJ_SHAREABLE_P

◆ RB_RACTOR_LOCAL_STORAGE_TYPE_FREE

Typedef Documentation

◆ rb_ractor_local_key_t

Function Documentation

◆ RB_OBJ_SET_FROZEN_SHAREABLE()

◆ rb_obj_set_shareable()

◆ rb_ractor_local_storage_ptr()

◆ rb_ractor_local_storage_ptr_newkey()

◆ rb_ractor_local_storage_ptr_set()

◆ rb_ractor_local_storage_value()

◆ rb_ractor_local_storage_value_lookup()

◆ rb_ractor_local_storage_value_newkey()

◆ rb_ractor_local_storage_value_set()

◆ rb_ractor_make_shareable()

◆ rb_ractor_make_shareable_copy()

◆ rb_ractor_shareable_p()

◆ rb_ractor_stderr()

◆ rb_ractor_stderr_set()

◆ rb_ractor_stdin()

◆ rb_ractor_stdin_set()

◆ rb_ractor_stdout()

◆ rb_ractor_stdout_set()

Variable Documentation

◆ rb_ractor_local_storage_type_free