3.13. Threading Functions

3.13. Threading Functions
Prev	Chapter 3. Function Library	Next

3.13.1. delete_all_thread_data()

Synopsis

Deletes all keys in the thread-local data hash.

Prototype

delete_all_thread_data()

Example

delete_all_thread_data();

Restrictions

Not available with PO_NO_THREAD_CONTROL

Table 3.440. 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.

Prototype

nothingdelete_thread_data(list)

nothingdelete_thread_data(...)

Example

delete_thread_data("key1", "key2");
delete_thread_data($list_of_strings);

Restrictions

Not available with PO_NO_THREAD_CONTROL

Table 3.441. Arguments and Return Values for delete_thread_data()

Arguments	Return Values	Description
`list`	n/a	Deletes the data associated to one or more keys in the thread-local data hash corresponding to the elements of the list converted to a string (if necessary).
`...`	n/a	Deletes the data associated to one or more keys in the thread-local data hash corresonding to each string argument in the top-level argument list; arguments are converted to strings if necessary.

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.

Prototype

hashget_all_thread_data() (CONST)

Example

$hash = get_all_thread_data();

Restrictions

Not available with PO_NO_THREAD_CONTROL or PO_NO_THREAD_INFO

Table 3.442. 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.
Prototype: hashgetAllThreadCallStacks()
Example: hashgetAllThreadCallStacks()
Platform Availability: HAVE_RUNTIME_THREAD_STACK_TRACE
Restrictions: Not available with PO_NO_THREAD_CONTROL or PO_NO_THREAD_INFO

Table 3.443. 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.444. 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.

Prototype

anyget_thread_data(string) (CONST)

nothingget_thread_data() (RT_NOOP)

Example

$data = get_thread_data("key1");

Restrictions

Not available with PO_NO_THREAD_CONTROL or PO_NO_THREAD_INFO

Table 3.445. Arguments and Return Values for get_thread_data()

Argument Type	Return Type	Description
`string`	`any`	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.

Prototype

intgettid() (CONST)

Example

$tid = gettid();

Restrictions

Not available with PO_NO_THREAD_INFO

Table 3.446. Arguments and Return Values for gettid()

Argument Type	Return Type	Description
n/a	`int`	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).

Prototype

intnum_threads() (CONST)

Example

$num = num_threads();

Restrictions

Not available with PO_NO_THREAD_INFO

Table 3.447. Arguments and Return Values for num_threads()

Argument Type	Return Type	Description
n/a	`int`	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.

Prototype

nothingremove_thread_data(list)

nothingremove_thread_data(...)

Example

remove_thread_data("key1", "key2");
remove_thread_data($list_of_strings);

Restrictions

Not available with PO_NO_THREAD_CONTROL

Table 3.448. Arguments and Return Values for remove_thread_data()

Arguments	Return Values	Description
`list`	n/a	Removes the data associated to one or more keys in the thread-local data hash corresponding to the elements of the list converted to a string (if necessary).
`...`	n/a	Removes the data associated to one or more keys in the thread-local data hash corresonding to each string argument in the top-level argument list; arguments are converted to strings if necessary.

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.

Prototype

nothingsave_thread_data(hash$hash)

nothingsave_thread_data(string$key, any$value)

nothingsave_thread_data() (RT_NOOP)

Example

save_thread_data("key1", $value);

Restrictions

Not available with PO_NO_THREAD_CONTROL

Table 3.449. Arguments and Return Values for save_thread_data()

Argument Type	Return Type	Description
`string$key, any$value`	n/a	Saves the data passed against the key passed in thread-local storage.
`hash$hash`	n/a	Saves the data passed in the hash giving key-value pairs in thread-local storage; the hash argument is added to the therad-local data, replacing any keys already present in the thread-local data.

This function does not throw any exceptions, however if a value is removed from the thread-local data hash by being overwritten with a new value, and the value is an object that goes out of scope, then such an object could throw an exception in its destructor.

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.

Prototype

listthread_list() (CONST)

Example

$list = thread_list();

Restrictions

Not available with PO_NO_THREAD_INFO

Table 3.450. 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).

Prototype

nothingthrowThreadResourceExceptions()

Example

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

Restrictions

Not available with PO_NO_THREAD_CONTROL

Table 3.451. 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.

Prev	Up	Next
3.12. Miscellaneous Functions	Home	3.14. Debug Functions