[#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&period;

== Synopsis

Declared in `&lt;bslmt&lowbar;threadutil&period;h&gt;`

[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&hyphen;specific key destructors&period;
| xref:BloombergLP/bslmt/ThreadUtil/Handle.adoc[`Handle`] 
| Thread handle type&period; Use this type to refer to a thread in a platform&hyphen;independent way&period;
| xref:BloombergLP/bslmt/ThreadUtil/Id.adoc[`Id`] 
| Thread identifier type &hyphen; distinguished from a `Handle` in that it does not have any resources associated with it, whereas `Handle` may, depending on platform&period;
| xref:BloombergLP/bslmt/ThreadUtil/Imp.adoc[`Imp`] 
| Platform&hyphen;specific implementation type&period;
| xref:BloombergLP/bslmt/ThreadUtil/Key.adoc[`Key`] 
| Thread&hyphen;specific key type, used to refer to thread&hyphen;specific storage&period;
| xref:BloombergLP/bslmt/ThreadUtil/NativeHandle-0a.adoc[`NativeHandle`] 
| Platform&hyphen;specific thread handle type&period;
| xref:BloombergLP/bslmt/ThreadUtil/ThreadFunction.adoc[`ThreadFunction`] 
| Prototype for thread entry&hyphen;point functions&period;
|===


== 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&period; Note that if _either_ of `a` or `b` is an invalid handle, but not both, this method returns `false`&period;
| 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&period;
| xref:BloombergLP/bslmt/ThreadUtil/convertToSchedulingPriority.adoc[`convertToSchedulingPriority`] 
| Return an integer scheduling priority appropriate for the specified `normalizedSchedulingPriority` and the specified `policy`&period; If either the minimum or maximum priority for this platform cannot be determined, return `ThreadAttributes&colon;&colon;e&lowbar;UNSET&lowbar;PRIORITY`&period; Higher values of `normalizedSchedulingPriority` are considered to represent more urgent priorities&period; The behavior is undefined unless `policy` is a valid `ThreadAttributes&colon;&colon;SchedulingPolicy` and `normalizedSchedulingPriority` is in the range `&lsqb; 0&period;0, 1&period;0 &rsqb;`&period;
| 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&hyphen;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&hyphen;zero and the value associated with `key` for that thread is non&hyphen;zero, with the associated value as an argument, after the function passed to `create` has returned and before the thread terminates&period; Return 0 on success, and a non&hyphen;zero value otherwise&period; Note that multiple keys can be defined, which can result in multiple thread key cleanup functions being called for a given thread&period;
| 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`)&period; Return 0 on success, and a non&hyphen;zero value otherwise&period; The behavior is undefined unless `key` was obtained from a successful call to `createKey` and has not already been deleted&period; Note that deleting a key does not delete any data referred to by the pointer values associated with that key in any thread&period;
| xref:BloombergLP/bslmt/ThreadUtil/detach.adoc[`detach`] 
| &quot;Detach&quot; the thread identified by the specified `handle` such that when it terminates, the resources associated with that thread will automatically be reclaimed&period; The behavior is undefined unless `handle` was obtained by a call to `create` or `self`&period; Note that once a thread is &quot;detached&quot;, it is no longer possible to `join` the thread to retrieve its exit status&period;
| xref:BloombergLP/bslmt/ThreadUtil/exit.adoc[`exit`] 
| Exit the current thread and return the specified `status`&period; If the current thread is not &quot;detached&quot;, then a call to `join` must be made to reclaim any resources used by the thread, and to retrieve the exit status&period; Note that the preferred method of exiting a thread is to return from the entry point function&period;
| xref:BloombergLP/bslmt/ThreadUtil/getMaxSchedulingPriority.adoc[`getMaxSchedulingPriority`] 
| Return the maximum available priority for the specified `policy`, where `policy` is of type `ThreadAttributes&colon;&colon;SchedulingPolicy`&period; Return `ThreadAttributes&colon;&colon;e&lowbar;UNSET&lowbar;PRIORITY` if the maximum scheduling priority cannot be determined&period; Note that, for some platform &sol; policy combinations, `getMinSchedulingPriority(policy)` and `getMaxSchedulingPriority(policy)` return the same value&period;
| xref:BloombergLP/bslmt/ThreadUtil/getMinSchedulingPriority.adoc[`getMinSchedulingPriority`] 
| Return the minimum available priority for the specified `policy`, where `policy` is of type `ThreadAttributes&colon;&colon;SchedulingPolicy`&period; Return `ThreadAttributes&colon;&colon;e&lowbar;UNSET&lowbar;PRIORITY` if the minimum scheduling priority cannot be determined&period; Note that, for some platform &sol; policy combinations, `getMinSchedulingPriority(policy)` and `getMaxSchedulingPriority(policy)` return the same value&period;
| xref:BloombergLP/bslmt/ThreadUtil/getSpecific.adoc[`getSpecific`] 
| Return the thread&hyphen;local value associated with the specified `key`&period; 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`&period; 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&period;
| xref:BloombergLP/bslmt/ThreadUtil/getThreadName.adoc[`getThreadName`] 
| Load the name of the current thread into the specified `&ast;threadName`&period; Note that this method clears `&ast;threadName` on platforms other than Linux, Solaris, Darwin, and Windows&period;
| xref:BloombergLP/bslmt/ThreadUtil/handleToId.adoc[`handleToId`] 
| Return the unique identifier of the thread having the specified `threadHandle` within the current process&period; The behavior is undefined unless `handle` was obtained by a call to `create` or `self`&period; Note that this value is valid only until the thread terminates, and may be reused thereafter&period;
| 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&period;
| 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&period; Note that this representation is particularly useful for logging purposes&period; Also note that this value is only valid until the thread terminates and may be reused thereafter&period;
| 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&period; Note that this representation is particularly useful for logging purposes&period; Also note that this value is only valid until the thread terminates and may be reused thereafter&period;
| xref:BloombergLP/bslmt/ThreadUtil/invalidHandle.adoc[`invalidHandle`] 
| Return a reference to the non&hyphen;modifiable `Handle` object that is guaranteed never to be a valid thread handle&period;
| 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&period; Note that if _either_ of `a` or `b` is an invalid handle, but not both, this method returns `false`&period;
| 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&period;
| xref:BloombergLP/bslmt/ThreadUtil/isThreadLimitReached.adoc[`isThreadLimitReached`] 
| Counts down the limit counter set by `ThreadUtil&colon;&colon;setThreadLimit`&period; Returns `true` if current thread creation attempt should be failed&period; 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`&period;
| 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`&period; Return 0 on success, and a non&hyphen;zero value otherwise&period; If the optionally specified `status` is not 0, load into `&ast;status` the value returned by the function supplied at the creation of the thread identified by `threadHandle`&period; The behavior is undefined unless `threadHandle` was obtained by a call to `create`&period;
| 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&period; 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&period;
| xref:BloombergLP/bslmt/ThreadUtil/nativeHandle-0c.adoc[`nativeHandle`] 
| Return the platform&hyphen;specific identifier associated with the thread referred to by the specified `handle`&period; The behavior is undefined unless `handle` was obtained by a call to `create` or `self`&period; Note that the returned native handle may not be a globally unique identifier for the thread (see `selfIdAsUint`)&period;
| 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&period; 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)&period;
| xref:BloombergLP/bslmt/ThreadUtil/selfId.adoc[`selfId`] 
| Return an identifier that can be used to uniquely identify the current thread within the current process&period; Note that the identifier is only valid until the thread terminates and may be reused thereafter&period;
| 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&period; Note that this representation is particularly useful for logging purposes&period; Also note that this value is only valid until the thread terminates and may be reused thereafter&period;
| 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&period; Note that this representation is particularly useful for logging purposes&period; Also note that this value is valid only until the thread terminates, and may be reused thereafter&period;
| 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&period; Note that this identifier may be different from the identifier returned by `selfIdAsUint64()`&period; Also note that this value is valid only until the thread terminates, and may be reused thereafter&period; 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)&period;
| xref:BloombergLP/bslmt/ThreadUtil/setSpecific.adoc[`setSpecific`] 
| Associate the specified thread&hyphen;local `value` with the specified process&hyphen;wide `key`&period; Return 0 on success, and a non&hyphen;zero value otherwise&period; The value associated with a thread for a given key is 0 until it has been set by that thread using `setSpecific`&period; 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&period;
| xref:BloombergLP/bslmt/ThreadUtil/setThreadLimit.adoc[`setThreadLimit`] 
| Enable a thread creation limit&period; If set to non&hyphen;zero value `n`&apos;th thread creation will fail&period; The limit is disabled by setting the limit to 0&period; Only intended to be used in tests to inject thread creation errors&period; Note that this can be called multiple times to reset the thread limit, e&period;g&period; between subtests for example&period;
| xref:BloombergLP/bslmt/ThreadUtil/setThreadName.adoc[`setThreadName`] 
| Set the name of the current thread to the specified `threadName`&period; On platforms other than Linux, Solaris, Darwin and Windows this method has no effect&period; Note that on those two platforms `threadName` will be truncated to a length of 15 bytes, not including the terminating &apos;0&apos;&period;
| 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&period; Note that the actual time suspended depends on many factors including system scheduling and system timer resolution&period;
| 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&apos;s queue and schedule another thread to run&period; Note that this allows cooperating threads of the same priority to share CPU resources equally&period;
|===



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