#ifndef RUBY_RACTOR_H /*-*-C++-*-vi:se ft=cpp:*/

[0] Fix | Delete

#define RUBY_RACTOR_H 1

[1] Fix | Delete

[2] Fix | Delete

/**

[3] Fix | Delete

* @file

[4] Fix | Delete

* @author Koichi Sasada

[5] Fix | Delete

* @date Tue Nov 17 16:39:15 2020

[6] Fix | Delete

* @copyright Copyright (C) 2020 Yukihiro Matsumoto

[7] Fix | Delete

* @copyright This file is a part of the programming language Ruby.

[8] Fix | Delete

* Permission is hereby granted, to either redistribute and/or

[9] Fix | Delete

* modify this file, provided that the conditions mentioned in the

[10] Fix | Delete

* file COPYING are met. Consult the file for details.

[11] Fix | Delete

*/

[12] Fix | Delete

#include "internal/dllexport.h" /* RUBY_EXTERN is here */

[13] Fix | Delete

#include "internal/fl_type.h" /* FL_TEST_RAW is here */

[14] Fix | Delete

#include "internal/special_consts.h" /* RB_SPECIAL_CONSTS_P is here */

[15] Fix | Delete

#include "internal/stdbool.h" /* bool is here */

[16] Fix | Delete

#include "internal/value.h" /* VALUE is here */

[17] Fix | Delete

[18] Fix | Delete

/** Type that defines a ractor-local storage. */

[19] Fix | Delete

struct rb_ractor_local_storage_type {

[20] Fix | Delete

[21] Fix | Delete

/**

[22] Fix | Delete

* A function to mark a ractor-local storage.

[23] Fix | Delete

*

[24] Fix | Delete

* @param[out] ptr A ractor-local storage.

[25] Fix | Delete

* @post Ruby objects inside of `ptr` are marked.

[26] Fix | Delete

*/

[27] Fix | Delete

void (*mark)(void *ptr);

[28] Fix | Delete

[29] Fix | Delete

/**

[30] Fix | Delete

* A function to destruct a ractor-local storage.

[31] Fix | Delete

*

[32] Fix | Delete

* @param[out] ptr A ractor-local storage.

[33] Fix | Delete

* @post `ptr` is not a valid pointer.

[34] Fix | Delete

*/

[35] Fix | Delete

void (*free)(void *ptr);

[36] Fix | Delete

// TODO: update

[37] Fix | Delete

};

[38] Fix | Delete

[39] Fix | Delete

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

[40] Fix | Delete

typedef struct rb_ractor_local_key_struct *rb_ractor_local_key_t;

[41] Fix | Delete

[42] Fix | Delete

RBIMPL_SYMBOL_EXPORT_BEGIN()

[43] Fix | Delete

[44] Fix | Delete

/**

[45] Fix | Delete

* `Ractor` class.

[46] Fix | Delete

*

[47] Fix | Delete

* @ingroup object

[48] Fix | Delete

*/

[49] Fix | Delete

RUBY_EXTERN VALUE rb_cRactor;

[50] Fix | Delete

[51] Fix | Delete

/**

[52] Fix | Delete

* Queries the standard input of the current Ractor that is calling this

[53] Fix | Delete

* function.

[54] Fix | Delete

*

[55] Fix | Delete

* @return An IO.

[56] Fix | Delete

* @note This can be different from the process-global one.

[57] Fix | Delete

*/

[58] Fix | Delete

VALUE rb_ractor_stdin(void);

[59] Fix | Delete

[60] Fix | Delete

/**

[61] Fix | Delete

* Queries the standard output of the current Ractor that is calling this

[62] Fix | Delete

* function.

[63] Fix | Delete

*

[64] Fix | Delete

* @return An IO.

[65] Fix | Delete

* @note This can be different from the process-global one.

[66] Fix | Delete

*/

[67] Fix | Delete

VALUE rb_ractor_stdout(void);

