include/ruby/ractor.h: add doxygen

Must not be a bad idea to improve documents. [ci skip]

1 files changed, 202 insertions, 7 deletions

diff --git a/include/ruby/ractor.h b/include/ruby/ractor.h
index 1d6687456c..47eac038c9 100644
--- a/include/ruby/ractor.h
+++ b/include/ruby/ractor.h
@@ -1,4 +1,4 @@
-#ifndef RUBY_RACTOR_H
+#ifndef RUBY_RACTOR_H                                /*-*-C++-*-vi:se ft=cpp:*/
 #define RUBY_RACTOR_H 1
 
 /**
@@ -11,50 +11,245 @@
  *             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)) {