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
using	ml::AtomicCounter = std::atomic_int32_t
	AtomicCounter is a thread-safe integer counter.
typedef boost::recursive_mutex	ml::RecursiveMutex
	Defines a recursive mutex.
typedef boost::mutex	ml::Mutex
	Defines a non-recursive mutex.

HIDDEN CODE 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.
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
	Similar to the other printAndNotify() function with the difference that reason is an MLErrorCode that is automatically translated to a string so that it is not needed to pass it manually as the last parameter.
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.
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.
MLMemoryBlockHandle &	MLMemoryBlockHandle::operator= (const MLMemoryBlockHandle &memoryBlockHandle)
	Creates a memory block handle from the memory block handle.
MLMemoryBlockHandle &	MLMemoryBlockHandle::operator= (const MLWeakMemoryBlockHandle &weakMemoryBlockHandle)
	Creates a memory block handle from the weak memory block handle.
MLMemoryBlockHandle	MLMemoryManager::allocate (unsigned int id, size_t size)
	Allocates a memory block with the given size in bytes.
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 that is later deleted by the given callback.
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.
size_t	MLMemoryManager::clearCachedMemory (size_t numBytes)
	Frees the given amount of memory by deleting cached memory blocks.
void	MLMemoryManager::clearCache ()
	Deletes all cached memory blocks.
void	MLMemoryManager::clearCacheToLimit ()
	Deletes cached memory blocks list until the cache and locked memory size is not greater than the limit.
size_t	MLMemoryManager::cacheAndLockedMemorySizeLimit () const
	Returns the limit of the accumulated sizes in bytes of the cache and the locked memory.
size_t	MLMemoryManager::cacheSize () const
	Returns the current size in bytes of the cache list.
size_t	MLMemoryManager::lockedMemorySize () const
	Returns the current size in bytes of the locked memory.
size_t	MLMemoryManager::cacheAndLockedMemorySize () const
	Returns the sum of the cache and locked memory size in bytes.
void	MLMemoryManager::printCache (std::ostream &out) const
	Prints some cache information to the ostream.
void	MLMemoryManager::setStatisticsEnabled (bool enabled)
	Sets whether collecting statistic data is enabled.
void	MLMemoryManager::printStatistics (std::ostream &out)
	Prints the current statistics.
MLWeakMemoryBlockHandle &	MLWeakMemoryBlockHandle::operator= (const MLMemoryBlockHandle &memoryBlockHandle)
	Creates a weak memory block handle from the memory block handle.
MLWeakMemoryBlockHandle &	MLWeakMemoryBlockHandle::operator= (const MLWeakMemoryBlockHandle &weakMemoryBlockHandle)
	Creates a weak memory block handle from the memory block handle.
bool	MLWeakMemoryBlockHandle::isNull () const
	Returns true if the weak memory block references a NULL memory block.

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

using ml::AtomicCounter = std::atomic_int32_t

AtomicCounter is a thread-safe integer counter.

Thread-safety: This class is thread-safe.

Definition at line 29 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 39 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 32 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 that is later deleted by the given callback.

Parameters

id	is 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.
data	Must be a valid pointer to the pre-allocated memory.
size	The size of the pre-allocated memory in bytes.
deleteMemoryBlockCallback	Is required. It is called to delete the data when the memory block is destroyed.
deleteMemoryBlockCallbackUserData	Is 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

id	is 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.
size	The 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,
		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

envVar	Specifies the debug symbol that must be defined to print the message given in reason.
libraryPrefix	Specifies the library string code to see from where the debug message comes.
reason	The message to be printed. NULL is legal and is handled as "".
file	The file name where the debug message (i.e., this call) comes from. May be passed as NULL and will be handled as "" then.
line	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,
		std::stringstream &	reason,
		const char *	file,
		int	line ) const

Function called from mlDebugPrint.

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

Parameters

envVar	Specifies the debug symbol that must be defined to print the message given in reason.
libraryPrefix	Specifies the library string code to see from where the debug message comes.
reason	The message to be printed.
file	The file name where the debug message (i.e., this call) comes from. May be passed as NULL and will be handled as "" then.
line	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]

MLMemoryBlockHandle & MLMemoryBlockHandle::operator=

(

const MLMemoryBlockHandle &

memoryBlockHandle

)

Creates a memory block handle from the memory block handle.

This operation is thread-safe.

operator=() [2/4]

MLWeakMemoryBlockHandle & MLWeakMemoryBlockHandle::operator=

(

const MLMemoryBlockHandle &

memoryBlockHandle

)

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

This operation is thread-safe.

operator=() [3/4]

MLMemoryBlockHandle & MLMemoryBlockHandle::operator=

(

const MLWeakMemoryBlockHandle &

weakMemoryBlockHandle

)

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

This operation is thread-safe.

operator=() [4/4]

MLWeakMemoryBlockHandle & MLWeakMemoryBlockHandle::operator=

(

const MLWeakMemoryBlockHandle &

weakMemoryBlockHandle

)

Creates a weak memory block handle from the 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

messageType	Specifies the message type.
libraryPrefix	Specifies the library the message comes from.
fPrefix	String inserted before function names.
functionName	Specifies the calling function or the environment variable related to the debug print.
reason	The reason for the error call or the debug information.
handling	The way how the error is handled.
file	The file calling this function.
line	The line number in the file calling this function.
dumpObj	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.
dumpObjRT	The runtime type of the object to be dumped or NULL.
errCode	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

Similar to the other printAndNotify() function with the difference that reason is an MLErrorCode that is automatically translated to a string so that it is not needed to pass it manually as the 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, as 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

cacheSizeLimit

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

setStatisticsEnabled()

void MLMemoryManager::setStatisticsEnabled

(

bool

enabled

)

Sets whether collecting statistic data is enabled.

This method is thread-safe.