Refactoring and comments

include/anki/util/Allocator.h

@@ -260,6 +260,9 @@ private:
 	TPool mpool;
 };
 
+/// @name GenericPoolAllocator global functions
+/// @{
+
 /// Another allocator of the same type can deallocate from this one
 template<typename T1, typename T2, typename TPool, Bool deallocationFlag>
 inline bool operator==(
@@ -298,6 +301,8 @@ inline bool operator!=(
 	return true;
 }
 
+/// @}
+
 /// Heap based allocator. The default allocator. It uses malloc and free for 
 /// allocations/deallocations
 template<typename T>

include/anki/util/Exception.h

@@ -31,7 +31,7 @@ public:
 	~Exception() throw()
 	{}
 
-	/// For re-throws
+	/// For re-throws.
 	/// Usage:
 	/// @code
 	/// catch(std::exception& e) {

include/anki/util/File.h

@@ -116,7 +116,7 @@ public:
 	/// Write data to the file
 	void write(void* buff, PtrSize size);
 
-	/// Write text
+	/// Write formated text
 	void writeText(const char* format, ...);
 	/// @}
 
@@ -139,7 +139,7 @@ public:
 	/// @}
 
 private:
-	void* file; ///< A native type
+	void* file; ///< A native file type
 	U16 flags; ///< All the flags. Initialy zero and set on open
 
 	/// Get the current machine's endianness

include/anki/util/Memory.h

@@ -22,11 +22,13 @@ void freeAligned(void* ptr) throw();
 class HeapMemoryPool
 {
 public:
+	/// Allocate memory
 	static void* allocate(PtrSize size, PtrSize alignment) throw()
 	{
 		return mallocAligned(size, alignment);
 	}
 
+	/// Free memory
 	static Bool free(void* ptr) throw()
 	{
 		freeAligned(ptr);
@@ -53,7 +55,10 @@ public:
 	}
 
 	/// Constructor with parameters
-	StackMemoryPool(PtrSize size, U32 alignmentBytes = ANKI_SAFE_ALIGNMENT);
+	/// @param size The size of the pool
+	/// @param alignmentBytes The maximum supported alignment for returned
+	///                       memory
+	StackMemoryPool(PtrSize size, PtrSize alignmentBytes = ANKI_SAFE_ALIGNMENT);
 
 	/// Destroy
 	~StackMemoryPool();
@@ -66,19 +71,15 @@ public:
 		return *this;
 	}
 
-	/// Access the total size
-	PtrSize getTotalSize() const;
-
-	/// Get the allocated size
-	PtrSize getAllocatedSize() const;
-
-	/// Allocate memory
+	/// Allocate aligned memory. The operation is thread safe
+	/// @param size The size to allocate
+	/// @param alignmentBytes The alignment of the returned address
 	/// @return The allocated memory or nullptr on failure
 	void* allocate(PtrSize size, PtrSize alignmentBytes) throw();
 
 	/// Free memory in StackMemoryPool. If the ptr is not the last allocation
-	/// then nothing happens and the method returns false
-	///
+	/// then nothing happens and the method returns false. The operation is
+	/// threadsafe
 	/// @param[in, out] ptr Memory block to deallocate
 	/// @return True if the deallocation actually happened and false otherwise
 	Bool free(void* ptr) throw();
@@ -86,6 +87,12 @@ public:
 	/// Reinit the pool. All existing allocated memory will be lost
 	void reset();
 
+	/// Get the total size
+	PtrSize getTotalSize() const;
+
+	/// Get the allocated size
+	PtrSize getAllocatedSize() const;
+
 private:
 	// Forward. Hide the implementation because Memory.h is the base of other
 	// files and should not include them
@@ -100,8 +107,9 @@ private:
 class ChainMemoryPool
 {
 public:
-	/// Chunk allocation method. Defines the size a newely created has chunk 
-	/// compared to the last created
+	/// Chunk allocation method. Defines the size a newely created chunk should
+	/// have compared to the last created. Used to grow chunks over the time of
+	/// allocations
 	enum ChunkAllocationStepMethod
 	{
 		FIXED, ///< All chunks have the same size
@@ -121,13 +129,14 @@ public:
 	/// @param chunkAllocStepMethod How new chunks grow compared to the old ones
 	/// @param chunkAllocStep Used along with chunkAllocStepMethod and defines
 	///                       the ammount of chunk size increase 
-	/// @param alignmentBytes The standard alignment of the allocations
+	/// @param alignmentBytes The maximum supported alignment for returned
+	///                       memory
 	ChainMemoryPool(
-		U32 initialChunkSize,
-		U32 maxChunkSize,
+		PtrSize initialChunkSize,
+		PtrSize maxChunkSize,
 		ChunkAllocationStepMethod chunkAllocStepMethod = MULTIPLY, 
-		U32 chunkAllocStep = 2, 
-		U32 alignmentBytes = ANKI_SAFE_ALIGNMENT);
+		PtrSize chunkAllocStep = 2, 
+		PtrSize alignmentBytes = ANKI_SAFE_ALIGNMENT);
 
 	/// Destroy
 	~ChainMemoryPool();
@@ -141,12 +150,13 @@ public:
 	}
 
 	/// Allocate memory. This operation is thread safe
+	/// @param size The size to allocate
+	/// @param alignmentBytes The alignment of the returned address
 	/// @return The allocated memory or nullptr on failure
 	void* allocate(PtrSize size, PtrSize alignmentBytes) throw();
 
 	/// Free memory. If the ptr is not the last allocation of the chunk
 	/// then nothing happens and the method returns false
-	///
 	/// @param[in, out] ptr Memory block to deallocate
 	/// @return True if the deallocation actually happened and false otherwise
 	Bool free(void* ptr) throw();

include/anki/util/StdTypes.h

@@ -10,19 +10,22 @@ namespace anki {
 
 /// @addtogroup util
 /// @{
-typedef int8_t I8;
+/// @addtogroup misc
+/// @{
+
+typedef int8_t I8; ///< Integer 8bit
 const I8 MAX_I8 = std::numeric_limits<I8>::max();
 const I8 MIN_I8 = std::numeric_limits<I8>::min();
 
-typedef int16_t I16;
+typedef int16_t I16; ///< Integer 16bit
 const I16 MAX_I16 = std::numeric_limits<I16>::max();
 const I16 MIN_I16 = std::numeric_limits<I16>::min();
 
-typedef int32_t I32;
+typedef int32_t I32; ///< Integer 32bit
 const I32 MAX_I32 = std::numeric_limits<I32>::max();
 const I32 MIN_I32 = std::numeric_limits<I32>::min();
 
-typedef int64_t I64;
+typedef int64_t I64; ///< Integer 64bit
 const I64 MAX_I64 = std::numeric_limits<I64>::max();
 const I64 MIN_I64 = std::numeric_limits<I64>::min();
 
@@ -30,23 +33,23 @@ typedef int_fast32_t I; ///< Fast signed integer at least 32bit
 const I MAX_I = std::numeric_limits<I>::max();
 const I MIN_I = std::numeric_limits<I>::min();
 
-typedef uint8_t U8;
+typedef uint8_t U8; ///< Unsigned integer 8bit
 const U8 MAX_U8 = std::numeric_limits<U8>::max();
 const U8 MIN_U8 = std::numeric_limits<U8>::min();
 
-typedef uint16_t U16;
+typedef uint16_t U16; ///< Unsigned integer 16bit
 const U16 MAX_U16 = std::numeric_limits<U16>::max();
 const U16 MIN_U16 = std::numeric_limits<U16>::min();
 
-typedef uint32_t U32;
+typedef uint32_t U32; ///< Unsigned integer 32bit
 const U32 MAX_U32 = std::numeric_limits<U32>::max();
 const U32 MIN_U32 = std::numeric_limits<U32>::min();
 
-typedef uint64_t U64;
+typedef uint64_t U64; ///< Unsigned integer 64bit
 const U64 MAX_U64 = std::numeric_limits<U64>::max();
 const U64 MIN_U64 = std::numeric_limits<U64>::min();
 
-typedef uint_fast32_t U; ///< fast unsigned integer at least 32bit
+typedef uint_fast32_t U; ///< Fast unsigned integer at least 32bit
 const U MAX_U = std::numeric_limits<U>::max();
 const U MIN_U = std::numeric_limits<U>::min();
 
@@ -54,16 +57,18 @@ typedef size_t PtrSize; ///< Like size_t
 const PtrSize MAX_PTR_SIZE = std::numeric_limits<PtrSize>::max();
 const PtrSize MIN_PTR_SIZE = std::numeric_limits<PtrSize>::min();
 
-typedef float F32;
+typedef float F32; ///< Floating point 32bit
 const F32 MAX_F32 = std::numeric_limits<F32>::max();
 const F32 MIN_F32 = -std::numeric_limits<F32>::max();
 
-typedef double F64;
+typedef double F64; ///< Floating point 64bit
 const F64 MAX_F64 = std::numeric_limits<F64>::max();
 const F64 MIN_F64 = -std::numeric_limits<F64>::max();
 
-typedef bool Bool;
-typedef U8 Bool8;
+typedef bool Bool; ///< Fast boolean type
+typedef U8 Bool8; ///< Small 8bit boolean type
+
+/// @}
 /// @}
 
 } // end namespace anki

src/util/Memory.cpp

@@ -70,22 +70,24 @@ void freeAligned(void* ptr) throw()
 //==============================================================================
 
 //==============================================================================
+/// The hidden implementation of StackMemoryPool
 class StackMemoryPool::Implementation: public NonCopyable
 {
 public:
 	/// The header of each allocation
 	struct MemoryBlockHeader
 	{
-		U8 size[4]; ///< It's U8 to allow whatever alignment
+		U8 size[sizeof(U32)]; ///< It's U8 to allow whatever alignment
 	};
 
 	static_assert(alignof(MemoryBlockHeader) == 1, "Alignment error");
+	static_assert(sizeof(MemoryBlockHeader) == sizeof(U32), "Size error");
 
 	/// Alignment of allocations
-	U32 alignmentBytes;
+	PtrSize alignmentBytes;
 
 	/// Aligned size of MemoryBlockHeader
-	U32 headerSize;
+	PtrSize headerSize;
 
 	/// Pre-allocated memory chunk
 	U8* memory = nullptr;
@@ -97,7 +99,7 @@ public:
 	std::atomic<U8*> top = {nullptr};
 
 	// Construct
-	Implementation(PtrSize size, U32 alignmentBytes_)
+	Implementation(PtrSize size, PtrSize alignmentBytes_)
 		:	alignmentBytes(alignmentBytes_), 
 			memsize(getAlignedRoundUp(alignmentBytes, size))
 	{
@@ -107,6 +109,11 @@ public:
 
 		if(memory != nullptr)
 		{
+#if ANKI_DEBUG
+			// Invalidate the memory
+			memset(memory, 0xCC, memsize);
+#endif
+
 			// Align allocated memory
 			top = memory;
 
@@ -161,6 +168,11 @@ public:
 
 		if(out + size <= memory + memsize)
 		{
+#if ANKI_DEBUG
+			// Invalidate the block
+			memset(out, 0xCC, size);
+#endif
+
 			// Write the block header
 			MemoryBlockHeader* header = (MemoryBlockHeader*)out;
 			U32 size32 = size;
@@ -237,7 +249,7 @@ public:
 };
 
 //==============================================================================
-StackMemoryPool::StackMemoryPool(PtrSize size, U32 alignmentBytes)
+StackMemoryPool::StackMemoryPool(PtrSize size, PtrSize alignmentBytes)
 {
 	impl.reset(new Implementation(size, alignmentBytes));
 }
@@ -286,6 +298,7 @@ void StackMemoryPool::reset()
 //==============================================================================
 
 //==============================================================================
+/// The hidden implementation of ChainMemoryPool
 class ChainMemoryPool::Implementation: public NonCopyable
 {
 public:
@@ -294,15 +307,15 @@ public:
 	{
 	public:
 		StackMemoryPool::Implementation pool;
-		U32 allocationsCount;
+		U32 allocationsCount; ///< Used to identify if the chunk can be deleted
 
-		Chunk(PtrSize size, U32 alignmentBytes)
+		Chunk(PtrSize size, PtrSize alignmentBytes)
 			: pool(size, alignmentBytes), allocationsCount(0)
 		{}
 	};
 
 	/// Alignment of allocations
-	U32 alignmentBytes;
+	PtrSize alignmentBytes;
 
 	/// A list of chunks
 	Vector<Chunk*> chunks;
@@ -314,10 +327,10 @@ public:
 	SpinLock lock;
 
 	/// Chunk first chunk size
-	U32 initSize;
+	PtrSize initSize;
 
 	/// Chunk max size
-	U32 maxSize;
+	PtrSize maxSize;
 
 	/// Chunk allocation method value
 	U32 step;
@@ -327,15 +340,15 @@ public:
 
 	/// Construct
 	Implementation(
-		U32 initialChunkSize,
-		U32 maxChunkSize,
+		PtrSize initialChunkSize,
+		PtrSize maxChunkSize,
 		ChunkAllocationStepMethod chunkAllocStepMethod, 
-		U32 chunkAllocStep, 
-		U32 alignmentBytes_)
+		PtrSize chunkAllocStep, 
+		PtrSize alignmentBytes_)
 		:	alignmentBytes(alignmentBytes_), 
 			initSize(initialChunkSize),
 			maxSize(maxChunkSize),
-			step(chunkAllocStep),
+			step((U32)chunkAllocStep),
 			method(chunkAllocStepMethod)
 	{
 		// Initial size should be > 0
@@ -542,11 +555,11 @@ public:
 
 //==============================================================================
 ChainMemoryPool::ChainMemoryPool(
-	U32 initialChunkSize,
-	U32 maxChunkSize,
+	PtrSize initialChunkSize,
+	PtrSize maxChunkSize,
 	ChunkAllocationStepMethod chunkAllocStepMethod, 
-	U32 chunkAllocStep, 
-	U32 alignmentBytes)
+	PtrSize chunkAllocStep, 
+	PtrSize alignmentBytes)
 {
 	impl.reset(new Implementation(
 		initialChunkSize, maxChunkSize, chunkAllocStepMethod, chunkAllocStep,