Qore Programming Language 1.19.5
Loading...
Searching...
No Matches
qore_thread.h File Reference
#include <cstdio>
#include <pthread.h>
#include <functional>
Include dependency graph for qore_thread.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

hashdecl  q_user_tld
 data structure for user thread-local data More...
 
class  QoreForeignThreadHelper
 use this class to temporarily register and deregister a foreign thread to allow Qore code to be executed and the Qore library to be used from threads not created by the Qore library More...
 
class  ThreadCleanupList
 list of functions to be run when a thread ends; required for some external libraries that require explicit cleanup when a thread terminates More...
 

Macros

#define QFT_ERROR   -1
 error when calling q_register_foreign_thread()
 
#define QFT_OK   0
 OK response when calling q_register_foreign_thread()
 
#define QFT_REGISTERED   -2
 thread already registered when calling q_register_foreign_thread()
 

Typedefs

typedef void(* q_thread_t) (ExceptionSink *xsink, void *arg)
 pointer to a function that can be started with q_start_thread()
 
typedef void(* qtdest_t) (void *)
 pointer to a qore thread destructor function
 
typedef void(* qtrdest_t) (void *, ExceptionSink *)
 pointer to a qore thread resource destructor function
 

Functions

DLLEXPORT bool check_thread_resource (AbstractThreadResource *atr)
 check if a thread resouce has been saved More...
 
DLLEXPORT const AbstractQoreZoneInfo * currentTZ ()
 returns the current local time zone, note that if 0 = UTC
 
DLLEXPORT QoreProgramgetProgram ()
 returns the current QoreProgram
 
DLLEXPORT bool is_valid_qore_thread ()
 returns true if the current thread is a valid qore thread; it is not safe to call most Qore functions unless the thread is registered with Qore More...
 
DLLEXPORT int q_deregister_foreign_thread ()
 deregisters the current thread as a foreign thread More...
 
DLLEXPORT int q_deregister_reserved_foreign_thread ()
 deregisters a foreign qore thread but retains the TID as reserved More...
 
DLLEXPORT void * q_get_thread_local_data (int key)
 returns thread-local data More...
 
DLLEXPORT q_user_tldq_get_thread_local_data_all (int key)
 returns thread-local data More...
 
DLLEXPORT int q_get_unique_thread_local_data_key ()
 returns a unique ID to use with thread_local_data APIs More...
 
DLLEXPORT int q_gettid () noexcept
 returns the current TID number More...
 
DLLEXPORT int q_register_foreign_thread ()
 registers the current thread as a Qore thread More...
 
DLLEXPORT int q_register_reserved_foreign_thread (int tid)
 registers a foreign qore thread as a Qore thread with a reserved TID More...
 
DLLEXPORT int q_release_reserved_foreign_thread_id (int tid)
 releases a TID reserved with q_reserve_foreign_thread_id() More...
 
DLLEXPORT int q_remove_thread_local_data (int key, q_user_tld &data, bool run_destructor=true)
 returns and removes thread-local data More...
 
DLLEXPORT int q_reserve_foreign_thread_id ()
 reserves a thread ID for later registration and returns the TID reserved; use q_release_reserved_foreign_thread_id() to release the reservation More...
 
DLLEXPORT void q_save_thread_local_data (int key, void *data, q_thread_local_destructor destructor=nullptr)
 saves thread-local data More...
 
int q_start_thread (ExceptionSink *xsink, q_thread_t f, void *arg=nullptr)
 starts a new thread with the given arguments, when the thread terminates, it deregisters itself More...
 
DLLEXPORT void * q_swap_thread_local_data (int key, void *new_data, q_thread_local_destructor destructor=nullptr, bool run_destructor=true)
 swaps thread-local data More...
 
DLLEXPORT QoreHashNodeqore_get_parent_caller_location (size_t offset=1)
 Returns a CallStackInfo hash for the caller's location, if available, otherwise returns nullptr. More...
 
DLLEXPORT q_trid_t qore_get_trid ()
 get a thread resource ID
 
DLLEXPORT int remove_thread_resource (AbstractThreadResource *atr)
 remove the resource from the thread resource list for the current thread More...
 
DLLEXPORT int remove_thread_resource (const ResolvedCallReferenceNode *rcr, ExceptionSink *xsink)
 remove the callable resource from the thread resource list for the current thread More...
 
DLLEXPORT void set_thread_resource (AbstractThreadResource *atr)
 save a resource against a thread for thread resource handling More...
 
DLLEXPORT void set_thread_resource (const ResolvedCallReferenceNode *rcr, const QoreValue arg)
 save a callable resource against a thread for thread resource handling More...
 

Variables

DLLEXPORT ThreadCleanupList tclist
 the interface to the thread cleanup list
 

Detailed Description

Provides definitions relative to threading in Qore.

Function Documentation

◆ check_thread_resource()

DLLEXPORT bool check_thread_resource ( AbstractThreadResource atr)

check if a thread resouce has been saved

Parameters
atrthread resource id to check
Returns
true if saved, false if not saved

◆ is_valid_qore_thread()

DLLEXPORT bool is_valid_qore_thread ( )

returns true if the current thread is a valid qore thread; it is not safe to call most Qore functions unless the thread is registered with Qore

See also

◆ q_deregister_foreign_thread()

DLLEXPORT int q_deregister_foreign_thread ( )

deregisters the current thread as a foreign thread

Returns
0 if the foreign thread was deregistered, -1 if it was not registered or was not a foreign thread
See also
Since
Qore 0.8.7

◆ q_deregister_reserved_foreign_thread()

DLLEXPORT int q_deregister_reserved_foreign_thread ( )

deregisters a foreign qore thread but retains the TID as reserved

Returns
0 for OK, -1 for error (TID invalid or not foreign)
Since
Qore 0.8.7

