Edgaru089/SFML
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improved documentation of more classes in the system module

Browse Source 
git-svn-id: https://sfml.svn.sourceforge.net/svnroot/sfml/branches/sfml2@1204 4e206d99-4929-0410-ac5d-dfc041789085
This commit is contained in:
LaurentGom 2009-08-17 10:55:11 +00:00
parent 351a43f696
commit fcdc5cdf82
11 changed files with 187 additions and 120 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
include/SFML/System/Randomizer.hpp
View File

@ -35,6 +35,7 @@ namespace sf
{
////////////////////////////////////////////////////////////
/// \brief Utility class for generating pseudo-random numbers
///
////////////////////////////////////////////////////////////
class SFML_API Randomizer
{

12
include/SFML/System/Resource.inl
View File

@ -23,8 +23,6 @@
////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////
/// Default constructor
////////////////////////////////////////////////////////////
template <typename T>
Resource<T>::Resource()
@ -33,8 +31,6 @@ Resource<T>::Resource()
}
////////////////////////////////////////////////////////////
/// Copy constructor
////////////////////////////////////////////////////////////
template <typename T>
Resource<T>::Resource(const Resource<T>&)
@ -43,8 +39,6 @@ Resource<T>::Resource(const Resource<T>&)
}
////////////////////////////////////////////////////////////
/// Destructor
////////////////////////////////////////////////////////////
template <typename T>
Resource<T>::~Resource()
@ -57,8 +51,6 @@ Resource<T>::~Resource()
}
////////////////////////////////////////////////////////////
/// Assignment operator
////////////////////////////////////////////////////////////
template <typename T>
Resource<T>& Resource<T>::operator =(const Resource<T>&)
@ -68,8 +60,6 @@ Resource<T>& Resource<T>::operator =(const Resource<T>&)
}
////////////////////////////////////////////////////////////
/// Connect a ResourcePtr to this resource
////////////////////////////////////////////////////////////
template <typename T>
void Resource<T>::Connect(ResourcePtr<T>& observer) const
@ -78,8 +68,6 @@ void Resource<T>::Connect(ResourcePtr<T>& observer) const
}
////////////////////////////////////////////////////////////
/// Disconnect a ResourcePtr from this resource
////////////////////////////////////////////////////////////
template <typename T>
void Resource<T>::Disconnect(ResourcePtr<T>& observer) const

24
include/SFML/System/ResourcePtr.inl
View File

@ -23,8 +23,6 @@
////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////
/// Default constructor
////////////////////////////////////////////////////////////
template <typename T>
ResourcePtr<T>::ResourcePtr() :
@ -34,8 +32,6 @@ myResource(NULL)
}
////////////////////////////////////////////////////////////
/// Construct from a raw resource
////////////////////////////////////////////////////////////
template <typename T>
ResourcePtr<T>::ResourcePtr(const T* resource) :
@ -46,8 +42,6 @@ myResource(resource)
}
////////////////////////////////////////////////////////////
/// Copy constructor
////////////////////////////////////////////////////////////
template <typename T>
ResourcePtr<T>::ResourcePtr(const ResourcePtr<T>& copy) :
@ -58,8 +52,6 @@ myResource(copy.myResource)
}
////////////////////////////////////////////////////////////
/// Destructor
////////////////////////////////////////////////////////////
template <typename T>
ResourcePtr<T>::~ResourcePtr()
@ -69,8 +61,6 @@ ResourcePtr<T>::~ResourcePtr()
}
////////////////////////////////////////////////////////////
/// Assignment operator from another ResourcePtr
////////////////////////////////////////////////////////////
template <typename T>
ResourcePtr<T>& ResourcePtr<T>::operator =(const ResourcePtr<T>& other)
@ -87,8 +77,6 @@ ResourcePtr<T>& ResourcePtr<T>::operator =(const ResourcePtr<T>& other)
}
////////////////////////////////////////////////////////////
/// Assignment operator from a raw resource
////////////////////////////////////////////////////////////
template <typename T>
ResourcePtr<T>& ResourcePtr<T>::operator =(const T* resource)
@ -105,11 +93,6 @@ ResourcePtr<T>& ResourcePtr<T>::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 <typename T>
ResourcePtr<T>::operator const T*() const
@ -118,8 +101,6 @@ ResourcePtr<T>::operator const T*() const
}
////////////////////////////////////////////////////////////
/// Operator * overload to return a reference to the actual resource
////////////////////////////////////////////////////////////
template <typename T>
const T& ResourcePtr<T>::operator *() const
@ -128,8 +109,6 @@ const T& ResourcePtr<T>::operator *() const
}
////////////////////////////////////////////////////////////
/// Operator -> overload to return a pointer to the actual resource
////////////////////////////////////////////////////////////
template <typename T>
const T* ResourcePtr<T>::operator ->() const
@ -138,9 +117,6 @@ const T* ResourcePtr<T>::operator ->() const
}
////////////////////////////////////////////////////////////
/// Function called when the observed resource is about to be
/// destroyed
////////////////////////////////////////////////////////////
template <typename T>
void ResourcePtr<T>::OnResourceDestroyed()

