From 983feb436130c06d4bbab4b32c956602b72d25bf Mon Sep 17 00:00:00 2001 From: bernhard-gatzhammer Date: Wed, 21 Oct 2015 11:11:47 +0200 Subject: [PATCH] Design for atomic variable initialization. EMBB-517 --- base_c/include/embb/base/c/atomic.h | 56 +++++++++++++++++++++++++++++++++++++++++++------------- base_c/include/embb/base/c/internal/atomic/init.h | 32 ++++++++++++++++++++++++++++++++ 2 files changed, 75 insertions(+), 13 deletions(-) create mode 100755 base_c/include/embb/base/c/internal/atomic/init.h diff --git a/base_c/include/embb/base/c/atomic.h b/base_c/include/embb/base/c/atomic.h index 8875432..c0eff42 100644 --- a/base_c/include/embb/base/c/atomic.h +++ b/base_c/include/embb/base/c/atomic.h @@ -85,9 +85,27 @@ #ifdef DOXYGEN /** + * Initializes an atomic variable. + * + * \pre The atomic variable has not been initialized. + * \post The atomic variable has the value \c initial_value and can be used in + * atomic operations. + * + * \ingroup C_BASE_ATOMIC + * \notthreadsafe + */ +void embb_atomic_init( + emb_atomic_TYPE* variable, + /**< [IN,OUT] Pointer to atomic variable to be initialized. */ + TYPE initial_value + /**< [IN] Initial value to be assigned to atomic variable. */ + ); + +/** * Computes the logical "and" of the value stored in \p variable and \c value. * - * The result is stored in \p variable. + * \pre The atomic variable has been initialized with \c embb_atomic_init + * \post The result is stored in \p variable. * * \see \ref general_desc_atomic_base "Detailed description" for general * information and the meaning of \b TYPE. @@ -95,12 +113,12 @@ * \ingroup C_BASE_ATOMIC * \waitfree */ -EMBB_PLATFORM_INLINE void embb_atomic_and_assign_TYPE( +void embb_atomic_and_assign_TYPE( embb_atomic_TYPE* variable, /**< [IN,OUT] Pointer to atomic variable which serves as left-hand side for the "and" operation and is used to store the result. */ TYPE value - /** [IN] Right-hand side of "and" operation, passed by value */ + /**< [IN] Right-hand side of "and" operation, passed by value */ ); /** @@ -111,6 +129,8 @@ EMBB_PLATFORM_INLINE void embb_atomic_and_assign_TYPE( * to the value of \p expected. Otherwise, stores the value of \p variable in * \p expected. * + * \pre The atomic variable has been initialized with \c embb_atomic_init + * * \return != 0 if the values of \p variable and \p expected were equivalent \n * 0 otherwise * @@ -120,7 +140,7 @@ EMBB_PLATFORM_INLINE void embb_atomic_and_assign_TYPE( * \ingroup C_BASE_ATOMIC * \waitfree */ -EMBB_PLATFORM_INLINE int embb_atomic_compare_and_swap_TYPE( +int embb_atomic_compare_and_swap_TYPE( embb_atomic_TYPE* variable, /**< [IN,OUT] Pointer to atomic variable */ TYPE* expected, @@ -132,6 +152,8 @@ EMBB_PLATFORM_INLINE int embb_atomic_compare_and_swap_TYPE( /** * Adds \p value to \p variable and returns its old value. * + * \pre The atomic variable has been initialized with \c embb_atomic_init + * * \return The value before the operation * * \see \ref general_desc_atomic_base "Detailed description" for general @@ -140,7 +162,7 @@ EMBB_PLATFORM_INLINE int embb_atomic_compare_and_swap_TYPE( * \ingroup C_BASE_ATOMIC * \waitfree */ -EMBB_PLATFORM_INLINE TYPE embb_atomic_fetch_and_add_TYPE( +TYPE embb_atomic_fetch_and_add_TYPE( embb_atomic_TYPE* variable, /**< [IN,OUT] Pointer to atomic variable*/ TYPE value @@ -150,6 +172,8 @@ EMBB_PLATFORM_INLINE TYPE embb_atomic_fetch_and_add_TYPE( /** * Loads the value of \p variable and returns it. * + * \pre The atomic variable has been initialized with \c embb_atomic_init + * * \return The value of the atomic variable. * * \see \ref general_desc_atomic_base "Detailed description" for general @@ -158,7 +182,7 @@ EMBB_PLATFORM_INLINE TYPE embb_atomic_fetch_and_add_TYPE( * \ingroup C_BASE_ATOMIC * \waitfree */ -EMBB_PLATFORM_INLINE TYPE embb_atomic_load_TYPE( +TYPE embb_atomic_load_TYPE( const embb_atomic_TYPE* variable /**< [IN] Pointer to atomic variable */ ); @@ -169,12 +193,13 @@ EMBB_PLATFORM_INLINE TYPE embb_atomic_load_TYPE( * \ingroup C_BASE_ATOMIC * \waitfree */ -EMBB_PLATFORM_INLINE void embb_atomic_memory_barrier(); +void embb_atomic_memory_barrier(); /** * Computes the logical "or" of the value stored in \p variable and \c value. * - * The result is stored in \p variable. + * \pre The atomic variable has been initialized with \c embb_atomic_init + * \post The result is stored in \p variable. * * \see \ref general_desc_atomic_base "Detailed description" for general * information and the meaning of \b TYPE. @@ -182,7 +207,7 @@ EMBB_PLATFORM_INLINE void embb_atomic_memory_barrier(); * \ingroup C_BASE_ATOMIC * \waitfree */ -EMBB_PLATFORM_INLINE void embb_atomic_or_assign_TYPE( +void embb_atomic_or_assign_TYPE( embb_atomic_TYPE* variable, /**< [IN,OUT] Pointer to atomic variable which serves as left-hand side for the "or" operation and is used to store the result. */ @@ -193,13 +218,15 @@ EMBB_PLATFORM_INLINE void embb_atomic_or_assign_TYPE( /** * Stores \p value in \p variable. * + * \pre The atomic variable has been initialized with \c embb_atomic_init + * * \see \ref general_desc_atomic_base "Detailed description" for general * information and the meaning of \b TYPE. * * \ingroup C_BASE_ATOMIC * \waitfree */ -EMBB_PLATFORM_INLINE void embb_atomic_store_TYPE( +void embb_atomic_store_TYPE( embb_atomic_TYPE* variable, /**< [IN,OUT] Pointer to atomic variable */ int value @@ -209,6 +236,8 @@ EMBB_PLATFORM_INLINE void embb_atomic_store_TYPE( /** * Swaps the current value of \p variable with \p value. * + * \pre The atomic variable has been initialized with \c embb_atomic_init + * * \return The old value of \p variable * * \see \ref general_desc_atomic_base "Detailed description" for general @@ -217,7 +246,7 @@ EMBB_PLATFORM_INLINE void embb_atomic_store_TYPE( * \ingroup C_BASE_ATOMIC * \waitfree */ -EMBB_PLATFORM_INLINE TYPE embb_atomic_swap_TYPE( +TYPE embb_atomic_swap_TYPE( embb_atomic_TYPE* variable, /**< [IN,OUT] Pointer to atomic variable whose value is swapped */ TYPE value @@ -227,7 +256,8 @@ EMBB_PLATFORM_INLINE TYPE embb_atomic_swap_TYPE( /** * Computes the logical "xor" of the value stored in \p variable and \c value. * -* The result is stored in \p variable. +* \pre The atomic variable has been initialized with \c embb_atomic_init +* \post The result is stored in \p variable. * * \see \ref general_desc_atomic_base "Detailed description" for general * information and the meaning of \b TYPE. @@ -235,7 +265,7 @@ EMBB_PLATFORM_INLINE TYPE embb_atomic_swap_TYPE( * \ingroup C_BASE_ATOMIC * \waitfree */ -EMBB_PLATFORM_INLINE void embb_atomic_xor_assign_TYPE( +void embb_atomic_xor_assign_TYPE( embb_atomic_TYPE* variable, /**< [IN,OUT] Pointer to atomic variable which serves as left-hand side for the "xor" operation and is used to store the result. */ diff --git a/base_c/include/embb/base/c/internal/atomic/init.h b/base_c/include/embb/base/c/internal/atomic/init.h new file mode 100755 index 0000000..e282f6c --- /dev/null +++ b/base_c/include/embb/base/c/internal/atomic/init.h @@ -0,0 +1,32 @@ +/* + * Copyright (c) 2014-2015, Siemens AG. All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + */ + +#ifndef EMBB_BASE_C_INTERNAL_ATOMIC_INIT_H_ +#define EMBB_BASE_C_INTERNAL_ATOMIC_INIT_H_ + +// TODO implementation of embb_atomic_init() + +#endif // EMBB_BASE_C_INTERNAL_ATOMIC_INIT_H_ -- libgit2 0.26.0