ruby-changes:67835
From: =E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3 <ko1@a...>
Date: Fri, 10 Sep 2021 20:02:33 +0900 (JST)
Subject: [ruby-changes:67835] 56c0475036 (master): include/ruby/ractor.h: add doxygen
https://git.ruby-lang.org/ruby.git/commit/?id=56c0475036 From 56c0475036846f542529c52d9c78be9586ecf87d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3?= <shyouhei@r...> Date: Fri, 2 Jul 2021 14:31:54 +0900 Subject: include/ruby/ractor.h: add doxygen Must not be a bad idea to improve documents. [ci skip] --- include/ruby/ractor.h | 209 ++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 202 insertions(+), 7 deletions(-) diff --git a/include/ruby/ractor.h b/include/ruby/ractor.h index 1d66874..47eac03 100644 --- a/include/ruby/ractor.h +++ b/include/ruby/ractor.h @@ -1,4 +1,4 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/ractor.h#L1 -#ifndef RUBY_RACTOR_H +#ifndef RUBY_RACTOR_H /*-*-C++-*-vi:se ft=cpp:*/ #define RUBY_RACTOR_H 1 /** @@ -11,50 +11,245 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/ractor.h#L11 * 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; -RUBY_SYMBOL_EXPORT_BEGIN +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); -void rb_ractor_stdin_set(VALUE); -void rb_ractor_stdout_set(VALUE); -void rb_ractor_stderr_set(VALUE); +/** + * 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 Arbitary 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); -RUBY_SYMBOL_EXPORT_END +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. + * @ + */ static inline bool rb_ractor_shareable_p(VALUE obj) { bool rb_ractor_shareable_p_continue(VALUE obj); - if (SPECIAL_CONST_P(obj)) { + if (RB_SPECIAL_CONST_P(obj)) { return true; } else if (RB_OBJ_SHAREABLE_P(obj)) { -- cgit v1.1 -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/