From 63ab2fedc86e463cb5132e19c285f5c3442ca5f7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3?= Date: Tue, 14 Sep 2021 16:25:28 +0900 Subject: [PATCH] include/ruby/atomic.h: add doxygen Must not be a bad idea to improve documents. [ci skip] --- include/ruby/atomic.h | 258 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 257 insertions(+), 1 deletion(-) diff --git a/include/ruby/atomic.h b/include/ruby/atomic.h index 083f1f6aa0d189..8665de692e7411 100644 --- a/include/ruby/atomic.h +++ b/include/ruby/atomic.h @@ -1,5 +1,28 @@ -#ifndef RUBY_ATOMIC_H +#ifndef RUBY_ATOMIC_H /*-*-C++-*-vi:se ft=cpp:*/ #define RUBY_ATOMIC_H +/** + * @file + * @author Ruby developers + * @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. + * @brief Atomic operations + * + * Basically, if we could assume either C11 or C++11, these macros are just + * redundant. Sadly we cannot. We have to do them ourselves. + */ /* * - RUBY_ATOMIC_CAS, RUBY_ATOMIC_EXCHANGE, RUBY_ATOMIC_FETCH_*: @@ -135,67 +158,300 @@ rb_atomic_fetch_sub(volatile rb_atomic_t *var, rb_atomic_t val) # define RUBY_ATOMIC_SIZE_EXCHANGE(var, val) atomic_swap_uint(&(var), (val)) # endif +#elif defined(__DOXYGEN__) +/** + * Asserts that your environment supports more than one atomic types. These + * days systems tend to have such property (C11 was a standard of decades ago, + * right?) but we still support older ones. + */ +# define RUBY_ATOMIC_GENERIC_MACRO 1 + +/** + * Type that is eligible for atomic operations. Depending on your host + * platform you might have more than one such type, but we choose one of them + * anyways. + */ +using rb_atomic_t = std::atomic; + +/** + * Atomically replaces the value pointed by `var` with the result of addition + * of `val` to the old value of `var`. In case #RUBY_ATOMIC_GENERIC_MACRO is + * set, this operation could be applied to a signed integer type. However + * there is no portabe way to know what happens on integer overflow on such + * situations. You might better stick to unsigned types. + * + * @param var A variable of ::rb_atomic_t. + * @param val Value to add. + * @return What was stored in `var` before the addition. + * @post `var` holds `var + val`. + */ +# define RUBY_ATOMIC_FETCH_ADD(var, val) std::atomic_fetch_add(&(var), val) + +/** + * Atomically replaces the value pointed by `var` with the result of addition + * of `val` to the old value of `var`. In case #RUBY_ATOMIC_GENERIC_MACRO is + * set, this operation could be applied to a signed integer type. However + * there is no portabe way to know what happens on integer overflow on such + * situations. You might better stick to unsigned types. + * + * @param var A variable of ::rb_atomic_t. + * @param val Value to subtract. + * @return What was stored in `var` before the suntraction. + * @post `var` holds `var - val`. + */ +# define RUBY_ATOMIC_FETCH_SUB(var, val) std::atomic_fetch_sub(&(var), val) + +/** + * Atomically replaces the value pointed by `var` with the result of + * bitwise OR between `val` and the old value of `var`. + * + * @param var A variable of ::rb_atomic_t. + * @param val Value to mix. + * @return void + * @post `var` holds `var | val`. + * @note For portability, this macro can return void. + */ +# define RUBY_ATOMIC_OR(var, val) (void)std::atomic_fetch_or(&(var), val) + +/** + * Atomically replaces the value pointed by `var` with `val`. This is just an + * assignment, but you can additionally know the previous value. + * + * @param var A variable of ::rb_atomic_t. + * @param val Value to set. + * @return What was stored in `var` before the assignment. + * @post `var` holds `val`. + */ +# define RUBY_ATOMIC_EXCHANGE(var, val) std::atomic_exchange(&(var), (val)) + +/** + * Atomic compare-and-swap. This stores `val` to `var` if and only if the + * assignment changes the value of `var` from `oldval` to `newval`. You can + * detect whether the assignment happened or not using the return value. + * + * @param var A variable of ::rb_atomic_t. + * @param oldval Expected value of `var` before the assignment. + * @param newval What you want to store at `var`. + * @retval 1 Successful assignment. + * @retval 0 Something different from `oldval` resides at `var`. + */ +# define RUBY_ATOMIC_CAS(var, oldval, newval) \ + std::atomic_compare_exchange_strong(&(var), (newval), (oldval)) + #else # error No atomic operation found #endif +/** + * Identical to #RUBY_ATOMIC_EXCHANGE, except for the return type. + * + * @param var A variable of ::rb_atomic_t. + * @param val Value to set. + * @return void + * @post `var` holds `val`. + */ #ifndef RUBY_ATOMIC_SET # define RUBY_ATOMIC_SET(var, val) (void)RUBY_ATOMIC_EXCHANGE(var, val) #endif +/** + * Identical to #RUBY_ATOMIC_FETCH_ADD, except for the return type. + * + * @param var A variable of ::rb_atomic_t. + * @param val Value to add. + * @return void + * @post `var` holds `var + val`. + */ #ifndef RUBY_ATOMIC_ADD # define RUBY_ATOMIC_ADD(var, val) (void)RUBY_ATOMIC_FETCH_ADD(var, val) #endif +/** + * Identical to #RUBY_ATOMIC_FETCH_ADD, except for the return type. + * + * @param var A variable of ::rb_atomic_t. + * @param val Value to subtract. + * @return void + * @post `var` holds `var - val`. + */ #ifndef RUBY_ATOMIC_SUB # define RUBY_ATOMIC_SUB(var, val) (void)RUBY_ATOMIC_FETCH_SUB(var, val) #endif +/** + * Atomically increments the value pointed by `var`. + * + * @param var A variable of ::rb_atomic_t. + * @return void + * @post `var` holds `var + 1`. + */ #ifndef RUBY_ATOMIC_INC # define RUBY_ATOMIC_INC(var) RUBY_ATOMIC_ADD(var, 1) #endif +/** + * Atomically decrements the value pointed by `var`. + * + * @param var A variable of ::rb_atomic_t. + * @return void + * @post `var` holds `var - 1`. + */ #ifndef RUBY_ATOMIC_DEC # define RUBY_ATOMIC_DEC(var) RUBY_ATOMIC_SUB(var, 1) #endif +/** + * Identical to #RUBY_ATOMIC_INC, except it expects its argument is an + * (possibly `_Atomic` qualified) unsigned integer of the same width of + * `size_t`. There are cases where ::rb_atomic_t is 32bit while `size_t` is + * 64bit. This should be used for size related operations to support such + * platforms. + * + * @param var A variable of (possibly _Atomic qualified) `size_t`. + * @return void + * @post `var` holds `var + 1`. + */ #ifndef RUBY_ATOMIC_SIZE_INC # define RUBY_ATOMIC_SIZE_INC(var) RUBY_ATOMIC_INC(var) #endif +/** + * Identical to #RUBY_ATOMIC_DEC, except it expects its argument is an + * (possibly `_Atomic` qualified) unsigned integer of the same width of + * `size_t`. There are cases where ::rb_atomic_t is 32bit while `size_t` is + * 64bit. This should be used for size related operations to support such + * platforms. + * + * @param var A variable of (possibly _Atomic qualified) `size_t`. + * @return void + * @post `var` holds `var - 1`. + */ #ifndef RUBY_ATOMIC_SIZE_DEC # define RUBY_ATOMIC_SIZE_DEC(var) RUBY_ATOMIC_DEC(var) #endif +/** + * Identical to #RUBY_ATOMIC_EXCHANGE, except it expects its arguments are + * (possibly `_Atomic` qualified) unsigned integers of the same width of + * `size_t`. There are cases where ::rb_atomic_t is 32bit while `size_t` is + * 64bit. This should be used for size related operations to support such + * platforms. + * + * @param var A variable of (possibly _Atomic qualified) `size_t`. + * @param val Value to set. + * @return What was stored in `var` before the assignment. + * @post `var` holds `val`. + */ #ifndef RUBY_ATOMIC_SIZE_EXCHANGE # define RUBY_ATOMIC_SIZE_EXCHANGE(var, val) RUBY_ATOMIC_EXCHANGE(var, val) #endif +/** + * Identical to #RUBY_ATOMIC_CAS, except it expects its arguments are (possibly + * `_Atomic` qualified) unsigned integers of the same width of `size_t`. There + * are cases where ::rb_atomic_t is 32bit while `size_t` is 64bit. This should + * be used for size related operations to support such platforms. + * + * @param var A variable of (possibly _Atomic qualified) `size_t`. + * @param oldval Expected value of `var` before the assignment. + * @param val What you want to store at `var`. + * @retval 1 Successful assignment. + * @retval 0 Something different from `oldval` resides at `var`. + */ #ifndef RUBY_ATOMIC_SIZE_CAS # define RUBY_ATOMIC_SIZE_CAS(var, oldval, val) RUBY_ATOMIC_CAS(var, oldval, val) #endif +/** + * Identical to #RUBY_ATOMIC_ADD, except it expects its arguments are (possibly + * `_Atomic` qualified) unsigned integers of the same width of `size_t`. There + * are cases where ::rb_atomic_t is 32bit while `size_t` is 64bit. This should + * be used for size related operations to support such platforms. + * + * @param var A variable of (possibly _Atomic qualified) `size_t`. + * @param val Value to add. + * @return void + * @post `var` holds `var + val`. + */ #ifndef RUBY_ATOMIC_SIZE_ADD # define RUBY_ATOMIC_SIZE_ADD(var, val) RUBY_ATOMIC_ADD(var, val) #endif +/** + * Identical to #RUBY_ATOMIC_SUB, except it expects its arguments are (possibly + * `_Atomic` qualified) unsigned integers of the same width of `size_t`. There + * are cases where ::rb_atomic_t is 32bit while `size_t` is 64bit. This should + * be used for size related operations to support such platforms. + * + * @param var A variable of (possibly _Atomic qualified) `size_t`. + * @param val Value to subtract. + * @return void + * @post `var` holds `var - val`. + */ #ifndef RUBY_ATOMIC_SIZE_SUB # define RUBY_ATOMIC_SIZE_SUB(var, val) RUBY_ATOMIC_SUB(var, val) #endif #if RUBY_ATOMIC_GENERIC_MACRO +/** + * Identical to #RUBY_ATOMIC_EXCHANGE, except it expects its arguments are + * (possibly `_Atomic` qualified) unsigned integers of the same width of + * `void*`. There are cases where ::rb_atomic_t is 32bit while `void*` is + * 64bit. This should be used for pointer related operations to support such + * platforms. + * + * @param var A variable of (possibly _Atomic qualified) `void *`. + * @param val Value to set. + * @return What was stored in `var` before the assignment. + * @post `var` holds `val`. + */ # ifndef RUBY_ATOMIC_PTR_EXCHANGE # define RUBY_ATOMIC_PTR_EXCHANGE(var, val) RUBY_ATOMIC_EXCHANGE(var, val) # endif +/** + * Identical to #RUBY_ATOMIC_CAS, except it expects its arguments are (possibly + * `_Atomic` qualified) unsigned integers of the same width of `void*`. There + * are cases where ::rb_atomic_t is 32bit while `void*` is 64bit. This should + * be used for size related operations to support such platforms. + * + * @param var A variable of (possibly _Atomic qualified) `void*`. + * @param oldval Expected value of `var` before the assignment. + * @param newval What you want to store at `var`. + * @retval 1 Successful assignment. + * @retval 0 Something different from `oldval` resides at `var`. + */ # ifndef RUBY_ATOMIC_PTR_CAS # define RUBY_ATOMIC_PTR_CAS(var, oldval, newval) RUBY_ATOMIC_CAS(var, oldval, newval) # endif +/** + * Identical to #RUBY_ATOMIC_EXCHANGE, except it expects its arguments are + * ::VALUE. There are cases where ::rb_atomic_t is 32bit while ::VALUE is + * 64bit. This should be used for pointer related operations to support such + * platforms. + * + * @param var A variable of ::VALUE. + * @param val Value to set. + * @return What was stored in `var` before the assignment. + * @post `var` holds `val`. + */ # ifndef RUBY_ATOMIC_VALUE_EXCHANGE # define RUBY_ATOMIC_VALUE_EXCHANGE(var, val) RUBY_ATOMIC_EXCHANGE(var, val) # endif +/** + * Identical to #RUBY_ATOMIC_CAS, except it expects its arguments are (possibly + * `_Atomic` qualified) unsigned integers of the same width of `void*`. There + * are cases where ::rb_atomic_t is 32bit while `void*` is 64bit. This should + * be used for size related operations to support such platforms. + * + * @param var A variable of (possibly _Atomic qualified) `void*`. + * @param oldval Expected value of `var` before the assignment. + * @param val What you want to store at `var`. + * @retval 1 Successful assignment. + * @retval 0 Something different from `oldval` resides at `var`. + */ # ifndef RUBY_ATOMIC_VALUE_CAS # define RUBY_ATOMIC_VALUE_CAS(var, oldval, val) RUBY_ATOMIC_CAS(var, oldval, val) # endif