[68] Fix | Delete

[69] Fix | Delete

/**

[70] Fix | Delete

* Queries the standard error of the current Ractor that is calling this

[71] Fix | Delete

* function.

[72] Fix | Delete

*

[73] Fix | Delete

* @return An IO.

[74] Fix | Delete

* @note This can be different from the process-global one.

[75] Fix | Delete

*/

[76] Fix | Delete

VALUE rb_ractor_stderr(void);

[77] Fix | Delete

[78] Fix | Delete

/**

[79] Fix | Delete

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

[80] Fix | Delete

* function.

[81] Fix | Delete

*

[82] Fix | Delete

* @param[in] io An IO.

[83] Fix | Delete

* @post `io` is the standard input of the current ractor.

[84] Fix | Delete

* @post In case the calling Ractor is the main Ractor, it also updates

[85] Fix | Delete

* the process global ::rb_stdin.

[86] Fix | Delete

*/

[87] Fix | Delete

void rb_ractor_stdin_set(VALUE io);

[88] Fix | Delete

[89] Fix | Delete

/**

[90] Fix | Delete

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

[91] Fix | Delete

* function.

[92] Fix | Delete

*

[93] Fix | Delete

* @param[in] io An IO.

[94] Fix | Delete

* @post `io` is the standard input of the current ractor.

[95] Fix | Delete

* @post In case the calling Ractor is the main Ractor, it also updates

[96] Fix | Delete

* the process global ::rb_stdout.

[97] Fix | Delete

*/

[98] Fix | Delete

void rb_ractor_stdout_set(VALUE io);

[99] Fix | Delete

[100] Fix | Delete

/**

[101] Fix | Delete

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

[102] Fix | Delete

* function.

[103] Fix | Delete

*

[104] Fix | Delete

* @param[in] io An IO.

[105] Fix | Delete

* @post `io` is the standard input of the current ractor.

[106] Fix | Delete

* @post In case the calling Ractor is the main Ractor, it also updates

[107] Fix | Delete

* the process global ::rb_stderr.

[108] Fix | Delete

*/

[109] Fix | Delete

void rb_ractor_stderr_set(VALUE io);

[110] Fix | Delete

[111] Fix | Delete

/**

[112] Fix | Delete

* Issues a new key.

[113] Fix | Delete

*

[114] Fix | Delete

* @return A newly issued ractor-local storage key. Keys issued using this

[115] Fix | Delete

* key can be associated to a Ruby object per Ractor.

[116] Fix | Delete

*/

[117] Fix | Delete

rb_ractor_local_key_t rb_ractor_local_storage_value_newkey(void);

[118] Fix | Delete

[119] Fix | Delete

/**

[120] Fix | Delete

* Queries the key.

[121] Fix | Delete

*

[122] Fix | Delete

* @param[in] key A ractor-local storage key to lookup.

[123] Fix | Delete

* @retval RUBY_Qnil No such key.

[124] Fix | Delete

* @retval otherwise A value corresponds to `key` in the current Ractor.

[125] Fix | Delete

* @note This cannot distinguish between a nonexistent key and a key

[126] Fix | Delete

* exists and corresponds to ::RUBY_Qnil.

[127] Fix | Delete

*/

[128] Fix | Delete

VALUE rb_ractor_local_storage_value(rb_ractor_local_key_t key);

[129] Fix | Delete

[130] Fix | Delete

/**

[131] Fix | Delete

* Queries the key.

[132] Fix | Delete

*

[133] Fix | Delete

* @param[in] key A ractor-local storage key to lookup.

[134] Fix | Delete

* @param[out] val Return value buffer.

[135] Fix | Delete

* @retval false `key` not found.

[136] Fix | Delete

* @retval true `key` found.

[137] Fix | Delete

* @post `val` is updated so that it has the value corresponds to `key`

[138] Fix | Delete

* in the current Ractor.

[139] Fix | Delete

*/

