/* Copyright (c) 2020, 2024, Oracle and/or its affiliates. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License, version 2.0, as published by the Free Software Foundation. This program is designed to work with certain software (including but not limited to OpenSSL) that is licensed under separate terms, as designated in a particular file or component or in included license documentation. The authors of MySQL hereby grant you an additional permission to link the program and your derivative works with the separately licensed software that they have either included with the program or referenced in the documentation. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License, version 2.0, for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ #ifndef LOCK_SHARED_SPIN_LOCK_INCLUDED #define LOCK_SHARED_SPIN_LOCK_INCLUDED #include #include #include #include #include "sql/memory/aligned_atomic.h" /** Provides atomic access in shared-exclusive modes. Shared mode allows for several threads to share lock acquisition. Exclusive mode will allow for a single thread to acquire the lock. The implementation also provides re-entrance, meaning that a thread is allowed to acquire the lock in the same mode several times without blocking. Re-entrance is symmetric, meaning, in the case the lock is acquired several times by the same thread, it should be released the same amount of times. Acquisition request priority management is implemented to avoid starvation, meaning: 1) When no thread is holding the lock, acquisition is granted to the first thread to request it. 2) If the lock is being held in shared mode and an exclusive acquisition request is made, no more shared or exclusive acquisition requests are granted until the exclusivity request is granted and released. The acquisition relation given to concurrent requests is as follows: ------------------------------------------------------------- | S2 | E2 | +-----------------------------+-----------------------------+ | REQUEST | ACQUIRED | REQUEST | ACQUIRED | -----------------+--------------+--------------------------------------------+ | | REQUEST | S1 & S2 | S1 & S2 | S1 | E2 | E2 | | S1 |---------+--------------+--------------+--------------+--------------+ | | ACQUIRED| S1 & S2 | S1 & S2 | S1 | - | -------+---------+--------------+--------------+--------------+--------------+ | | REQUEST | E1 | S2 | E1 | E2 | E2 | | E1 |---------+--------------+--------------+--------------+--------------+ | | ACQUIRED| E1 | - | E1 | - | ------------------------------------------------------------------------------ Legend: - S1: Thread that is requesting or has acquired in shared mode - S2: Thread that is requesting or has acquired in shared mode - E1: Thread that is requesting or has acquired in exclusive mode - E2: Thread that is requesting or has acquired in exclusive mode */ namespace lock { class Shared_spin_lock { public: enum class enum_lock_acquisition { SL_EXCLUSIVE = 0, SL_SHARED = 1, SL_NO_ACQUISITION = 2 }; /** Sentry class for `Shared_spin_lock` to deliver RAII pattern usability. */ class Guard { public: friend class Shared_spin_lock; /** Class constructor that receives the target spin-lock, whether or not it can be a shared acquisition and whether or not it should be a try-and-fail lock attempt, instead of a blocking attempt. @param target The target spin-lock. @param acquisition the acquisition type, SHARED, EXCLUSIVE or NO_ACQUISITION @param try_and_fail whether or not the lock attempt should be blocking (only used if acquisition type is SHARED or EXCLUSIVE). */ Guard(Shared_spin_lock &target, enum_lock_acquisition acquisition = enum_lock_acquisition::SL_SHARED, bool try_and_fail = false); // Delete copy and move constructors Guard(Shared_spin_lock::Guard const &) = delete; Guard(Shared_spin_lock::Guard &&) = delete; // /** Destructor for the sentry. It will release any acquisition, shared or exclusive. */ virtual ~Guard(); // Delete copy and move operators Shared_spin_lock::Guard &operator=(Shared_spin_lock::Guard const &) = delete; Shared_spin_lock::Guard &operator=(Shared_spin_lock::Guard &&) = delete; // /** Arrow operator to access the underlying lock. @return A pointer to the underlying lock. */ Shared_spin_lock *operator->(); /** Star operator to access the underlying lock. @return A reference to the underlying lock. */ Shared_spin_lock &operator*(); /** If this instance was initialized without acquiring the lock (`NO_ACQUISITION ` passed to constructor) or the acquisition request wasn't granted (passing `try_and_fail = true` to the constructor), invoking this method will try to acquire the lock in the provided mode. @param acquisition the acquisition type, SHARED or EXCLUSIVE @param try_and_fail whether or not the lock attempt should be blocking @return A reference to `this` object, for chaining purposes. */ Shared_spin_lock::Guard &acquire(enum_lock_acquisition acquisition, bool try_and_fail = false); /** Releases the underlying lock acquisition, if any. @return A reference to `this` object, for chaining purposes. */ Shared_spin_lock::Guard &release(); private: /** The underlying lock */ Shared_spin_lock &m_target; /** The type of lock acquisition to be requested */ enum_lock_acquisition m_acquisition{enum_lock_acquisition::SL_SHARED}; }; friend class Shared_spin_lock::Guard; /** Default class constructor. */ Shared_spin_lock() = default; /** Default class destructor. */ virtual ~Shared_spin_lock() = default; /** Blocks until the lock is acquired in shared mode. @return A reference to `this` object, for chaining purposes. */ Shared_spin_lock &acquire_shared(); /** Blocks until the lock is acquired in exclusive mode. @return A reference to `this` object, for chaining purposes. */ Shared_spin_lock &acquire_exclusive(); /** Tries to acquire the lock in shared mode. @return A reference to `this` object, for chaining purposes. */ Shared_spin_lock &try_shared(); /** Tries to acquire the lock in exclusive mode. @return A reference to `this` object, for chaining purposes. */ Shared_spin_lock &try_exclusive(); /** Releases the previously granted shared acquisition request. @return A reference to `this` object, for chaining purposes. */ Shared_spin_lock &release_shared(); /** Releases the previously granted exclusive acquisition request. @return A reference to `this` object, for chaining purposes. */ Shared_spin_lock &release_exclusive(); /** Returns whether the lock is acquired for shared access by the invoking thread. @return true if the lock was acquired in shared mode by the invoking thread */ bool is_shared_acquisition(); /** Returns whether the lock is acquired for exclusive access by the invoking thread. @return true if the lock was acquired in exclusive mode by the invoking thread */ bool is_exclusive_acquisition(); private: /** The total amount of threads accessing in shared mode */ memory::Aligned_atomic m_shared_access{0}; /** Whether or not any thread is accessing in or waiting for exclusive mode */ memory::Aligned_atomic m_exclusive_access{false}; /** Tries to lock or waits for locking in shared mode and increases the thread-local lock acquisition shared counter. @param try_and_fail Whether or not to try to lock of wait for acquiring. @return A reference to `this` object, for chaining purposes. */ Shared_spin_lock &try_or_spin_shared_lock(bool try_and_fail); /** Tries to lock or waits for locking in shared mode and increases the thread-local lock acquisition shared counter. @param try_and_fail Whether or not to try to lock of wait for acquiring. @return A reference to `this` object, for chaining purposes. */ Shared_spin_lock &try_or_spin_exclusive_lock(bool try_and_fail); /** Tries to acquire in shared mode. @return `true` if the attempt to acquire the lock in shared mode was successful. */ bool try_shared_lock(); /** Tries to acquire in exclusive mode. @return `true` if the attempt to acquire the lock in exclusive mode was successful. */ bool try_exclusive_lock(); /** Blocks until the lock is acquired in shared mode. */ void spin_shared_lock(); /** Blocks until the lock is acquired in exclusive mode. */ void spin_exclusive_lock(); /** Returns the thread-local lock counter map. */ static std::map &acquired_spins(); }; } // namespace lock #endif // LOCK_SHARED_SPIN_LOCK_INCLUDED