Qore Programming Language Reference Manual  0.8.12.11
 All Classes Namespaces Functions Variables Groups Pages
Threading Functions

Functions

nothing Qore::delete_all_thread_data ()
 Deletes all keys in the thread-local data hash. More...
 
nothing Qore::delete_thread_data (...)
 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. More...
 
nothing Qore::delete_thread_data (list l)
 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. More...
 
hash Qore::getAllThreadCallStacks ()
 Returns a hash of call stacks keyed by each TID (thread ID) More...
 
hash Qore::get_all_thread_call_stacks ()
 Returns a hash of call stacks keyed by each TID (thread ID) More...
 
hash Qore::get_all_thread_data ()
 Returns the entire thread-local data hash. More...
 
any Qore::get_thread_data (string key)
 Returns the value of the thread-local data attached to the key passed. More...
 
nothing Qore::get_thread_data ()
 This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
 
*TimeZone Qore::get_thread_tz ()
 Returns any TimeZone set for the current thread, NOTHING if none is set. More...
 
int Qore::gettid ()
 Returns the Qore thread ID (TID) of the current thread. More...
 
nothing Qore::mark_thread_resources ()
 Marks thread resources so that any thread resources left allocated after this call will be cleaned up when throw_thread_resource_exceptions_to_mark() is called. More...
 
int Qore::num_threads ()
 Returns the current number of threads in the process (not including the special signal handling thread) More...
 
*hash Qore::remove_thread_data (...)
 Removes the data associated to one or more keys in the thread-local data hash and returns the data removed. More...
 
hash Qore::remove_thread_data (list l)
 Removes the data associated to one or more keys in the thread-local data hash from a literal list passed as the first argument and returns the data removed. More...
 
bool Qore::remove_thread_resource (AbstractThreadResource resource)
 removes a thread resource from the current thread More...
 
bool Qore::remove_thread_resource (code resource)
 removes a callable thread resource from the current thread More...
 
nothing Qore::save_thread_data (hash h)
 Saves the data passed in the thread-local hash; all keys are merged into the thread-local hash, overwriting any information that may have been there before. More...
 
nothing Qore::save_thread_data (string key, any value)
 Saves the data passed against the key passed as an argument in thread-local storage. More...
 
nothing Qore::save_thread_data ()
 This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
 
bool Qore::set_thread_init (code init)
 Sets a call reference or closure to run every time a new thread is started. More...
 
nothing Qore::set_thread_resource (AbstractThreadResource resource)
 sets a thread resource for the current thread More...
 
nothing Qore::set_thread_resource (code resource, any arg)
 sets a callable thread resource for the current thread with an optional argument More...
 
nothing Qore::set_thread_tz (TimeZone zone)
 Sets the default time zone for the current thread. More...
 
nothing Qore::set_thread_tz ()
 Clears the thread-local time zone for the current thread; after this call TimeZone::get() will return the value set for the current Program. More...
 
list Qore::thread_list ()
 Returns a list of all current thread IDs. More...
 
nothing Qore::throwThreadResourceExceptions ()
 Immediately runs all thread resource cleanup routines for the current thread and throws all associated exceptions. More...
 
nothing Qore::throw_thread_resource_exceptions ()
 Immediately runs all thread resource cleanup routines for the current thread and throws all associated exceptions. More...
 
bool Qore::throw_thread_resource_exceptions_to_mark ()
 Immediately runs all thread resource cleanup routines for the current thread for thread resources created since the last call to mark_thread_resources() and throws all associated exceptions. More...
 

Detailed Description

Threading functions

Function Documentation

nothing Qore::delete_all_thread_data ( )

Deletes all keys in the thread-local data hash.

Restrictions:
Qore::PO_NO_THREAD_CONTROL
Example:
Note
This function does not throw any exceptions, however if an object is deleted from the thread-local data hash, then it could throw an exception in its destructor
nothing Qore::delete_thread_data (   ...)

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.

