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.
typedef boost::recursive_mutex	ml::RecursiveMutex
	Defines a recursive mutex.
typedef boost::mutex	ml::Mutex
	Defines a non-recursive mutex.
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=NULL, const RuntimeType dumpObjRT=NULL, 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=NULL, const RuntimeType dumpObjRT=NULL) 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.
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, which is later deleted by the given callback.
void	MLMemoryManager::deleteMemoryBlockData (void *data)
	Deletes the memory of a memory block.
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 if 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

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.

typedef boost::mutex ml::Mutex

Defines a non-recursive mutex.

Thread-safety: This class is thread-safe.

Definition at line 43 of file mlMutex.h.

typedef boost::recursive_mutex ml::RecursiveMutex

Defines a recursive mutex.

Thread-safety: This class is thread-safe.

Definition at line 36 of file mlMutex.h.

Function Documentation

MLMemoryBlockHandle MLMemoryManager::addAllocatedMemory	(	unsigned int	id,
		void *	data,
		size_t	size,
		MLDeleteMemoryBlockCallback	deleteMemoryBlockCallback,
		void *	deleteMemoryBlockCallbackUserData
	)			`[inherited]`

Adds a pre-allocated memory block of the given size in bytes, which 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

MLMemoryBlockHandle MLMemoryManager::allocate	(	unsigned int	id,
		size_t	size
	)			`[inherited]`

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

size_t MLMemoryManager::cacheAndLockedMemorySize ( ) const [inherited]

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

This method is thread safe.

size_t MLMemoryManager::cacheAndLockedMemorySizeLimit ( ) const [inherited]

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

This method is thread safe.

size_t MLMemoryManager::cacheSize ( ) const [inherited]

Returns the current size in bytes of the cache list.

This method is thread safe.

void MLMemoryManager::clearCache ( ) [inherited]

Deletes all cached memory blocks.

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

size_t MLMemoryManager::clearCachedMemory ( size_t numBytes ) [inherited]

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

Returns the actually freed amount of memory.

void MLMemoryManager::clearCacheToLimit ( ) [inherited]

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

This method is thread safe.

void MLMemoryManager::deleteMemoryBlockData ( void * data ) [inherited]

Deletes the memory of a memory block.

This is typically used when it is known that a memory block is allocated by the memory manager, but it is deleted in an own callback.

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

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 which 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	is 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	is the line of file where the debug message (i.e., this call) comes from. Unknown line numbers should be passed as -1.

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

Function called from mlDebugPrint.

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

Parameters:

	envVar	specifies the debug symbol which 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	is 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	is the line of file where the debug message (i.e., this call) comes from. Unknown line numbers should be passed as -1.

bool MLWeakMemoryBlockHandle::isNull ( ) const [inherited]

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

size_t MLMemoryManager::lockedMemorySize ( ) const [inherited]

Returns the current size in bytes of the locked memory.

This method is thread safe.

MLWeakMemoryBlockHandle& MLWeakMemoryBlockHandle::operator= ( const MLWeakMemoryBlockHandle & weakMemoryBlockHandle ) [inherited]

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

This operation is thread safe.

MLMemoryBlockHandle& MLMemoryBlockHandle::operator= ( const MLWeakMemoryBlockHandle & weakMemoryBlockHandle ) [inherited]

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

This operation is thread safe.

MLWeakMemoryBlockHandle& MLWeakMemoryBlockHandle::operator= ( const MLMemoryBlockHandle & memoryBlockHandle ) [inherited]

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

This operation is thread safe.

MLMemoryBlockHandle& MLMemoryBlockHandle::operator= ( const MLMemoryBlockHandle & memoryBlockHandle ) [inherited]

Creates a memory block handle from the memory block handle.

This operation is thread safe.

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 = `NULL`,
		const RuntimeType *	dumpObjRT = `NULL`
	)			const `[inherited]`

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.

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 = `NULL`,
		const RuntimeType *	dumpObjRT = `NULL`,
		MLErrorCode	errCode = `ML_RESULT_OK`
	)			const `[inherited]`

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	is the reason for the error call or the debug information.
	handling	is the way how the error is handled.
	file	is the file calling this function.
	line	is the line number in the file calling this function.
	dumpObj	is 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	is the runtime type of the object to be dumped or NULL.
	errCode	is 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.

void MLMemoryManager::printCache ( std::ostream & out ) const [inherited]

Prints some cache information to the ostream.

This method is thread safe.

void MLMemoryManager::printStatistics ( std::ostream & out ) [inherited]

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.

void MLMemoryManager::setCacheAndLockedMemorySizeLimit ( const size_t cacheSizeLimit ) [inherited]

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

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

void MLMemoryManager::setStatisticsEnabled ( bool enabled ) [inherited]

Sets if collecting statistic data is enabled.

This method is thread safe.

Thread-safe Classes and Functions

Classes

Typedefs

HIDDEN STUFF WHICH IS REQUIRED TO BE PUBLIC FOR MACRO USAGE

Detailed Description

Typedef Documentation

Function Documentation