mirror of
https://github.com/ruby/ruby.git
synced 2022-11-09 12:17:21 -05:00
2fa4715bf2
My bad. The document is clearly broken. Maybe I pressed my delete key too much. [ci skip]
264 lines
8.7 KiB
C++
264 lines
8.7 KiB
C++
#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 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);
|
|
|
|
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 */
|