[140] Fix | Delete

bool rb_ractor_local_storage_value_lookup(rb_ractor_local_key_t key, VALUE *val);

[141] Fix | Delete

[142] Fix | Delete

/**

[143] Fix | Delete

* Associates the passed value to the passed key.

[144] Fix | Delete

*

[145] Fix | Delete

* @param[in] key A ractor-local storage key.

[146] Fix | Delete

* @param[in] val Arbitrary ruby object.

[147] Fix | Delete

* @post `val` corresponds to `key` in the current Ractor.

[148] Fix | Delete

*/

[149] Fix | Delete

void rb_ractor_local_storage_value_set(rb_ractor_local_key_t key, VALUE val);

[150] Fix | Delete

[151] Fix | Delete

/**

[152] Fix | Delete

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

[153] Fix | Delete

*

[154] Fix | Delete

* @internal

[155] Fix | Delete

*

[156] Fix | Delete

* Why it is visible from 3rd party extension libraries is not obvious to

[157] Fix | Delete

* @shyouhei.

[158] Fix | Delete

*/

[159] Fix | Delete

RUBY_EXTERN const struct rb_ractor_local_storage_type rb_ractor_local_storage_type_free;

[160] Fix | Delete

[161] Fix | Delete

/** @alias{rb_ractor_local_storage_type_free} */

[162] Fix | Delete

#define RB_RACTOR_LOCAL_STORAGE_TYPE_FREE (&rb_ractor_local_storage_type_free)

[163] Fix | Delete

[164] Fix | Delete

/**

[165] Fix | Delete

* Extended version of rb_ractor_local_storage_value_newkey(). It additionally

[166] Fix | Delete

* takes the type of the issuing key.

[167] Fix | Delete

*

[168] Fix | Delete

* @param[in] type How the value associated with the issuing key should

[169] Fix | Delete

* behave.

[170] Fix | Delete

* @return A newly issued ractor-local storage key, of type `type`.

[171] Fix | Delete

*/

[172] Fix | Delete

rb_ractor_local_key_t rb_ractor_local_storage_ptr_newkey(const struct rb_ractor_local_storage_type *type);

[173] Fix | Delete

[174] Fix | Delete

/**

[175] Fix | Delete

* Identical to rb_ractor_local_storage_value() except the return type.

[176] Fix | Delete

*

[177] Fix | Delete

* @param[in] key A ractor-local storage key to lookup.

[178] Fix | Delete

* @retval NULL No such key.

[179] Fix | Delete

* @retval otherwise A value corresponds to `key` in the current Ractor.

[180] Fix | Delete

*/

[181] Fix | Delete

void *rb_ractor_local_storage_ptr(rb_ractor_local_key_t key);

[182] Fix | Delete

[183] Fix | Delete

/**

[184] Fix | Delete

* Identical to rb_ractor_local_storage_value_set() except the parameter type.

[185] Fix | Delete

*

[186] Fix | Delete

* @param[in] key A ractor-local storage key.

[187] Fix | Delete

* @param[in] ptr A pointer that conforms `key`'s type.

[188] Fix | Delete

* @post `ptr` corresponds to `key` in the current Ractor.

[189] Fix | Delete

*/

[190] Fix | Delete

void rb_ractor_local_storage_ptr_set(rb_ractor_local_key_t key, void *ptr);

[191] Fix | Delete

[192] Fix | Delete

