Ruby: include/ruby/internal/rgengc.h File Reference

Ruby 3.2.5p208 (2024-07-26 revision 31d0f1a2e7dbfb60731d1f05b868e1d578cda493)

Macros | Functions
rgengc.h File Reference

RGENGC write-barrier APIs. More...

`#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"`

Go to the source code of this file.

## Macros
#define | USE_RGENGC 1
#define | USE_RINCGC 1
| This is a compile-time flag to enable/disable incremental GC feature.
#define | USE_RGENGC_LOGGING_WB_UNPROTECT 0
#define | RGENGC_WB_PROTECTED_ARRAY 1
| This is a compile-time flag to enable/disable write barrier for struct RArray.
#define | RGENGC_WB_PROTECTED_HASH 1
| This is a compile-time flag to enable/disable write barrier for struct RHash.
#define | RGENGC_WB_PROTECTED_STRUCT 1
| This is a compile-time flag to enable/disable write barrier for struct RStruct.
#define | RGENGC_WB_PROTECTED_STRING 1
| This is a compile-time flag to enable/disable write barrier for struct RString.
#define | RGENGC_WB_PROTECTED_OBJECT 1
| This is a compile-time flag to enable/disable write barrier for struct RObject.
#define | RGENGC_WB_PROTECTED_REGEXP 1
| This is a compile-time flag to enable/disable write barrier for struct RRegexp.
#define | RGENGC_WB_PROTECTED_CLASS 1
| This is a compile-time flag to enable/disable write barrier for struct RClass.
#define | RGENGC_WB_PROTECTED_FLOAT 1
| This is a compile-time flag to enable/disable write barrier for struct RFloat.
#define | RGENGC_WB_PROTECTED_COMPLEX 1
| This is a compile-time flag to enable/disable write barrier for struct RComplex.
#define | RGENGC_WB_PROTECTED_RATIONAL 1
| This is a compile-time flag to enable/disable write barrier for struct RRational.
#define | RGENGC_WB_PROTECTED_BIGNUM 1
| This is a compile-time flag to enable/disable write barrier for struct RBignum.
#define | RGENGC_WB_PROTECTED_NODE_CREF 1
#define | RB_OBJ_WRITE(old, slot, young)
| Declaration of a "back" pointer.
#define | RB_OBJ_WRITTEN(old, oldv, young)
| Identical to RB_OBJ_WRITE(), except it doesn't write any values, but only a WB declaration.
#define | OBJ_PROMOTED_RAW RB_OBJ_PROMOTED_RAW
| Old name of RB_OBJ_PROMOTED_RAW.
#define | OBJ_PROMOTED RB_OBJ_PROMOTED
| Old name of RB_OBJ_PROMOTED.
#define | OBJ_WB_UNPROTECT RB_OBJ_WB_UNPROTECT
| Old name of RB_OBJ_WB_UNPROTECT.
#define | RB_OBJ_WB_UNPROTECT(x)
| Asserts that the passed object is not fenced by write barriers.
#define | RB_OBJ_WB_UNPROTECT_FOR(type, obj)
| Identical to RB_OBJ_WB_UNPROTECT(), except it can also assert that the given object is of given type.
#define | RGENGC_LOGGING_WB_UNPROTECT rb_gc_unprotect_logging
| This is an implementation detail of rb_obj_wb_unprotect().

## Functions
void | rb_gc_writebarrier (VALUE old, VALUE young)
| This is the implementation of RB_OBJ_WRITE().
void | rb_gc_writebarrier_unprotect (VALUE obj)
| This is the implementation of RB_OBJ_WB_UNPROTECT().
static bool | RB_OBJ_PROMOTED_RAW (VALUE obj)
| This is the implementation of RB_OBJ_PROMOTED().
static bool | RB_OBJ_PROMOTED (VALUE obj)
| Tests if the object is "promoted" – that is, whether the object experienced one or more GC marks.
static VALUE | rb_obj_wb_unprotect (VALUE x, const char *filename, int line)
| This is the implementation of RB_OBJ_WB_UNPROTECT().

## Detailed Description

RGENGC write-barrier APIs.

Author
  Ruby developers ruby-.nosp@m.core.nosp@m.@ruby.nosp@m.-lan.nosp@m.g.org

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.

Warning
  Symbols prefixed with either `RBIMPL` or `rbimpl` are implementation details. Don't take them as canon. They could rapidly appear then vanish. The name (path) of this header file is also an implementation detail. Do not expect it to persist at the place it is now. Developers are free to move it anywhere anytime at will.

Note
  To ruby-core: remember that this header can be possibly recursively included from extension libraries written in C++. Do not expect for instance `__VA_ARGS__` is always available. We assume C99 for ruby itself but we don't assume languages of extension libraries. They could be written in C++98.

See also
  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

Definition in file rgengc.h.

## Macro Definition Documentation

## ◆ RB_OBJ_WB_UNPROTECT

#define RB_OBJ_WB_UNPROTECT | ( |  | x | ) |

Value:
rb_obj_wb_unprotect(x, __FILE__, __LINE__)
rb_obj_wb_unprotect
static VALUE rb_obj_wb_unprotect(VALUE x, const char *filename, int line)
This is the implementation of RB_OBJ_WB_UNPROTECT().
Definition rgengc.h:363

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.

Parameters

  [out] | x | An object that would not be protected by the barrier.

Definition at line 247 of file rgengc.h.

## ◆ RB_OBJ_WB_UNPROTECT_FOR

#define RB_OBJ_WB_UNPROTECT_FOR | ( |  | type,
|  |  | obj )

