#include <bslmt_threadutil.h>

Public Types
typedef ThreadUtilImpl< Platform::ThreadPolicy >	Imp
	Platform-specific implementation type.

typedef Imp::Handle	Handle

typedef Imp::NativeHandle	NativeHandle
	Platform-specific thread handle type.

typedef Imp::Id	Id

typedef bslmt_ThreadFunction	ThreadFunction
	Prototype for thread entry-point functions.

typedef Imp::Key	Key
	Thread-specific key type, used to refer to thread-specific storage.

typedef bslmt_KeyDestructorFunction	Destructor
	Prototype for thread-specific key destructors.

Static Public Member Functions
static int	convertToSchedulingPriority (ThreadAttributes::SchedulingPolicy policy, double normalizedSchedulingPriority)

static int	create (Handle handle, ThreadFunction function, void userData)

static int	create (Handle handle, const ThreadAttributes &attributes, ThreadFunction function, void userData)

template<class INVOKABLE >
static int	create (Handle *handle, const INVOKABLE &function)

template<class INVOKABLE >
static int	create (Handle *handle, const ThreadAttributes &attributes, const INVOKABLE &function)

static int	createWithAllocator (Handle handle, ThreadFunction function, void userData, bslma::Allocator *allocator)

static int	createWithAllocator (Handle handle, const ThreadAttributes &attributes, ThreadFunction function, void userData, bslma::Allocator *allocator)

template<class INVOKABLE >
static int	createWithAllocator (Handle handle, const INVOKABLE &function, bslma::Allocator allocator)

template<class INVOKABLE >
static int	createWithAllocator (Handle handle, const ThreadAttributes &attributes, const INVOKABLE &function, bslma::Allocator allocator)

static int	detach (Handle &handle)

static void	exit (void *status)

static int	getMinSchedulingPriority (ThreadAttributes::SchedulingPolicy policy)

static int	getMaxSchedulingPriority (ThreadAttributes::SchedulingPolicy policy)

static void	getThreadName (bsl::string *threadName)

static int	join (Handle &threadHandle, void **status=0)

static void	microSleep (int microseconds, int seconds=0)

static void	setThreadName (const bslstl::StringRef &threadName)

static void	sleep (const bsls::TimeInterval &sleepTime)

template<class REP_TYPE , class PERIOD_TYPE >
static void	sleep (const bsl::chrono::duration< REP_TYPE, PERIOD_TYPE > &sleepTime)

static void	sleepUntil (const bsls::TimeInterval &absoluteTime, bsls::SystemClockType::Enum clockType=bsls::SystemClockType::e_REALTIME)

template<class CLOCK , class DURATION >
static void	sleepUntil (const bsl::chrono::time_point< CLOCK, DURATION > &absoluteTime)

static void	yield ()

static bool	areEqual (const Handle &a, const Handle &b)

static bool	areEqualId (const Id &a, const Id &b)

static Id	handleToId (const Handle &threadHandle)

static bsls::Types::Uint64	idAsUint64 (const Id &threadId)

static int	idAsInt (const Id &threadId)

static const Handle &	invalidHandle ()

static bool	isEqual (const Handle &a, const Handle &b)

static bool	isEqualId (const Id &a, const Id &b)

static NativeHandle	nativeHandle (const Handle &handle)

static Handle	self ()

static Id	selfId ()

static bsls::Types::Uint64	selfIdAsInt ()

static bsls::Types::Uint64	selfIdAsUint64 ()

static int	createKey (Key *key, Destructor threadKeyCleanupFunction)

static int	deleteKey (Key &key)

static void *	getSpecific (const Key &key)

static int	setSpecific (const Key &key, const void *value)

static unsigned int	hardwareConcurrency ()

Detailed Description

This struct provides a suite of portable utility functions for managing threads.

Member Typedef Documentation

◆ Destructor

typedef bslmt_KeyDestructorFunction bslmt::ThreadUtil::Destructor

◆ Handle

typedef Imp::Handle bslmt::ThreadUtil::Handle

Thread handle type. Use this type to refer to a thread in a platform-independent way.

◆ Id

typedef Imp::Id bslmt::ThreadUtil::Id

