From 9e074c081ff30a41105c2405998ae50db70af185 Mon Sep 17 00:00:00 2001 From: bernhard-gatzhammer Date: Tue, 3 Nov 2015 11:11:12 +0100 Subject: [PATCH] First draft for spinlock (C and C++) designs. EMBB-509 --- base_c/include/embb/base/c/spinlock.h | 149 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ base_cpp/include/embb/base/spinlock.h | 101 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 250 insertions(+) create mode 100755 base_c/include/embb/base/c/spinlock.h create mode 100755 base_cpp/include/embb/base/spinlock.h diff --git a/base_c/include/embb/base/c/spinlock.h b/base_c/include/embb/base/c/spinlock.h new file mode 100755 index 0000000..8ead24b --- /dev/null +++ b/base_c/include/embb/base/c/spinlock.h @@ -0,0 +1,149 @@ +/* + * 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_SPINLOCK_H_ +#define EMBB_BASE_C_SPINLOCK_H_ + +/** + * \defgroup C_BASE_SPINLOCK Spinlock + * + * Spinlock for thread synchronization + * + * Provides an abstraction from platform-specific spinlock implementations. + * + * \ingroup C_BASE + * \{ + */ + +#ifdef __cplusplus +extern "C" { +#endif + +#include +#include + +#ifdef DOXYGEN +/** + * Opaque type representing a spinlock. + */ +typedef opaque_type embb_spinlock_t; + +#else + +/** + * Spinlock type, treat as opaque. + */ +struct embb_spinlock_t; +#endif /* DOXYGEN */ + + +/** + * Initializes a spinlock + * + * \post \c spinlock is initialized + * \return EMBB_SUCCESS if spinlock could be initialized \n + * EMBB_ERROR otherwise + * \memory (Potentially) allocates dynamic memory + * \notthreadsafe + * \see embb_spinlock_destroy() + */ +int embb_spin_init( + embb_spinlock_t* spinlock + /**< [OUT] Pointer to spinlock */ + ); + +/** + * Spins until the spinlock can be locked and locks it. + * + * \pre \c spinlock is initialized \n + * \post If successful, \c spinlock is locked. + * \return EMBB_SUCCESS if spinlock could be locked \n + * EMBB_ERROR otherwise + * \threadsafe + * \see embb_spinlock_try_lock(), embb_mutex_unlock() + */ +int embb_spin_lock( + embb_spinlock_t* spinlock + /**< [IN/OUT] Pointer to spinlock */ + ); + +/** + * Tries to lock the spinlock and returns if not successful. + * + * \pre \c spinlock is initialized + * \post If successful, \c spinlock is locked + * + * \return EMBB_SUCCESS if spinlock could be locked \n + * EMBB_BUSY if spinlock could not be locked \n + * EMBB_ERROR if an error occurred + * \threadsafe + * \see embb_spin_lock(), embb_spin_unlock() + */ +int embb_spin_try_lock( + embb_spinlock_t* spinlock, + /**< [IN/OUT] Pointer to spinlock */ + unsigned int number_spins + /**< [IN] Number of attempts the locking operation is repeated if + * unsuccessful */ + ); + +/** + * Unlocks a locked spinlock. + * + * \pre \c spinlock has been locked by the current thread. + * \post If successful, \c spinlock is unlocked. + * \return EMBB_SUCCESS if the operation was successful \n + * EMBB_ERROR otherwise + * \threadsafe + * \see embb_spin_lock(), embb_spin_try_lock() + */ +int embb_spin_unlock( + embb_spinlock_t* spinlock + /**< [IN/OUT] Pointer to spinlock */ + ); + +/** + * Destroys a spinlock and frees its resources. + * + * \pre \c spinlock has been initialized + * \post \c spinlock is uninitialized + * \notthreadsafe + * \see embb_spin_init() + */ +void embb_spin_destroy( + embb_spinlock_t* spinlock + /**< [IN/OUT] Pointer to spinlock */ + ); + +#ifdef __cplusplus +} /* Close extern "C" { */ +#endif + +/** + * \} + */ + +#endif /* EMBB_BASE_C_SPINLOCK_H_ */ diff --git a/base_cpp/include/embb/base/spinlock.h b/base_cpp/include/embb/base/spinlock.h new file mode 100755 index 0000000..c8a57ac --- /dev/null +++ b/base_cpp/include/embb/base/spinlock.h @@ -0,0 +1,101 @@ +/* + * 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_SPINLOCK_H_ +#define EMBB_BASE_SPINLOCK_H_ + +#include +#include + +namespace embb { +namespace base { + +/** + * \defgroup CPP_BASE_SPINLOCK Spinlock + * + * Spinlock for thread synchronization. + * + * \ingroup CPP_BASE + */ + +/** + * Spinlock + * + * \ingroup CPP_BASE_SPINLOCK + */ +class Spinlock { + public: + /** + * Creates a spinlock which is in unlocked state. + * + * \notthreadsafe + */ + Spinlock(); + + /** + * Waits until the spinlock can be locked and locks it. + * + * \pre The spinlock is not locked by the current thread. + * \post The spinlock is locked + * \threadsafe + * \see TryLock(), Unlock() + */ + void Lock(); + + /** + * Tries to lock the spinlock for \c number_spins times and returns. + * + * \pre The spinlock is not locked by the current thread. + * \post If successful, the spinlock is locked. + * \return \c true if the spinlock could be locked, otherwise \c false. + * \threadsafe + * \see Lock(), Unlock() + */ + bool TryLock(unsigned int number_spins = 0); + + /** + * Unlocks the spinlock. + * + * \pre The spinlock is locked by the current thread + * \post The spinlock is unlocked + * \threadsafe + * \see Lock(), TryLock() + */ + void Unlock(); + + private: + /** + * Disables copy construction and assignment. + */ + Spinlock(const Spinlock&); + Spinlock& operator=(const Spinlock&); + +}; + +} // namespace base +} // namespace embb + +#endif // EMBB_BASE_SPINLOCK_H_ -- libgit2 0.26.0