◆ q_get_thread_local_data()

DLLEXPORT void * q_get_thread_local_data ( int  key)

returns thread-local data

Note
can only be called in a registered Qore thread
Since
Qore 0.9.5

◆ q_get_thread_local_data_all()

DLLEXPORT q_user_tld * q_get_thread_local_data_all ( int  key)

returns thread-local data

Parameters
keythe key used to save the data
Returns
nullptr if the data was not found, otherwise a pointer to the data structure holding the data
Note
can only be called in a registered Qore thread
Since
Qore 0.9.5

◆ q_get_unique_thread_local_data_key()

DLLEXPORT int q_get_unique_thread_local_data_key ( )

returns a unique ID to use with thread_local_data APIs

Since
Qore 0.9.5

◆ q_gettid()

DLLEXPORT int q_gettid ( )
noexcept

returns the current TID number

Since
Qore 0.9.5.1

Referenced by StreamBase::check(), StreamBase::reassignThread(), and StreamBase::unassignThread().

◆ q_register_foreign_thread()

DLLEXPORT int q_register_foreign_thread ( )

registers the current thread as a Qore thread

call q_deregister_foreign_thread() when Qore functionality is no longer required; not calling q_deregister_foreign_thread() will cause a memory leak

Returns
QFT_OK (0) if the thread was successfully registered, QFT_ERROR (-1) if an error occurred, or QFT_REGISTERED (-2) if it was already registered; see Return Value Codes for q_register_foreign_thread() for more info
See also
Since
  • Qore 0.8.7: introduced
  • QOre 1.0.10: TIDs are reassigned if possible to supoport Qore thread affinity in foreign language modules

◆ q_register_reserved_foreign_thread()

DLLEXPORT int q_register_reserved_foreign_thread ( int  tid)

registers a foreign qore thread as a Qore thread with a reserved TID

Parameters
tidthe TID reserved with q_reserve_foreign_thread_id()
Returns
0 for OK, -1 for error (TID invalid or not reserved)
Since
Qore 0.8.7

◆ q_release_reserved_foreign_thread_id()

DLLEXPORT int q_release_reserved_foreign_thread_id ( int  tid)

releases a TID reserved with q_reserve_foreign_thread_id()

Parameters
tidthe TID reserved with q_reserve_foreign_thread_id()
Returns
0 for OK, -1 for error (TID invalid or not reserved)
Since
Qore 0.8.7

◆ q_remove_thread_local_data()

DLLEXPORT int q_remove_thread_local_data ( int  key,
q_user_tld data,
bool  run_destructor = true 
)

returns and removes thread-local data

Parameters
keythe key used to save the data
datathe data structure, if found (output variable)
run_destructorif true then the destructor is run when the data is removed; if false, it is not
Returns
-1 if the data was not found, 0 if found and returned
Note
can only be called in a registered Qore thread
Since
Qore 0.9.5

◆ q_reserve_foreign_thread_id()

DLLEXPORT int q_reserve_foreign_thread_id ( )

reserves a thread ID for later registration and returns the TID reserved; use q_release_reserved_foreign_thread_id() to release the reservation

Returns
the TID reserved or -1 if an error occurred (thread table full)
Since
Qore 0.8.7

◆ q_save_thread_local_data()

DLLEXPORT void q_save_thread_local_data ( int  key,
void *  data,
q_thread_local_destructor  destructor = nullptr 
)

saves thread-local data

can only be called in a registered Qore thread

Since
Qore 0.9.5

◆ q_start_thread()

int q_start_thread ( ExceptionSink xsink,
q_thread_t  f,
void *  arg = nullptr 
)

starts a new thread with the given arguments, when the thread terminates, it deregisters itself

Parameters
argthe argument to the function
fthe function to start in the new thread
xsinkany errors starting the new thread will be raised here and cause -1 to be returned
Returns
the new TID or -1 if an error occurred
Since
Qore 0.8.8

◆ q_swap_thread_local_data()

DLLEXPORT void * q_swap_thread_local_data ( int  key,
void *  new_data,
q_thread_local_destructor  destructor = nullptr,
bool  run_destructor = true 
)

swaps thread-local data

can only be called in a registered Qore thread

Since
Qore 0.9.5

◆ qore_get_parent_caller_location()

DLLEXPORT QoreHashNode * qore_get_parent_caller_location ( size_t  offset = 1)

Returns a CallStackInfo hash for the caller's location, if available, otherwise returns nullptr.

Parameters
offsetthe call stack entry offset

◆ remove_thread_resource() [1/2]

DLLEXPORT int remove_thread_resource ( AbstractThreadResource atr)

remove the resource from the thread resource list for the current thread

Parameters
atra pointer to the thread resource to remove
Returns
0 if successful (resource was found and removed), -1 if the resource was not found

◆ remove_thread_resource() [2/2]

DLLEXPORT int remove_thread_resource ( const ResolvedCallReferenceNode rcr,
ExceptionSink xsink 
)

remove the callable resource from the thread resource list for the current thread

Parameters
rcra pointer to the thread resource to remove
xsinkany Qore-language exceptions raised when dereferencing the callable object will be saved here
Returns
0 if successful (resource was found and removed), -1 if the resource was not found

◆ set_thread_resource() [1/2]

DLLEXPORT void set_thread_resource ( AbstractThreadResource atr)

save a resource against a thread for thread resource handling

Parameters
atra pointer to the thread resource to save

◆ set_thread_resource() [2/2]

DLLEXPORT void set_thread_resource ( const ResolvedCallReferenceNode rcr,
const QoreValue  arg 
)

save a callable resource against a thread for thread resource handling

Parameters
rcra pointer to a callable node for thread resource handling
argan argument to use when calling the thread resource handler