Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: code/branches/tutorial3/src/libraries/util/SmallObjectAllocator.h @ 10904

Last change on this file since 10904 was 7401, checked in by landauf, 14 years ago

merged doc branch back to trunk

  • Property svn:eol-style set to native
File size: 4.3 KB
Line 
1/*
2 *   ORXONOX - the hottest 3D action shooter ever to exist
3 *                    > www.orxonox.net <
4 *
5 *
6 *   License notice:
7 *
8 *   This program is free software; you can redistribute it and/or
9 *   modify it under the terms of the GNU General Public License
10 *   as published by the Free Software Foundation; either version 2
11 *   of the License, or (at your option) any later version.
12 *
13 *   This program is distributed in the hope that it will be useful,
14 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
15 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16 *   GNU General Public License for more details.
17 *
18 *   You should have received a copy of the GNU General Public License
19 *   along with this program; if not, write to the Free Software
20 *   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
21 *
22 *   Author:
23 *      Fabian 'x3n' Landau
24 *   Co-authors:
25 *      ...
26 *
27 */
28
29/**
30    @defgroup SmallObjectAllocator SmallObjectAllocator
31    @ingroup Util
32*/
33
34/**
35    @file
36    @ingroup SmallObjectAllocator
37    @brief Declaration of SmallObjectAllocator
38
39    @anchor SmallObjectAllocatorExample
40
41    The default implementations of new and delete are designed to work with objects of
42    arbitrary size. They are thus not optimal for small objects.
43    @ref orxonox::SmallObjectAllocator "SmallObjectAllocator" allocates a large memory
44    block and divides it into small chunks. These chunks are returned by the function
45    @ref orxonox::SmallObjectAllocator::alloc() "alloc()" and can be used to create a
46    new object using the placement new operator. Instead of delete, the function
47    @ref orxonox::SmallObjectAllocator::free() "free()" is used to give the memory
48    back to SmallObjectAllocator.
49
50    Example:
51    @code
52    SmallObjectAllocator allocator(sizeof(MySmallObject));  // Create an allocator. The size of the memory chunks must equal the size of the desired class
53
54    void* chunk = allocator.alloc();                        // Allocate a memory chunk
55    MySmallObject* object = new (chunk) MySmallObject();    // Call the placement new operator
56
57    object->someFunction();                                 // Do something with the object
58
59    object->~MySmallObject();                               // Call the destructor
60    allocator.free(object);                                 // Free the allocated memory
61    @endcode
62
63    @b Important: You have to call the destructor of the object manually, because this
64    is not automatically done by the allocator nor free().
65
66    @note The destructor can be ignored if it is empty or not implemented. This saves
67    another amount of time.
68
69    @remarks For a distributed usage of SmallObjectAllocator it may be a good idea to
70    create a static function that returns an instance to it. The allocator then works
71    like a singleton and can be accesses from everywhere.
72*/
73
74#ifndef _SmallObjectAllocator_H__
75#define _SmallObjectAllocator_H__
76
77#include "UtilPrereqs.h"
78#include <vector>
79
80namespace orxonox
81{
82    /**
83        @brief This class is used to allocate and free small objects (usually not polymorphic).
84
85        SmallObjectAllocator provides a fast alternative to new and delete for small objects.
86
87        @see See @ref SmallObjectAllocatorExample "this description" for more information and an example.
88    */
89    class _UtilExport SmallObjectAllocator
90    {
91        /// The memory chunk is at the same time an element of a single linked list.
92        struct Chunk
93        {
94            Chunk* next_;   ///< A pointer to the next chunk in the list
95        };
96
97        public:
98            SmallObjectAllocator(size_t objectSize, size_t numObjects = 64);
99            ~SmallObjectAllocator();
100
101            void* alloc();
102            void free(void* chunk);
103
104        private:
105            static void setNext(void* chunk, void* next);
106            static void* getNext(void* chunk);
107
108            void* first_;                   ///< A pointer to the first free memory chunk
109            size_t chunkSize_;              ///< The size of each chunk (and usually also the size of the created objects)
110            size_t numChunksPerBlock_;      ///< The number of chunks per memory block
111
112            std::vector<char*> blocks_;     ///< A list of all allocated memory blocks (used to destroy them again)
113    };
114}
115
116#endif /* _SmallObjectAllocator_H__ */
Note: See TracBrowser for help on using the repository browser.