7
include/SFML/System/Sleep.hpp
View File

@ -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);

108
include/SFML/System/Thread.hpp
View File

@ -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).
///
////////////////////////////////////////////////////////////

31
include/SFML/System/ThreadLocal.hpp
View File

@ -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.
///
////////////////////////////////////////////////////////////

85
include/SFML/System/ThreadLocalPtr.hpp
View File

@ -34,7 +34,8 @@
namespace sf
{
////////////////////////////////////////////////////////////
/// Type-safe wrapper for thread local pointer variables
/// \brief Pointer to a thread-local variable
///
////////////////////////////////////////////////////////////
template <typename T>
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<T>& 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<T>& operator =(const ThreadLocalPtr<T>& 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<MyClass> 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.
///
////////////////////////////////////////////////////////////

12
include/SFML/System/ThreadLocalPtr.inl
View File

@ -26,8 +26,6 @@
namespace sf
{
////////////////////////////////////////////////////////////
/// Default constructor
////////////////////////////////////////////////////////////
template <typename T>
ThreadLocalPtr<T>::ThreadLocalPtr(T* Value) :
ThreadLocal(Value)
@ -35,8 +33,6 @@ ThreadLocal(Value)
}
////////////////////////////////////////////////////////////
/// Operator * overload to return a reference to the variable
////////////////////////////////////////////////////////////
template <typename T>
T& ThreadLocalPtr<T>::operator *() const
@ -45,8 +41,6 @@ T& ThreadLocalPtr<T>::operator *() const
}
////////////////////////////////////////////////////////////
/// Operator -> overload to return a pointer to the variable
////////////////////////////////////////////////////////////
template <typename T>
T* ThreadLocalPtr<T>::operator ->() const
@ -55,8 +49,6 @@ T* ThreadLocalPtr<T>::operator ->() const
}
////////////////////////////////////////////////////////////
/// Implicit cast operator to T*
////////////////////////////////////////////////////////////
template <typename T>
ThreadLocalPtr<T>::operator T*() const
@ -65,8 +57,6 @@ ThreadLocalPtr<T>::operator T*() const
}
////////////////////////////////////////////////////////////
/// Assignment operator
////////////////////////////////////////////////////////////
template <typename T>
ThreadLocalPtr<T>& ThreadLocalPtr<T>::operator =(T* Value)
@ -76,8 +66,6 @@ ThreadLocalPtr<T>& ThreadLocalPtr<T>::operator =(T* Value)
}
////////////////////////////////////////////////////////////
/// Assignment operator
////////////////////////////////////////////////////////////
template <typename T>
ThreadLocalPtr<T>& ThreadLocalPtr<T>::operator =(const ThreadLocalPtr<T>& Other)

2
src/SFML/System/Sleep.cpp
View File

@ -32,8 +32,6 @@
namespace sf
{
////////////////////////////////////////////////////////////
/// Make the current thread sleep for a given time
////////////////////////////////////////////////////////////
void Sleep(float duration)
{
if (duration >= 0)

17
src/SFML/System/Thread.cpp
View File

@ -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()
{

8
src/SFML/System/ThreadLocal.cpp
View File

@ -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
{