Thread identifier type - distinguished from a Handle in that it does not have any resources associated with it, whereas Handle may, depending on platform.

◆ Imp

typedef ThreadUtilImpl<Platform::ThreadPolicy> bslmt::ThreadUtil::Imp

◆ Key

typedef Imp::Key bslmt::ThreadUtil::Key

◆ NativeHandle

typedef Imp::NativeHandle bslmt::ThreadUtil::NativeHandle

◆ ThreadFunction

typedef bslmt_ThreadFunction bslmt::ThreadUtil::ThreadFunction

Member Function Documentation

◆ areEqual()

bool bslmt::ThreadUtil::areEqual	(	const Handle &	a,
		const Handle &	b
	)

inlinestatic

Return true if the specified a and b thread handles identify the same thread, or if both a and b are invalid handles, and false otherwise. Note that if either of a or b is an invalid handle, but not both, this method returns false.

◆ areEqualId()

bool bslmt::ThreadUtil::areEqualId	(	const Id &	a,
		const Id &	b
	)

inlinestatic

Return true if the specified a thread identifier is associated with the same thread as the specified b thread identifier, and false otherwise.

◆ convertToSchedulingPriority()

static int bslmt::ThreadUtil::convertToSchedulingPriority	(	ThreadAttributes::SchedulingPolicy	policy,
		double	normalizedSchedulingPriority
	)

static

Return an integer scheduling priority appropriate for the specified normalizedSchedulingPriority and the specified policy. If either the minimum or maximum priority for this platform cannot be determined, return ThreadAttributes::e_UNSET_PRIORITY. Higher values of normalizedSchedulingPriority are considered to represent more urgent priorities. The behavior is undefined unless policy is a valid ThreadAttributes::SchedulingPolicy and normalizedSchedulingPriority is in the range [ 0.0, 1.0 ].

◆ create() [1/4]

template<class INVOKABLE >

int bslmt::ThreadUtil::create	(	Handle *	handle,
		const INVOKABLE &	function
	)

inlinestatic

Create a new thread of program control whose entry point will invoke the specified function object, and load into the specified handle an identifier that may be used to refer to this thread in calls to other ThreadUtil methods. Optionally specify attributes describing the properties for the new thread. If attributes is not supplied, a default ThreadAttributes object is used. Use the global allocator to supply memory. Return 0 on success, and a non-zero value otherwise. function shall be a reference to a type, INVOKABLE, that can be copy-constructed, and where the expression (void)function() will execute a function call (i.e., either a void()() function, or a functor object implementing void operator()()). bslmt::Configuration is used to determine the created thread's default stack-size if either attributes is not supplied or if attributes.stackSize() has the unset value. The behavior is undefined unless attributes, if specified, has a stackSize that is either greater than 0 or e_UNSET_STACK_SIZE. Note that unless the created thread is explicitly "detached" (by invoking the detach class method with handle) or the k_CREATE_DETACHED attribute is specified, a call to join must be made to reclaim any system resources associated with the newly-created thread. Also note that users are encouraged to either explicitly provide a stack size attribute, or configure a bslmt-wide default using bslmt::Configuration, because the default stack size is surprisingly small on some platforms.

◆ create() [2/4]

template<class INVOKABLE >

int bslmt::ThreadUtil::create	(	Handle *	handle,
		const ThreadAttributes &	attributes,
		const INVOKABLE &	function
	)

inlinestatic

◆ create() [3/4]

static int bslmt::ThreadUtil::create	(	Handle *	handle,
		const ThreadAttributes &	attributes,
		ThreadFunction	function,
		void *	userData
	)

static

Create a new thread of program control whose entry point will be the specified function, and which will be passed the specified userData as its sole argument, and load into the specified handle an identifier that may be used to refer to this thread in calls to other ThreadUtil methods. Optionally specify attributes describing the properties for the new thread. If attributes is not supplied, a default ThreadAttributes object is used. Use the global allocator to supply memory. Return 0 on success, and a non-zero value otherwise. bslmt::Configuration is used to determine the created thread's default stack-size if either attributes is not supplied or if attributes.stackSize() has the unset value. The behavior is undefined unless attributes, if specified, has a stackSize that is either greater than 0 or e_UNSET_STACK_SIZE. Note that unless the created thread is explicitly "detached" (by invoking the detach class method with handle) or the k_CREATE_DETACHED attribute is specified, a call to join must be made to reclaim any system resources associated with the newly-created thread. Also note that users are encouraged to either explicitly provide a stack size attribute, or configure a bslmt-wide default using bslmt::Configuration, because the default stack size is surprisingly small on some platforms.

