diff options
Diffstat (limited to 'include/ruby/ractor.h')
| -rw-r--r-- | include/ruby/ractor.h | 264 |
1 files changed, 0 insertions, 264 deletions
diff --git a/include/ruby/ractor.h b/include/ruby/ractor.h deleted file mode 100644 index 7811616f6d..0000000000 --- a/include/ruby/ractor.h +++ /dev/null @@ -1,264 +0,0 @@ -#ifndef RUBY_RACTOR_H /*-*-C++-*-vi:se ft=cpp:*/ -#define RUBY_RACTOR_H 1 - -/** - * @file - * @author Koichi Sasada - * @date Tue Nov 17 16:39:15 2020 - * @copyright Copyright (C) 2020 Yukihiro Matsumoto - * @copyright 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. - */ -#include "internal/dllexport.h" /* RUBY_EXTERN is here */ -#include "internal/fl_type.h" /* FL_TEST_RAW is here */ -#include "internal/special_consts.h" /* RB_SPECIAL_CONSTS_P is here */ -#include "internal/stdbool.h" /* bool is here */ -#include "internal/value.h" /* VALUE is here */ - -/** Type that defines a ractor-local storage. */ -struct rb_ractor_local_storage_type { - - /** - * A function to mark a ractor-local storage. - * - * @param[out] ptr A ractor-local storage. - * @post Ruby objects inside of `ptr` are marked. - */ - void (*mark)(void *ptr); - - /** - * A function to destruct a ractor-local storage. - * - * @param[out] ptr A ractor-local storage. - * @post `ptr` is not a valid pointer. - */ - void (*free)(void *ptr); - // TODO: update -}; - -/** (Opaque) struct that holds a ractor-local storage key. */ -typedef struct rb_ractor_local_key_struct *rb_ractor_local_key_t; - -RBIMPL_SYMBOL_EXPORT_BEGIN() - -/** - * `Ractor` class. - * - * @ingroup object - */ -RUBY_EXTERN VALUE rb_cRactor; - -/** - * Queries the standard input of the current Ractor that is calling this - * function. - * - * @return An IO. - * @note This can be different from the process-global one. - */ -VALUE rb_ractor_stdin(void); - -/** - * Queries the standard output of the current Ractor that is calling this - * function. - * - * @return An IO. - * @note This can be different from the process-global one. - */ -VALUE rb_ractor_stdout(void); - -/** - * Queries the standard error of the current Ractor that is calling this - * function. - * - * @return An IO. - * @note This can be different from the process-global one. - */ -VALUE rb_ractor_stderr(void); - -/** - * Assigns an IO to the standard input of the Ractor that is calling this - * function. - * - * @param[in] io An IO. - * @post `io` is the standard input of the current ractor. - * @post In case the calling Ractor is the main Ractor, it also updates - * the process global ::rb_stdin. - */ -void rb_ractor_stdin_set(VALUE io); - -/** - * Assigns an IO to the standard output of the Ractor that is calling this - * function. - * - * @param[in] io An IO. - * @post `io` is the standard input of the current ractor. - * @post In case the calling Ractor is the main Ractor, it also updates - * the process global ::rb_stdout. - */ -void rb_ractor_stdout_set(VALUE io); - -/** - * Assigns an IO to the standard error of the Ractor that is calling this - * function. - * - * @param[in] io An IO. - * @post `io` is the standard input of the current ractor. - * @post In case the calling Ractor is the main Ractor, it also updates - * the process global ::rb_stderr. - */ -void rb_ractor_stderr_set(VALUE io); - -/** - * Issues a new key. - * - * @return A newly issued ractor-local storage key. Keys issued using this - * key can be associated to a Ruby object per Ractor. - */ -rb_ractor_local_key_t rb_ractor_local_storage_value_newkey(void); - -/** - * Queries the key. - * - * @param[in] key A ractor-local storage key to lookup. - * @retval RUBY_Qnil No such key. - * @retval 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. - */ -VALUE rb_ractor_local_storage_value(rb_ractor_local_key_t key); - -/** - * Queries the key. - * - * @param[in] key A ractor-local storage key to lookup. - * @param[out] val Return value buffer. - * @retval false `key` not found. - * @retval true `key` found. - * @post `val` is updated so that it has the value corresponds to `key` - * in the current Ractor. - */ -bool rb_ractor_local_storage_value_lookup(rb_ractor_local_key_t key, VALUE *val); - -/** - * Associates the passed value to the passed key. - * - * @param[in] key A ractor-local storage key. - * @param[in] val Arbitrary ruby object. - * @post `val` corresponds to `key` in the current Ractor. - */ -void rb_ractor_local_storage_value_set(rb_ractor_local_key_t key, VALUE val); - -/** - * A type of ractor-local storage that destructs itself using ::ruby_xfree. - * - * @internal - * - * Why it is visible from 3rd party extension libraries is not obvious to - * @shyouhei. - */ -RUBY_EXTERN const struct rb_ractor_local_storage_type rb_ractor_local_storage_type_free; - -/** @alias{rb_ractor_local_storage_type_free} */ -#define RB_RACTOR_LOCAL_STORAGE_TYPE_FREE (&rb_ractor_local_storage_type_free) - -/** - * Extended version of rb_ractor_local_storage_value_newkey(). It additionally - * takes the type of the issuing key. - * - * @param[in] type How the value associated with the issuing key should - * behave. - * @return A newly issued ractor-local storage key, of type `type`. - */ -rb_ractor_local_key_t rb_ractor_local_storage_ptr_newkey(const struct rb_ractor_local_storage_type *type); - -/** - * Identical to rb_ractor_local_storage_value() except the return type. - * - * @param[in] key A ractor-local storage key to lookup. - * @retval NULL No such key. - * @retval otherwise A value corresponds to `key` in the current Ractor. - */ -void *rb_ractor_local_storage_ptr(rb_ractor_local_key_t key); - -/** - * Identical to rb_ractor_local_storage_value_set() except the parameter type. - * - * @param[in] key A ractor-local storage key. - * @param[in] ptr A pointer that conforms `key`'s type. - * @post `ptr` corresponds to `key` in the current Ractor. - */ -void rb_ractor_local_storage_ptr_set(rb_ractor_local_key_t key, void *ptr); - -/** - * 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. - * - * @param[out] obj Arbitrary ruby object to modify. - * @exception rb_eRactorError Ractors cannot share `obj` by nature. - * @return Passed `obj`. - * @post Multiple Ractors can share `obj`. - * - * @internal - * - * In case an exception is raised, `obj` remains in an intermediate state where - * some of its part is frozen and others are not. @shyouhei is not sure if it - * is either an intended behaviour, current implementation limitation, or - * simply a bug. Note also that there is no way to "melt" a frozen object. - */ -VALUE rb_ractor_make_shareable(VALUE obj); - -/** - * Identical to rb_ractor_make_shareable(), except it returns a (deep) copy of - * the passed one instead of modifying it in-place. - * - * @param[in] obj Arbitrary ruby object to duplicate. - * @exception rb_eRactorError Ractors cannot share `obj` by nature. - * @return A deep copy of `obj` which is sharable among Ractors. - */ -VALUE rb_ractor_make_shareable_copy(VALUE obj); - -RBIMPL_SYMBOL_EXPORT_END() - -/** - * 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. - * - * @param[in] obj Object in question. - * @retval RUBY_FL_SHAREABLE It once was shareable before. - * @retval 0 Otherwise. - */ -#define RB_OBJ_SHAREABLE_P(obj) FL_TEST_RAW((obj), RUBY_FL_SHAREABLE) - -/** - * 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. - * - * @param[in] obj Arbitrary ruby object. - * @retval true `obj` is capable of shared across ractors. - * @retval false `obj` cannot travel across ractor boundaries. - */ -static inline bool -rb_ractor_shareable_p(VALUE obj) -{ - bool rb_ractor_shareable_p_continue(VALUE obj); - - if (RB_SPECIAL_CONST_P(obj)) { - return true; - } - else if (RB_OBJ_SHAREABLE_P(obj)) { - return true; - } - else { - return rb_ractor_shareable_p_continue(obj); - } -} - -#endif /* RUBY_RACTOR_H */ |