SeqAn-1.1/seqan/basic/basic_allocator_interface.h

   1  /*==========================================================================
   2                 SeqAn - The Library for Sequence Analysis
   3                           http://www.seqan.de
   4  ============================================================================
   5   Copyright (C) 2007
   6
   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.
  11
  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.
  16
  17  ============================================================================
  18   $Id: basic_allocator_interface.h,v 1.1 2008/08/25 16:20:02 langmead Exp $
  19  ==========================================================================*/
  20
  21 #ifndef SEQAN_HEADER_BASIC_ALLOCATOR_INTERFACE_H
  22 #define SEQAN_HEADER_BASIC_ALLOCATOR_INTERFACE_H
  23
  24 namespace SEQAN_NAMESPACE_MAIN
  25 {
  26 //////////////////////////////////////////////////////////////////////////////
  27 //Allocator
  28 //////////////////////////////////////////////////////////////////////////////
  29
  30
  31 /**
  32 .Class.Allocator:
  33 ..cat:Basic
  34 ..summary:Manager for allocated memory.
  35 ..signature:Allocator<TSpec>
  36 ..param.TSpec:The specializing type.
  37 ...metafunction:Metafunction.Spec
  38 ..implements:Concept.Allocator
  39 ..include:basic.h
  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
  46 pooled memory blocks.
  47 */
  48
  49 template <typename TSpec>
  50 struct Allocator;
  51
  52 ///.Function.allocate.param.object.type:Class.Allocator
  53 ///.Function.deallocate.param.object.type:Class.Allocator
  54
  55
  56 //////////////////////////////////////////////////////////////////////////////
  57 // Metafunctions
  58 //////////////////////////////////////////////////////////////////////////////
  59
  60 //.Metafunction.Spec.param.T.type:Class.Allocator
  61
  62 template <typename TSpec>
  63 struct Spec<Allocator<TSpec> >
  64 {
  65         typedef TSpec Type;
  66 };
  67
  68
  69 //////////////////////////////////////////////////////////////////////////////
  70 /**
  71 .Tag.Allocator Usage:
  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
  77 */
  78 struct TagAllocateUnspecified_; //< usage not specified
  79 typedef Tag<TagAllocateUnspecified_> const TagAllocateUnspecified;
  80
  81 struct TagAllocateTemp_; //< allocate temporary memory
  82 typedef Tag<TagAllocateTemp_> const TagAllocateTemp;
  83
  84 struct TagAllocateStorage_; //< allocate memory for storing member data
  85 typedef Tag<TagAllocateStorage_> const TagAllocateStorage;
  86
  87
  88 //////////////////////////////////////////////////////////////////////////////
  89 //allocates memory on heap. No c'tors are called.
  90 //////////////////////////////////////////////////////////////////////////////
  91
  92 /**
  93 .Function.allocate:
  94 ..cat:Memory
  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.
 108 ..remarks:
 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
 123 */
 124 template <typename T, typename TValue, typename TSize>
 125 inline void
 126 allocate(T const & me,
 127                  TValue * & data,
 128                  TSize count)
 129 {
 130         allocate(me, data, count, TagAllocateUnspecified());
 131 }
 132 template <typename T, typename TValue, typename TSize>
 133 inline void
 134 allocate(T & me,
 135                  TValue * & data,
 136                  TSize count)
 137 {
 138         allocate(me, data, count, TagAllocateUnspecified());
 139 }
 140
 141 template <typename T, typename TValue, typename TSize, typename TUsage>
 142 inline void
 143 allocate(T const &,
 144                  TValue * & data,
 145                  TSize count,
 146                  Tag<TUsage> const)
 147 {
 148         data = (TValue *) operator new(count * sizeof(TValue));
 149         if (data)
 150             SEQAN_PROADD(SEQAN_PROMEMORY, count * sizeof(TValue));
 151 }
 152 template <typename T, typename TValue, typename TSize, typename TUsage>
 153 inline void
 154 allocate(T &,
 155                  TValue * & data,
 156                  TSize count,
 157                  Tag<TUsage> const)
 158 {
 159         data = (TValue *) operator new(count * sizeof(TValue));
 160         if (data)
 161             SEQAN_PROADD(SEQAN_PROMEMORY, count * sizeof(TValue));
 162 }
 163
 164
 165 //////////////////////////////////////////////////////////////////////////////
 166 //deallocates memory that was allocates using allocate(.)
 167
 168 /**
 169 .Function.deallocate:
 170 ..cat:Memory
 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@
 182 ..remarks:
 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
 192 */
 193 template <typename T, typename TValue, typename TSize>
 194 inline void
 195 deallocate(T const & me,
 196                    TValue * data,
 197                    TSize const count)
 198 {
 199         deallocate(me, data, count, TagAllocateUnspecified());
 200 }
 201 template <typename T, typename TValue, typename TSize>
 202 inline void
 203 deallocate(T & me,
 204                    TValue * data,
 205                    TSize const count)
 206 {
 207         deallocate(me, data, count, TagAllocateUnspecified());
 208 }
 209
 210 template <typename T, typename TValue, typename TSize, typename TUsage>
 211 inline void
 212 deallocate(T const & /*me*/,
 213                    TValue * data,
 214                    TSize count,
 215                    Tag<TUsage> const)
 216 {
 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);
 220 }
 221 template <typename T, typename TValue, typename TSize, typename TUsage>
 222 inline void
 223 deallocate(T & /*me*/,
 224                    TValue * data,
 225                    TSize count,
 226                    Tag<TUsage> const)
 227 {
 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);
 231 }
 232 //////////////////////////////////////////////////////////////////////////////
 233
 234 } //namespace SEQAN_NAMESPACE_MAIN
 235
 236 #endif //#ifndef SEQAN_HEADER_...