Changeset 7401 for code/trunk/src/libraries/util/SmallObjectAllocator.h

Timestamp:

Sep 11, 2010, 12:34:00 AM (14 years ago)

Author:

landauf

Message:

merged doc branch back to trunk

Location:

code/trunk

Files:

• . (modified) (1 prop)
• src/libraries/util/SmallObjectAllocator.h (modified) (3 diffs)

code/trunk/src/libraries/util/SmallObjectAllocator.h

@@ -27 +27 @@
  */
 
+/**
+    @defgroup SmallObjectAllocator SmallObjectAllocator
+    @ingroup Util
+*/
+
+/**
+    @file
+    @ingroup SmallObjectAllocator
+    @brief Declaration of SmallObjectAllocator
+
+    @anchor SmallObjectAllocatorExample
+
+    The default implementations of new and delete are designed to work with objects of
+    arbitrary size. They are thus not optimal for small objects.
+    @ref orxonox::SmallObjectAllocator "SmallObjectAllocator" allocates a large memory
+    block and divides it into small chunks. These chunks are returned by the function
+    @ref orxonox::SmallObjectAllocator::alloc() "alloc()" and can be used to create a
+    new object using the placement new operator. Instead of delete, the function
+    @ref orxonox::SmallObjectAllocator::free() "free()" is used to give the memory
+    back to SmallObjectAllocator.
+
+    Example:
+    @code
+    SmallObjectAllocator allocator(sizeof(MySmallObject));  // Create an allocator. The size of the memory chunks must equal the size of the desired class
+
+    void* chunk = allocator.alloc();                        // Allocate a memory chunk
+    MySmallObject* object = new (chunk) MySmallObject();    // Call the placement new operator
+
+    object->someFunction();                                 // Do something with the object
+
+    object->~MySmallObject();                               // Call the destructor
+    allocator.free(object);                                 // Free the allocated memory
+    @endcode
+
+    @b Important: You have to call the destructor of the object manually, because this
+    is not automatically done by the allocator nor free().
+
+    @note The destructor can be ignored if it is empty or not implemented. This saves
+    another amount of time.
+
+    @remarks For a distributed usage of SmallObjectAllocator it may be a good idea to
+    create a static function that returns an instance to it. The allocator then works
+    like a singleton and can be accesses from everywhere.
+*/
+
 #ifndef _SmallObjectAllocator_H__
 #define _SmallObjectAllocator_H__
@@ -35 +80 @@
 namespace orxonox
 {
+    /**
+        @brief This class is used to allocate and free small objects (usually not polymorphic).
+
+        SmallObjectAllocator provides a fast alternative to new and delete for small objects.
+
+        @see See @ref SmallObjectAllocatorExample "this description" for more information and an example.
+    */
     class _UtilExport SmallObjectAllocator
     {
+        /// The memory chunk is at the same time an element of a single linked list.
         struct Chunk
         {
-            Chunk* next_;
+            Chunk* next_;   ///< A pointer to the next chunk in the list
         };
 
@@ -53 +106 @@
             static void* getNext(void* chunk);
 
-            void* first_;
-            size_t objectSize_;
-            size_t numObjects_;
+            void* first_;                   ///< A pointer to the first free memory chunk
+            size_t chunkSize_;              ///< The size of each chunk (and usually also the size of the created objects)
+            size_t numChunksPerBlock_;      ///< The number of chunks per memory block
 
-            std::vector<char*> blocks_;
+            std::vector<char*> blocks_;     ///< A list of all allocated memory blocks (used to destroy them again)
     };
 }