src/NCollection/NCollection_StdAllocator.hxx

   1 // Author: Roman Lygin, 2012.
   2 // This file is in the Public Domain and thus can freely be used for any purpose.
   3 // The author disclaims any rights and liabilities.
   4
   5 #ifndef _NCollection_StdAllocator_HeaderFile
   6 #define _NCollection_StdAllocator_HeaderFile
   7
   8 #include <NCollection_BaseAllocator.hxx>
   9
  10 #if _MSC_VER
  11   //Workaround for false "unreferenced parameter" warning in destroy().
  12   #pragma warning (push)
  13   #pragma warning (disable: 4100)
  14 #endif
  15
  16 //! Implements allocator requirements as defined in ISO C++ Standard 2003, section 20.1.5.
  17 /*! The allocator uses instance of the NCollection_BaseAllocator (sub)class for memory
  18   allocation/deallocation. The allocator can be used with standard
  19   containers (std::vector, std::map, etc) to take advantage of NCollection_IncAllocator
  20   which implements memory region concept, and hence to increase performance in specific
  21   cases.
  22
  23   The underlying NCollection_BaseAllocator instance can be received using the Allocator()
  24   method.
  25
  26   Example of use:
  27   \code
  28   Handle(NCollection_IncAllocator) anIncAlloc = new NCollection_IncAllocator();
  29   NCollection_StdAllocator<TopoDS_Shape> aSAlloc (anIncAlloc);
  30   std::list<TopoDS_Shape, NCollection_StdAllocator<TopoDS_Shape> > aL (aSAlloc);
  31   TopoDS_Solid aSolid = BRepPrimAPI_MakeBox (10., 20., 30.);
  32   aL.push_back (aSolid);
  33   \endcode
  34 */
  35 template<typename T>
  36 class NCollection_StdAllocator {
  37 public:
  38   typedef T value_type;
  39   typedef value_type* pointer;
  40   typedef const value_type* const_pointer;
  41   typedef value_type& reference;
  42   typedef const value_type& const_reference;
  43   typedef size_t size_type;
  44   typedef ptrdiff_t difference_type;
  45   template<typename U> struct rebind {
  46     typedef NCollection_StdAllocator<U> other;
  47   };
  48
  49   //! Constructor.
  50   /*! Creates an object using default Open CASCADE allocation mechanism, i.e. which uses
  51     Standard::Allocate() and Standard::Free() underneath.
  52   */
  53   NCollection_StdAllocator() throw()
  54   { myAlloc = NCollection_BaseAllocator::CommonBaseAllocator(); }
  55
  56   //! Constructor.
  57   /*! Saves \a theAlloc as an underlying allocator instance.*/
  58   NCollection_StdAllocator( const Handle(NCollection_BaseAllocator)& theAlloc) throw()
  59   { myAlloc = theAlloc; }
  60
  61   //! Copy constructor.
  62   /*! Copies Allocator() from \a Y.*/
  63   template<typename U> NCollection_StdAllocator( const NCollection_StdAllocator<U>& Y) throw()
  64   { myAlloc = Y.Allocator(); }
  65
  66   //! Assignment operator
  67   template<typename U> NCollection_StdAllocator& operator= (const NCollection_StdAllocator<U>& Y) throw()
  68   { myAlloc = Y.Allocator(); return *this; }
  69
  70   //! Returns an object address.
  71   /*! Returns &x.*/
  72   pointer address( reference x ) const { return &x; }
  73
  74   //! Returns an object address.
  75   /*! Returns &x.*/
  76   const_pointer address( const_reference x ) const { return &x; }
  77
  78   //! Allocates memory for \a n objects.
  79   /*! Uses underlying allocator to allocate memory.*/
  80   pointer allocate( size_type n, const void* /*hint*/ = 0 )
  81   { return pointer( myAlloc->Allocate( n * sizeof( value_type ))); }
  82
  83   //! Frees previously allocated memory.
  84   /*! Uses underlying allocator to deallocate memory.*/
  85   void deallocate( pointer p, size_type ) { myAlloc->Free( p ); }
  86
  87   //! Returns the largest value for which method allocate might succeed.
  88   size_type max_size() const throw()
  89   {
  90     size_type aMax = static_cast<size_type>( -1 ) / sizeof( value_type );
  91     return aMax;
  92   }
  93
  94   //! Constructs an object.
  95   /*! Uses placement new operator and copy constructor to construct an object.*/
  96   void construct( pointer p, const_reference val )
  97   { new( static_cast<void*>( p )) value_type( val ); }
  98
  99   //! Destroys the object.
 100   /*! Uses object destructor.*/
 101   void destroy( pointer p ) { p->~value_type(); }
 102
 103   //! Returns an underlying NCollection_BaseAllocator instance.
 104   /*! Returns an object specified in the constructor.*/
 105   const Handle(NCollection_BaseAllocator)& Allocator() const { return myAlloc; }
 106
 107 protected:
 108   Handle(NCollection_BaseAllocator) myAlloc;
 109 };
 110
 111 #if _MSC_VER
 112   #pragma warning (pop)
 113 #endif
 114
 115
 116 //! Implements specialization NCollection_StdAllocator<void>.
 117 /*! Specialization is of low value and should normally be avoided in favor of a typed specialization.
 118
 119   Example of use:
 120   \code
 121   Handle(NCollection_IncAllocator) anIncAlloc = new NCollection_IncAllocator();
 122   NCollection_StdAllocator<void> aVAlloc (anIncAlloc);
 123   std::vector<double, NCollection_StdAllocator<double> > aV3 (aVAlloc);
 124   aV3.push_back (10.);
 125   \endcode
 126 */
 127 template<>
 128 class NCollection_StdAllocator<void> {
 129 public:
 130   typedef void* pointer;
 131   typedef const void* const_pointer;
 132   typedef void value_type;
 133   template<typename U> struct rebind {
 134     typedef NCollection_StdAllocator<U> other;
 135   };
 136
 137   //! Constructor.
 138   /*! Creates an object using default Open CASCADE allocation mechanism, i.e. which uses
 139     Standard::Allocate() and Standard::Free() underneath.
 140   */
 141   NCollection_StdAllocator() throw()
 142   { myAlloc = NCollection_BaseAllocator::CommonBaseAllocator(); }
 143
 144   //! Constructor.
 145   /*! Saves \a theAlloc as an underlying allocator instance.*/
 146   NCollection_StdAllocator( const Handle(NCollection_BaseAllocator)& theAlloc) throw()
 147   { myAlloc = theAlloc; }
 148
 149   //! Constructor.
 150   /*! Copies Allocator() from \a X.*/
 151   NCollection_StdAllocator( const NCollection_StdAllocator& X) throw() { myAlloc = X.myAlloc; }
 152
 153   //! Returns an underlying NCollection_BaseAllocator instance.
 154   /*! Returns an object specified in the constructor.*/
 155   const Handle(NCollection_BaseAllocator)& Allocator() const { return myAlloc; }
 156
 157   //! Assignment operator
 158   NCollection_StdAllocator& operator=(const NCollection_StdAllocator& X) throw()
 159   {
 160     myAlloc = X.myAlloc;
 161     return *this;
 162   }
 163
 164 protected:
 165   Handle(NCollection_BaseAllocator) myAlloc;
 166 };
 167
 168 template<typename T, typename U>
 169 inline bool operator==( const NCollection_StdAllocator<T>& X, const NCollection_StdAllocator<U>& Y)
 170 { return !!(X.Allocator() == Y.Allocator()); }
 171
 172 template<typename T, typename U>
 173 inline bool operator!=( const NCollection_StdAllocator<T>& X, const NCollection_StdAllocator<U>& Y)
 174 { return !(X == Y); }
 175
 176
 177 #endif