mirror of
https://github.com/ruby/ruby.git
synced 2022-11-09 12:17:21 -05:00
include/ruby/internal/rgengc.h: add dosygen
Must not be a bad idea to improve documents. [ci skip]
This commit is contained in:
卜部昌平
parent
2061dadb0a
commit
c3c0bf6823
Notes:
git
2021-09-10 20:01:52 +09:00
2 changed files with 265 additions and 20 deletions
|
|
@ -22,106 +22,250 @@
|
|||
* @see Sasada, K., "Gradual write-barrier insertion into a Ruby
|
||||
* interpreter", in proceedings of the 2019 ACM SIGPLAN
|
||||
* International Symposium on Memory Management (ISMM 2019), pp
|
||||
* 115-121, 2019. https://doi.org/10.1145/3315573.3329986
|
||||
* 115-121, 2019. https://doi.org/10.1145/3315573.3329986
|
||||
*/
|
||||
#include "ruby/internal/attr/artificial.h"
|
||||
#include "ruby/internal/attr/maybe_unused.h"
|
||||
#include "ruby/internal/attr/pure.h"
|
||||
#include "ruby/internal/dllexport.h"
|
||||
#include "ruby/internal/special_consts.h"
|
||||
#include "ruby/internal/stdbool.h"
|
||||
#include "ruby/internal/value.h"
|
||||
#include "ruby/assert.h"
|
||||
#include "ruby/backward/2/attributes.h"
|
||||
|
||||
/**
|
||||
* @private
|
||||
*
|
||||
* @deprecated This macro once was a thing in the old days, but makes no sense
|
||||
* any longer today. Exists here for backwards compatibility
|
||||
* only. You can safely forget about it.
|
||||
*/
|
||||
#undef USE_RGENGC
|
||||
#define USE_RGENGC 1
|
||||
|
||||
/**
|
||||
* @private
|
||||
*
|
||||
* This is a compile-time flag to enable/disable incremental GC feature. It
|
||||
* has to be set at the time ruby itself compiles. Makes no sense for 3rd
|
||||
* parties. It is safe for them to set this though; that just doesn't change
|
||||
* anything.
|
||||
*/
|
||||
#ifndef USE_RINCGC
|
||||
# define USE_RINCGC 1
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @deprecated This macro seems broken. Setting this to anything other than
|
||||
* zero just doesn't compile. We need to KonMari.
|
||||
*/
|
||||
#ifndef USE_RGENGC_LOGGING_WB_UNPROTECT
|
||||
# define USE_RGENGC_LOGGING_WB_UNPROTECT 0
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @private
|
||||
*
|
||||
* This is a compile-time flag to enable/disable write barrier for
|
||||
* struct ::RArray. It has to be set at the time ruby itself compiles. Makes
|
||||
* no sense for 3rd parties.
|
||||
*/
|
||||
#ifndef RGENGC_WB_PROTECTED_ARRAY
|
||||
# define RGENGC_WB_PROTECTED_ARRAY 1
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @private
|
||||
*
|
||||
* This is a compile-time flag to enable/disable write barrier for
|
||||
* struct ::RHash. It has to be set at the time ruby itself compiles. Makes
|
||||
* no sense for 3rd parties.
|
||||
*/
|
||||
#ifndef RGENGC_WB_PROTECTED_HASH
|
||||
# define RGENGC_WB_PROTECTED_HASH 1
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @private
|
||||
*
|
||||
* This is a compile-time flag to enable/disable write barrier for
|
||||
* struct ::RStruct. It has to be set at the time ruby itself compiles. Makes
|
||||
* no sense for 3rd parties.
|
||||
*/
|
||||
#ifndef RGENGC_WB_PROTECTED_STRUCT
|
||||
# define RGENGC_WB_PROTECTED_STRUCT 1
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @private
|
||||
*
|
||||
* This is a compile-time flag to enable/disable write barrier for
|
||||
* struct ::RString. It has to be set at the time ruby itself compiles. Makes
|
||||
* no sense for 3rd parties.
|
||||
*/
|
||||
#ifndef RGENGC_WB_PROTECTED_STRING
|
||||
# define RGENGC_WB_PROTECTED_STRING 1
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @private
|
||||
*
|
||||
* This is a compile-time flag to enable/disable write barrier for
|
||||
* struct ::RObject. It has to be set at the time ruby itself compiles. Makes
|
||||
* no sense for 3rd parties.
|
||||
*/
|
||||
#ifndef RGENGC_WB_PROTECTED_OBJECT
|
||||
# define RGENGC_WB_PROTECTED_OBJECT 1
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @private
|
||||
*
|
||||
* This is a compile-time flag to enable/disable write barrier for
|
||||
* struct ::RRegexp. It has to be set at the time ruby itself compiles. Makes
|
||||
* no sense for 3rd parties.
|
||||
*/
|
||||
#ifndef RGENGC_WB_PROTECTED_REGEXP
|
||||
# define RGENGC_WB_PROTECTED_REGEXP 1
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @private
|
||||
*
|
||||
* This is a compile-time flag to enable/disable write barrier for
|
||||
* struct ::RClass. It has to be set at the time ruby itself compiles. Makes
|
||||
* no sense for 3rd parties.
|
||||
*/
|
||||
#ifndef RGENGC_WB_PROTECTED_CLASS
|
||||
# define RGENGC_WB_PROTECTED_CLASS 1
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @private
|
||||
*
|
||||
* This is a compile-time flag to enable/disable write barrier for
|
||||
* struct ::RFloat. It has to be set at the time ruby itself compiles. Makes
|
||||
* no sense for 3rd parties.
|
||||
*/
|
||||
#ifndef RGENGC_WB_PROTECTED_FLOAT
|
||||
# define RGENGC_WB_PROTECTED_FLOAT 1
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @private
|
||||
*
|
||||
* This is a compile-time flag to enable/disable write barrier for
|
||||
* struct ::RComplex. It has to be set at the time ruby itself compiles.
|
||||
* Makes no sense for 3rd parties.
|
||||
*/
|
||||
#ifndef RGENGC_WB_PROTECTED_COMPLEX
|
||||
# define RGENGC_WB_PROTECTED_COMPLEX 1
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @private
|
||||
*
|
||||
* This is a compile-time flag to enable/disable write barrier for
|
||||
* struct ::RRational. It has to be set at the time ruby itself compiles.
|
||||
* Makes no sense for 3rd parties.
|
||||
*/
|
||||
#ifndef RGENGC_WB_PROTECTED_RATIONAL
|
||||
# define RGENGC_WB_PROTECTED_RATIONAL 1
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @private
|
||||
*
|
||||
* This is a compile-time flag to enable/disable write barrier for
|
||||
* struct ::RBignum. It has to be set at the time ruby itself compiles. Makes
|
||||
* no sense for 3rd parties.
|
||||
*/
|
||||
#ifndef RGENGC_WB_PROTECTED_BIGNUM
|
||||
# define RGENGC_WB_PROTECTED_BIGNUM 1
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @private
|
||||
*
|
||||
* @deprecated This macro once was a thing in the old days, but makes no sense
|
||||
* any longer today. Exists here for backwards compatibility
|
||||
* only. You can safely forget about it.
|
||||
*
|
||||
* @internal
|
||||
*
|
||||
* @shyouhei doesn't think anybody uses this right now.
|
||||
*/
|
||||
#ifndef RGENGC_WB_PROTECTED_NODE_CREF
|
||||
# define RGENGC_WB_PROTECTED_NODE_CREF 1
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @name Write barrier (WB) interfaces:
|
||||
* @{
|
||||
* @defgroup rgengc Write barrier (WB) interfaces:
|
||||
*
|
||||
* @note The following core interfaces can be changed in the future. Please
|
||||
* catch up if you want to insert WB into C-extensions correctly.
|
||||
*
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* WB for new reference from `a' to `b'. Write `b' into `*slot'. `slot' is a
|
||||
* pointer in `a'.
|
||||
* Declaration of a "back" pointer. This is a write barrier for new reference
|
||||
* from "old" generation to "young" generation. It writes `young` into
|
||||
* `*slot`, which is a pointer inside of `old`.
|
||||
*
|
||||
* @param[in] old An old object.
|
||||
* @param[in] slot A pointer inside of `old`.
|
||||
* @param[out] young A young object.
|
||||
*/
|
||||
#define RB_OBJ_WRITE(a, slot, b) \
|
||||
RBIMPL_CAST(rb_obj_write((VALUE)(a), (VALUE *)(slot), (VALUE)(b), __FILE__, __LINE__))
|
||||
#define RB_OBJ_WRITE(old, slot, young) \
|
||||
RBIMPL_CAST(rb_obj_write((VALUE)(old), (VALUE *)(slot), (VALUE)(young), __FILE__, __LINE__))
|
||||
|
||||
/**
|
||||
* WB for new reference from `a' to `b'. This doesn't write any values, but
|
||||
* only a WB declaration. `oldv' is replaced value with `b' (not used in
|
||||
* current Ruby).
|
||||
* Identical to #RB_OBJ_WRITE(), except it doesn't write any values, but only a
|
||||
* WB declaration. `oldv` is replaced value with `b` (not used in current
|
||||
* Ruby).
|
||||
*
|
||||
* @param[in] old An old object.
|
||||
* @param[in] oldv An object previously stored inside of `old`.
|
||||
* @param[out] young A young object.
|
||||
*/
|
||||
#define RB_OBJ_WRITTEN(a, oldv, b) \
|
||||
RBIMPL_CAST(rb_obj_written((VALUE)(a), (VALUE)(oldv), (VALUE)(b), __FILE__, __LINE__))
|
||||
#define RB_OBJ_WRITTEN(old, oldv, young) \
|
||||
RBIMPL_CAST(rb_obj_written((VALUE)(old), (VALUE)(oldv), (VALUE)(young), __FILE__, __LINE__))
|
||||
/** @} */
|
||||
|
||||
#define OBJ_PROMOTED_RAW RB_OBJ_PROMOTED_RAW
|
||||
#define OBJ_PROMOTED RB_OBJ_PROMOTED
|
||||
#define OBJ_WB_UNPROTECT RB_OBJ_WB_UNPROTECT
|
||||
#define OBJ_PROMOTED_RAW RB_OBJ_PROMOTED_RAW /**< @old{RB_OBJ_PROMOTED_RAW} */
|
||||
#define OBJ_PROMOTED RB_OBJ_PROMOTED /**< @old{RB_OBJ_PROMOTED} */
|
||||
#define OBJ_WB_UNPROTECT RB_OBJ_WB_UNPROTECT /**< @old{RB_OBJ_WB_UNPROTECT} */
|
||||
|
||||
/**
|
||||
* Asserts that the passed object is not fenced by write barriers. Objects of
|
||||
* such property do not contribute to generational GCs. They are scanned
|
||||
* always.
|
||||
*
|
||||
* @param[out] x An object that would not be protected by the barrier.
|
||||
*/
|
||||
#define RB_OBJ_WB_UNPROTECT(x) rb_obj_wb_unprotect(x, __FILE__, __LINE__)
|
||||
|
||||
/**
|
||||
* Identical to #RB_OBJ_WB_UNPROTECT(), except it can also assert that the
|
||||
* given object is of given type.
|
||||
*
|
||||
* @param[in] type One of `ARRAY`, `STRING`, etc.
|
||||
* @param[out] obj An object of `type` that would not be protected.
|
||||
*
|
||||
* @internal
|
||||
*
|
||||
* @shyouhei doesn't understand why this has to be visible from extensions.
|
||||
*/
|
||||
#define RB_OBJ_WB_UNPROTECT_FOR(type, obj) \
|
||||
(RGENGC_WB_PROTECTED_##type ? OBJ_WB_UNPROTECT(obj) : obj)
|
||||
|
||||
/**
|
||||
* @private
|
||||
*
|
||||
* This is an implementation detail of rb_obj_wb_unprotect(). People don't use
|
||||
* it directly.
|
||||
*/
|
||||
#define RGENGC_LOGGING_WB_UNPROTECT rb_gc_unprotect_logging
|
||||
|
||||
/** @cond INTERNAL_MACRO */
|
||||
|
|
@ -130,15 +274,51 @@
|
|||
/** @endcond */
|
||||
|
||||
RBIMPL_SYMBOL_EXPORT_BEGIN()
|
||||
void rb_gc_writebarrier(VALUE a, VALUE b);
|
||||
/**
|
||||
* This is the implementation of #RB_OBJ_WRITE(). People don't use it
|
||||
* directly.
|
||||
*
|
||||
* @param[in] old An object that points to `young`.
|
||||
* @param[out] young An object that is referenced from `old`.
|
||||
*/
|
||||
void rb_gc_writebarrier(VALUE old, VALUE young);
|
||||
|
||||
/**
|
||||
* This is the implementation of #RB_OBJ_WB_UNPROTECT(). People don't use it
|
||||
* directly.
|
||||
*
|
||||
* @param[out] obj An object that does not participate in WB.
|
||||
*/
|
||||
void rb_gc_writebarrier_unprotect(VALUE obj);
|
||||
|
||||
#if USE_RGENGC_LOGGING_WB_UNPROTECT
|
||||
/**
|
||||
* @private
|
||||
*
|
||||
* This is the implementation of #RGENGC_LOGGING_WB_UNPROTECT(). People
|
||||
* don't use it directly.
|
||||
*
|
||||
* @param[in] objptr Don't know why this is a pointer to void but in
|
||||
* reality this is a pointer to an object that is about
|
||||
* to be un-protected.
|
||||
* @param[in] filename Pass C's `__FILE__` here.
|
||||
* @param[in] line Pass C's `__LINE__` here.
|
||||
*/
|
||||
void rb_gc_unprotect_logging(void *objptr, const char *filename, int line);
|
||||
#endif
|
||||
|
||||
RBIMPL_SYMBOL_EXPORT_END()
|
||||
|
||||
RBIMPL_ATTR_PURE_UNLESS_DEBUG()
|
||||
RBIMPL_ATTR_ARTIFICIAL()
|
||||
/**
|
||||
* This is the implementation of #RB_OBJ_PROMOTED(). People don't use it
|
||||
* directly.
|
||||
*
|
||||
* @param[in] obj An object to query.
|
||||
* @retval true The object is "promoted".
|
||||
* @retval false The object is young. Have not experienced GC at all.
|
||||
*/
|
||||
static inline bool
|
||||
RB_OBJ_PROMOTED_RAW(VALUE obj)
|
||||
{
|
||||
|
|
@ -148,6 +328,17 @@ RB_OBJ_PROMOTED_RAW(VALUE obj)
|
|||
|
||||
RBIMPL_ATTR_PURE_UNLESS_DEBUG()
|
||||
RBIMPL_ATTR_ARTIFICIAL()
|
||||
/**
|
||||
* Tests if the object is "promoted" -- that is, whether the object experienced
|
||||
* one or more GC marks.
|
||||
*
|
||||
* @param[in] obj An object to query.
|
||||
* @retval true The object is "promoted".
|
||||
* @retval false The object is young. Have not experienced GC at all.
|
||||
* @note Hello, is anyone actively calling this function? @shyouhei have
|
||||
* never seen any actual usages outside of the GC implementation
|
||||
* itself.
|
||||
*/
|
||||
static inline bool
|
||||
RB_OBJ_PROMOTED(VALUE obj)
|
||||
{
|
||||
|
|
@ -159,8 +350,22 @@ RB_OBJ_PROMOTED(VALUE obj)
|
|||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* This is the implementation of #RB_OBJ_WB_UNPROTECT(). People don't use it
|
||||
* directly.
|
||||
*
|
||||
* @param[out] x An object that does not participate in WB.
|
||||
* @param[in] filename C's `__FILE__` of the caller function.
|
||||
* @param[in] line C's `__LINE__` of the caller function.
|
||||
* @return x
|
||||
*/
|
||||
static inline VALUE
|
||||
rb_obj_wb_unprotect(VALUE x, RB_UNUSED_VAR(const char *filename), RB_UNUSED_VAR(int line))
|
||||
rb_obj_wb_unprotect(
|
||||
VALUE x,
|
||||
RBIMPL_ATTR_MAYBE_UNUSED()
|
||||
const char *filename,
|
||||
RBIMPL_ATTR_MAYBE_UNUSED()
|
||||
int line)
|
||||
{
|
||||
#if USE_RGENGC_LOGGING_WB_UNPROTECT
|
||||
RGENGC_LOGGING_WB_UNPROTECT(RBIMPL_CAST((void *)x), filename, line);
|
||||
|
|
@ -169,8 +374,29 @@ rb_obj_wb_unprotect(VALUE x, RB_UNUSED_VAR(const char *filename), RB_UNUSED_VAR(
|
|||
return x;
|
||||
}
|
||||
|
||||
/**
|
||||
* @private
|
||||
*
|
||||
* This is the implementation of #RB_OBJ_WRITTEN(). People don't use it
|
||||
* directly.
|
||||
*
|
||||
* @param[in] a An old object.
|
||||
* @param[in] oldv An object previously stored inside of `old`.
|
||||
* @param[out] b A young object.
|
||||
* @param[in] filename C's `__FILE__` of the caller function.
|
||||
* @param[in] line C's `__LINE__` of the caller function.
|
||||
* @return a
|
||||
*/
|
||||
static inline VALUE
|
||||
rb_obj_written(VALUE a, RB_UNUSED_VAR(VALUE oldv), VALUE b, RB_UNUSED_VAR(const char *filename), RB_UNUSED_VAR(int line))
|
||||
rb_obj_written(
|
||||
VALUE a,
|
||||
RBIMPL_ATTR_MAYBE_UNUSED()
|
||||
VALUE oldv,
|
||||
VALUE b,
|
||||
RBIMPL_ATTR_MAYBE_UNUSED()
|
||||
const char *filename,
|
||||
RBIMPL_ATTR_MAYBE_UNUSED()
|
||||
int line)
|
||||
{
|
||||
#if USE_RGENGC_LOGGING_WB_UNPROTECT
|
||||
RGENGC_LOGGING_OBJ_WRITTEN(a, oldv, b, filename, line);
|
||||
|
|
@ -183,8 +409,26 @@ rb_obj_written(VALUE a, RB_UNUSED_VAR(VALUE oldv), VALUE b, RB_UNUSED_VAR(const
|
|||
return a;
|
||||
}
|
||||
|
||||
/**
|
||||
* @private
|
||||
*
|
||||
* This is the implementation of #RB_OBJ_WRITE(). People don't use it
|
||||
* directly.
|
||||
*
|
||||
* @param[in] a An old object.
|
||||
* @param[in] slot A pointer inside of `old`.
|
||||
* @param[out] b A young object.
|
||||
* @param[in] filename C's `__FILE__` of the caller function.
|
||||
* @param[in] line C's `__LINE__` of the caller function.
|
||||
* @return a
|
||||
*/
|
||||
static inline VALUE
|
||||
rb_obj_write(VALUE a, VALUE *slot, VALUE b, RB_UNUSED_VAR(const char *filename), RB_UNUSED_VAR(int line))
|
||||
rb_obj_write(
|
||||
VALUE a, VALUE *slot, VALUE b,
|
||||
RBIMPL_ATTR_MAYBE_UNUSED()
|
||||
const char *filename,
|
||||
RBIMPL_ATTR_MAYBE_UNUSED()
|
||||
int line)
|
||||
{
|
||||
#ifdef RGENGC_LOGGING_WRITE
|
||||
RGENGC_LOGGING_WRITE(a, slot, b, filename, line);
|
||||
|
|
|
|||
|
|
@ -2230,6 +2230,7 @@ PREDEFINED += NOINLINE(_)=_
|
|||
PREDEFINED += NORETURN(_)=_
|
||||
PREDEFINED += PRINTF_ARGS(_,__,___)=_
|
||||
PREDEFINED += PUREFUNC(_)=_
|
||||
PREDEFINED += RB_UNUSED_VAR(_)=_
|
||||
PREDEFINED += RUBY_EXTERN=extern
|
||||
PREDEFINED += RUBY_FUNC_EXPORTED=
|
||||
PREDEFINED += RUBY_FUNC_NONNULL(__,_)=_
|
||||
|
|
|
|||
Loading…
Reference in a new issue