(892c46283a5ea4179500d951c9d4866c0051f27b)

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

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

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

Functions
VALUE	rb_ractor_stdin (void)
	Queries the standard input of the current Ractor that is calling this function. More...

VALUE	rb_ractor_stdout (void)
	Queries the standard output of the current Ractor that is calling this function. More...

VALUE	rb_ractor_stderr (void)
	Queries the standard error of the current Ractor that is calling this function. More...

void	rb_ractor_stdin_set (VALUE io)
	Assigns an IO to the standard input of the Ractor that is calling this function. More...

void	rb_ractor_stdout_set (VALUE io)
	Assigns an IO to the standard output of the Ractor that is calling this function. More...

void	rb_ractor_stderr_set (VALUE io)
	Assigns an IO to the standard error of the Ractor that is calling this function. More...

rb_ractor_local_key_t	rb_ractor_local_storage_value_newkey (void)
	Issues a new key. More...

VALUE	rb_ractor_local_storage_value (rb_ractor_local_key_t key)
	Queries the key. More...

bool	rb_ractor_local_storage_value_lookup (rb_ractor_local_key_t key, VALUE *val)
	Queries the key. More...

void	rb_ractor_local_storage_value_set (rb_ractor_local_key_t key, VALUE val)
	Associates the passed value to the passed key. More...

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(). More...

void *	rb_ractor_local_storage_ptr (rb_ractor_local_key_t key)
	Identical to rb_ractor_local_storage_value() except the return type. More...

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

VALUE	rb_ractor_make_shareable (VALUE obj)
	Destructively transforms the passed object so that multiple Ractors can share it. More...

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

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

Variables
VALUE	rb_cRactor
	`Ractor` class. More...

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

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 ) 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 235 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_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 3823 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 3725 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 3835 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 3794 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 3806 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 3734 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 3817 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 3078 of file ractor.c.

Referenced by 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 3087 of file ractor.c.

◆ 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 2724 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 2760 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 2700 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 2736 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 2712 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 2748 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 3704 of file ractor.c.

(892c46283a5ea4179500d951c9d4866c0051f27b)

Data Structures

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ RB_OBJ_SHAREABLE_P

◆ RB_RACTOR_LOCAL_STORAGE_TYPE_FREE

Typedef Documentation

◆ rb_ractor_local_key_t

Function Documentation

◆ 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