◆ create() [4/4]

int bslmt::ThreadUtil::create	(	Handle *	handle,
		ThreadFunction	function,
		void *	userData
	)

inlinestatic

◆ createKey()

int bslmt::ThreadUtil::createKey	(	Key *	key,
		Destructor	threadKeyCleanupFunction
	)

inlinestatic

Load into the specified key a new process-wide identifier that can be used to store (via setSpecific) and retrieve (via getSpecific) a pointer value local to each thread, and associate with the new key the specified threadKeyCleanupFunction, which will be called by each thread, if threadKeyCleanupFunction is non-zero and the value associated with key for that thread is non-zero, with the associated value as an argument, after the function passed to create has returned and before the thread terminates. Return 0 on success, and a non-zero value otherwise. Note that multiple keys can be defined, which can result in multiple thread key cleanup functions being called for a given thread.

◆ createWithAllocator() [1/4]

template<class INVOKABLE >

int bslmt::ThreadUtil::createWithAllocator	(	Handle *	handle,
		const INVOKABLE &	function,
		bslma::Allocator *	allocator
	)

inlinestatic

Create a new thread of program control whose entry point will invoke the specified function object (using the specified allocator to supply memory to copy function), and load into the specified handle an identifier that may be used to refer to this thread in calls to other ThreadUtil methods. Optionally specify attributes describing the properties for the new thread. If attributes is not supplied, a default ThreadAttributes object is used. Return 0 on success, and a non-zero value otherwise. function shall be a reference to a type, INVOKABLE, that can be copy-constructed, and where the expression (void)function() will execute a function call (i.e., either a void()() function, or a functor object implementing void operator()()). bslmt::Configuration is used to determine the created thread's default stack-size if either attributes is not supplied or if attributes.stackSize() has the unset value. The behavior is undefined unless attributes, if specified, has a stackSize that is either greater than 0 or e_UNSET_STACK_SIZE. Note that unless the created thread is explicitly "detached" (by invoking the detach class method with handle) or the k_CREATE_DETACHED attribute is specified, a call to join must be made to reclaim any system resources associated with the newly-created thread. Also note that the lifetime of allocator must exceed the lifetime of the thread. Also note that users are encouraged to either explicitly provide a stack size attribute, or configure a bslmt-wide default using bslmt::Configuration, because the default stack size is surprisingly small on some platforms.

◆ createWithAllocator() [2/4]

template<class INVOKABLE >

int bslmt::ThreadUtil::createWithAllocator	(	Handle *	handle,
		const ThreadAttributes &	attributes,
		const INVOKABLE &	function,
		bslma::Allocator *	allocator
	)

inlinestatic

◆ createWithAllocator() [3/4]

static int bslmt::ThreadUtil::createWithAllocator	(	Handle *	handle,
		const ThreadAttributes &	attributes,
		ThreadFunction	function,
		void *	userData,
		bslma::Allocator *	allocator
	)

static

Create a new thread of program control whose entry point will be the specified function, and which will be passed the specified userData as its sole argument, and load into the specified handle an identifier that may be used to refer to this thread in calls to other ThreadUtil methods. Optionally specify attributes describing the properties for the new thread. If attributes is not supplied, a default ThreadAttributes object is used. Use the specified allocator to supply memory. Return 0 on success, and a non-zero value otherwise. bslmt::Configuration is used to determine the created thread's default stack-size if either attributes is not supplied or if attributes.stackSize() has the unset value. The behavior is undefined unless attributes, if specified, has a stackSize that is either greater than 0 or e_UNSET_STACK_SIZE. Note that unless the created thread is explicitly "detached" (by invoking the detach class method with handle) or the k_CREATE_DETACHED attribute is specified, a call to join must be made to reclaim any system resources associated with the newly-created thread. Also note that users are encouraged to either explicitly provide a stack size attribute, or configure a bslmt-wide default using bslmt::Configuration, because the default stack size is surprisingly small on some platforms.

