[#BloombergLP-bslmt-ThreadUtil]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bslmt.adoc[bslmt]::ThreadUtil
:relfileprefix: ../../
:mrdocs:

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

== Synopsis

Declared in `<bslmt_threadutil.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
struct ThreadUtil;
----

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bslmt/ThreadUtil/Destructor.adoc[`Destructor`] 
| Prototype for thread‐specific key destructors.
| xref:BloombergLP/bslmt/ThreadUtil/Handle.adoc[`Handle`] 
| Thread handle type. Use this type to refer to a thread in a platform‐independent way.
| xref:BloombergLP/bslmt/ThreadUtil/Id.adoc[`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.
| xref:BloombergLP/bslmt/ThreadUtil/Imp.adoc[`Imp`] 
| Platform‐specific implementation type.
| xref:BloombergLP/bslmt/ThreadUtil/Key.adoc[`Key`] 
| Thread‐specific key type, used to refer to thread‐specific storage.
| xref:BloombergLP/bslmt/ThreadUtil/NativeHandle-0a.adoc[`NativeHandle`] 
| Platform‐specific thread handle type.
| xref:BloombergLP/bslmt/ThreadUtil/ThreadFunction.adoc[`ThreadFunction`] 
| Prototype for thread entry‐point functions.
|===


== Static Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bslmt/ThreadUtil/areEqual.adoc[`areEqual`] 
| 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`.
| xref:BloombergLP/bslmt/ThreadUtil/areEqualId.adoc[`areEqualId`] 
| Return `true` if the specified `a` thread identifier is associated with the same thread as the specified `b` thread identifier, and `false` otherwise.
| xref:BloombergLP/bslmt/ThreadUtil/convertToSchedulingPriority.adoc[`convertToSchedulingPriority`] 
| 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 ]`.
| xref:BloombergLP/bslmt/ThreadUtil/create-0e78.adoc[`create`] 
| `create` overloads
| xref:BloombergLP/bslmt/ThreadUtil/createKey.adoc[`createKey`] 
| 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.
| xref:BloombergLP/bslmt/ThreadUtil/createWithAllocator-0a.adoc[`createWithAllocator`] 
| `createWithAllocator` overloads
| xref:BloombergLP/bslmt/ThreadUtil/deleteKey.adoc[`deleteKey`] 
| 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.
| xref:BloombergLP/bslmt/ThreadUtil/detach.adoc[`detach`] 
| "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.
| xref:BloombergLP/bslmt/ThreadUtil/exit.adoc[`exit`] 
| 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.
| xref:BloombergLP/bslmt/ThreadUtil/getMaxSchedulingPriority.adoc[`getMaxSchedulingPriority`] 
| 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.
| xref:BloombergLP/bslmt/ThreadUtil/getMinSchedulingPriority.adoc[`getMinSchedulingPriority`] 
| 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.
| xref:BloombergLP/bslmt/ThreadUtil/getSpecific.adoc[`getSpecific`] 
| 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.
| xref:BloombergLP/bslmt/ThreadUtil/getThreadName.adoc[`getThreadName`] 
| 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.
| xref:BloombergLP/bslmt/ThreadUtil/handleToId.adoc[`handleToId`] 
| 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.
| xref:BloombergLP/bslmt/ThreadUtil/hardwareConcurrency.adoc[`hardwareConcurrency`] 
| Return a _hint_ at the number of concurrent threads supported by this platform on success, and 0 otherwise.
| xref:BloombergLP/bslmt/ThreadUtil/idAsInt.adoc[`idAsInt`] 
| 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.
| xref:BloombergLP/bslmt/ThreadUtil/idAsUint64.adoc[`idAsUint64`] 
| 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.
| xref:BloombergLP/bslmt/ThreadUtil/invalidHandle.adoc[`invalidHandle`] 
| Return a reference to the non‐modifiable `Handle` object that is guaranteed never to be a valid thread handle.
| xref:BloombergLP/bslmt/ThreadUtil/isEqual.adoc[`isEqual`] 
| 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`.
| xref:BloombergLP/bslmt/ThreadUtil/isEqualId.adoc[`isEqualId`] 
| Return `true` if the specified `lhs` thread identifier is associated with the same thread as the specified `rhs` thread identifier, and `false` otherwise.
| xref:BloombergLP/bslmt/ThreadUtil/isThreadLimitReached.adoc[`isThreadLimitReached`] 
| Counts down the limit counter set by `ThreadUtil::setThreadLimit`. Returns `true` if current thread creation attempt should be failed. Note that if the thread limit is reached, all future thread creation attempts will fail, unless the limit is reset by a call to `setThreadLimit`.
| xref:BloombergLP/bslmt/ThreadUtil/join.adoc[`join`] 
| 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`.
| xref:BloombergLP/bslmt/ThreadUtil/microSleep.adoc[`microSleep`] 
| 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.
| xref:BloombergLP/bslmt/ThreadUtil/nativeHandle-0c.adoc[`nativeHandle`] 
| 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`).
| xref:BloombergLP/bslmt/ThreadUtil/self.adoc[`self`] 
| 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).
| xref:BloombergLP/bslmt/ThreadUtil/selfId.adoc[`selfId`] 
| 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.
| xref:BloombergLP/bslmt/ThreadUtil/selfIdAsInt.adoc[`selfIdAsInt`] 
| 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.
| xref:BloombergLP/bslmt/ThreadUtil/selfIdAsUint64.adoc[`selfIdAsUint64`] 
| 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.
| xref:BloombergLP/bslmt/ThreadUtil/selfKernelIdAsUint64.adoc[`selfKernelIdAsUint64`] 
| Return an integral identifier that can be used to uniquely identify the kernel thread within the current process. Note that this identifier may be different from the identifier returned by `selfIdAsUint64()`. Also note that this value is valid only until the thread terminates, and may be reused thereafter. Also note that this method returns the kernel thread id only on the operating systems which implement that (on Windows, the thread ids returned by both methods are the same).
| xref:BloombergLP/bslmt/ThreadUtil/setSpecific.adoc[`setSpecific`] 
| 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.
| xref:BloombergLP/bslmt/ThreadUtil/setThreadLimit.adoc[`setThreadLimit`] 
| Enable a thread creation limit. If set to non‐zero value `n`'th thread creation will fail. The limit is disabled by setting the limit to 0. Only intended to be used in tests to inject thread creation errors. Note that this can be called multiple times to reset the thread limit, e.g. between subtests for example.
| xref:BloombergLP/bslmt/ThreadUtil/setThreadName.adoc[`setThreadName`] 
| 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'.
| xref:BloombergLP/bslmt/ThreadUtil/sleep-09.adoc[`sleep`] 
| 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.
| xref:BloombergLP/bslmt/ThreadUtil/sleepUntil-0be.adoc[`sleepUntil`] 
| `sleepUntil` overloads
| xref:BloombergLP/bslmt/ThreadUtil/yield.adoc[`yield`] 
| 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.
|===



[.small]#Created with https://www.mrdocs.com[MrDocs]#