Restrictions:
Qore::PO_NO_THREAD_CONTROL
Parameters
...Deletes the data associated to one or more keys in the thread-local data hash corresponding to each string argument in the top-level argument list; arguments are converted to strings if necessary
Example:
1 delete_thread_data("key1", "key2");
Note
This function does not throw any exceptions, however if an object is deleted from the thread-local data hash, then it could throw an exception in its destructor
See Also
remove_thread_data() for a similar function that does not explicitly destroy objects in the thread-local data hash
nothing Qore::delete_thread_data ( list  l)

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.

Restrictions:
Qore::PO_NO_THREAD_CONTROL
Parameters
la list of key names for deleting keys in the thread-local data hash; values are converted to strings if necessary
Example:
1 delete_thread_data(list_of_keys);
Note
This function does not throw any exceptions, however if an object is deleted from the thread-local data hash, then it could throw an exception in its destructor
See Also
remove_thread_data() for a similar function that does not explicitly destroy objects in the thread-local data hash
hash Qore::get_all_thread_call_stacks ( )

Returns a hash of call stacks keyed by each TID (thread ID)

Platform Availability:
Qore::Option::HAVE_RUNTIME_THREAD_STACK_TRACE
Restrictions:
Qore::PO_NO_THREAD_CONTROL, Qore::PO_NO_THREAD_INFO
Returns
a hash of call stacks keyed by each TID (thread ID); see call stacks for the format of the hash values
Example:
2 foreach string tid in (cs.keyIterator()) {
3  printf("TID %d\n", tid);
4  int i;
5  foreach hash l in (cs{tid})
6  if (l.type != "new-thread")
7  printf(" %d: %s() called at %s:%d (%s function)\n", ++i, l.function, l.file, l.line, l.type);
8  else
9  printf(" %d: *** thread started by background operator ***\n", ++i);
10 }
Since
Qore 0.8.12 as a replacement for deprecated camel-case getAllThreadCallStacks()
hash Qore::get_all_thread_data ( )

Returns the entire thread-local data hash.

Returns
the entire thread-local data hash
Restrictions:
Qore::PO_NO_THREAD_CONTROL, Qore::PO_NO_THREAD_INFO
Code Flags:
RET_VALUE_ONLY
Example:
1 hash th = get_all_thread_data();
Note
this function is not flagged with CONSTANT since its value could change at runtime
any Qore::get_thread_data ( string  key)

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

Returns
the value of the thread-local data attached to the key passed
Restrictions:
Qore::PO_NO_THREAD_CONTROL, Qore::PO_NO_THREAD_INFO
Code Flags:
RET_VALUE_ONLY
Example:
1 any data = get_thread_data("key1");
Note
this function is not flagged with CONSTANT since its value could change at runtime
nothing Qore::get_thread_data ( )

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Restrictions:
Qore::PO_NO_THREAD_CONTROL, Qore::PO_NO_THREAD_INFO
Code Flags:
RUNTIME_NOOP
*TimeZone Qore::get_thread_tz ( )

Returns any TimeZone set for the current thread, NOTHING if none is set.

Returns
any TimeZone set for the current thread, NOTHING if none is set
Restrictions:
Qore::PO_NO_LOCALE_CONTROL
Example:
1 *TimeZone tz = get_thread_tz();
2 set_thread_tz(new TimeZone("Europe/Prague"));
3 on_exit set_thread_tz(tz);
See Also
Since
Qore 0.8.5
hash Qore::getAllThreadCallStacks ( )

Returns a hash of call stacks keyed by each TID (thread ID)

Platform Availability:
Qore::Option::HAVE_RUNTIME_THREAD_STACK_TRACE
Restrictions:
Qore::PO_NO_THREAD_CONTROL, Qore::PO_NO_THREAD_INFO
Code Flags:
DEPRECATED
Returns
a hash of call stacks keyed by each TID (thread ID); see call stacks for the format of the hash values
Deprecated:
use get_all_thread_call_stacks(); camel-case function names were deprecated in Qore 0.8.12
int Qore::gettid ( )

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

Returns
the Qore thread ID (TID) of the current thread
Restrictions:
Qore::PO_NO_THREAD_INFO
Code Flags:
RET_VALUE_ONLY
Example:
1 int tid = gettid();
Note
this function is not flagged with CONSTANT since its value could change at runtime
nothing Qore::mark_thread_resources ( )