◆ createWithAllocator() [4/4]

static int bslmt::ThreadUtil::createWithAllocator	(	Handle *	handle,
		ThreadFunction	function,
		void *	userData,
		bslma::Allocator *	allocator
	)

static

◆ deleteKey()

int bslmt::ThreadUtil::deleteKey ( Key & key )

inlinestatic

Delete the specified key from the calling process, and disassociate all threads from the thread key cleanup function supplied when key was created (see createKey). Return 0 on success, and a non-zero value otherwise. The behavior is undefined unless key was obtained from a successful call to createKey and has not already been deleted. Note that deleting a key does not delete any data referred to by the pointer values associated with that key in any thread.

◆ detach()

int bslmt::ThreadUtil::detach ( Handle & handle )

inlinestatic

"Detach" the thread identified by the specified handle such that when it terminates, the resources associated with that thread will automatically be reclaimed. The behavior is undefined unless handle was obtained by a call to create or self. Note that once a thread is "detached", it is no longer possible to join the thread to retrieve its exit status.

◆ exit()

void bslmt::ThreadUtil::exit ( void * status )

inlinestatic

Exit the current thread and return the specified status. If the current thread is not "detached", then a call to join must be made to reclaim any resources used by the thread, and to retrieve the exit status. Note that the preferred method of exiting a thread is to return from the entry point function.

◆ getMaxSchedulingPriority()

int bslmt::ThreadUtil::getMaxSchedulingPriority ( ThreadAttributes::SchedulingPolicy policy )

inlinestatic

Return the maximum available priority for the specified policy, where policy is of type ThreadAttributes::SchedulingPolicy. Return ThreadAttributes::e_UNSET_PRIORITY if the maximum scheduling priority cannot be determined. Note that, for some platform / policy combinations, getMinSchedulingPriority(policy) and getMaxSchedulingPriority(policy) return the same value.

◆ getMinSchedulingPriority()

int bslmt::ThreadUtil::getMinSchedulingPriority ( ThreadAttributes::SchedulingPolicy policy )

inlinestatic

Return the minimum available priority for the specified policy, where policy is of type ThreadAttributes::SchedulingPolicy. Return ThreadAttributes::e_UNSET_PRIORITY if the minimum scheduling priority cannot be determined. Note that, for some platform / policy combinations, getMinSchedulingPriority(policy) and getMaxSchedulingPriority(policy) return the same value.

◆ getSpecific()

void * bslmt::ThreadUtil::getSpecific ( const Key & key )

inlinestatic

Return the thread-local value associated with the specified key. A key is shared among all threads and the value associated with key for each thread is 0 until it is set by that thread using setSpecific. The behavior is undefined unless this method is called outside any thread key cleanup function associated with any key by createKey, key was obtained from a successful call to createKey, and key has not been deleted.

◆ getThreadName()

void bslmt::ThreadUtil::getThreadName ( bsl::string * threadName )

inlinestatic

Load the name of the current thread into the specified *threadName. Note that this method clears *threadName on platforms other than Linux, Solaris, Darwin, and Windows.

◆ handleToId()

ThreadUtil::Id bslmt::ThreadUtil::handleToId ( const Handle & threadHandle )

inlinestatic

Return the unique identifier of the thread having the specified threadHandle within the current process. The behavior is undefined unless handle was obtained by a call to create or self. Note that this value is valid only until the thread terminates, and may be reused thereafter.

◆ hardwareConcurrency()

unsigned int bslmt::ThreadUtil::hardwareConcurrency ( )

inlinestatic

Return a hint at the number of concurrent threads supported by this platform on success, and 0 otherwise.

◆ idAsInt()

int bslmt::ThreadUtil::idAsInt ( const Id & threadId )

inlinestatic

Return the unique integral identifier of a thread uniquely identified by the specified threadId within the current process. Note that this representation is particularly useful for logging purposes. Also note that this value is only valid until the thread terminates and may be reused thereafter.

DEPRECATED: use idAsUint64.

