iLab Neuromorphic Robotics Toolkit  0.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Allocation.H
Go to the documentation of this file.
1 /*! @file
2  @author Randolph Voorhies
3  @copyright GNU Public License (GPL v3)
4  @section License
5  @verbatim
6  // ////////////////////////////////////////////////////////////////////////
7  // The iLab Neuromorphic Robotics Toolkit (NRT) //
8  // Copyright 2010-2012 by the University of Southern California (USC) //
9  // and the iLab at USC. //
10  // //
11  // iLab - University of Southern California //
12  // Hedco Neurociences Building, Room HNB-10 //
13  // Los Angeles, Ca 90089-2520 - USA //
14  // //
15  // See http://ilab.usc.edu for information about this project. //
16  // ////////////////////////////////////////////////////////////////////////
17  // This file is part of The iLab Neuromorphic Robotics Toolkit. //
18  // //
19  // The iLab Neuromorphic Robotics Toolkit is free software: you can //
20  // redistribute it and/or modify it under the terms of the GNU General //
21  // Public License as published by the Free Software Foundation, either //
22  // version 3 of the License, or (at your option) any later version. //
23  // //
24  // The iLab Neuromorphic Robotics Toolkit is distributed in the hope //
25  // that it will be useful, but WITHOUT ANY WARRANTY; without even the //
26  // implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR //
27  // PURPOSE. See the GNU General Public License for more details. //
28  // //
29  // You should have received a copy of the GNU General Public License //
30  // along with The iLab Neuromorphic Robotics Toolkit. If not, see //
31  // <http://www.gnu.org/licenses/>. //
32  // ////////////////////////////////////////////////////////////////////////
33  @endverbatim */
34 
35 
36 #ifndef INCLUDE_NRT_CORE_MEMORY_ALLOCATION_H
37 #define INCLUDE_NRT_CORE_MEMORY_ALLOCATION_H
38 
39 #include <cstddef>
40 #include <memory>
41 #include <mutex>
42 
44 
45 namespace nrt
46 {
47  /*! \defgroup memory Memory-related functions and classes
48 
49  Provides optimized memory allocation, dynamic arrays, etc
50 
51  \ingroup core */
52 
53  /*! \defgroup arrays Array classes featuring copy-on-write and ref-counting
54 
55  \ingroup memory */
56 
57  /*! \defgroup memalloc Optimized memory allocation using alignment and/or caching of memory blocks
58  \ingroup memory */
59 
60  /*! @{ */ // **********************************************************************
61 
62  //! Allocate nbytes of memory, throwing an exception in case of failure.
63  void* allocate(size_t nbytes);
64 
65  //! Deallocate the given memory region.
66  void deallocate(void* mem);
67 
68  //! Released any cached free memory blocks (e.g. to conserve memory)
70 
71  //! Turn on/off caching of memory blocks of commonly-used sizes
72  void allocation_allow_caching(bool on);
73 
74  //! Turn on/off memory-allocation debugging statements.
75  /*! If on, each nrt::allocate() and nrt::deallocate() call will print some stats about the memory block being
76  currently allocated/deallocated, as well as some general stats about the total amount of memory allocated and the
77  amount of memory currently in use */
78  void allocation_debug_print(bool print);
79 
80  //! Print current stats for whatever memory allocator is in use.
81  /*! @param verbosity If greater than 0, will request additional stats to be displayed
82 
83  @param pfx If non-null, will be printed at the beginning of each stats line.
84 
85  @param units If non-zero, allocated memory blocks will be listed as multiples of this number of bytes; otherwise
86  memory blocks will be listed as multiples of the units specified in the most recent call to
87  allocation_set_stats_units(). */
88  void allocation_show_stats(int verbosity = 0, const char* pfx = 0, const size_t units = 0);
89 
90  //! Set the units to be used by default in invt_allocation_show_stats()
91  void allocation_set_stats_units(const size_t units);
92 
93  //! A C++ STL compatible allocator using nrt::allocate
94  /*! This allocator will use the same strategy that nrt::allocate has been compiled
95  to use.
96 
97  @tparam T The data type to allocate */
98  template <class T>
99  class Allocator : public std::allocator<T>
100  {
101  public:
102  typedef typename std::allocator<T>::size_type size_type;
103  typedef typename std::allocator<T>::difference_type difference_type;
104  typedef typename std::allocator<T>::pointer pointer;
105  typedef typename std::allocator<T>::const_pointer const_pointer;
106  typedef typename std::allocator<T>::reference reference;
107  typedef typename std::allocator<T>::const_reference const_reference;
108  typedef typename std::allocator<T>::value_type value_type;
109 
110  template<class U>
111  struct rebind{ typedef Allocator<U> other; };
112 
113  Allocator() noexcept;
114 
115  Allocator( Allocator const & other ) noexcept;
116 
117  template <class U>
118  Allocator( Allocator<U> const & other ) noexcept;
119 
120  ~Allocator() noexcept;
121 
122  pointer allocate( size_type n, const void * = 0 );
123 
124  void deallocate( pointer p, size_type );
125  }; // class Allocator
126 
127  //! A c++ STL compatible allocator that always performs aligned allocation
128  /*! This differs from nrt::Allocator in that it will always perform aligned allocation
129  regardless of the settings nrt::allocate has been compiled to use. In general this will
130  often mean that this allocator does not use caching. In addition, this allocator
131  has an easier interface in the sense that NRT does not need to be recompiled when
132  the allocation boundary is changed.
133 
134  @tparam T The underlying type to allocate
135  @tparam N The size, in bytes, of the boundary to align to. Must be a power of two. */
136  template <class T, size_t N>
137  class AlignedAllocator : public std::allocator<T>
138  {
139  static_assert( ( N != 0ul ) && ( ( N & ( N - 1ul ) ) == 0ul ), "N must be a power of two!" );
140 
141  public:
142  typedef typename std::allocator<T>::size_type size_type;
143  typedef typename std::allocator<T>::difference_type difference_type;
144  typedef typename std::allocator<T>::pointer pointer;
145  typedef typename std::allocator<T>::const_pointer const_pointer;
146  typedef typename std::allocator<T>::reference reference;
147  typedef typename std::allocator<T>::const_reference const_reference;
148  typedef typename std::allocator<T>::value_type value_type;
149 
150  template<class U>
151  struct rebind{ typedef AlignedAllocator<U, N> other; };
152 
153  AlignedAllocator() noexcept;
154 
155  AlignedAllocator( AlignedAllocator const & other ) noexcept;
156 
157  template <class U>
158  AlignedAllocator( AlignedAllocator<U, N> const & other ) noexcept;
159 
160  ~AlignedAllocator() noexcept;
161 
162  pointer allocate( size_type n, const void * = 0 );
163 
164  void deallocate( pointer p, size_type );
165 
166  private:
167  static std::mutex itsMutex;
169  }; // class AlignedAllocator
170 
171  /*! @} */ // **********************************************************************
172 
173  //! Creates an std::unique_ptr by calling the constructor for T with the specified arguments
174  /*! This works identically to make_shared and will be added in C++14
175  @ingroup memory */
176  template <class T, class ... Args>
177  std::unique_ptr<T> make_unique( Args && ... args );
178 }
179 
181 
182 #endif // INCLUDE_NRT_CORE_MEMORY_ALLOCATION_H
183 
184