MeVisLabToolboxReference
Thread-safe Classes and Functions

Classes

class  ml::Barrier
 A barrier class that handles synchronization of multiple threads Thread-safety: This class is thread-safe. More...
 
class  ml::WaitCondition
 WaitCondition implements a wait condition for thread synchronization. More...
 

Typedefs

typedef boost::detail::atomic_count ml::AtomicCounter
 AtomicCounter is a thread-safe integer counter. More...
 
typedef boost::recursive_mutex ml::RecursiveMutex
 Defines a recursive mutex. More...
 
typedef boost::mutex ml::Mutex
 Defines a non-recursive mutex. More...
 

HIDDEN STUFF WHICH IS REQUIRED TO BE PUBLIC FOR MACRO USAGE

The following functions are called by macros and therefore they need to be public.

Nevertheless these functions should not be called directly by any user or application.

void ml::ErrorOutput::printAndNotify (MLMessageType messageType, const std::string &libraryPrefix, const std::string &fPrefix, const std::string &functionName, const std::string &reason, const std::string &handling="", const std::string &file="", int line=-1, const void *dumpObj=nullptr, const RuntimeType *dumpObjRT=nullptr, MLErrorCode errCode=ML_RESULT_OK) const
 Core error printing function used by all other functions. More...
 
void ml::ErrorOutput::printAndNotify (MLMessageType messageType, const std::string &libraryPrefix, const std::string &fPrefix, const std::string &functionName, MLErrorCode reason, const std::string &handling="", const std::string &file="", int line=-1, const void *dumpObj=nullptr, const RuntimeType *dumpObjRT=nullptr) const
 Like the other printAndNotify() function with the difference that reason is an MLErrorCode which is automatically translated to a string so that it is not needed to pass it manually as last parameter. More...
 
void ml::ErrorOutput::handleDebugPrint (const std::string &envVar, const std::string &libraryPrefix, std::stringstream &reason, const char *file, int line) const
 Function called from mlDebugPrint. More...
 
void ml::ErrorOutput::handleDebugPrint (const std::string &envVar, const std::string &libraryPrefix, const char *reason, const char *file, int line) const
 Function called from mlDebugPrint. More...
 
MLMemoryBlockHandleMLMemoryBlockHandle::operator= (const MLMemoryBlockHandle &memoryBlockHandle)
 Creates a memory block handle from the memory block handle. More...
 
MLMemoryBlockHandleMLMemoryBlockHandle::operator= (const MLWeakMemoryBlockHandle &weakMemoryBlockHandle)
 Creates a memory block handle from the weak memory block handle. More...
 
MLMemoryBlockHandle MLMemoryManager::allocate (unsigned int id, size_t size)
 Allocates a memory block with the given size in bytes. More...
 
MLMemoryBlockHandle MLMemoryManager::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 callback. More...
 
void MLMemoryManager::setCacheAndLockedMemorySizeLimit (const size_t cacheSizeLimit)
 The memory manager deletes memory blocks in the cache list automatically if the cache and locked memory size limit is reached or exceeded. More...
 
size_t MLMemoryManager::clearCachedMemory (size_t numBytes)
 Frees the given amount of memory by deleting cached memory blocks. More...
 
void MLMemoryManager::clearCache ()
 Deletes all cached memory blocks. More...
 
void MLMemoryManager::clearCacheToLimit ()
 Deletes cached memory blocks list until the cache and locked memory size is not greater than the limit. More...
 
size_t MLMemoryManager::cacheAndLockedMemorySizeLimit () const
 Returns the limit of the accumulated sizes in bytes of the cache and the locked memory. More...
 
size_t MLMemoryManager::cacheSize () const
 Returns the current size in bytes of the cache list. More...
 
size_t MLMemoryManager::lockedMemorySize () const
 Returns the current size in bytes of the locked memory. More...
 
size_t MLMemoryManager::cacheAndLockedMemorySize () const
 Returns the sum of the cache and locked memory size in bytes. More...
 
void MLMemoryManager::printCache (std::ostream &out) const
 Prints some cache information to the ostream. More...
 
void MLMemoryManager::setStatisticsEnabled (bool enabled)
 Sets if collecting statistic data is enabled. More...
 
void MLMemoryManager::printStatistics (std::ostream &out)
 Prints the current statistics. More...
 
MLWeakMemoryBlockHandleMLWeakMemoryBlockHandle::operator= (const MLMemoryBlockHandle &memoryBlockHandle)
 Creates a weak memory block handle from the memory block handle. More...
 
MLWeakMemoryBlockHandleMLWeakMemoryBlockHandle::operator= (const MLWeakMemoryBlockHandle &weakMemoryBlockHandle)
 Creates a weak memory block handle from the memory block handle. More...
 