Marks thread resources so that any thread resources left allocated after this call will be cleaned up when throw_thread_resource_exceptions_to_mark() is called.

When exceptions are thrown by this function, thread-local resources are also cleaned up at the same time.

Restrictions:
Qore::PO_NO_THREAD_CONTROL
Example:
1 try {
3 
4  # calling the following function will ensure that any thread-resources
5  # allocated since the last call to mark_thread_resources() will be cleaned
6  # up and associated exceptions will be thrown
8 
9  # ... some code or calls that may allocate thread resources
10 }
11 catch (ex) {
12  # ... log or handle exceptions
13 }
See Also
Since
Qore 0.8.4
int Qore::num_threads ( )

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

Returns
the current number of threads in the process (not including the special signal handling thread)
Restrictions:
Qore::PO_NO_THREAD_INFO
Code Flags:
RET_VALUE_ONLY
Example:
1 int num = num_threads();
Note
this function is not flagged with CONSTANT since its value could change at runtime
*hash Qore::remove_thread_data (   ...)

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

Restrictions:
Qore::PO_NO_THREAD_CONTROL
Parameters
...the key names should be given directly in the argument list with this variant. If the given hash keys do not exist in the thread-local data hash, then the given key in the return value will have no value assigned
Returns
a hash of the data removed or NOTHING if no arguments were passed to the function
Example:
1 hash h = remove_thread_data("filename");
Since
Qore 0.8.4 this function returns the values it removes
hash Qore::remove_thread_data ( list  l)

Removes the data associated to one or more keys in the thread-local data hash from a literal list passed as the first argument and returns the data removed.

Restrictions:
Qore::PO_NO_THREAD_CONTROL
Parameters
la list of key names to remove from the thread-local data hash. If the given hash keys do not exist in the thread-local data hash, then the given key in the return value will have no value assigned
Returns
a hash of the data removed
Example:
1 hash h = remove_thread_data(key_list);
Since
Qore 0.8.4 this function returns the values it removes
bool Qore::remove_thread_resource ( AbstractThreadResource  resource)

removes a thread resource from the current thread

Restrictions:
Qore::PO_NO_THREAD_CONTROL
Example:
Parameters
resourcethe thread resource to remove
Returns
True if the resource was removed, False if not
See Also
Since
Qore 0.8.12
bool Qore::remove_thread_resource ( code  resource)

removes a callable thread resource from the current thread

Restrictions:
Qore::PO_NO_THREAD_CONTROL
Example:
Parameters
resourcethe callable thread resource to remove
Returns
True if the resource was removed, False if not
See Also
Since
Qore 0.8.12
nothing Qore::save_thread_data ( hash  h)

Saves the data passed in the thread-local hash; all keys are merged into the thread-local hash, overwriting any information that may have been there before.

Restrictions:
Qore::PO_NO_THREAD_CONTROL
Parameters
ha hash of data to save in the thread-local data hash
Example:
Note
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
nothing Qore::save_thread_data ( string  key,
any  value 
)

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

Restrictions:
Qore::PO_NO_THREAD_CONTROL
Parameters
keythe name of the key in the thread-local hash to save the data against
valuethe value to save in the thread-local hash against the key
Example:
1 save_thread_data("key1", value);
Note
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
nothing Qore::save_thread_data ( )

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Restrictions:
Qore::PO_NO_THREAD_CONTROL
Code Flags:
RUNTIME_NOOP
bool Qore::set_thread_init ( code  init)

Sets a call reference or closure to run every time a new thread is started.

This code can be used to initialize global thread-local variables, for example.

Returns
True if there was already user initialization code set, False if not
Restrictions:
Qore::PO_NO_THREAD_CONTROL
Example:
1 set_thread_init(sub () { var = 123; });
Note
the code will be run for all new threads, but is not run by this function for the current thread
nothing Qore::set_thread_resource ( AbstractThreadResource  resource)

sets a thread resource for the current thread

Restrictions:
Qore::PO_NO_THREAD_CONTROL
Example:
Parameters
resourcethe thread resource to set
See Also
Since
Qore 0.8.12
nothing Qore::set_thread_resource ( code  resource,
any  arg 
)

sets a callable thread resource for the current thread with an optional argument

