SFML/System/Lock.hpp

0001 ////////////////////////////////////////////////////////////
0002 //
0003 // SFML - Simple and Fast Multimedia Library
0004 // Copyright (C) 2007-2023 Laurent Gomila (laurent@sfml-dev.org)
0005 //
0006 // This software is provided 'as-is', without any express or implied warranty.
0007 // In no event will the authors be held liable for any damages arising from the use of this software.
0008 //
0009 // Permission is granted to anyone to use this software for any purpose,
0010 // including commercial applications, and to alter it and redistribute it freely,
0011 // subject to the following restrictions:
0012 //
0013 // 1. The origin of this software must not be misrepresented;
0014 //    you must not claim that you wrote the original software.
0015 //    If you use this software in a product, an acknowledgment
0016 //    in the product documentation would be appreciated but is not required.
0017 //
0018 // 2. Altered source versions must be plainly marked as such,
0019 //    and must not be misrepresented as being the original software.
0020 //
0021 // 3. This notice may not be removed or altered from any source distribution.
0022 //
0023 ////////////////////////////////////////////////////////////
0024
0025 #ifndef SFML_LOCK_HPP
0026 #define SFML_LOCK_HPP
0027
0028 ////////////////////////////////////////////////////////////
0029 // Headers
0030 ////////////////////////////////////////////////////////////
0031 #include <SFML/System/Export.hpp>
0032 #include <SFML/System/NonCopyable.hpp>
0033
0034
0035 namespace sf
0036 {
0037 class Mutex;
0038
0039 ////////////////////////////////////////////////////////////
0040 /// \brief Automatic wrapper for locking and unlocking mutexes
0041 ///
0042 ////////////////////////////////////////////////////////////
0043 class SFML_SYSTEM_API Lock : NonCopyable
0044 {
0045 public:
0046
0047     ////////////////////////////////////////////////////////////
0048     /// \brief Construct the lock with a target mutex
0049     ///
0050     /// The mutex passed to sf::Lock is automatically locked.
0051     ///
0052     /// \param mutex Mutex to lock
0053     ///
0054     ////////////////////////////////////////////////////////////
0055     explicit Lock(Mutex& mutex);
0056
0057     ////////////////////////////////////////////////////////////
0058     /// \brief Destructor
0059     ///
0060     /// The destructor of sf::Lock automatically unlocks its mutex.
0061     ///
0062     ////////////////////////////////////////////////////////////
0063     ~Lock();
0064
0065 private:
0066
0067     ////////////////////////////////////////////////////////////
0068     // Member data
0069     ////////////////////////////////////////////////////////////
0070     Mutex& m_mutex; //!< Mutex to lock / unlock
0071 };
0072
0073 } // namespace sf
0074
0075
0076 #endif // SFML_LOCK_HPP
0077
0078
0079 ////////////////////////////////////////////////////////////
0080 /// \class sf::Lock
0081 /// \ingroup system
0082 ///
0083 /// sf::Lock is a RAII wrapper for sf::Mutex. By unlocking
0084 /// it in its destructor, it ensures that the mutex will
0085 /// always be released when the current scope (most likely
0086 /// a function) ends.
0087 /// This is even more important when an exception or an early
0088 /// return statement can interrupt the execution flow of the
0089 /// function.
0090 ///
0091 /// For maximum robustness, sf::Lock should always be used
0092 /// to lock/unlock a mutex.
0093 ///
0094 /// Usage example:
0095 /// \code
0096 /// sf::Mutex mutex;
0097 ///
0098 /// void function()
0099 /// {
0100 ///     sf::Lock lock(mutex); // mutex is now locked
0101 ///
0102 ///     functionThatMayThrowAnException(); // mutex is unlocked if this function throws
0103 ///
0104 ///     if (someCondition)
0105 ///         return; // mutex is unlocked
0106 ///
0107 /// } // mutex is unlocked
0108 /// \endcode
0109 ///
0110 /// Because the mutex is not explicitly unlocked in the code,
0111 /// it may remain locked longer than needed. If the region
0112 /// of the code that needs to be protected by the mutex is
0113 /// not the entire function, a good practice is to create a
0114 /// smaller, inner scope so that the lock is limited to this
0115 /// part of the code.
0116 ///
0117 /// \code
0118 /// sf::Mutex mutex;
0119 ///
0120 /// void function()
0121 /// {
0122 ///     {
0123 ///       sf::Lock lock(mutex);
0124 ///       codeThatRequiresProtection();
0125 ///
0126 ///     } // mutex is unlocked here
0127 ///
0128 ///     codeThatDoesntCareAboutTheMutex();
0129 /// }
0130 /// \endcode
0131 ///
0132 /// Having a mutex locked longer than required is a bad practice
0133 /// which can lead to bad performances. Don't forget that when
0134 /// a mutex is locked, other threads may be waiting doing nothing
0135 /// until it is released.
0136 ///
0137 /// \see sf::Mutex
0138 ///
0139 ////////////////////////////////////////////////////////////