◆ idAsUint64()

bsls::Types::Uint64 bslmt::ThreadUtil::idAsUint64 ( const Id & threadId )

inlinestatic

Return the unique integral identifier of a thread uniquely identified by the specified threadId within the current process. Note that this representation is particularly useful for logging purposes. Also note that this value is only valid until the thread terminates and may be reused thereafter.

◆ invalidHandle()

const ThreadUtil::Handle & bslmt::ThreadUtil::invalidHandle ( )

inlinestatic

Return a reference to the non-modifiable Handle object that is guaranteed never to be a valid thread handle.

◆ isEqual()

bool bslmt::ThreadUtil::isEqual	(	const Handle &	a,
		const Handle &	b
	)

inlinestatic

Return true if the specified a and b thread handles identify the same thread, or if both a and b are invalid handles, and false otherwise. Note that if either of a or b is an invalid handle, but not both, this method returns false.

DEPRECATED: use areEqual instead.

◆ isEqualId()

bool bslmt::ThreadUtil::isEqualId	(	const Id &	a,
		const Id &	b
	)

inlinestatic

Return true if the specified lhs thread identifier is associated with the same thread as the specified rhs thread identifier, and false otherwise.

DEPRECATED: use areEqualId instead.

◆ join()

int bslmt::ThreadUtil::join	(	Handle &	threadHandle,
		void **	status = `0`
	)

inlinestatic

Suspend execution of the current thread until the thread referred to by the specified threadHandle terminates, and reclaim any system resources associated with threadHandle. Return 0 on success, and a non-zero value otherwise. If the optionally specified status is not 0, load into *status the value returned by the function supplied at the creation of the thread identified by threadHandle. The behavior is undefined unless threadHandle was obtained by a call to create.

◆ microSleep()

void bslmt::ThreadUtil::microSleep	(	int	microseconds,
		int	seconds = `0`
	)

inlinestatic

Suspend execution of the current thread for a period of at least the specified microseconds and the optionally specified seconds (relative time), or an interrupting signal is received. Note that the actual time suspended depends on many factors including system scheduling and system timer resolution, and may be significantly longer than the time requested.

◆ nativeHandle()

ThreadUtil::NativeHandle bslmt::ThreadUtil::nativeHandle ( const Handle & handle )

inlinestatic

Return the platform-specific identifier associated with the thread referred to by the specified handle. The behavior is undefined unless handle was obtained by a call to create or self. Note that the returned native handle may not be a globally unique identifier for the thread (see selfIdAsUint).

◆ self()

ThreadUtil::Handle bslmt::ThreadUtil::self ( )

inlinestatic

Return an opaque thread identifier that can be used to refer to the current thread in calls to other ThreadUtil methods. Note that identifier may only be used to refer to the current thread from the current thread (the handle returned is not valid in other threads).

◆ selfId()

ThreadUtil::Id bslmt::ThreadUtil::selfId ( )

inlinestatic

Return an identifier that can be used to uniquely identify the current thread within the current process. Note that the identifier is only valid until the thread terminates and may be reused thereafter.

◆ selfIdAsInt()

bsls::Types::Uint64 bslmt::ThreadUtil::selfIdAsInt ( )

inlinestatic

Return an integral identifier that can be used to uniquely identify the current thread within the current process. Note that this representation is particularly useful for logging purposes. Also note that this value is only valid until the thread terminates and may be reused thereafter.

DEPRECATED: use selfIdAsUint64 instead.

◆ selfIdAsUint64()

bsls::Types::Uint64 bslmt::ThreadUtil::selfIdAsUint64 ( )

inlinestatic

Return an integral identifier that can be used to uniquely identify the current thread within the current process. Note that this representation is particularly useful for logging purposes. Also note that this value is valid only until the thread terminates, and may be reused thereafter.

◆ setSpecific()

int bslmt::ThreadUtil::setSpecific	(	const Key &	key,
		const void *	value
	)

inlinestatic

Associate the specified thread-local value with the specified process-wide key. Return 0 on success, and a non-zero value otherwise. The value associated with a thread for a given key is 0 until it has been set by that thread using setSpecific. The behavior is undefined unless this method is called outside any thread key cleanup function associated with any key by createKey, key was obtained from a successful call to createKey, and key has not been deleted.