Restrictions:
Qore::PO_NO_THREAD_CONTROL
Example:
1 set_thread_resource(\func(), code);
Parameters
resourcethe thread resource handler to set
argan argument to use when calling the thread resource handler
See Also
Since
Qore 0.8.12
nothing Qore::set_thread_tz ( TimeZone  zone)

Sets the default time zone for the current thread.

Restrictions:
Qore::PO_NO_LOCALE_CONTROL
Parameters
zonethe TimeZone object for the current thread

This will cause the TimeZone::get() method to return the given TimeZone when called from the same thread

Example:
1 *TimeZone tz = get_thread_tz();
2 set_thread_tz(new TimeZone("Europe/Prague"));
3 on_exit set_thread_tz(tz);
Note
The TimeZone will only be set for the current thread in the current Program
See Also
Since
Qore 0.8.5
nothing Qore::set_thread_tz ( )

Clears the thread-local time zone for the current thread; after this call TimeZone::get() will return the value set for the current Program.

Restrictions:
Qore::PO_NO_LOCALE_CONTROL
Example:
1 *TimeZone tz = get_thread_tz();
2 set_thread_tz(new TimeZone("Europe/Prague"));
3 on_exit set_thread_tz(tz);
Note
The TimeZone will only be cleared in the current thread in the current Program
See Also
Since
Qore 0.8.5
list Qore::thread_list ( )

Returns a list of all current thread IDs.

Note that the special signal handling thread with TID 0 is never included in the list returned by this function

Returns
a list of all current thread IDs
Restrictions:
Qore::PO_NO_THREAD_INFO
Code Flags:
RET_VALUE_ONLY
Example:
1 list l = thread_list();
Note
this function is not flagged with CONSTANT since its value could change at runtime
nothing Qore::throw_thread_resource_exceptions ( )

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) - this can be used when control returns to the "master" program to ensure that no thread-local resources have been left active.

This function will run all thread resource cleanup routines even if mark_thread_resources() has been called (i.e. it clears all marks as well).

When exceptions are thrown by this function, thread-local resources are also cleaned up at the same time.

Restrictions:
Qore::PO_NO_THREAD_CONTROL
Example:
1 try {
3 }
4 catch (ex) {
5  # ... log or handle exceptions
6 }
Note
may not throw an exception even if there are thread resources in place that get cleaned up in case the Qore::Thread::AbstractThreadResource::cleanup() method performs the cleanup but does not throw an exception
See Also
Since
Qore 0.8.12 as a replacement for deprecated camel-case throwThreadResourceExceptions()
bool Qore::throw_thread_resource_exceptions_to_mark ( )

Immediately runs all thread resource cleanup routines for the current thread for thread resources created since the last call to mark_thread_resources() and throws all associated exceptions.

When exceptions are thrown by this function, thread-local resources are also cleaned up at the same time.

Returns
True if there are additional thread resource marks to process, False if there are no more
Restrictions:
Qore::PO_NO_THREAD_CONTROL
Example:
1 try {
3  # ... some code or calls that may allocate thread resources
4 
5  # calling the following will ensure that any thread-resources allocated since
6  # the last call to mark_thread_resources() will be cleaned up and associated
7  # exceptions will be thrown
9 }
10 catch (ex) {
11  # ... log or handle exceptions
12 }
Note
may not throw an exception even if there are thread resources in place that get cleaned up in case the Qore::Thread::AbstractThreadResource::cleanup() method performs the cleanup but does not throw an exception
See Also
Since
Qore 0.8.4
nothing Qore::throwThreadResourceExceptions ( )

Immediately runs all thread resource cleanup routines for the current thread and throws all associated exceptions.

Restrictions:
Qore::PO_NO_THREAD_CONTROL
Code Flags:
DEPRECATED

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) - this can be used when control returns to the "master" program to ensure that no thread-local resources have been left active.

This function will run all thread resource cleanup routines even if mark_thread_resources() has been called (i.e. it clears all marks as well).

When exceptions are thrown by this function, thread-local resources are also cleaned up at the same time.

See Also
Deprecated:
use throw_thread_resource_exceptions(); camel-case function names were deprecated in Qore 0.8.12