3.13. Threading Functions

3.13.1. delete_all_thread_data()

Synopsis

Deletes all keys in the thread-local data hash.

Usage
delete_all_thread_data()
Example
delete_all_thread_data();
Restrictions

Not available with PO_NO_THREAD_CONTROL

Table 3.372. Arguments and Return Values for delete_all_thread_data()

Argument Type

Return Type

Description

n/a

n/a

Deletes all keys in the thread-local data hash.


This function does not throw any exceptions.

3.13.2. delete_thread_data()

Synopsis

Deletes the data associated to one or more keys in the thread-local data hash; if the data is an object, then it is destroyed. See remove_thread_data() for a similar function that does not explicitly destroy objects in the thread-local data hash.

Usage
delete_thread_data(key_string, [key_string, ...])
Example
delete_thread_data("key1", "key2");
Restrictions

Not available with PO_NO_THREAD_CONTROL

Table 3.373. Arguments and Return Values for delete_thread_data()

Arguments

Return Values

Description

String, [String ...]

n/a

Deletes the data associated to one or more keys in the thread-local data hash.


This function does not throw any exceptions, however any objects deleted could throw exceptions in their destructors.

3.13.3. get_all_thread_data()

Synopsis

Returns the entire thread-local data hash.

Usage
get_all_thread_data()
Example
$hash = get_all_thread_data();
Restrictions

Not available with PO_NO_THREAD_CONTROL

Table 3.374. Arguments and Return Values for get_all_thread_data()

Argument Type

Return Type

Description

n/a

Hash

Returns the entire thread-local data hash.


This function does not throw any exceptions.

3.13.4. getAllThreadCallStacks()

Synopsis

Returns a hash of call stacks keyed by each TID (thread ID). The availability of this function depends on an optional debugging feature in the Qore library (maintaining run-time thread call stacks incurrs a performance penalty, therefore this option is normally only available in debugging builds of Qore); the function is only available if the constant HAVE_RUNTIME_THREAD_STACK_TRACE is True. See Library Option Constants for a list of all option constants.

Usage
getAllThreadCallStacks()
Example
$hash = getAllThreadCallStacks();
Restrictions

Not available with PO_NO_THREAD_CONTROL

Table 3.375. Arguments and Return Values for getAllThreadCallStacks()

Argument Type

Return Type

Description

n/a

Hash

Returns a hash of call stacks keyed by each TID (thread ID). See Call Stack Description for a description of the call stack format.


Table 3.376. Exceptions Thrown by getAllThreadCallStacks()

err

desc

MISSING-FEATURE-ERROR

This exception is thrown when the function is not available; for maximum portability, check the constant HAVE_RUNTIME_THREAD_STACK_TRACE before calling this function.


3.13.5. get_thread_data()

Synopsis

Returns the value of the thread-local data attached to the key passed.

Usage
get_thread_data(key_string)
Example
$data = get_thread_data("key1");
Restrictions

Not available with PO_NO_THREAD_CONTROL

Table 3.377. Arguments and Return Values for get_thread_data()

Argument Type

Return Type

Description

String

depends on key

Returns the value of the thread-local data attached to the key passed.


This function does not throw any exceptions.

3.13.6. gettid()

Synopsis

Returns the Qore thread ID (TID) of the current thread.

Usage
gettid()
Example
$tid = gettid();

Table 3.378. Arguments and Return Values for gettid()

Argument Type

Return Type

Description

n/a

Integer

Returns the Qore thread ID (TID) of the current thread.


This function does not throw any exceptions.

3.13.7. num_threads()

Synopsis

Returns the current number of threads in the process (not including the special signal handling thread).

Usage
num_threads()
Example
$num = num_threads();

Table 3.379. Arguments and Return Values for num_threads()

Argument Type

Return Type

Description

n/a

Integer

Returns the current number of threads in the process.


This function does not throw any exceptions.

3.13.8. remove_thread_data()

Synopsis

Removes the data associated to one or more keys in the thread-local data hash. For a similar function that also explicitly destroys objects, see delete_thread_data.

Usage
remove_thread_data(key_string, [key_string, ...])
Example
remove_thread_data("key1", "key2");
Restrictions

Not available with PO_NO_THREAD_CONTROL

Table 3.380. Arguments and Return Values for remove_thread_data()

Arguments

Return Values

Description

String, [String ...]

n/a

Removes the data associated to one or more keys in the thread-local data hash.


This function does not throw any exceptions.

3.13.9. save_thread_data()

Synopsis

Saves the data passed against the key passed in thread-local storage.

Usage
save_thread_data(key_string, value_expression)
Example
save_thread_data("key1", $value);
Restrictions

Not available with PO_NO_THREAD_CONTROL

Table 3.381. Arguments and Return Values for save_thread_data()

Argument Type

Return Type

Description

String, Any

n/a

Saves the data passed against the key passed in thread-local storage.


This function does not throw any exceptions.

3.13.10. thread_list()

Synopsis

Returns a list of all current thread IDs. Note that the special signal handling thread with TID 0 is never included in this list.

Usage
thread_list()
Example
$list = thread_list();

Table 3.382. Arguments and Return Values for thread_list()

Argument Type

Return Type

Description

n/a

List

Returns a list of all current thread IDs


This function does not throw any exceptions.

3.13.11. throwThreadResourceExceptions()

Synopsis

Immediately runs all thread resource cleanup routines for the current thread and throws all associated exceptions. This function is particularly useful when used in combination with embedded code in order to catch (and log, for example) thread resource errors (ex: uncommitted transactions, unlocked locks, etc).

Usage
throwThreadResourceExceptions()
Example
try {
    throwThreadResourceExceptions();
}
catch ($ex)
{
    # ... log or handle exceptions
}
Restrictions

Not available with PO_NO_THREAD_CONTROL

Table 3.383. Arguments and Return Values for throwThreadResourceExceptions()

Argument Type

Return Type

Description

n/a

n/a

This function returns no value.


This function can throw any exception thrown by a thread resource handler.