1 /*==========================================================================
2 SeqAn - The Library for Sequence Analysis
4 ============================================================================
7 This library is free software; you can redistribute it and/or
8 modify it under the terms of the GNU Lesser General Public
9 License as published by the Free Software Foundation; either
10 version 3 of the License, or (at your option) any later version.
12 This library is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 Lesser General Public License for more details.
17 ============================================================================
18 $Id: basic_allocator_interface.h,v 1.1 2008/08/25 16:20:02 langmead Exp $
19 ==========================================================================*/
21 #ifndef SEQAN_HEADER_BASIC_ALLOCATOR_INTERFACE_H
22 #define SEQAN_HEADER_BASIC_ALLOCATOR_INTERFACE_H
24 namespace SEQAN_NAMESPACE_MAIN
26 //////////////////////////////////////////////////////////////////////////////
28 //////////////////////////////////////////////////////////////////////////////
34 ..summary:Manager for allocated memory.
35 ..signature:Allocator<TSpec>
36 ..param.TSpec:The specializing type.
37 ...metafunction:Metafunction.Spec
38 ..implements:Concept.Allocator
40 ..remarks:There are two reasons for using non-trivial allocators:
41 ...text:1. Allocators support the function @Function.Allocator#clear@ for a fast deallocation of all
42 allocated memory blocks.
43 ...text:2. Some allocators are faster in allocating an deallocating memory.
44 Pool allocators like e.g. @Spec.Single Pool Allocator@ or @Spec.Multi Pool Allocator@
45 speed up @Function.allocate@, @Function.deallocate@, and @Function.Allocator#clear@ for
49 template <typename TSpec>
52 ///.Function.allocate.param.object.type:Class.Allocator
53 ///.Function.deallocate.param.object.type:Class.Allocator
56 //////////////////////////////////////////////////////////////////////////////
58 //////////////////////////////////////////////////////////////////////////////
60 //.Metafunction.Spec.param.T.type:Class.Allocator
62 template <typename TSpec>
63 struct Spec<Allocator<TSpec> >
69 //////////////////////////////////////////////////////////////////////////////
72 ..summary:The purpose of an allocated memory block.
73 ..tag.TagAllocateTemp:Temporary memory.
74 ..tag.TagAllocateStorage:Memory for storing container content.
75 ..see:Function.allocate
76 ..see:Function.deallocate
78 struct TagAllocateUnspecified_; //< usage not specified
79 typedef Tag<TagAllocateUnspecified_> const TagAllocateUnspecified;
81 struct TagAllocateTemp_; //< allocate temporary memory
82 typedef Tag<TagAllocateTemp_> const TagAllocateTemp;
84 struct TagAllocateStorage_; //< allocate memory for storing member data
85 typedef Tag<TagAllocateStorage_> const TagAllocateStorage;
88 //////////////////////////////////////////////////////////////////////////////
89 //allocates memory on heap. No c'tors are called.
90 //////////////////////////////////////////////////////////////////////////////
95 ..summary:Allocates memory from heap.
96 ..signature:allocate(object, data, count [, usage_tag])
97 ..param.object:Allocator object.
98 ...remarks:$object$ is conceptually the "owner" of the allocated memory.
99 Objects of all types can be used as allocators. If no special behavior is implemented,
100 default functions allocation/deallocation are applied that uses standard
101 $new$ and $delete$ operators.
102 ..param.count:Number of items that could be stored in the allocated memory.
103 ...text:The type of the allocated items is given by the type of $data$.
104 ..param.usage_tag:A tag the specifies the purpose for the allocated memory.
105 ...value:@Tag.Allocator Usage@
106 ..returns.param.data:Pointer to allocated memory.
107 ...remarks:The value of this pointer is overwritten by the function.
109 ...text:The function allocates at least $count*sizeof(data)$ bytes.
110 The allocated memory is large enough
111 to hold $count$ objects of type $T$, where $T *$ is type of $data$.
112 ...note:These objects are not constructed by $allocate$.
113 ...text:Use e.g. one of the functions @Function.valueConstruct@, @Function.arrayConstruct@, @Function.arrayConstructCopy@ or @Function.arrayFill@
114 to construct the objects.
115 A $new$ operator which is part of the C++ standard (defined in $<new>$)
116 can also be used to construct objects at a given memory address.
117 ..note:All allocated memory blocks should be deallocated by the corresponding function @Function.deallocate@.
118 ..see:Function.deallocate
119 ..see:Function.valueConstruct
120 ..see:Function.arrayFill
121 ..see:Function.arrayConstruct
122 ..see:Function.arrayConstructCopy
124 template <typename T, typename TValue, typename TSize>
126 allocate(T const & me,
130 allocate(me, data, count, TagAllocateUnspecified());
132 template <typename T, typename TValue, typename TSize>
138 allocate(me, data, count, TagAllocateUnspecified());
141 template <typename T, typename TValue, typename TSize, typename TUsage>
148 data = (TValue *) operator new(count * sizeof(TValue));
150 SEQAN_PROADD(SEQAN_PROMEMORY, count * sizeof(TValue));
152 template <typename T, typename TValue, typename TSize, typename TUsage>
159 data = (TValue *) operator new(count * sizeof(TValue));
161 SEQAN_PROADD(SEQAN_PROMEMORY, count * sizeof(TValue));
165 //////////////////////////////////////////////////////////////////////////////
166 //deallocates memory that was allocates using allocate(.)
169 .Function.deallocate:
171 ..summary:Deallocates memory.
172 ..signature:deallocate(object, data, count [, usage_tag])
173 ..param.object:Allocator object.
174 ...remarks:$object$ is conceptually the "owner" of the allocated memory.
175 Objects of all types can be used as allocators. If no special behavior is implemented,
176 default functions allocation/deallocation are applied that uses standard
177 $new$ and $delete$ operators.
178 ..param.data:Pointer to allocated memory that was allocated by $allocate$.
179 ..param.count:Number of items that could be stored in the allocated memory.
180 ..param.usage_tag:A tag the specifies the purpose for the allocated memory.
181 ...value:@Tag.Allocator Usage@
183 ...text:The values for $object$, $count$ and $usage_tag$ should be the same that was
184 used when $allocate$ was called. The value of $data$ should be the same that was
185 returned by $allocate$.
186 ...note:$deallocate$ does not destruct objects.
187 ...text:Use e.g. one of the functions @Function.valueDestruct@ or @Function.arrayDestruct@ to destruct the objects.
188 $delete$ and $delete []$ operators which are part of the C++ standard (defined in $<new>$)
189 can also be used to destruct objects at a given memory address.
190 ..see:Function.valueDestruct
191 ..see:Function.arrayDestruct
193 template <typename T, typename TValue, typename TSize>
195 deallocate(T const & me,
199 deallocate(me, data, count, TagAllocateUnspecified());
201 template <typename T, typename TValue, typename TSize>
207 deallocate(me, data, count, TagAllocateUnspecified());
210 template <typename T, typename TValue, typename TSize, typename TUsage>
212 deallocate(T const & /*me*/,
217 if (data && count) // .. to use count if SEQAN_PROFILE is not defined
218 SEQAN_PROSUB(SEQAN_PROMEMORY, count * sizeof(TValue));
219 operator delete ((void *) data);
221 template <typename T, typename TValue, typename TSize, typename TUsage>
223 deallocate(T & /*me*/,
228 if (data && count) // .. to use count if SEQAN_PROFILE is not defined
229 SEQAN_PROSUB(SEQAN_PROMEMORY, count * sizeof(TValue));
230 operator delete ((void *) data);
232 //////////////////////////////////////////////////////////////////////////////
234 } //namespace SEQAN_NAMESPACE_MAIN
236 #endif //#ifndef SEQAN_HEADER_...