(2d6097a0f588527a6b23679fc1503c361c068200)

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"

Include dependency graph for rgengc.h:

This graph shows which files directly or indirectly include this file:

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. More...

#define	RGENGC_WB_PROTECTED_ARRAY 1
	This is a compile-time flag to enable/disable write barrier for struct RArray. More...

#define	RGENGC_WB_PROTECTED_HASH 1
	This is a compile-time flag to enable/disable write barrier for struct RHash. More...

#define	RGENGC_WB_PROTECTED_STRUCT 1
	This is a compile-time flag to enable/disable write barrier for struct RStruct. More...

#define	RGENGC_WB_PROTECTED_STRING 1
	This is a compile-time flag to enable/disable write barrier for struct RString. More...

#define	RGENGC_WB_PROTECTED_OBJECT 1
	This is a compile-time flag to enable/disable write barrier for struct RObject. More...

#define	RGENGC_WB_PROTECTED_REGEXP 1
	This is a compile-time flag to enable/disable write barrier for struct RRegexp. More...

#define	RGENGC_WB_PROTECTED_MATCH 1
	This is a compile-time flag to enable/disable write barrier for struct RMatch. More...

#define	RGENGC_WB_PROTECTED_CLASS 1
	This is a compile-time flag to enable/disable write barrier for struct RClass. More...

#define	RGENGC_WB_PROTECTED_FLOAT 1
	This is a compile-time flag to enable/disable write barrier for struct RFloat. More...

#define	RGENGC_WB_PROTECTED_COMPLEX 1
	This is a compile-time flag to enable/disable write barrier for struct RComplex. More...

#define	RGENGC_WB_PROTECTED_RATIONAL 1
	This is a compile-time flag to enable/disable write barrier for struct RRational. More...

#define	RGENGC_WB_PROTECTED_BIGNUM 1
	This is a compile-time flag to enable/disable write barrier for struct RBignum. More...

#define	RGENGC_WB_PROTECTED_NODE_CREF 1

#define	RB_OBJ_WRITE(old, slot, young) RBIMPL_CAST(rb_obj_write((VALUE)(old), (VALUE *)(slot), (VALUE)(young), __FILE__, __LINE__))
	Declaration of a "back" pointer. More...

#define	RB_OBJ_WRITTEN(old, oldv, young) RBIMPL_CAST(rb_obj_written((VALUE)(old), (VALUE)(oldv), (VALUE)(young), __FILE__, __LINE__))
	Identical to RB_OBJ_WRITE(), except it doesn't write any values, but only a WB declaration. More...

#define	OBJ_PROMOTED_RAW RB_OBJ_PROMOTED_RAW
	Old name of RB_OBJ_PROMOTED_RAW. More...

#define	OBJ_PROMOTED RB_OBJ_PROMOTED
	Old name of RB_OBJ_PROMOTED. More...

#define	OBJ_WB_UNPROTECT RB_OBJ_WB_UNPROTECT
	Old name of RB_OBJ_WB_UNPROTECT. More...

#define	RB_OBJ_WB_UNPROTECT(x) rb_obj_wb_unprotect(x, __FILE__, __LINE__)
	Asserts that the passed object is not fenced by write barriers. More...

#define	RB_OBJ_WB_UNPROTECT_FOR(type, obj) (RGENGC_WB_PROTECTED_##type ? OBJ_WB_UNPROTECT(obj) : obj)
	Identical to RB_OBJ_WB_UNPROTECT(), except it can also assert that the given object is of given type. More...

#define	RGENGC_LOGGING_WB_UNPROTECT rb_gc_unprotect_logging
	This is an implementation detail of rb_obj_wb_unprotect(). More...

#define	RGENGC_LOGGING_OBJ_WRITTEN rb_gc_obj_written_logging

Functions
void	rb_gc_writebarrier (VALUE old, VALUE young)
	This is the implementation of RB_OBJ_WRITE(). More...

void	rb_gc_writebarrier_unprotect (VALUE obj)
	This is the implementation of RB_OBJ_WB_UNPROTECT(). More...

static bool	RB_OBJ_PROMOTED_RAW (VALUE obj)
	This is the implementation of RB_OBJ_PROMOTED(). More...

static bool	RB_OBJ_PROMOTED (VALUE obj)
	Tests if the object is "promoted" – that is, whether the object experienced one or more GC marks. More...

static VALUE	rb_obj_wb_unprotect (VALUE x, const char *filename, int line)
	This is the implementation of RB_OBJ_WB_UNPROTECT(). More...

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 ) rb_obj_wb_unprotect(x, __FILE__, __LINE__)

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 250 of file rgengc.h.

◆ RB_OBJ_WB_UNPROTECT_FOR

#define RB_OBJ_WB_UNPROTECT_FOR	(	type,
		obj
	)	(RGENGC_WB_PROTECTED_##type ? OBJ_WB_UNPROTECT(obj) : obj)

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 263 of file rgengc.h.

◆ 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 272 of file rgengc.h.

◆ 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 66 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 187 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 143 of file rgengc.h.

◆ 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 165 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 154 of file rgengc.h.

◆ 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 77 of file rgengc.h.

◆ RGENGC_WB_PROTECTED_MATCH

#define RGENGC_WB_PROTECTED_MATCH 1

This is a compile-time flag to enable/disable write barrier for struct RMatch.

It has to be set at the time ruby itself compiles. Makes no sense for 3rd parties.

Definition at line 132 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 202 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 110 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 176 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 121 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 99 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 88 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_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 9092 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 9130 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 330 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 310 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 350 of file rgengc.h.

(2d6097a0f588527a6b23679fc1503c361c068200)

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ RB_OBJ_WB_UNPROTECT

◆ RB_OBJ_WB_UNPROTECT_FOR

◆ RGENGC_LOGGING_WB_UNPROTECT

◆ RGENGC_WB_PROTECTED_ARRAY

◆ RGENGC_WB_PROTECTED_BIGNUM

◆ RGENGC_WB_PROTECTED_CLASS

◆ RGENGC_WB_PROTECTED_COMPLEX

◆ RGENGC_WB_PROTECTED_FLOAT

◆ RGENGC_WB_PROTECTED_HASH

◆ RGENGC_WB_PROTECTED_MATCH

◆ RGENGC_WB_PROTECTED_NODE_CREF

◆ RGENGC_WB_PROTECTED_OBJECT

◆ RGENGC_WB_PROTECTED_RATIONAL

◆ RGENGC_WB_PROTECTED_REGEXP

◆ RGENGC_WB_PROTECTED_STRING

◆ RGENGC_WB_PROTECTED_STRUCT

◆ USE_RGENGC

◆ USE_RINCGC

Function Documentation

◆ rb_gc_writebarrier()

◆ rb_gc_writebarrier_unprotect()

◆ RB_OBJ_PROMOTED()

◆ RB_OBJ_PROMOTED_RAW()

◆ rb_obj_wb_unprotect()