Value:
(RGENGC_WB_PROTECTED_##type ? OBJ_WB_UNPROTECT(obj) : obj)
OBJ_WB_UNPROTECT
#define OBJ_WB_UNPROTECT
Old name of RB_OBJ_WB_UNPROTECT.
Definition rgengc.h:238

Identical to RB_OBJ_WB_UNPROTECT(), except it can also assert that the given object is of given type.

Parameters

  [in] | type | One of `ARRAY`, `STRING`, etc.
  [out] | obj | An object of `type` that would not be protected.

Definition at line 260 of file rgengc.h.

Referenced by RARRAY_PTR().

## ◆ RGENGC_LOGGING_WB_UNPROTECT

#define RGENGC_LOGGING_WB_UNPROTECT rb_gc_unprotect_logging

This is an implementation detail of rb_obj_wb_unprotect().

People don't use it directly.

Definition at line 269 of file rgengc.h.

Referenced by rb_obj_wb_unprotect().

## ◆ RGENGC_WB_PROTECTED_ARRAY

#define RGENGC_WB_PROTECTED_ARRAY 1

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.

Definition at line 74 of file rgengc.h.

## ◆ RGENGC_WB_PROTECTED_BIGNUM

#define RGENGC_WB_PROTECTED_BIGNUM 1

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.

Definition at line 184 of file rgengc.h.

## ◆ RGENGC_WB_PROTECTED_CLASS

#define RGENGC_WB_PROTECTED_CLASS 1

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.

Definition at line 140 of file rgengc.h.

Referenced by class_alloc().

## ◆ RGENGC_WB_PROTECTED_COMPLEX

#define RGENGC_WB_PROTECTED_COMPLEX 1

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.

Definition at line 162 of file rgengc.h.

## ◆ RGENGC_WB_PROTECTED_FLOAT

#define RGENGC_WB_PROTECTED_FLOAT 1

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.

Definition at line 151 of file rgengc.h.

Referenced by rb_float_new_in_heap().

## ◆ RGENGC_WB_PROTECTED_HASH

#define RGENGC_WB_PROTECTED_HASH 1

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.

Definition at line 85 of file rgengc.h.

## ◆ RGENGC_WB_PROTECTED_NODE_CREF

#define RGENGC_WB_PROTECTED_NODE_CREF 1

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.

Definition at line 199 of file rgengc.h.

## ◆ RGENGC_WB_PROTECTED_OBJECT

#define RGENGC_WB_PROTECTED_OBJECT 1

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.

Definition at line 118 of file rgengc.h.

## ◆ RGENGC_WB_PROTECTED_RATIONAL

#define RGENGC_WB_PROTECTED_RATIONAL 1

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.

Definition at line 173 of file rgengc.h.

## ◆ RGENGC_WB_PROTECTED_REGEXP

#define RGENGC_WB_PROTECTED_REGEXP 1

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.

Definition at line 129 of file rgengc.h.

## ◆ RGENGC_WB_PROTECTED_STRING

#define RGENGC_WB_PROTECTED_STRING 1

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.

Definition at line 107 of file rgengc.h.

## ◆ RGENGC_WB_PROTECTED_STRUCT

#define RGENGC_WB_PROTECTED_STRUCT 1

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.

Definition at line 96 of file rgengc.h.

## ◆ USE_RGENGC

#define USE_RGENGC 1

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.

Definition at line 44 of file rgengc.h.

## ◆ USE_RGENGC_LOGGING_WB_UNPROTECT

#define USE_RGENGC_LOGGING_WB_UNPROTECT 0

Deprecated
  This macro seems broken. Setting this to anything other than zero just doesn't compile. We need to KonMari.

Definition at line 63 of file rgengc.h.

## ◆ USE_RINCGC

#define USE_RINCGC 1

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.

Definition at line 55 of file rgengc.h.

## Function Documentation

## ◆ rb_gc_writebarrier()

void rb_gc_writebarrier | ( | VALUE | old,
|  | VALUE | young )

This is the implementation of RB_OBJ_WRITE().

People don't use it directly.

Parameters

  [in] | old | An object that points to `young`.
  [out] | young | An object that is referenced from `old`.

Definition at line 9025 of file gc.c.

## ◆ rb_gc_writebarrier_unprotect()

void rb_gc_writebarrier_unprotect | ( | VALUE | obj | ) |

This is the implementation of RB_OBJ_WB_UNPROTECT().

People don't use it directly.

Parameters

  [out] | obj | An object that does not participate in WB.

Definition at line 9063 of file gc.c.

Referenced by rb_obj_wb_unprotect().

## ◆ RB_OBJ_PROMOTED()

static bool RB_OBJ_PROMOTED | ( | VALUE | obj | ) |
| inlinestatic

Tests if the object is "promoted" – that is, whether the object experienced one or more GC marks.

Parameters

  [in] | obj | An object to query.

Return values

  true | The object is "promoted".
  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.

Definition at line 343 of file rgengc.h.

## ◆ RB_OBJ_PROMOTED_RAW()

static bool RB_OBJ_PROMOTED_RAW | ( | VALUE | obj | ) |
| inlinestatic

This is the implementation of RB_OBJ_PROMOTED().

People don't use it directly.

Parameters

  [in] | obj | An object to query.

Return values

  true | The object is "promoted".
  false | The object is young. Have not experienced GC at all.

Definition at line 323 of file rgengc.h.

Referenced by RB_OBJ_PROMOTED().

## ◆ rb_obj_wb_unprotect()

static VALUE rb_obj_wb_unprotect | ( | VALUE | x,
|  | const char * | filename,
|  | int | line )
| inlinestatic

This is the implementation of RB_OBJ_WB_UNPROTECT().

People don't use it directly.

Parameters

  [out] | x | An object that does not participate in WB.
  [in] | filename | C's `__FILE__` of the caller function.
  [in] | line | C's `__LINE__` of the caller function.

Returns
  x

Definition at line 363 of file rgengc.h.