bool MLWeakMemoryBlockHandle::isNull () const
 Returns true if the weak memory block references a NULL memory block. More...
 

Detailed Description

The following classes and methods in the ML are known to be thread-safe.

Note: This list is not yet complete, but it will grow over time.

Typedef Documentation

◆ AtomicCounter

typedef boost::detail::atomic_count ml::AtomicCounter

AtomicCounter is a thread-safe integer counter.

Thread-safety: This class is thread-safe.

Definition at line 28 of file mlAtomicCounter.h.

◆ Mutex

typedef boost::mutex ml::Mutex

Defines a non-recursive mutex.

Thread-safety: This class is thread-safe.

Definition at line 34 of file mlMutex.h.

◆ RecursiveMutex

typedef boost::recursive_mutex ml::RecursiveMutex

Defines a recursive mutex.

Thread-safety: This class is thread-safe.

Definition at line 27 of file mlMutex.h.

Function Documentation

◆ addAllocatedMemory()

MLMemoryBlockHandle MLMemoryManager::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 callback.

Parameters
idis used for statistics and should be the same for all allocations from the same library. For example, the ML uses one id for all allocations. This method is thread safe.
datamust be a valid pointer to the pre-allocated memory.
sizeThe size of the pre-allocated memory in bytes.
deleteMemoryBlockCallbackis required. It is called to delete the data when the memory block is destroyed.
deleteMemoryBlockCallbackUserDatais passed to the callback and may be NULL, if it is not required for deleting the data.
Returns
A newly created memory block handle is returned.
See also
Adding already allocated memory

◆ allocate()

MLMemoryBlockHandle MLMemoryManager::allocate ( unsigned int  id,
size_t  size 
)

Allocates a memory block with the given size in bytes.

Parameters
idis used for statistics and should be the same for all allocations from the same library. For example, the ML uses one id for all allocations. This method is thread safe.
sizeThe size of the memory block in bytes. It is allowed to pass 0, which results in a valid data pointer.
Returns
The returned handle might be null if the allocation failed.
See also
Allocating a memory block

◆ cacheAndLockedMemorySize()

size_t MLMemoryManager::cacheAndLockedMemorySize ( ) const

Returns the sum of the cache and locked memory size in bytes.

This method is thread safe.

◆ cacheAndLockedMemorySizeLimit()

size_t MLMemoryManager::cacheAndLockedMemorySizeLimit ( ) const

Returns the limit of the accumulated sizes in bytes of the cache and the locked memory.

This method is thread safe.

◆ cacheSize()

size_t MLMemoryManager::cacheSize ( ) const

Returns the current size in bytes of the cache list.

This method is thread safe.

◆ clearCache()

void MLMemoryManager::clearCache ( )

Deletes all cached memory blocks.

Locked memory is not cached and remains untouched. This method is thread safe.

◆ clearCachedMemory()

size_t MLMemoryManager::clearCachedMemory ( size_t  numBytes)

Frees the given amount of memory by deleting cached memory blocks.

Returns the actually freed amount of memory.

◆ clearCacheToLimit()

void MLMemoryManager::clearCacheToLimit ( )

Deletes cached memory blocks list until the cache and locked memory size is not greater than the limit.

This method is thread safe.

◆ handleDebugPrint() [1/2]

void ml::ErrorOutput::handleDebugPrint ( const std::string &  envVar,
const std::string &  libraryPrefix,
std::stringstream &  reason,
const char *  file,
int  line 
) const

Function called from mlDebugPrint.

The message in reason is passed as a std::stringstream.

Parameters
envVarspecifies the debug symbol which must be defined to print the message given in reason.
libraryPrefixspecifies the library string code to see from where the debug message comes.
reasonthe message to be printed.
fileis the file name where the debug message (i.e., this call) comes from. May be passed as NULL and will be handled as "" then.
lineis the line of file where the debug message (i.e., this call) comes from. Unknown line numbers should be passed as -1.

◆ handleDebugPrint() [2/2]

void ml::ErrorOutput::handleDebugPrint ( const std::string &  envVar,
const std::string &  libraryPrefix,
const char *  reason,
const char *  file,
int  line 
) const

Function called from mlDebugPrint.

Does the same like the other mlDebugPrint version, only the reason is passed as character string constant and not as std::strstream.

Parameters
envVarspecifies the debug symbol which must be defined to print the message given in reason.
libraryPrefixspecifies the library string code to see from where the debug message comes.
reasonis the message to be printed. NULL is legal and is handled as "".
filethe file name where the debug message (i.e., this call) comes from. May be passed as NULL and will be handled as "" then.
lineis the line of file where the debug message (i.e., this call) comes from. Unknown line numbers should be passed as -1.

