Architecture-specific thread function calls. More...

Include dependency graph for threads.h:

This graph shows which files directly or indirectly include this file:

Macros
#define	ARCH_SPIN_PAUSE()
	ARCH_SPIN_PAUSE – 'pause' on x86, 'yield' on arm.

Enumerations
enum	ArchThreadPriority { ArchThreadPriorityLowest , ArchThreadPriorityLow }
	Specifies a reduced-priority level for ArchSetThisThreadPriority(). More...

Functions
ARCH_API bool	ArchIsMainThread ()
	Return true if the calling thread is the main thread, false otherwise.

ARCH_API std::thread::id	ArchGetMainThreadId ()
	Return the std::thread_id for the thread arch considers to be the "main" thread.

ARCH_API bool	ArchSetThisThreadName (char const *name)
	Set the name of the calling thread as UTF-8 text.

ARCH_API std::string	ArchGetThisThreadName ()
	Return the name of the calling thread as a UTF-8 string, as previously set either by ArchSetThisThreadName() or by another entity calling the underlying OS thread naming APIs.

ARCH_API bool	ArchSetThisThreadPriority (ArchThreadPriority priority)
	Lower the priority of the calling thread to `priority`.

Detailed Description

Architecture-specific thread function calls.

Definition in file threads.h.

Macro Definition Documentation

◆ ARCH_SPIN_PAUSE

#define ARCH_SPIN_PAUSE ( )

ARCH_SPIN_PAUSE – 'pause' on x86, 'yield' on arm.

Definition at line 125 of file threads.h.

Enumeration Type Documentation

◆ ArchThreadPriority

enum ArchThreadPriority

Specifies a reduced-priority level for ArchSetThisThreadPriority().

Enumerators are ordered ascending by priority, so 'a < b' means "a is lower priority than b".

Enumerator

ArchThreadPriorityLowest

Idle priority.

The thread runs only when no other thread wants the core. Appropriate for work that must never interfere with foreground activity.

ArchThreadPriorityLow

Below-normal priority.

The thread yields to normal-priority threads but still competes actively for CPU time.

Definition at line 84 of file threads.h.

Function Documentation

◆ ArchGetMainThreadId()

ARCH_API std::thread::id ArchGetMainThreadId ( )

Return the std::thread_id for the thread arch considers to be the "main" thread.

◆ ArchGetThisThreadName()

ARCH_API std::string ArchGetThisThreadName ( )

Return the name of the calling thread as a UTF-8 string, as previously set either by ArchSetThisThreadName() or by another entity calling the underlying OS thread naming APIs.

Return an empty string if the name cannot be retrieved.

Note: A thread that was never explicitly named does not necessarily have an empty name. On Linux a thread's name defaults to the executable's basename, and a newly created thread inherits its creator's name.; Conversely, some platforms provide no way to read a name back, so this can return an empty string even immediately after ArchSetThisThreadName() succeeded. WASM is an example: Emscripten offers a set but no corresponding get.

◆ ArchSetThisThreadName()

ARCH_API bool ArchSetThisThreadName ( char const * name )

Set the name of the calling thread as UTF-8 text.

The name is typically visible in debuggers and OS tools. Return true if the name was set, possibly after truncation (see below). Return false if name is null, if the OS rejected the name, or if the platform provides no thread naming facility.

Note: Only call this on threads that your code created or explicitly owns. Calling this on your caller's thread (especially in library code) or on a shared worker thread is inadvisable. For example, TBB reuses worker threads across tasks, so a name set in one task will persist on that thread after the task completes, misleading debuggers and profilers for all subsequent work scheduled onto it.; Names are truncated to a platform-specific byte limit imposed by the underlying API: 15 bytes on Linux, 63 bytes on MacOS, and 31 bytes on WASM, none counting the null terminator. Linux and MacOS reject an over-long name outright; Emscripten cuts one on a byte boundary, which can split a multi-byte character. In all three cases we truncate first, at a UTF-8 character boundary so the result remains valid UTF-8, which means ArchGetThisThreadName() may return a shorter name than the one passed here. No truncation is applied on Windows.; On WASM the name is recorded only in builds that enable Emscripten's thread profiler (–threadprofiler). Without it, the underlying call is a documented no-op, so this returns false in that case.

◆ ArchSetThisThreadPriority()

ARCH_API bool ArchSetThisThreadPriority ( ArchThreadPriority priority )

Lower the priority of the calling thread to priority.

Return true if the priority was successfully changed, false if the thread is already at or below the requested level, if the request failed, or if the platform has no thread priority facility. This is a one-way operation – there is no facility to raise priority back to the inherited default, and calling this function will never raise priority above the current level.

Note: WASM has no thread priority facility, so this always returns false there. Threads are Web Workers, which expose no priority control.; Only call this on threads that your code created or explicitly owns. See ArchSetThisThreadName() for the same rationale.

Macros

Enumerations

Functions