From 95a10bb008f74f45b3346727a71b8f96c3284315 Mon Sep 17 00:00:00 2001 From: doodspav Date: Wed, 8 May 2024 19:56:11 +0300 Subject: [PATCH] GHI #32 Add basic opsigs for ops/transaction.h --- CMakeLists.txt | 3 +- include/patomic/types/ops.h | 3 +- include/patomic/types/ops/explicit.h | 2 +- include/patomic/types/ops/implicit.h | 2 +- include/patomic/types/ops/transaction.h | 481 ++++++++++++++++++++++++ 5 files changed, 487 insertions(+), 4 deletions(-) create mode 100644 include/patomic/types/ops/transaction.h diff --git a/CMakeLists.txt b/CMakeLists.txt index 7117ae70d..7f86217ee 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -46,8 +46,9 @@ target_sources( include/patomic/types/options.h include/patomic/types/transaction.h # include/types/ops - include/patomic/types/ops/implicit.h include/patomic/types/ops/explicit.h + include/patomic/types/ops/implicit.h + include/patomic/types/ops/transaction.h ) # add /src files to target diff --git a/include/patomic/types/ops.h b/include/patomic/types/ops.h index 148401868..74fa049eb 100644 --- a/include/patomic/types/ops.h +++ b/include/patomic/types/ops.h @@ -1,7 +1,8 @@ #ifndef PATOMIC_OPS_H #define PATOMIC_OPS_H -#include "ops/implicit.h" #include "ops/explicit.h" +#include "ops/implicit.h" +#include "ops/transaction.h" #endif /* PATOMIC_OPS_H */ diff --git a/include/patomic/types/ops/explicit.h b/include/patomic/types/ops/explicit.h index d4fa6abdb..95d80c935 100644 --- a/include/patomic/types/ops/explicit.h +++ b/include/patomic/types/ops/explicit.h @@ -152,7 +152,7 @@ typedef int (* patomic_opsig_explicit_cmpxchg_t) ( * @addtogroup ops.explicit * * @brief - * Function signature for an atomic bit test operation wth explicit memory + * Function signature for an atomic bit test operation with explicit memory * order. * * @details diff --git a/include/patomic/types/ops/implicit.h b/include/patomic/types/ops/implicit.h index 6de0e9bab..a0971b827 100644 --- a/include/patomic/types/ops/implicit.h +++ b/include/patomic/types/ops/implicit.h @@ -131,7 +131,7 @@ typedef int (* patomic_opsig_cmpxchg_t) ( * @addtogroup ops.implicit * * @brief - * Function signature for an atomic bit test operation wth implicit memory + * Function signature for an atomic bit test operation with implicit memory * order. * * @details diff --git a/include/patomic/types/ops/transaction.h b/include/patomic/types/ops/transaction.h new file mode 100644 index 000000000..7bc2bb440 --- /dev/null +++ b/include/patomic/types/ops/transaction.h @@ -0,0 +1,481 @@ +#ifndef PATOMIC_OPS_TRANSACTION_H +#define PATOMIC_OPS_TRANSACTION_H + +#include "../transaction.h" + +// TODO: extern "C" + + +/** + * @addtogroup ops.transaction + * + * @brief + * Function signature for an atomic store operation implemented using a + * sequentially consistent transaction. + * + * @details + * Attempts to atomically store a desired value into an object, however the + * transaction may fail. + * + * @param obj + * Pointer to object into which to atomically store a value. + * + * @param desired + * Pointer to object holding value to be atomically stored. + * + * @param config + * Configuration for transaction. + * + * @param result + * Pointer to object holding result of transaction, including status code and + * attempts made. + * + * @note + * If config.width == 0, the transaction proceeds as normal with no + * short-circuiting. Parameters (except for "config" and "result") may be + * passed a default value of 0 or NULL. + * + * @note + * If config.attempts == 0, the transaction will not be attempted. The status + * will be set to TABORT_EXPLICIT with reason 0, and attempts_made to 0. + * Parameters (except for "config" and "result") may be passed a default value + * of 0 or NULL. + */ +typedef void (* patomic_opsig_transaction_store_t) ( + volatile void *obj, + const void *desired, + patomic_transaction_config_t config, + patomic_transaction_result_t *result +); + + +/** + * @addtogroup ops.transaction + * + * @brief + * Function signature for an atomic load operation implemented using a + * sequentially consistent transaction. + * + * @details + * Atomically loads a value from an object, however the transaction may fail. + * + * @param obj + * Pointer to object from which a value will be atomically loaded. + * + * @param ret + * Pointer to object into which to write the atomically loaded value. + * + * @param config + * Configuration for transaction. + * + * @param result + * Pointer to object holding result of transaction, including status code and + * attempts made. + * + * @note + * If config.width == 0, the transaction proceeds as normal with no + * short-circuiting. Parameters (except for "config" and "result") may be + * passed a default value of 0 or NULL. + * + * @note + * If config.attempts == 0, the transaction will not be attempted. The status + * will be set to TABORT_EXPLICIT with reason 0, and attempts_made to 0. + * Parameters (except for "config" and "result") may be passed a default value + * of 0 or NULL. + */ +typedef void (* patomic_opsig_transaction_load_t) ( + const volatile void *obj, + void *ret, + patomic_transaction_config_t config, + patomic_transaction_result_t *result +); + + +/** + * @addtogroup ops.transaction + * + * @brief + * Function signature for an atomic exchange operation implemented using a + * sequentially consistent transaction. + * + * @details + * Atomically replaces the value of an object with a desired value and returns + * the value the object held previously, in a single read-modify-write atomic + * operation, however the transaction may fail. + * + * @param obj + * Pointer to object whose value to atomically exchange with desired value. + * + * @param desired + * Pointer to object whose value will replace the existing value of "obj". + * + * @param ret + * Pointer to object into which to write the existing value held by "obj". + * + * @param config + * Configuration for transaction. + * + * @param result + * Pointer to object holding result of transaction, including status code and + * attempts made. + * + * @note + * If config.width == 0, the transaction proceeds as normal with no + * short-circuiting. Parameters (except for "config" and "result") may be + * passed a default value of 0 or NULL. + * + * @note + * If config.attempts == 0, the transaction will not be attempted. The status + * will be set to TABORT_EXPLICIT with reason 0, and attempts_made to 0. + * Parameters (except for "config" and "result") may be passed a default value + * of 0 or NULL. + */ +typedef void (* patomic_opsig_transaction_exchange_t) ( + volatile void *obj, + const void *desired, + void *ret, + patomic_transaction_config_t config, + patomic_transaction_result_t *result +); + + +/** + * @addtogroup ops.transaction + * + * @brief + * Function signature for an atomic compare-exchange (cmpxchg) operation + * implemented using a sequentially consistent transaction. + * + * @details + * Atomically compares the value of the object with with the value of an + * expected object; if these compare equal, replaces the value of the object + * with a desired value and returns 1, otherwise stores the value of the + * object into the expected object, and returns 0. This is done in a single + * read-modify-write atomic operation if 1 is returned, otherwise this is a + * single atomic read (load) operation. The transaction may fail, in which + * case 0 is returned. + * + * @param obj + * Pointer to object whose value to atomically cmpxchg with expected object + * and desired value. + * + * @param expected + * Pointer to object whose value is compared against the existing value of + * "obj", and into which "obj"'s existing value will be stored if the + * comparison fails. + * + * @param desired + * Pointer to object whose value will replace the existing value of "obj". + * + * @param config + * Configuration for transaction. + * + * @param result + * Pointer to object holding result of transaction, including status code and + * attempts made. + * + * @returns + * The value 1 if the existing value of "obj" compares equal to the value of + * "expected", otherwise the value 0. If the transaction fails, 0 is returned. + * + * @note + * If config.width == 0, the transaction proceeds as normal with no + * short-circuiting. Parameters (except for "config" and "result") may be + * passed a default value of 0 or NULL. + * + * @note + * If config.attempts == 0, the transaction will not be attempted. The status + * will be set to TABORT_EXPLICIT with reason 0, and attempts_made to 0. + * Parameters (except for "config" and "result") may be passed a default value + * of 0 or NULL. + */ +typedef int (* patomic_opsig_transaction_cmpxchg_t) ( + volatile void *obj, + void *expected, + const void *desired, + patomic_transaction_config_t config, + patomic_transaction_result_t *result +); + + +/** + * @addtogroup ops.transaction + * + * @brief + * Function signature for an atomic bit test operation implemented using a + * sequentially consistent transaction. + * + * @details + * Atomically tests a single bit from an object, returning 1 if it is set and + * 0 if it is not set. The whole object is atomically loaded in order to test + * the bit. The transaction may fail, in which case 0 is returned. + * + * @param obj + * Pointer to object from which bit will be atomically loaded. + * + * @param offset + * Zero-based bit index. + * + * @param config + * Configuration for transaction. + * + * @param result + * Pointer to object holding result of transaction, including status code and + * attempts made. + * + * @returns + * The value of the tested bit, or 0 if the transaction failed. + * + * @note + * If config.width == 0, the transaction proceeds as normal with no + * short-circuiting. Parameters (except for "config" and "result") may be + * passed a default value of 0 or NULL. + * + * @note + * If config.attempts == 0, the transaction will not be attempted. The status + * will be set to TABORT_EXPLICIT with reason 0, and attempts_made to 0. + * Parameters (except for "config" and "result") may be passed a default value + * of 0 or NULL. + */ +typedef int (* patomic_opsig_transaction_test_t) ( + const volatile void *obj, + int offset, + patomic_transaction_config_t config, + patomic_transaction_result_t *result +); + + +/** + * @addtogroup ops.transaction + * + * @brief + * Function signature for an atomic bit test-and-set operation implemented + * using a sequentially consistent transaction. + * + * @details + * Atomically modifies a single bit from an object with an implicitly known + * unary bitwise operation, returning the original value of the bit (0 or 1). + * The whole object is loaded and stored in a single atomic read-modify-write + * operation. The transaction may fail, in which case 0 is returned. + * + * @param obj + * Pointer to object from which bit will be atomically modified. + * + * @param offset + * Zero-based bit index. + * + * @param config + * Configuration for transaction. + * + * @param result + * Pointer to object holding result of transaction, including status code and + * attempts made. + * + * @returns + * The original value of the tested bit before modification, or 0 if the + * transaction failed. + * + * @note + * If config.width == 0, the transaction proceeds as normal with no + * short-circuiting. Parameters (except for "config" and "result") may be + * passed a default value of 0 or NULL. + * + * @note + * If config.attempts == 0, the transaction will not be attempted. The status + * will be set to TABORT_EXPLICIT with reason 0, and attempts_made to 0. + * Parameters (except for "config" and "result") may be passed a default value + * of 0 or NULL. + */ +typedef int (* patomic_opsig_transaction_test_modify_t) ( + volatile void *obj, + int offset, + patomic_transaction_config_t config, + patomic_transaction_result_t *result +); + + +/** + * @addtogroup ops.transaction + * + * @brief + * Function signature for an atomic fetch binary operation implemented using + * a sequentially consistent transaction. + * + * @details + * Atomically loads an object, performs an implicitly known binary operation + * on the value, and stores the result in a single atomic read-modify-write + * operation, however the transaction may fail. + * + * @param obj + * Pointer to object whose value will be atomically modified, and passed as + * first parameter in the binary operation. + * + * @param arg + * Pointer to object whose value is passed as the second parameter in the + * binary operation. + * + * @param ret + * Pointer to object into which to write the original value of "obj" before + * modification. + * + * @param config + * Configuration for transaction. + * + * @param result + * Pointer to object holding result of transaction, including status code and + * attempts made. + * + * @note + * If config.width == 0, the transaction proceeds as normal with no + * short-circuiting. Parameters (except for "config" and "result") may be + * passed a default value of 0 or NULL. + * + * @note + * If config.attempts == 0, the transaction will not be attempted. The status + * will be set to TABORT_EXPLICIT with reason 0, and attempts_made to 0. + * Parameters (except for "config" and "result") may be passed a default value + * of 0 or NULL. + */ +typedef void (* patomic_opsig_transaction_fetch_t) ( + volatile void *obj, + const void *arg, + void *ret, + patomic_transaction_config_t config, + patomic_transaction_result_t *result +); + + +/** + * @addtogroup ops.transaction + * + * @brief + * Function signature for an atomic fetch unary operation implemented using a + * sequentially consistent transaction. + * + * @details + * Atomically loads an object, performs an implicitly known unary operation on + * the value, and stores the result in a single atomic read-modify-write + * operation, however the transaction may fail. + * + * @param obj + * Pointer to object whose value will be atomically modified, and passed as + * first parameter in the unary operation. + * + * @param ret + * Pointer to object into which to write the original value of "obj" before + * modification. + * + * @param config + * Configuration for transaction. + * + * @param result + * Pointer to object holding result of transaction, including status code and + * attempts made. + * + * @note + * If config.width == 0, the transaction proceeds as normal with no + * short-circuiting. Parameters (except for "config" and "result") may be + * passed a default value of 0 or NULL. + * + * @note + * If config.attempts == 0, the transaction will not be attempted. The status + * will be set to TABORT_EXPLICIT with reason 0, and attempts_made to 0. + * Parameters (except for "config" and "result") may be passed a default value + * of 0 or NULL. + */ +typedef void (* patomic_opsig_transaction_fetch_noarg_t) ( + volatile void *obj, + void *ret, + patomic_transaction_config_t config, + patomic_transaction_result_t *result +); + + +/** + * @addtogroup ops.transaction + * + * @brief + * Function signature for an atomic binary operation implemented using a + * sequentially consistent transaction. + * + * @details + * Atomically loads an object, performs an implicitly known binary operation + * on the value, and stores the result in a single atomic read-modify-write + * operation, however the transaction may fail. + * + * @param obj + * Pointer to object whose value will be atomically modified, and passed as + * first parameter in the binary operation. + * + * @param arg + * Pointer to object whose value is passed as the second parameter in the + * binary operation. + * + * @param config + * Configuration for transaction. + * + * @param result + * Pointer to object holding result of transaction, including status code and + * attempts made. + * + * @note + * If config.width == 0, the transaction proceeds as normal with no + * short-circuiting. Parameters (except for "config" and "result") may be + * passed a default value of 0 or NULL. + * + * @note + * If config.attempts == 0, the transaction will not be attempted. The status + * will be set to TABORT_EXPLICIT with reason 0, and attempts_made to 0. + * Parameters (except for "config" and "result") may be passed a default value + * of 0 or NULL. + */ +typedef void (* patomic_opsig_transaction_void_t) ( + volatile void *obj, + const void *arg, + patomic_transaction_config_t config, + patomic_transaction_result_t *result +); + + +/** + * @addtogroup ops.transaction + * + * @brief + * Function signature for an atomic unary operation implemented using a + * sequentially consistent transaction. + * + * @details + * Atomically loads an object, performs an implicitly known unary operation on + * the value, and stores the result in a single atomic read-modify-write + * operation, however the transaction may fail. + * + * @param obj + * Pointer to object whose value will be atomically modified, and passed as + * first parameter in the unary operation. + * + * @param config + * Configuration for transaction. + * + * @param result + * Pointer to object holding result of transaction, including status code and + * attempts made. + * + * @note + * If config.width == 0, the transaction proceeds as normal with no + * short-circuiting. Parameters (except for "config" and "result") may be + * passed a default value of 0 or NULL. + * + * @note + * If config.attempts == 0, the transaction will not be attempted. The status + * will be set to TABORT_EXPLICIT with reason 0, and attempts_made to 0. + * Parameters (except for "config" and "result") may be passed a default value + * of 0 or NULL. + */ +typedef void (* patomic_opsig_transaction_void_noarg_t) ( + volatile void *obj, + patomic_transaction_config_t config, + patomic_transaction_result_t *result +); + + +#endif /* PATOMIC_OPS_TRANSACTION_H */