/**

[193] Fix | Delete

* Destructively transforms the passed object so that multiple Ractors can

[194] Fix | Delete

* share it. What is a shareable object and what is not is a nuanced concept,

[195] Fix | Delete

* and @ko1 says the definition can still change. However extension library

[196] Fix | Delete

* authors might interest to learn how to use #RUBY_TYPED_FROZEN_SHAREABLE.

[197] Fix | Delete

*

[198] Fix | Delete

* @param[out] obj Arbitrary ruby object to modify.

[199] Fix | Delete

* @exception rb_eRactorError Ractors cannot share `obj` by nature.

[200] Fix | Delete

* @return Passed `obj`.

[201] Fix | Delete

* @post Multiple Ractors can share `obj`.

[202] Fix | Delete

*

[203] Fix | Delete

* @internal

[204] Fix | Delete

*

[205] Fix | Delete

* In case an exception is raised, `obj` remains in an intermediate state where

[206] Fix | Delete

* some of its part is frozen and others are not. @shyouhei is not sure if it

[207] Fix | Delete

* is either an intended behaviour, current implementation limitation, or

[208] Fix | Delete

* simply a bug. Note also that there is no way to "melt" a frozen object.

[209] Fix | Delete

*/

[210] Fix | Delete

VALUE rb_ractor_make_shareable(VALUE obj);

[211] Fix | Delete

[212] Fix | Delete

/**

[213] Fix | Delete

* Identical to rb_ractor_make_shareable(), except it returns a (deep) copy of

[214] Fix | Delete

* the passed one instead of modifying it in-place.

[215] Fix | Delete

*

[216] Fix | Delete

* @param[in] obj Arbitrary ruby object to duplicate.

[217] Fix | Delete

* @exception rb_eRactorError Ractors cannot share `obj` by nature.

[218] Fix | Delete

* @return A deep copy of `obj` which is sharable among Ractors.

[219] Fix | Delete

*/

[220] Fix | Delete

VALUE rb_ractor_make_shareable_copy(VALUE obj);

[221] Fix | Delete

[222] Fix | Delete

RBIMPL_SYMBOL_EXPORT_END()

[223] Fix | Delete

[224] Fix | Delete

/**

[225] Fix | Delete

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

[226] Fix | Delete

* This doesn't mean anything in practice... Objects can be shared later.

[227] Fix | Delete

* Always use rb_ractor_shareable_p() instead.

[228] Fix | Delete

*

[229] Fix | Delete

* @param[in] obj Object in question.

[230] Fix | Delete

* @retval RUBY_FL_SHAREABLE It once was shareable before.

[231] Fix | Delete

* @retval 0 Otherwise.

[232] Fix | Delete

*/

[233] Fix | Delete

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

[234] Fix | Delete

[235] Fix | Delete

/**

[236] Fix | Delete

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

[237] Fix | Delete

* without protecting each other. Sharing an object among them is basically

[238] Fix | Delete

* dangerous, disabled by default. However there are objects that are

[239] Fix | Delete

* extremely carefully implemented to be Ractor-safe; for instance integers

[240] Fix | Delete

* have such property. This function can classify that.

[241] Fix | Delete

*

[242] Fix | Delete

* @param[in] obj Arbitrary ruby object.

[243] Fix | Delete

* @retval true `obj` is capable of shared across ractors.

[244] Fix | Delete

* @retval false `obj` cannot travel across ractor boundaries.

[245] Fix | Delete

*/

[246] Fix | Delete

static inline bool

[247] Fix | Delete

rb_ractor_shareable_p(VALUE obj)

[248] Fix | Delete

{

[249] Fix | Delete

bool rb_ractor_shareable_p_continue(VALUE obj);

[250] Fix | Delete

[251] Fix | Delete

if (RB_SPECIAL_CONST_P(obj)) {

[252] Fix | Delete

return true;

[253] Fix | Delete

}

[254] Fix | Delete

else if (RB_OBJ_SHAREABLE_P(obj)) {

[255] Fix | Delete

return true;

[256] Fix | Delete

}

[257] Fix | Delete

else {

[258] Fix | Delete

return rb_ractor_shareable_p_continue(obj);

[259] Fix | Delete

}

[260] Fix | Delete

}

[261] Fix | Delete

[262] Fix | Delete

#endif /* RUBY_RACTOR_H */

[263] Fix | Delete

[264] Fix | Delete