From fcdc5cdf82b0bc7e9f4ac36631af95231988a929 Mon Sep 17 00:00:00 2001 From: LaurentGom Date: Mon, 17 Aug 2009 10:55:11 +0000 Subject: [PATCH] Improved documentation of more classes in the system module git-svn-id: https://sfml.svn.sourceforge.net/svnroot/sfml/branches/sfml2@1204 4e206d99-4929-0410-ac5d-dfc041789085 --- include/SFML/System/Randomizer.hpp | 1 + include/SFML/System/Resource.inl | 12 --- include/SFML/System/ResourcePtr.inl | 24 ------ include/SFML/System/Sleep.hpp | 7 +- include/SFML/System/Thread.hpp | 108 +++++++++++++++++++++---- include/SFML/System/ThreadLocal.hpp | 31 ++++--- include/SFML/System/ThreadLocalPtr.hpp | 85 +++++++++++++++---- include/SFML/System/ThreadLocalPtr.inl | 12 --- src/SFML/System/Sleep.cpp | 2 - src/SFML/System/Thread.cpp | 17 ---- src/SFML/System/ThreadLocal.cpp | 8 -- 11 files changed, 187 insertions(+), 120 deletions(-) diff --git a/include/SFML/System/Randomizer.hpp b/include/SFML/System/Randomizer.hpp index 34f22b427..ca54d6efc 100644 --- a/include/SFML/System/Randomizer.hpp +++ b/include/SFML/System/Randomizer.hpp @@ -35,6 +35,7 @@ namespace sf { //////////////////////////////////////////////////////////// /// \brief Utility class for generating pseudo-random numbers +/// //////////////////////////////////////////////////////////// class SFML_API Randomizer { diff --git a/include/SFML/System/Resource.inl b/include/SFML/System/Resource.inl index 357cc5e44..c1fb52968 100644 --- a/include/SFML/System/Resource.inl +++ b/include/SFML/System/Resource.inl @@ -23,8 +23,6 @@ //////////////////////////////////////////////////////////// -//////////////////////////////////////////////////////////// -/// Default constructor //////////////////////////////////////////////////////////// template Resource::Resource() @@ -33,8 +31,6 @@ Resource::Resource() } -//////////////////////////////////////////////////////////// -/// Copy constructor //////////////////////////////////////////////////////////// template Resource::Resource(const Resource&) @@ -43,8 +39,6 @@ Resource::Resource(const Resource&) } -//////////////////////////////////////////////////////////// -/// Destructor //////////////////////////////////////////////////////////// template Resource::~Resource() @@ -57,8 +51,6 @@ Resource::~Resource() } -//////////////////////////////////////////////////////////// -/// Assignment operator //////////////////////////////////////////////////////////// template Resource& Resource::operator =(const Resource&) @@ -68,8 +60,6 @@ Resource& Resource::operator =(const Resource&) } -//////////////////////////////////////////////////////////// -/// Connect a ResourcePtr to this resource //////////////////////////////////////////////////////////// template void Resource::Connect(ResourcePtr& observer) const @@ -78,8 +68,6 @@ void Resource::Connect(ResourcePtr& observer) const } -//////////////////////////////////////////////////////////// -/// Disconnect a ResourcePtr from this resource //////////////////////////////////////////////////////////// template void Resource::Disconnect(ResourcePtr& observer) const diff --git a/include/SFML/System/ResourcePtr.inl b/include/SFML/System/ResourcePtr.inl index 2399bc04c..b94e5e8f2 100644 --- a/include/SFML/System/ResourcePtr.inl +++ b/include/SFML/System/ResourcePtr.inl @@ -23,8 +23,6 @@ //////////////////////////////////////////////////////////// -//////////////////////////////////////////////////////////// -/// Default constructor //////////////////////////////////////////////////////////// template ResourcePtr::ResourcePtr() : @@ -34,8 +32,6 @@ myResource(NULL) } -//////////////////////////////////////////////////////////// -/// Construct from a raw resource //////////////////////////////////////////////////////////// template ResourcePtr::ResourcePtr(const T* resource) : @@ -46,8 +42,6 @@ myResource(resource) } -//////////////////////////////////////////////////////////// -/// Copy constructor //////////////////////////////////////////////////////////// template ResourcePtr::ResourcePtr(const ResourcePtr& copy) : @@ -58,8 +52,6 @@ myResource(copy.myResource) } -//////////////////////////////////////////////////////////// -/// Destructor //////////////////////////////////////////////////////////// template ResourcePtr::~ResourcePtr() @@ -69,8 +61,6 @@ ResourcePtr::~ResourcePtr() } -//////////////////////////////////////////////////////////// -/// Assignment operator from another ResourcePtr //////////////////////////////////////////////////////////// template ResourcePtr& ResourcePtr::operator =(const ResourcePtr& other) @@ -87,8 +77,6 @@ ResourcePtr& ResourcePtr::operator =(const ResourcePtr& other) } -//////////////////////////////////////////////////////////// -/// Assignment operator from a raw resource //////////////////////////////////////////////////////////// template ResourcePtr& ResourcePtr::operator =(const T* resource) @@ -105,11 +93,6 @@ ResourcePtr& ResourcePtr::operator =(const T* resource) } -//////////////////////////////////////////////////////////// -/// Cast operator to implicitely convert the resource pointer to -/// its raw pointer type. -/// This might be dangerous in the general case, but in this context -/// it is safe enough to define this operator //////////////////////////////////////////////////////////// template ResourcePtr::operator const T*() const @@ -118,8 +101,6 @@ ResourcePtr::operator const T*() const } -//////////////////////////////////////////////////////////// -/// Operator * overload to return a reference to the actual resource //////////////////////////////////////////////////////////// template const T& ResourcePtr::operator *() const @@ -128,8 +109,6 @@ const T& ResourcePtr::operator *() const } -//////////////////////////////////////////////////////////// -/// Operator -> overload to return a pointer to the actual resource //////////////////////////////////////////////////////////// template const T* ResourcePtr::operator ->() const @@ -138,9 +117,6 @@ const T* ResourcePtr::operator ->() const } -//////////////////////////////////////////////////////////// -/// Function called when the observed resource is about to be -/// destroyed //////////////////////////////////////////////////////////// template void ResourcePtr::OnResourceDestroyed() diff --git a/include/SFML/System/Sleep.hpp b/include/SFML/System/Sleep.hpp index 279e6ad09..a4f9cda99 100644 --- a/include/SFML/System/Sleep.hpp +++ b/include/SFML/System/Sleep.hpp @@ -34,9 +34,12 @@ namespace sf { //////////////////////////////////////////////////////////// -/// Make the current thread sleep for a given time +/// \brief Make the current thread sleep for a given time /// -/// \param duration : Time to sleep, in seconds (must be >= 0) +/// sf::Sleep is the best way to block a program or one of its +/// threads, as it doesn't consume any CPU power. +/// +/// \param duration Time to sleep, in seconds (must be positive) /// //////////////////////////////////////////////////////////// void SFML_API Sleep(float duration); diff --git a/include/SFML/System/Thread.hpp b/include/SFML/System/Thread.hpp index 4048b5e84..8b0a8a788 100644 --- a/include/SFML/System/Thread.hpp +++ b/include/SFML/System/Thread.hpp @@ -41,11 +41,7 @@ namespace priv } //////////////////////////////////////////////////////////// -/// Thread defines an easy way to manipulate a thread. -/// There are two ways to use Thread : -/// - Inherit from it and override the Run() virtual function -/// - Construct a Thread instance and pass it a function -/// pointer to call +/// \brief Utility class to manipulate threads //////////////////////////////////////////////////////////// class SFML_API Thread : NonCopyable { @@ -54,37 +50,47 @@ public : typedef void (*FuncType)(void*); //////////////////////////////////////////////////////////// - /// Construct the thread from a function pointer + /// \brief Construct the thread from a function pointer /// - /// \param function : Entry point of the thread - /// \param userData : Data to pass to the thread function (NULL by default) + /// \param function Entry point of the thread + /// \param userData Data to pass to the thread function (NULL by default) /// //////////////////////////////////////////////////////////// Thread(FuncType function, void* userData = NULL); //////////////////////////////////////////////////////////// - /// Virtual destructor + /// \brief Virtual destructor + /// + /// This destructor calls Wait(), so that the thread cannot + /// survive when its sf::Thread instance is destroyed. /// //////////////////////////////////////////////////////////// virtual ~Thread(); //////////////////////////////////////////////////////////// - /// Create and run the thread + /// \brief Run the thread /// //////////////////////////////////////////////////////////// void Launch(); //////////////////////////////////////////////////////////// - /// Wait until the thread finishes + /// \brief Wait until the thread finishes + /// + /// This function will block the execution until the + /// thread's function ends. /// //////////////////////////////////////////////////////////// void Wait(); //////////////////////////////////////////////////////////// - /// Terminate the thread + /// \brief Terminate the thread + /// + /// This function immediately stops the thread, without waiting + /// for its function to finish. /// Terminating a thread with this function is not safe, - /// you should rather try to make the thread function - /// terminate by itself + /// and can lead to local variables not being destroyed + /// on some operating systems. You should rather try to make + /// the thread function terminate by itself. /// //////////////////////////////////////////////////////////// void Terminate(); @@ -92,7 +98,9 @@ public : protected : //////////////////////////////////////////////////////////// - /// Default constructor + /// \brief Default constructor + /// + /// This constructor is only accessible from derived classes /// //////////////////////////////////////////////////////////// Thread(); @@ -102,7 +110,10 @@ private : friend class priv::ThreadImpl; //////////////////////////////////////////////////////////// - /// Function called as the thread entry point + /// \brief Function called as the entry point of the thread + /// + /// You must override this function when inheriting from + /// sf::Thread. /// //////////////////////////////////////////////////////////// virtual void Run(); @@ -119,3 +130,68 @@ private : #endif // SFML_THREAD_HPP + + +//////////////////////////////////////////////////////////// +/// \class sf::Thread +/// +/// Threads provide a way to run multiple parts of the code +/// in parallel. When you launch a new thread, the execution +/// is split and both the new thread and the caller run +/// in parallel. +/// +/// There are two ways to use sf::Thread. The first (and +/// preferred) way of using it is to created derived classes. +/// When inheriting from sf::Thread, the virtual function +/// Run() has to be overriden, and defines the entry point +/// of the thread. The thread automatically stops when +/// this function ends. +/// +/// Usage example: +/// \code +/// class MyThread : public sf::Thread +/// { +/// private : +/// +/// virtual void Run() +/// { +/// // beginning of the thread +/// ... +/// // end of the thread +/// } +/// }; +/// +/// MyThread mythread; +/// mythread.Launch(); // start the thread (internally calls thread.Run()) +/// +/// // from now on, both mythread and the main thread run in parallel +/// \endcode +/// +/// The second way of using sf::Thread uses a non-member function +/// as the entry point and thus doesn't involve creating +/// a new class. However, this method is only provided for +/// compatibility with C-style code or for fast prototyping; +/// you are strongly encouraged to use the first method. +/// +/// Usage example: +/// \code +/// void ThreadFunc(void* data) +/// { +/// // beginning of the thread +/// ... +/// // end of the thread +/// } +/// +/// sf::Thread mythread(&ThreadFunc, NULL); +/// mythread.Launch(); // start the thread (internally calls ThreadFunc(NULL)) +/// +/// // from now on, both mythread and the main thread run in parallel +/// \endcode +/// +/// Creating parallel threads of execution can be dangerous: +/// all threads inside the same process share the same memory space, +/// which means that you may end up accessing the same variable +/// from multiple threads at the same time. To prevent this +/// kind of situations, you can use mutexes (see sf::Mutex). +/// +//////////////////////////////////////////////////////////// diff --git a/include/SFML/System/ThreadLocal.hpp b/include/SFML/System/ThreadLocal.hpp index 9219ac619..1112b1b4d 100644 --- a/include/SFML/System/ThreadLocal.hpp +++ b/include/SFML/System/ThreadLocal.hpp @@ -41,42 +41,39 @@ namespace priv } //////////////////////////////////////////////////////////// -/// Wrapper to handle variables that are local to threads. -/// This means that the same ThreadLocalStorage variable will -/// hold a different value for each different thread. -/// For a more strongly-typed interface, use the ThreadLocal -/// template class. +/// \brief Defines variables with thread-local storage +/// //////////////////////////////////////////////////////////// class SFML_API ThreadLocal : NonCopyable { public : //////////////////////////////////////////////////////////// - /// Default constructor + /// \brief Default constructor /// - /// \param value : Optional value to initalize the variable (NULL by default) + /// \param value Optional value to initalize the variable (NULL by default) /// //////////////////////////////////////////////////////////// ThreadLocal(void* value = NULL); //////////////////////////////////////////////////////////// - /// Destructor + /// \brief Destructor /// //////////////////////////////////////////////////////////// ~ThreadLocal(); //////////////////////////////////////////////////////////// - /// Set the thread-specific value of the variable + /// \brief Set the thread-specific value of the variable /// - /// \param Value : Value of the variable for this thread + /// \param value Value of the variable for the current thread /// //////////////////////////////////////////////////////////// void SetValue(void* value); //////////////////////////////////////////////////////////// - /// Retrieve the thread-specific value of the variable + /// \brief Retrieve the thread-specific value of the variable /// - /// \return Value of the variable for this thread + /// \return Value of the variable for the current thread /// //////////////////////////////////////////////////////////// void* GetValue() const; @@ -93,3 +90,13 @@ private : #endif // SFML_THREADLOCAL_HPP + + +//////////////////////////////////////////////////////////// +/// \class sf::ThreadLocal +/// +/// This class manipulates void* parameters and thus is not +/// appropriate for strongly-typed variables. You should rather +/// use the sf::ThreadLocalPtr template class. +/// +//////////////////////////////////////////////////////////// diff --git a/include/SFML/System/ThreadLocalPtr.hpp b/include/SFML/System/ThreadLocalPtr.hpp index cfdd1ab9c..060c22cf3 100644 --- a/include/SFML/System/ThreadLocalPtr.hpp +++ b/include/SFML/System/ThreadLocalPtr.hpp @@ -34,7 +34,8 @@ namespace sf { //////////////////////////////////////////////////////////// -/// Type-safe wrapper for thread local pointer variables +/// \brief Pointer to a thread-local variable +/// //////////////////////////////////////////////////////////// template class ThreadLocalPtr : private ThreadLocal @@ -42,53 +43,60 @@ class ThreadLocalPtr : private ThreadLocal public : //////////////////////////////////////////////////////////// - /// Default constructor + /// \brief Default constructor /// - /// \param value : Optional value to initalize the variable (NULL by default) + /// \param value Optional value to initalize the variable (NULL by default) /// //////////////////////////////////////////////////////////// ThreadLocalPtr(T* value = NULL); //////////////////////////////////////////////////////////// - /// Operator * overload to return a reference to the variable + /// \brief Overload of unary operator * /// - /// \return Reference to the thread-local value of the variable + /// Like raw pointers, applying the * operator returns a + /// reference to the pointed object. + /// + /// \return Reference to the pointed object /// //////////////////////////////////////////////////////////// T& operator *() const; //////////////////////////////////////////////////////////// - /// Operator -> overload to return a pointer to the variable + /// \brief Overload of operator -> /// - /// \return Pointer to the thread-local value of the variable + /// Like raw pointers, applying the -> operator returns the + /// pointed object. + /// + /// \return Pointed object /// //////////////////////////////////////////////////////////// T* operator ->() const; //////////////////////////////////////////////////////////// - /// Implicit cast operator to T* + /// \brief Cast operator to implicitely convert the + /// pointer to its raw pointer type (T*) /// - /// \return Value of the pointer for this thread + /// \return Pointer to the actual object /// //////////////////////////////////////////////////////////// operator T*() const; //////////////////////////////////////////////////////////// - /// Assignment operator + /// \brief Assignment operator for a raw pointer parameter /// - /// \param value : New pointer value to assign for this thread + /// \param resource Pointer to assign /// - /// \return Reference to this + /// \return Reference to self /// //////////////////////////////////////////////////////////// ThreadLocalPtr& operator =(T* value); //////////////////////////////////////////////////////////// - /// Assignment operator + /// \brief Assignment operator for a ThreadLocalPtr parameter /// - /// \param other : Other thread-local pointer value to assign + /// \param other ThreadLocalPtr to assign /// - /// \return Reference to this + /// \return Reference to self /// //////////////////////////////////////////////////////////// ThreadLocalPtr& operator =(const ThreadLocalPtr& other); @@ -100,3 +108,50 @@ public : #endif // SFML_THREADLOCALPTR_HPP + + +//////////////////////////////////////////////////////////// +/// \class sf::ThreadLocalPtr +/// +/// sf::ThreadLocalPtr is a type-safe wrapper for storing +/// pointers to thread-local variables. A thread-local +/// variable holds a different value for each different +/// thread, unlike normal variable that are shared. +/// +/// Its usage is completely transparent, so that it is similar +/// to manipulating the raw pointer directly (like any smart pointer). +/// +/// Usage example: +/// \code +/// MyClass object1; +/// MyClass object2; +/// sf::ThreadLocalPtr objectPtr; +/// +/// void Thread1(void*) +/// { +/// objectPtr = &object1; // doesn't impact Thread2 +/// ... +/// } +/// +/// void Thread1(void*) +/// { +/// objectPtr = &object2; // doesn't impact Thread1 +/// ... +/// } +/// +/// int main() +/// { +/// // Create and launch the two threads +/// sf::Thread thread1(&Thread1); +/// sf::Thread thread2(&Thread2); +/// thread1.Launch(); +/// thread2.Launch(); +/// +/// return 0; +/// } +/// \endcode +/// +/// ThreadLocalPtr is designed for internal use; however you +/// can use it if you feel like it fits well your implementation. +/// +//////////////////////////////////////////////////////////// diff --git a/include/SFML/System/ThreadLocalPtr.inl b/include/SFML/System/ThreadLocalPtr.inl index c4f8719d7..cd92a147a 100644 --- a/include/SFML/System/ThreadLocalPtr.inl +++ b/include/SFML/System/ThreadLocalPtr.inl @@ -26,8 +26,6 @@ namespace sf { //////////////////////////////////////////////////////////// -/// Default constructor -//////////////////////////////////////////////////////////// template ThreadLocalPtr::ThreadLocalPtr(T* Value) : ThreadLocal(Value) @@ -35,8 +33,6 @@ ThreadLocal(Value) } -//////////////////////////////////////////////////////////// -/// Operator * overload to return a reference to the variable //////////////////////////////////////////////////////////// template T& ThreadLocalPtr::operator *() const @@ -45,8 +41,6 @@ T& ThreadLocalPtr::operator *() const } -//////////////////////////////////////////////////////////// -/// Operator -> overload to return a pointer to the variable //////////////////////////////////////////////////////////// template T* ThreadLocalPtr::operator ->() const @@ -55,8 +49,6 @@ T* ThreadLocalPtr::operator ->() const } -//////////////////////////////////////////////////////////// -/// Implicit cast operator to T* //////////////////////////////////////////////////////////// template ThreadLocalPtr::operator T*() const @@ -65,8 +57,6 @@ ThreadLocalPtr::operator T*() const } -//////////////////////////////////////////////////////////// -/// Assignment operator //////////////////////////////////////////////////////////// template ThreadLocalPtr& ThreadLocalPtr::operator =(T* Value) @@ -76,8 +66,6 @@ ThreadLocalPtr& ThreadLocalPtr::operator =(T* Value) } -//////////////////////////////////////////////////////////// -/// Assignment operator //////////////////////////////////////////////////////////// template ThreadLocalPtr& ThreadLocalPtr::operator =(const ThreadLocalPtr& Other) diff --git a/src/SFML/System/Sleep.cpp b/src/SFML/System/Sleep.cpp index ed65e8620..bdbd8497c 100644 --- a/src/SFML/System/Sleep.cpp +++ b/src/SFML/System/Sleep.cpp @@ -32,8 +32,6 @@ namespace sf { //////////////////////////////////////////////////////////// -/// Make the current thread sleep for a given time -//////////////////////////////////////////////////////////// void Sleep(float duration) { if (duration >= 0) diff --git a/src/SFML/System/Thread.cpp b/src/SFML/System/Thread.cpp index d981cf98b..ae561c399 100644 --- a/src/SFML/System/Thread.cpp +++ b/src/SFML/System/Thread.cpp @@ -42,8 +42,6 @@ namespace sf { //////////////////////////////////////////////////////////// -/// Default constructor -//////////////////////////////////////////////////////////// Thread::Thread() : myThreadImpl(NULL), myFunction (NULL), @@ -53,8 +51,6 @@ myUserData (NULL) } -//////////////////////////////////////////////////////////// -/// Construct the thread from a function pointer //////////////////////////////////////////////////////////// Thread::Thread(Thread::FuncType function, void* userData) : myThreadImpl(NULL), @@ -65,8 +61,6 @@ myUserData (userData) } -//////////////////////////////////////////////////////////// -/// Virtual destructor //////////////////////////////////////////////////////////// Thread::~Thread() { @@ -74,8 +68,6 @@ Thread::~Thread() } -//////////////////////////////////////////////////////////// -/// Create and run the thread //////////////////////////////////////////////////////////// void Thread::Launch() { @@ -84,8 +76,6 @@ void Thread::Launch() } -//////////////////////////////////////////////////////////// -/// Wait until the thread finishes //////////////////////////////////////////////////////////// void Thread::Wait() { @@ -98,11 +88,6 @@ void Thread::Wait() } -//////////////////////////////////////////////////////////// -/// Terminate the thread -/// Terminating a thread with this function is not safe, -/// you should rather try to make the thread function -/// terminate by itself //////////////////////////////////////////////////////////// void Thread::Terminate() { @@ -115,8 +100,6 @@ void Thread::Terminate() } -//////////////////////////////////////////////////////////// -/// Function called as the thread entry point //////////////////////////////////////////////////////////// void Thread::Run() { diff --git a/src/SFML/System/ThreadLocal.cpp b/src/SFML/System/ThreadLocal.cpp index 49744f5e6..594c1d035 100644 --- a/src/SFML/System/ThreadLocal.cpp +++ b/src/SFML/System/ThreadLocal.cpp @@ -42,8 +42,6 @@ namespace sf { //////////////////////////////////////////////////////////// -/// Default constructor -//////////////////////////////////////////////////////////// ThreadLocal::ThreadLocal(void* value) { myImpl = new priv::ThreadLocalImpl; @@ -51,8 +49,6 @@ ThreadLocal::ThreadLocal(void* value) } -//////////////////////////////////////////////////////////// -/// Destructor //////////////////////////////////////////////////////////// ThreadLocal::~ThreadLocal() { @@ -60,8 +56,6 @@ ThreadLocal::~ThreadLocal() } -//////////////////////////////////////////////////////////// -/// Set the thread-specific value of the variable //////////////////////////////////////////////////////////// void ThreadLocal::SetValue(void* value) { @@ -69,8 +63,6 @@ void ThreadLocal::SetValue(void* value) } -//////////////////////////////////////////////////////////// -/// Retrieve the thread-specific value of the variable //////////////////////////////////////////////////////////// void* ThreadLocal::GetValue() const {