MeVisLab Toolbox Reference
mlMemoryManager.h
Go to the documentation of this file.
1 /*************************************************************************************
2 **
3 ** Copyright 2008, MeVis Medical Solutions AG
4 **
5 ** The user may use this file in accordance with the license agreement provided with
6 ** the Software or, alternatively, in accordance with the terms contained in a
7 ** written agreement between the user and MeVis Medical Solutions AG.
8 **
9 ** For further information use the contact form at https://www.mevislab.de/contact
10 **
11 **************************************************************************************/
12 
13 #ifndef ML_MEMORY_MANAGER_H
14 #define ML_MEMORY_MANAGER_H
15 
16 #include <iosfwd>
17 #include <string>
18 
19 #include "../mlMemoryManagerDllExport.h"
20 
22 #include "mlMemoryBlockHandle.h"
23 
24 // Included for convenience, i.e. a user needs only to
25 // include this header file.
29 
30 
35 #define ML_BYTE_TO_KB(x) ((x) >> 10)
37 #define ML_BYTE_TO_MB(x) ((x) >> 20)
39 #define ML_BYTE_TO_GB(x) ((x) >> 30)
41 #define ML_KB_TO_BYTE(x) ((x) << 10)
43 #define ML_MB_TO_BYTE(x) ((x) << 20)
45 #define ML_GB_TO_BYTE(x) ((x) << 30) // End of group Macros
47 
50 MLMEMORYMANAGER_EXPORT std::string mlByteToHumanReadable(size_t byte);
51 
52 
53 #ifndef DOXYGEN_SHOULD_SKIP_THIS
54 
56 class MLMemoryManagerPrivate;
57 
58 #endif // DOXYGEN_SHOULD_SKIP_THIS
59 
61 namespace boost
62 {
63  class mutex;
64 }
65 
66 
70 {
73 
76  Abort
77 };
78 
79 
81 typedef void (*MLMemoryManagerErrorHandler)(const std::string& message, const char* file, int line,
82  MLMemoryManagerErrorHandlingType errorHandling);
83 
84 
86 class MLMEMORYMANAGER_EXPORT MLMemoryManager
87 {
88 public:
95  static void initialize();
96 
102  static void deinitialize();
103 
107 
109 
121  MLMemoryBlockHandle allocate(unsigned int id, size_t size);
122 
134  void* data,
135  size_t size,
136  MLDeleteMemoryBlockCallback deleteMemoryBlockCallback,
137  void* deleteMemoryBlockCallbackUserData);
138 
143  void setCacheAndLockedMemorySizeLimit(const size_t cacheSizeLimit);
144 
147  size_t clearCachedMemory(size_t numBytes);
148 
151  void clearCache();
152 
157 
161 
164  size_t cacheSize() const;
165 
168  size_t lockedMemorySize() const;
169 
172  size_t cacheAndLockedMemorySize() const;
173 
176  void printCache(std::ostream& out) const;
177 
180  void setStatisticsEnabled(bool enabled);
181 
185  void printStatistics(std::ostream& out);
186  // End of group ThreadSafe
188 
192  unsigned int registerLibrary(const std::string& libraryName);
193 
197 
201  boost::mutex& getCacheAccessMutex();
202 
203  /*
204  * returns true, if registration was successful
205  * returns false, if memoryBlock is empty or registration fails, because deletion is already
206  * ongoing
207  */
208  template <typename T>
209  static bool registerDeletionCallbackUnsafe(const T &handle, MLDeleteMemoryBlockCallback callback,
210  void *userData);
211 
212  enum class Ownership{UserDataOwnershipStaysWithCaller,
213  UserDataOwnershipGoesToMemoryBlock};
214 
215  template <typename T>
218  const void *userData);
219 
220 
225  template <typename T>
226  void replaceDeletionCallback(const T &handle,
227  MLDeleteMemoryBlockCallback newCallback,
228  void *newUserData,
229  MLDeleteMemoryBlockCallback *oldCallback = nullptr,
230  void **oldUserData = nullptr) const;
231 
233 
236  void clearMemoryBlockHandles(MLMemoryBlockHandle** handles, size_t handleCount);
237 
240  void clearMemoryBlockHandles(MLWeakMemoryBlockHandle** handles, size_t handleCount);
241 
242 
243 private:
244 #ifndef DOXYGEN_SHOULD_SKIP_THIS
245  MLMemoryManager(size_t cacheSizeLimit);
247  MLMemoryManager& operator=(const MLMemoryManager&);
248 
249 
250 private:
251  MLMemoryManagerPrivate* _private;
252 
253  friend class MLMemoryBlock;
254  friend class MLMemoryBlockHandle;
255  friend class MLWeakMemoryBlockHandle;
256 #endif
257 };
258 
259 extern template bool MLMEMORYMANAGER_EXPORT MLMemoryManager::registerDeletionCallbackUnsafe<MLWeakMemoryBlockHandle>(
260  const MLWeakMemoryBlockHandle &handle, MLDeleteMemoryBlockCallback callback, void *userData);
261 
262 extern template bool MLMEMORYMANAGER_EXPORT MLMemoryManager::registerDeletionCallbackUnsafe<MLMemoryBlockHandle>(
263  const MLMemoryBlockHandle &handle, MLDeleteMemoryBlockCallback callback, void *userData);
264 
265 extern template MLMemoryManager::Ownership MLMEMORYMANAGER_EXPORT
266 MLMemoryManager::deregisterDeletionCallbackUnsafe<MLWeakMemoryBlockHandle>(
268  const void *userData);
269 
270 extern template MLMemoryManager::Ownership MLMEMORYMANAGER_EXPORT
271 MLMemoryManager::deregisterDeletionCallbackUnsafe<MLMemoryBlockHandle>(
272  const MLMemoryBlockHandle &handle, MLDeleteMemoryBlockCallback callback, const void *userData);
273 
274 
275 extern template void MLMEMORYMANAGER_EXPORT MLMemoryManager::replaceDeletionCallback<MLWeakMemoryBlockHandle>(
276  const MLWeakMemoryBlockHandle &handle, MLDeleteMemoryBlockCallback newCallback,
277  void *newUserData, MLDeleteMemoryBlockCallback *oldCallback, void **oldUserData) const;
278 
279 extern template void MLMEMORYMANAGER_EXPORT MLMemoryManager::replaceDeletionCallback<MLMemoryBlockHandle>(
280  const MLMemoryBlockHandle &handle, MLDeleteMemoryBlockCallback newCallback, void *newUserData,
281  MLDeleteMemoryBlockCallback *oldCallback, void **oldUserData) const;
282 
283 
284 #endif // MLMEMORYMANAGER_H_INCLUDED
@ T
Definition: SoKeyGrabber.h:71
The strong handle of a MLMemoryBlock.
The memory manager.
void clearMemoryBlockHandles(MLMemoryBlockHandle **handles, size_t handleCount)
Clears a list of memory block handles.
boost::mutex & getCacheAccessMutex()
Advanced memory manager handling.
void setErrorHandlingCallback(MLMemoryManagerErrorHandler errorHandler)
Sets the error handler callback.
unsigned int registerLibrary(const std::string &libraryName)
Registers a library and returns an id.
static MLMemoryManager * singleton()
The singleton is the only way to communicate with the memory manager.
void clearMemoryBlockHandles(MLWeakMemoryBlockHandle **handles, size_t handleCount)
Clears a list of weak memory block handles.
static Ownership deregisterDeletionCallbackUnsafe(const T &handle, MLDeleteMemoryBlockCallback callback, const void *userData)
void replaceDeletionCallback(const T &handle, MLDeleteMemoryBlockCallback newCallback, void *newUserData, MLDeleteMemoryBlockCallback *oldCallback=nullptr, void **oldUserData=nullptr) const
Replaces the deletion callback and user data that are registered for the memory block.
static void deinitialize()
Deinitializes the memory manager.
static void initialize()
Initializes the memory manager with a default limit of one gigabyte for the joint size of the cache a...
static bool registerDeletionCallbackUnsafe(const T &handle, MLDeleteMemoryBlockCallback callback, void *userData)
The weak handle of a MLMemoryBlock.
void setCacheAndLockedMemorySizeLimit(const size_t cacheSizeLimit)
The memory manager deletes memory blocks in the cache list automatically if the cache and locked memo...
size_t cacheSize() const
Returns the current size in bytes of the cache list.
size_t lockedMemorySize() const
Returns the current size in bytes of the locked memory.
size_t clearCachedMemory(size_t numBytes)
Frees the given amount of memory by deleting cached memory blocks.
MLMemoryBlockHandle allocate(unsigned int id, size_t size)
Allocates a memory block with the given size in bytes.
void setStatisticsEnabled(bool enabled)
Sets if collecting statistic data is enabled.
size_t cacheAndLockedMemorySizeLimit() const
Returns the limit of the accumulated sizes in bytes of the cache and the locked memory.
MLMemoryBlockHandle addAllocatedMemory(unsigned int id, void *data, size_t size, MLDeleteMemoryBlockCallback deleteMemoryBlockCallback, void *deleteMemoryBlockCallbackUserData)
Adds a pre-allocated memory block of the given size in bytes, which is later deleted by the given cal...
void printStatistics(std::ostream &out)
Prints the current statistics.
void printCache(std::ostream &out) const
Prints some cache information to the ostream.
void clearCache()
Deletes all cached memory blocks.
void clearCacheToLimit()
Deletes cached memory blocks list until the cache and locked memory size is not greater than the limi...
size_t cacheAndLockedMemorySize() const
Returns the sum of the cache and locked memory size in bytes.
void(* MLDeleteMemoryBlockCallback)(void *data, size_t size, void *userData)
The callback function type for deleting a memory block.
MLMemoryManagerErrorHandlingType
This enum is passed to the memory manager error handler callback to request a certain error handling.
@ NotifyUser
An error occurred and the user should be notified about it.
@ Abort
The error handling requests programm termination, because it is in an unstable state.
void(* MLMemoryManagerErrorHandler)(const std::string &message, const char *file, int line, MLMemoryManagerErrorHandlingType errorHandling)
Function callback to handle memory manager errors.
MLMEMORYMANAGER_EXPORT std::string mlByteToHumanReadable(size_t byte)
Converts the byte value into a string with human readable format.
Forward declaration for the boost::mutex class.