Documentation for Synchronisation primitives

Former-commit-id: 39f86b2f9cd1f44a6b8e52101458f090183707e4

src/Nazara/Core/ConditionVariable.cpp

@@ -18,32 +18,84 @@
 
 namespace Nz
 {
+	/*!
+	* \class Nz::ConditionVariable
+	* \brief Core class that represents a condition variable
+	*
+	* The ConditionVariable class is a synchronization primitive that can be used to block a thread, or multiple threads at the same time, until another thread both modifies a shared variable (the condition), and notifies the ConditionVariable
+	*/
+
+	/*!
+	* \brief Constructs a ConditionVariable object by default
+	*/
+
 	ConditionVariable::ConditionVariable()
 	{
 		m_impl = new ConditionVariableImpl;
 	}
 
+	/*!
+	* \brief Destructs the object
+	*/
+
 	ConditionVariable::~ConditionVariable()
 	{
 		delete m_impl;
 	}
 
+	/*!
+	* \brief Sends a signal to one thread waiting on the condition
+	*
+	* If any threads are waiting on *this, calling Signal unblocks one of the waiting threads
+	*
+	* \see SignalAll
+	*/
+
 	void ConditionVariable::Signal()
 	{
 		m_impl->Signal();
 	}
 
+	/*!
+	* \brief Sends a signal to every threads waiting on the condition
+	*
+	* Unblocks all threads currently waiting for *this
+	*
+	* \see Signal
+	*/
+
 	void ConditionVariable::SignalAll()
 	{
 		m_impl->SignalAll();
 	}
 
+	/*!
+	* \brief Makes the thread wait on the condition
+	*
+	* Wait causes the current thread to block until the condition variable is notified or a spurious wakeup occurs
+	*
+	* \param mutex Mutex for the condition
+	*
+	* \remark Produces a NazaraAssert if mutex is invalid
+	*/
+
 	void ConditionVariable::Wait(Mutex* mutex)
 	{
 		NazaraAssert(mutex != nullptr, "Mutex must be valid");
 		m_impl->Wait(mutex->m_impl);
 	}
 
+	/*!
+	* \brief Makes the thread wait on the condition for a certain amount of time
+	*
+	* Wait causes the current thread to block until the condition variable is notified, a specific time is reached, or a spurious wakeup occurs
+	*
+	* \param mutex Mutex for the condition
+	* \param timeout Time before expiration of the waiting
+	*
+	* \remark Produces a NazaraAssert if mutex is invalid
+	*/
+
 	bool ConditionVariable::Wait(Mutex* mutex, UInt32 timeout)
 	{
 		NazaraAssert(mutex != nullptr, "Mutex must be valid");

src/Nazara/Core/LockGuard.cpp

@@ -8,12 +8,27 @@
 
 namespace Nz
 {
+	/*!
+	* \class Nz::LockGuard
+	* \brief Core class that represents a mutex wrapper that provides a convenient RAII-style mechanism
+	*/
+
+	/*!
+	* \brief Constructs a LockGuard object with a mutex
+	*
+	* \param mutex Mutex to lock
+	*/
+
 	LockGuard::LockGuard(Mutex& mutex) :
 	m_mutex(mutex)
 	{
 		m_mutex.Lock();
 	}
 
+	/*!
+	* \brief Destructs a LockGuard object and unlocks the mutex
+	*/
+
 	LockGuard::~LockGuard()
 	{
 		m_mutex.Unlock();

src/Nazara/Core/Mutex.cpp

@@ -16,26 +16,58 @@
 
 namespace Nz
 {
+	/*!
+	* \class Nz::Mutex
+	* \brief Core class that represents a binary semaphore, a mutex
+	*
+	* \remark The mutex is recursive, it means that a thread who owns the mutex can call the same function which needs the same mutex
+	*/
+
+	/*!
+	* \brief Constructs a Mutex object by default
+	*/
+
 	Mutex::Mutex()
 	{
 		m_impl = new MutexImpl;
 	}
 
+	/*!
+	* \brief Destructs the object
+	*/
+
 	Mutex::~Mutex()
 	{
 		delete m_impl;
 	}
 
+	/*!
+	* \brief Locks the mutex
+	*
+	* If another thread has already locked the mutex, a call to lock will block execution until the lock is acquired. A thread may call lock on a recursive mutex repeatedly. Ownership will only be released after the thread makes a matching number of calls to unlock
+	*/
+
 	void Mutex::Lock()
 	{
 		m_impl->Lock();
 	}
 
+	/*!
+	* \brief Tries to lock the mutex
+	* \return true if the lock was acquired successfully
+	*/
+
 	bool Mutex::TryLock()
 	{
 		return m_impl->TryLock();
 	}
 
+	/*!
+	* \brief Unlocks the mutex
+	*
+	* Unlocks the mutex if its level of ownership is 1 (there was exactly one more call to Lock() than there were calls to Unlock() made by this thread), reduces the level of ownership by 1 otherwise
+	*/
+
 	void Mutex::Unlock()
 	{
 		m_impl->Unlock();

src/Nazara/Core/Posix/FileImpl.cpp

@@ -70,7 +70,7 @@ namespace Nz
 			flags |= O_TRUNC;
 
 		///TODO: lock
-	//	if ((mode & OpenMode_Lock) == 0)
+		//if ((mode & OpenMode_Lock) == 0)
 		//	shareMode |= FILE_SHARE_WRITE;
 
 		m_fileDescriptor = open64(filePath.GetConstBuffer(), flags, permissions);

src/Nazara/Core/Posix/SemaphoreImpl.cpp

@@ -13,7 +13,7 @@ namespace Nz
 {
 	SemaphoreImpl::SemaphoreImpl(unsigned int count)
 	{
-		if(sem_init(&m_semaphore, 0, count) != 0)
+		if (sem_init(&m_semaphore, 0, count) != 0)
 			NazaraError("Failed to create semaphore: " + Error::GetLastSystemError());
 	}
 

src/Nazara/Core/Semaphore.cpp

@@ -16,31 +16,68 @@
 
 namespace Nz
 {
+	/*!
+	* \class Nz::Semaphore
+	* \brief Core class that represents a counting semaphore
+	*/
+
+	/*!
+	* \brief Constructs a semaphore object with a count
+	*/
+
 	Semaphore::Semaphore(unsigned int count)
 	{
 		m_impl = new SemaphoreImpl(count);
 	}
 
+	/*!
+	* \brief Destructs the object
+	*/
+
 	Semaphore::~Semaphore()
 	{
 		delete m_impl;
 	}
 
+	/*!
+	* \brief Gets the number of count that can handle the semaphore
+	* \return Number of count associated with the semaphore
+	*/
+
 	unsigned int Semaphore::GetCount() const
 	{
 		return m_impl->GetCount();
 	}
 
+	/*!
+	* \brief Increments the count of the semaphore and wait if count equals zero
+	*
+	*  Increments the value of semaphore variable by 1. After the increment, if the pre-increment value was negative (meaning there are processes waiting for a resource), it transfers a blocked process from the semaphore's waiting queue to the ready queue
+	*/
+
 	void Semaphore::Post()
 	{
 		m_impl->Post();
 	}
 
+	/*!
+	* \brief Decrements the count of the semaphore and wait if count equals zero
+	*
+	* If the value of semaphore variable is not negative, decrements it by 1. If the semaphore variable is now negative, the process executing Wait is blocked (i.e., added to the semaphore's queue) until the value is greater or equal to 1. Otherwise, the process continues execution, having used a unit of the resource
+	*/
+
 	void Semaphore::Wait()
 	{
 		m_impl->Wait();
 	}
 
+	/*!
+	* \brief Decrements the count of the semaphore and wait if count equals zero
+	* \return true if the semaphore successfully decrements before timeout
+	*
+	* If the value of semaphore variable is not negative, decrements it by 1. If the semaphore variable is now negative, the process executing Wait is blocked (i.e., added to the semaphore's queue) until the value is greater or equal to 1. Otherwise, the process continues execution, having used a unit of the resource
+	*/
+
 	bool Semaphore::Wait(UInt32 timeout)
 	{
 		return m_impl->Wait(timeout);