Documentation for Memory

Former-commit-id: 85e41e916df2c2e2bffa31f5540643144223a322

include/Nazara/Core/MemoryHelper.inl

@@ -2,7 +2,7 @@
 // This file is part of the "Nazara Engine - Core module"
 // For conditions of distribution and use, see copyright notice in Config.hpp
 
-// Je ne suis pas fier des cinq lignes qui suivent mais difficile de faire autrement pour le moment...
+// I'm not proud of those five following lines but ti's hard to do with another way now
 #ifdef NAZARA_DEBUG_NEWREDEFINITION_DISABLE_REDEFINITION
 	#define NAZARA_DEBUG_NEWREDEFINITION_DISABLE_REDEFINITION_DEFINED
 #else
@@ -16,6 +16,17 @@
 
 namespace Nz
 {
+	/*!
+	* \fn Nz::MemoryHelper
+	* \brief Core functions that helps the handle of memory in the engine
+	*/
+
+	/*!
+	* \brief Calls the operator delete on the pointer
+	*
+	* \remark Uses MemoryManager with NAZARA_CORE_MANAGE_MEMORY defined else operator delete
+	*/
+
 	inline void OperatorDelete(void* ptr)
 	{
 		#if NAZARA_CORE_MANAGE_MEMORY
@@ -25,6 +36,12 @@ namespace Nz
 		#endif
 	}
 
+	/*!
+	* \brief Calls the operator new on the pointer
+	*
+	* \remark Uses MemoryManager with NAZARA_CORE_MANAGE_MEMORY defined else operator new
+	*/
+
 	inline void* OperatorNew(std::size_t size)
 	{
 		#if NAZARA_CORE_MANAGE_MEMORY
@@ -34,6 +51,14 @@ namespace Nz
 		#endif
 	}
 
+	/*!
+	* \brief Constructs the object inplace
+	* \return Pointer to the constructed object
+	*
+	* \param ptr Pointer to raw memory allocated
+	* \param args Arguments for the constructor
+	*/
+
 	template<typename T, typename... Args>
 	T* PlacementNew(void* ptr, Args&&... args)
 	{
@@ -43,7 +68,7 @@ namespace Nz
 
 #include <Nazara/Core/DebugOff.hpp>
 
-// Si c'est nous qui avons défini la constante, alors il nous faut l'enlever (Pour éviter que le moteur entier n'en souffre)
+// If we have defined the constant, then we have to undefine it (to avoid bloating in the engine)
 #ifndef NAZARA_DEBUG_NEWREDEFINITION_DISABLE_REDEFINITION_DEFINED
 	#undef NAZARA_DEBUG_NEWREDEFINITION_DISABLE_REDEFINITION
 #endif

include/Nazara/Core/MemoryStream.inl

@@ -7,18 +7,36 @@
 
 namespace Nz
 {
+	/*!
+	* \brief Constructs a MemoryStream object by default
+	*/
+
 	inline MemoryStream::MemoryStream() :
 	Stream(StreamOption_None, OpenMode_ReadWrite),
 	m_pos(0)
 	{
 	}
 
+	/*!
+	* \brief Constructs a MemoryStream object with a byte array
+	*
+	* \param byteArray Bytes to stream
+	* \param openMode Reading/writing mode for the stream
+	*/
+
 	inline MemoryStream::MemoryStream(ByteArray* byteArray, UInt32 openMode) :
 	MemoryStream()
 	{
 		SetBuffer(byteArray, openMode);
 	}
 
+	/*!
+	* \brief Gets the internal buffer
+	* \return Buffer of bytes
+	*
+	* \remark Produces a NazaraAssert if buffer is invalid
+	*/
+
 	inline ByteArray& MemoryStream::GetBuffer()
 	{
 		NazaraAssert(m_buffer, "Invalid buffer");
@@ -26,6 +44,13 @@ namespace Nz
 		return *m_buffer;
 	}
 
+	/*!
+	* \brief Gets the internal buffer
+	* \return Buffer of bytes
+	*
+	* \remark Produces a NazaraAssert if buffer is invalid
+	*/
+
 	inline const ByteArray& MemoryStream::GetBuffer() const
 	{
 		NazaraAssert(m_buffer, "Invalid buffer");

src/Nazara/Core/MemoryManager.cpp

@@ -15,7 +15,7 @@
 	#include <pthread.h>
 #endif
 
-// Le seul fichier n'ayant pas à inclure Debug.hpp
+// The only file that does not need to include Debug.hpp
 
 namespace Nz
 {
@@ -61,18 +61,43 @@ namespace Nz
 		CRITICAL_SECTION s_mutex;
 		#elif defined(NAZARA_PLATFORM_POSIX)
 		pthread_mutex_t s_mutex = PTHREAD_MUTEX_INITIALIZER;
+		#else
+		#error Lack of implementation: Mutex
 		#endif
 	}
 	
+	/*!
+	* \class Nz::MemoryManager
+	* \brief Core class that represents a manager for the memory
+	*/
+
+	/*!
+	* \brief Constructs a MemoryManager object by default
+	*/
+
 	MemoryManager::MemoryManager()
 	{
 	}
 
+	/*!
+	* \brief Destructs a MemoryManager object and calls Unitialize
+	*/
+
 	MemoryManager::~MemoryManager()
 	{
 		Uninitialize();
 	}
 
+	/*!
+	* \brief Allocates memory
+	* \return Raw memory allocated
+	*
+	* \param size Size to allocate
+	* \parma multi Array or not
+	* \param file File of the allocation
+	* \param line Line of the allocation in the file
+	*/
+
 	void* MemoryManager::Allocate(std::size_t size, bool multi, const char* file, unsigned int line)
 	{
 		if (!s_initialized)
@@ -147,16 +172,37 @@ namespace Nz
 		return reinterpret_cast<UInt8*>(ptr) + sizeof(Block);
 	}
 
+	/*!
+	* \brief Enables the filling of the allocation
+	*
+	* \param allocationFilling If true, sets the rest of the allocation block to '0xFF'
+	*/
+
 	void MemoryManager::EnableAllocationFilling(bool allocationFilling)
 	{
 		s_allocationFilling = allocationFilling;
 	}
 
+	/*!
+	* \brief Enables the logging of the allocation
+	*
+	* \param logAllocations If true, registers every allocation
+	*/
+
 	void MemoryManager::EnableAllocationLogging(bool logAllocations)
 	{
 		s_allocationLogging = logAllocations;
 	}
 
+	/*!
+	* \brief Frees the pointer
+	*
+	* \param pointer Pointer to free
+	* \param multi Array or not
+	*
+	* \remark If pointer is nullptr, nothing is done
+	*/
+
 	void MemoryManager::Free(void* pointer, bool multi)
 	{
 		if (!pointer)
@@ -227,37 +273,73 @@ namespace Nz
 		#endif
 	}
 
+	/*!
+	* \brief Gets the number of allocated blocks
+	* \return Number of allocated blocks
+	*/
+
 	unsigned int MemoryManager::GetAllocatedBlockCount()
 	{
 		return s_allocatedBlock;
 	}
 
+	/*!
+	* \brief Gets the allocated size
+	* \return Size of total allocation
+	*/
+
 	std::size_t MemoryManager::GetAllocatedSize()
 	{
 		return s_allocatedSize;
 	}
 
+	/*!
+	* \brief Gets the number of allocations
+	* \return Number of allocations
+	*/
+
 	unsigned int MemoryManager::GetAllocationCount()
 	{
 		return s_allocationCount;
 	}
 
+	/*!
+	* \brief Checks whether the filling of allocation is enabled
+	* \return true if it is filling
+	*/
+
 	bool MemoryManager::IsAllocationFillingEnabled()
 	{
 		return s_allocationFilling;
 	}
 
+	/*!
+	* \brief Checks whether the logging of allocation is enabled
+	* \return true if it is logging
+	*/
+
 	bool MemoryManager::IsAllocationLoggingEnabled()
 	{
 		return s_allocationLogging;
 	}
 
+	/*!
+	* \brief Sets the next free
+	*
+	* \param file Name of the file
+	* \param line Line in the file
+	*/
+
 	void MemoryManager::NextFree(const char* file, unsigned int line)
 	{
 		s_nextFreeFile = file;
 		s_nextFreeLine = line;
 	}
 
+	/*!
+	* \brief Initializes the MemoryManager
+	*/
+
 	void MemoryManager::Initialize()
 	{
 		char timeStr[23];
@@ -282,12 +364,22 @@ namespace Nz
 		s_initialized = true;
 	}
 
+	/*!
+	* \brief Gets the time
+	*
+	* \param buffer Buffer to set the time in
+	*/
+
 	void MemoryManager::TimeInfo(char buffer[23])
 	{
 		time_t currentTime = std::time(nullptr);
 		std::strftime(buffer, 23, "%d/%m/%Y - %H:%M:%S:", std::localtime(&currentTime));
 	}
 
+	/*!
+	* \brief Uninitializes the MemoryManager
+	*/
+
 	void MemoryManager::Uninitialize()
 	{
 		#ifdef NAZARA_PLATFORM_WINDOWS

src/Nazara/Core/MemoryStream.cpp

@@ -10,33 +10,75 @@
 
 namespace Nz
 {
+	/*!
+	* \class Nz::MemoryStream
+	* \brief Core class that represents a stream of memory
+	*/
+
+	/*!
+	* \brief Clears the content of the stream
+	*/
+
 	void MemoryStream::Clear()
 	{
 		m_buffer->Clear();
 		m_pos = 0;
 	}
 
+	/*!
+	* \brief Checks whether the stream reached the end of the stream
+	* \return true if cursor is at the end of the stream
+	*/
+
 	bool MemoryStream::EndOfStream() const
 	{
 		return m_pos >= m_buffer->size();
 	}
 
+	/*!
+	* \brief Gets the position of the cursor
+	* \return Position of the cursor
+	*/
+
 	UInt64 MemoryStream::GetCursorPos() const
 	{
 		return m_pos;
 	}
 
+	/*!
+	* \brief Gets the size of the raw memory
+	* \return Size of the memory
+	*/
+
 	UInt64 MemoryStream::GetSize() const
 	{
 		return m_buffer->GetSize();
 	}
 
+	/*!
+	* \brief Sets the buffer for the memory stream
+	*
+	* \param byteArray Bytes to stream
+	* \param openMode Reading/writing mode for the stream
+	*
+	* \remark Produces a NazaraAssert if byteArray is nullptr
+	*/
+
 	void MemoryStream::SetBuffer(ByteArray* byteArray, UInt32 openMode)
 	{
+		NazaraAssert(byteArray, "Invalid ByteArray");
+
 		m_buffer = byteArray;
 		m_openMode = openMode;
 	}
 
+	/*!
+	* \brief Sets the position of the cursor
+	* \return true
+	*
+	* \param offset Offset according to the beginning of the stream
+	*/
+
 	bool MemoryStream::SetCursorPos(UInt64 offset)
 	{
 		m_pos = offset;
@@ -44,11 +86,23 @@ namespace Nz
 		return true;
 	}
 
+	/*!
+	* \brief Flushes the stream
+	*/
+
 	void MemoryStream::FlushStream()
 	{
 		// Nothing to flush
 	}
 
+	/*!
+	* \brief Reads blocks
+	* \return Number of blocks read
+	*
+	* \param buffer Preallocated buffer to contain information read
+	* \param size Size of the read and thus of the buffer
+	*/
+
 	std::size_t MemoryStream::ReadBlock(void* buffer, std::size_t size)
 	{
 		if (EndOfStream())
@@ -63,12 +117,24 @@ namespace Nz
 		return readSize;
 	}
 
+	/*!
+	* \brief Writes blocks
+	* \return Number of blocks written
+	*
+	* \param buffer Preallocated buffer containing information to write
+	* \param size Size of the writting and thus of the buffer
+	*
+	* \remark Produces a NazaraAssert if buffer is nullptr
+	*/
+
 	std::size_t MemoryStream::WriteBlock(const void* buffer, std::size_t size)
 	{
 		std::size_t endPos = static_cast<std::size_t>(m_pos + size);
 		if (endPos > m_buffer->GetSize())
 			m_buffer->Resize(endPos);
 
+		NazaraAssert(buffer, "Invalid buffer");
+
 		std::memcpy(m_buffer->GetBuffer() + m_pos, buffer, size);
 
 		m_pos = endPos;

src/Nazara/Core/MemoryView.cpp

@@ -9,6 +9,20 @@
 
 namespace Nz
 {
+	/*!
+	* \class Nz::MemoryView
+	* \brief Core class that represents a view of the memory behaving like a stream
+	*/
+
+	/*!
+	* \brief Constructs a MemoryView object with a raw memory and a size
+	*
+	* \param ptr Pointer to raw memory
+	* \param size Size that can be read
+	*
+	* \remark If preallocated space of ptr is less than the size, the behaviour is undefined
+	*/
+
 	MemoryView::MemoryView(void* ptr, UInt64 size) :
 	Stream(StreamOption_None, OpenMode_ReadWrite),
 	m_ptr(reinterpret_cast<UInt8*>(ptr)), 
@@ -17,6 +31,15 @@ namespace Nz
 	{
 	}
 
+	/*!
+	* \brief Constructs a MemoryView object with a raw memory and a size
+	*
+	* \param ptr Constant pointer to raw memory
+	* \param size Size that can be read
+	*
+	* \remark If preallocated space of ptr is less than the size, the behaviour is undefined
+	*/
+
 	MemoryView::MemoryView(const void* ptr, UInt64 size) :
 	Stream(StreamOption_None, OpenMode_ReadOnly),
 	m_ptr(reinterpret_cast<UInt8*>(const_cast<void*>(ptr))), //< Okay, right, const_cast is bad, but this pointer is still read-only
@@ -25,21 +48,43 @@ namespace Nz
 	{
 	}
 
+	/*!
+	* \brief Checks whether the stream reached the end of the stream
+	* \return true if cursor is at the end of the stream
+	*/
+
 	bool MemoryView::EndOfStream() const
 	{
 		return m_pos >= m_size;
 	}
 
+	/*!
+	* \brief Gets the position of the cursor
+	* \return Position of the cursor
+	*/
+
 	UInt64 MemoryView::GetCursorPos() const
 	{
 		return m_pos;
 	}
 
+	/*!
+	* \brief Gets the size of the raw memory
+	* \return Size of the memory
+	*/
+
 	UInt64 MemoryView::GetSize() const
 	{
 		return m_size;
 	}
 
+	/*!
+	* \brief Sets the position of the cursor
+	* \return true
+	*
+	* \param offset Offset according to the beginning of the stream
+	*/
+
 	bool MemoryView::SetCursorPos(UInt64 offset)
 	{
 		m_pos = std::min(offset, m_size);
@@ -47,11 +92,23 @@ namespace Nz
 		return true;
 	}
 
+	/*!
+	* \brief Flushes the stream
+	*/
+
 	void MemoryView::FlushStream()
 	{
 		// Nothing to do
 	}
 
+	/*!
+	* \brief Reads blocks
+	* \return Number of blocks read
+	*
+	* \param buffer Preallocated buffer to contain information read
+	* \param size Size of the read and thus of the buffer
+	*/
+
 	std::size_t MemoryView::ReadBlock(void* buffer, std::size_t size)
 	{
 		std::size_t readSize = std::min<std::size_t>(size, static_cast<std::size_t>(m_size - m_pos));
@@ -63,12 +120,24 @@ namespace Nz
 		return readSize;
 	}
 
+	/*!
+	* \brief Writes blocks
+	* \return Number of blocks written
+	*
+	* \param buffer Preallocated buffer containing information to write
+	* \param size Size of the writting and thus of the buffer
+	*
+	* \remark Produces a NazaraAssert if buffer is nullptr
+	*/
+
 	std::size_t MemoryView::WriteBlock(const void* buffer, std::size_t size)
 	{
 		std::size_t endPos = static_cast<std::size_t>(m_pos + size);
 		if (endPos > m_size)
 			size = m_size - m_pos;
 
+		NazaraAssert(buffer, "Invalid buffer");
+
 		std::memcpy(&m_ptr[m_pos], buffer, size);
 
 		m_pos += size;