◆ setThreadName()

void bslmt::ThreadUtil::setThreadName ( const bslstl::StringRef & threadName )

inlinestatic

Set the name of the current thread to the specified threadName. On platforms other than Linux, Solaris, Darwin and Windows this method has no effect. Note that on those two platforms threadName will be truncated to a length of 15 bytes, not including the terminating '\0'.

◆ sleep() [1/2]

template<class REP_TYPE , class PERIOD_TYPE >

void bslmt::ThreadUtil::sleep ( const bsl::chrono::duration< REP_TYPE, PERIOD_TYPE > & sleepTime )

inlinestatic

Suspend execution of the current thread for a period of at least the specified (relative) sleepTime, or an interrupting signal is received. Note that the actual time suspended depends on many factors including system scheduling and system timer resolution.

◆ sleep() [2/2]

void bslmt::ThreadUtil::sleep ( const bsls::TimeInterval & sleepTime )

inlinestatic

Suspend execution of the current thread for a period of at least the specified (relative) sleepTime, or an interrupting signal is received. Note that the actual time suspended depends on many factors including system scheduling and system timer resolution.

◆ sleepUntil() [1/2]

template<class CLOCK , class DURATION >

void bslmt::ThreadUtil::sleepUntil ( const bsl::chrono::time_point< CLOCK, DURATION > & absoluteTime )

static

Suspend execution of the current thread until the specified absoluteTime, which is an absolute time represented as an interval from some epoch, determined by the clock associated with the time point. The behavior is undefined unless absoluteTime represents a time after January 1, 1970 and before the end of December 31, 9999. Note that the actual time suspended depends on many factors including system scheduling and system timer resolution.

◆ sleepUntil() [2/2]

void bslmt::ThreadUtil::sleepUntil	(	const bsls::TimeInterval &	absoluteTime,
		bsls::SystemClockType::Enum	clockType = `bsls::SystemClockType::e_REALTIME`
	)

inlinestatic

Suspend execution of the current thread until the specified absoluteTime, or an interrupting signal is received. Optionally specify clockType which determines the epoch from which the interval absoluteTime is measured (see {Supported Clock-Types} in the component documentation). The behavior is undefined unless absoluteTime represents a time after January 1, 1970 and before the end of December 31, 9999 (i.e., a time interval greater than or equal to 0, and less than 253,402,300,800 seconds). Note that the actual time suspended depends on many factors including system scheduling and system timer resolution.

◆ yield()

void bslmt::ThreadUtil::yield ( )

inlinestatic

Move the current thread to the end of the scheduler's queue and schedule another thread to run. Note that this allows cooperating threads of the same priority to share CPU resources equally.

The documentation for this struct was generated from the following file:

bslmt_threadutil.h

Public Types

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ Destructor

◆ Handle

◆ Id

◆ Imp

◆ Key

◆ NativeHandle

◆ ThreadFunction

Member Function Documentation

◆ areEqual()

◆ areEqualId()

◆ convertToSchedulingPriority()

◆ create() [1/4]

◆ create() [2/4]

◆ create() [3/4]

◆ create() [4/4]

◆ createKey()

◆ createWithAllocator() [1/4]

◆ createWithAllocator() [2/4]

◆ createWithAllocator() [3/4]

◆ createWithAllocator() [4/4]

◆ deleteKey()

◆ detach()

◆ exit()

◆ getMaxSchedulingPriority()

◆ getMinSchedulingPriority()

◆ getSpecific()

◆ getThreadName()

◆ handleToId()

◆ hardwareConcurrency()

◆ idAsInt()

◆ idAsUint64()

◆ invalidHandle()

◆ isEqual()

◆ isEqualId()

◆ join()

◆ microSleep()

◆ nativeHandle()

◆ self()

◆ selfId()

◆ selfIdAsInt()

◆ selfIdAsUint64()

◆ setSpecific()

◆ setThreadName()

◆ sleep() [1/2]

◆ sleep() [2/2]

◆ sleepUntil() [1/2]

◆ sleepUntil() [2/2]

◆ yield()