iox-eclipse-iceoryx#2301 Add SpinLock

doc/website/release-notes/iceoryx-unreleased.md

@@ -726,7 +726,7 @@
  // after
  iox::optional<iox::mutex> myMutex;
  iox::MutexBuilder()
-  .mutexType(iox::MutexType::RECURSIVE)
+  .lock_behavior(iox::LockBehavior::RECURSIVE)
   .create(myMutex);
  myMutex->lock();
  ```

iceoryx_hoofs/BUILD.bazel

@@ -34,6 +34,7 @@ cc_library(
  srcs = glob([
  "cli/source/*.cpp",
  "concurrent/buffer/source/*.cpp",
+ "concurrent/sync/source/*.cpp",
  "design/source/*.cpp",
  "filesystem/source/*.cpp",
  "memory/source/*.cpp",

iceoryx_hoofs/CMakeLists.txt

@@ -104,6 +104,7 @@ iox_add_library(
  cli/source/option_definition.cpp
  cli/source/option_manager.cpp
  concurrent/buffer/source/mpmc_loffli.cpp
+ concurrent/sync/source/spin_lock.cpp
  filesystem/source/file_reader.cpp
  filesystem/source/filesystem.cpp
  memory/source/bump_allocator.cpp

iceoryx_hoofs/concurrent/sync/include/iox/spin_lock.hpp

@@ -0,0 +1,96 @@
+// Copyright (c) 2024 by ekxide IO GmbH. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+#ifndef IOX_HOOFS_CONCURRENT_SYNC_SPIN_LOCK_HPP
+#define IOX_HOOFS_CONCURRENT_SYNC_SPIN_LOCK_HPP
+
+#include "iox/atomic.hpp"
+#include "iox/lock_interface.hpp"
+
+#include <thread>
+
+namespace iox
+{
+namespace concurrent
+{
+class SpinLockBuilder;
+
+/// @brief A spin lock implementation as drop-in replacement for a mutex
+class SpinLock : public LockInterface<SpinLock>
+{
+ public:
+ using Builder = SpinLockBuilder;
+
+ SpinLock(const SpinLock&) = delete;
+ SpinLock(SpinLock&&) = delete;
+ SpinLock& operator=(const SpinLock&) = delete;
+ SpinLock& operator=(SpinLock&&) = delete;
+
+ ~SpinLock() noexcept = default;
+
+ private:
+ friend class optional<SpinLock>;
+ friend class LockInterface<SpinLock>;
+
+ explicit SpinLock(const LockBehavior lock_behavior) noexcept;
+
+ expected<void, LockError> lock_impl() noexcept;
+
+ expected<void, UnlockError> unlock_impl() noexcept;
+
+ expected<TryLock, TryLockError> try_lock_impl() noexcept;
+
+ struct LockInfo
+ {
+ pid_t tid;
+ uint32_t recursive_count;
+ };
+
+ private:
+ concurrent::AtomicFlag m_lock_flag =
+ ATOMIC_FLAG_INIT; // NOTE: only initialization via assignment is guaranteed to work
+ const concurrent::Atomic<bool> m_recursive{false};
+ concurrent::Atomic<uint64_t> m_recursive_count{0};
+ concurrent::Atomic<std::thread::id> m_tid{};
+};
+
+class SpinLockBuilder
+{
+ public:
+ enum class Error : uint8_t
+ {
+ LOCK_ALREADY_INITIALIZED,
+ INTER_PROCESS_LOCK_UNSUPPORTED_BY_PLATFORM,
+ UNKNOWN_ERROR
+ };
+
+ /// @brief Defines if the SpinLock should be usable in an inter process context. Default: true
+ IOX_BUILDER_PARAMETER(bool, is_inter_process_capable, true)
+
+ /// @brief Sets the LockBehavior, default: LockBehavior::RECURSIVE
+ IOX_BUILDER_PARAMETER(LockBehavior, lock_behavior, LockBehavior::RECURSIVE)
+
+ public:
+ /// @brief Initializes a provided uninitialized SpinLock
+ /// @param[in] uninitializedLock the uninitialized SpinLock which should be initialized
+ /// @return On failure LockCreationError which explains the error
+ expected<void, Error> create(optional<SpinLock>& uninitializedLock) noexcept;
+};
+
+} // namespace concurrent
+} // namespace iox
+
+#endif // IOX_HOOFS_CONCURRENT_SYNC_SPIN_LOCK_HPP

iceoryx_hoofs/concurrent/sync/source/spin_lock.cpp

@@ -0,0 +1,117 @@
+// Copyright (c) 2024 by ekxide IO GmbH. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+#include "iox/spin_lock.hpp"
+#include "iox/detail/adaptive_wait.hpp"
+
+namespace iox
+{
+namespace concurrent
+{
+expected<void, SpinLockBuilder::Error>
+SpinLockBuilder::create(optional<concurrent::SpinLock>& uninitializedLock) noexcept
+{
+ if (uninitializedLock.has_value())
+ {
+ IOX_LOG(ERROR, "Unable to override an already initialized SpinLock with a new SpinLock");
+ return err(Error::LOCK_ALREADY_INITIALIZED);
+ }
+
+ uninitializedLock.emplace(m_lock_behavior);
+ return ok();
+}
+
+SpinLock::SpinLock(const LockBehavior lock_behavior) noexcept
+ : m_recursive(lock_behavior == LockBehavior::RECURSIVE)
+{
+}
+
+expected<void, LockError> SpinLock::lock_impl() noexcept
+{
+ auto tid = std::this_thread::get_id();
+
+ if (m_tid.load() == tid)
+ {
+ if (m_recursive.load(std::memory_order_relaxed))
+ {
+ m_recursive_count.fetch_add(1);
+
+ return ok();
+ }
+
+ return err(LockError::DEADLOCK_CONDITION);
+ }
+
+ detail::adaptive_wait spinner;
+ spinner.wait_loop([this] { return this->m_lock_flag.test_and_set(std::memory_order_acquire); });
+
+ m_tid.store(tid);
+ m_recursive_count.store(1);
+
+ return ok();
+}
+
+expected<void, UnlockError> SpinLock::unlock_impl() noexcept
+{
+ auto tid = std::this_thread::get_id();
+
+ if (m_tid.load() != tid)
+ {
+ return err(UnlockError::NOT_OWNED_BY_THREAD);
+ }
+
+ if (m_recursive_count.load() == 0)
+ {
+ return err(UnlockError::NOT_LOCKED);
+ }
+
+ auto old_recursive_count = m_recursive_count.fetch_sub(1);
+ if (old_recursive_count == 1)
+ {
+ m_tid.store(std::thread::id());
+ m_lock_flag.clear(std::memory_order_release);
+ }
+
+ return ok();
+}
+
+expected<TryLock, TryLockError> SpinLock::try_lock_impl() noexcept
+{
+ auto tid = std::this_thread::get_id();
+
+ if (m_tid.load() == tid)
+ {
+ if (m_recursive.load(std::memory_order_relaxed))
+ {
+ m_recursive_count.fetch_add(1);
+ return ok(TryLock::LOCK_SUCCEEDED);
+ }
+
+ return ok(TryLock::FAILED_TO_ACQUIRE_LOCK);
+ }
+
+ if (!m_lock_flag.test_and_set(std::memory_order_acquire))
+ {
+ m_tid.store(tid);
+ m_recursive_count.store(1);
+
+ return ok(TryLock::LOCK_SUCCEEDED);
+ }
+ return ok(TryLock::FAILED_TO_ACQUIRE_LOCK);
+}
+
+} // namespace concurrent
+} // namespace iox

iceoryx_hoofs/design/include/iox/lock_interface.hpp

@@ -0,0 +1,112 @@
+// Copyright (c) 2024 by ekxide IO GmbH. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+#ifndef IOX_HOOFS_DESIGN_LOCK_INTERFACE_HPP
+#define IOX_HOOFS_DESIGN_LOCK_INTERFACE_HPP
+
+#include "iceoryx_platform/pthread.hpp"
+#include "iox/builder.hpp"
+#include "iox/expected.hpp"
+#include "iox/optional.hpp"
+
+#include <cstdint>
+
+namespace iox
+{
+enum class LockError : uint8_t
+{
+ PRIORITY_MISMATCH,
+ MAXIMUM_NUMBER_OF_RECURSIVE_LOCKS_EXCEEDED,
+ DEADLOCK_CONDITION,
+ LOCK_ACQUIRED_BUT_HAS_INCONSISTENT_STATE_SINCE_OWNER_DIED,
+ UNKNOWN_ERROR
+};
+
+enum class UnlockError : uint8_t
+{
+ NOT_OWNED_BY_THREAD,
+ NOT_LOCKED,
+ UNKNOWN_ERROR
+};
+
+enum class TryLockError : uint8_t
+{
+ PRIORITY_MISMATCH,
+ MAXIMUM_NUMBER_OF_RECURSIVE_LOCKS_EXCEEDED,
+ LOCK_ACQUIRED_BUT_HAS_INCONSISTENT_STATE_SINCE_OWNER_DIED,
+ UNKNOWN_ERROR
+};
+
+enum class TryLock : uint8_t
+{
+ LOCK_SUCCEEDED,
+ FAILED_TO_ACQUIRE_LOCK
+};
+
+template <typename Lock>
+class LockInterface
+{
+ public:
+ /// @brief Engages the lock.
+ /// @return When it fails it returns an enum describing the error.
+ expected<void, LockError> lock() noexcept
+ {
+ return static_cast<Lock*>(this)->lock_impl();
+ }
+
+ /// @brief Releases the lock.
+ /// @return When it fails it returns an enum describing the error.
+ expected<void, UnlockError> unlock() noexcept
+ {
+ return static_cast<Lock*>(this)->unlock_impl();
+ }
+
+ /// @brief Tries to engage the lock.
+ /// @return If the lock was acquired LockInterfaceTryLock::LOCK_SUCCEEDED will be returned otherwise
+ /// LockInterfaceTryLock::FAILED_TO_ACQUIRE_LOCK.
+ /// If the lock is a recursive lock, this call will also succeed.
+ /// On failure it returns an enum describing the failure.
+ expected<TryLock, TryLockError> try_lock() noexcept
+ {
+ return static_cast<Lock*>(this)->try_lock_impl();
+ }
+
+ protected:
+ LockInterface() noexcept = default;
+};
+
+/// @brief Describes the behavior of the lock.
+// NOLINTNEXTLINE(performance-enum-size) int32_t required for POSIX API
+enum class LockBehavior : int32_t
+{
+ /// @brief Behavior without error detection and multiple locks from within
+ /// the same thread lead to deadlock
+ NORMAL = IOX_PTHREAD_MUTEX_NORMAL,
+
+ /// @brief Multiple locks from within the same thread do not lead to deadlock
+ /// but one requires the same amount of unlocks to make the thread lockable
+ /// from other threads
+ RECURSIVE = IOX_PTHREAD_MUTEX_RECURSIVE,
+
+ /// @brief Multiple locks from within the same thread will be detected and
+ /// reported. It detects also when unlock is called from a different
+ /// thread.
+ WITH_DEADLOCK_DETECTION = IOX_PTHREAD_MUTEX_ERRORCHECK,
+};
+
+} // namespace iox
+
+#endif // IOX_HOOFS_DESIGN_LOCK_INTERFACE_HPP