◆ isNull()

bool MLWeakMemoryBlockHandle::isNull ( ) const

Returns true if the weak memory block references a NULL memory block.

◆ lockedMemorySize()

size_t MLMemoryManager::lockedMemorySize ( ) const

Returns the current size in bytes of the locked memory.

This method is thread safe.

◆ operator=() [1/4]

MLWeakMemoryBlockHandle& MLWeakMemoryBlockHandle::operator= ( const MLMemoryBlockHandle memoryBlockHandle)

Creates a weak memory block handle from the memory block handle.

This operation is thread safe.

◆ operator=() [2/4]

MLWeakMemoryBlockHandle& MLWeakMemoryBlockHandle::operator= ( const MLWeakMemoryBlockHandle weakMemoryBlockHandle)

Creates a weak memory block handle from the memory block handle.

This operation is thread safe.

◆ operator=() [3/4]

MLMemoryBlockHandle& MLMemoryBlockHandle::operator= ( const MLMemoryBlockHandle memoryBlockHandle)

Creates a memory block handle from the memory block handle.

This operation is thread safe.

◆ operator=() [4/4]

MLMemoryBlockHandle& MLMemoryBlockHandle::operator= ( const MLWeakMemoryBlockHandle weakMemoryBlockHandle)

Creates a memory block handle from the weak memory block handle.

This operation is thread safe.

◆ printAndNotify() [1/2]

void ml::ErrorOutput::printAndNotify ( MLMessageType  messageType,
const std::string &  libraryPrefix,
const std::string &  fPrefix,
const std::string &  functionName,
const std::string &  reason,
const std::string &  handling = "",
const std::string &  file = "",
int  line = -1,
const void *  dumpObj = nullptr,
const RuntimeType dumpObjRT = nullptr,
MLErrorCode  errCode = ML_RESULT_OK 
) const

Core error printing function used by all other functions.

Thread-safety: This method is thread-safe.

It calculates the ErrorOutputInfos and calls all registered callback functions to propagate the ErrorOutputInfos. It redirects an error message or a debug print to all registered routines.

Parameters
messageTypespecifies the message type.
libraryPrefixspecifies the library the message comes from.
fPrefixstring inserted before function names.
functionNamespecifies the calling function or the environment variable related to the debug print.
reasonis the reason for the error call or the debug information.
handlingis the way how the error is handled.
fileis the file calling this function.
lineis the line number in the file calling this function.
dumpObjis a NULL or object pointer to a runtime typed object. If there is a registered dump function in the ML C-API then it will be dumped and appended to the error output.
dumpObjRTis the runtime type of the object to be dumped or NULL.
errCodeis the code of the error causing this call.
Calling example:
// ErrorOutput::printAndNotify(ML_WARNING, // message type
// "ML_", // Library prefix
// "Function=", // function prefix
// "MyFunction", // functionName
// "MyFunction had an overflow", // reason
// "I will do nothing to handle it", // handling
// __FILE__, // file
// __LINE__); // line
// NULL, // no runtime object to be dumped
// NULL, // no runtime type of any object
// ML_CALCULATION_ERROR); // line
Note that this routine does not print anything directly. It only converts all parameters into a struct form and calls all registered routines.

◆ printAndNotify() [2/2]

void ml::ErrorOutput::printAndNotify ( MLMessageType  messageType,
const std::string &  libraryPrefix,
const std::string &  fPrefix,
const std::string &  functionName,
MLErrorCode  reason,
const std::string &  handling = "",
const std::string &  file = "",
int  line = -1,
const void *  dumpObj = nullptr,
const RuntimeType dumpObjRT = nullptr 
) const

Like the other printAndNotify() function with the difference that reason is an MLErrorCode which is automatically translated to a string so that it is not needed to pass it manually as last parameter.

◆ printCache()

void MLMemoryManager::printCache ( std::ostream &  out) const

Prints some cache information to the ostream.

This method is thread safe.

◆ printStatistics()

void MLMemoryManager::printStatistics ( std::ostream &  out)

Prints the current statistics.

Do not rely on the output format, because it may change in the future. All information is queryable from the memory manager. This method is thread safe.

◆ setCacheAndLockedMemorySizeLimit()

void MLMemoryManager::setCacheAndLockedMemorySizeLimit ( const size_t  cacheSizeLimit)

The memory manager deletes memory blocks in the cache list automatically if the cache and locked memory size limit is reached or exceeded.

This method is thread safe.

Parameters
cacheSizeLimitis the new limit for the cache and locked memory size in bytes.

◆ setStatisticsEnabled()

void MLMemoryManager::setStatisticsEnabled ( bool  enabled)

Sets if collecting statistic data is enabled.

This method is thread safe.