A thread is an independent sequence of execution of Qore code within a Qore program or script. Each thread has a thread ID or TID. The first thread of execution in a Qore program has TID 1. TID 0 is always reserved for the special \mbox{\hyperlink{signal_handling}{signal handler thread}}. The Qore language is designed to be thread-\/safe and Qore programs should not crash the Qore executable due to threading errors. Threading errors should only cause exceptions to be thrown or application errors to occur. Threading functionality in Qore is provided by the operating system\textquotesingle{}s POSIX threads library.\hypertarget{threading_creating_and_terminating_threads}{}\doxysection{Creating and Terminating Threads}\label{threading_creating_and_terminating_threads} New threads are created with the \mbox{\hyperlink{operators_background}{background operator}}. This operator executes the expression given as an argument in a new thread and returns the TID (integer thread ID) of the new thread to the calling thread. This is most useful for calling user functions or object methods designed to run in a separate thread. To terminate a thread, the \mbox{\hyperlink{statements_thread_exit}{thread\+\_\+exit statement}} should be called, as calling the exit() function will terminate the entire process (and therefore all threads) immediately.\hypertarget{threading_threading_and_variables}{}\doxysection{Threading and Variables}\label{threading_threading_and_variables} All global variables are shared in Qore programs, while local variables (declared with {\ttfamily {\bfseries{my}}}) are generally local to each thread (and thus accessed without any mutual-\/exclusion locking), regardless of location. This means that if a variable is declared with {\ttfamily {\bfseries{my}}} at the top level, it will actually have global scope, but also each thread will have its own copy of the variable. In effect, declaring a top-\/level local variable with {\ttfamily {\bfseries{my}}} actually creates a global thread-\/local variable. The following code gives an example of declaring a global thread-\/local variable by using {\ttfamily {\bfseries{my}}} at the top-\/level\+: \begin{DoxyCode}{0} \DoxyCodeLine{\%new-\/style} \DoxyCodeLine{\%require-\/types} \DoxyCodeLine{\%strict-\/args} \DoxyCodeLine{} \DoxyCodeLine{sub t() \{} \DoxyCodeLine{ \mbox{\hyperlink{group__string__functions_ga32070517a9f8a70a32ef48f83a6f128e}{printf}}(\textcolor{stringliteral}{"{}x=\%y\(\backslash\)n"{}}, x);} \DoxyCodeLine{\}} \DoxyCodeLine{int x = 2;} \DoxyCodeLine{t();} \DoxyCodeLine{background t();} \end{DoxyCode} This will print out\+: \begin{DoxyVerb}x=2 x=null\end{DoxyVerb} Note that the second time the local variable is accessed in the background thread, it has no value. Due to the way Qore\textquotesingle{}s local variables work, it is illegal to declare a top-\/level local variable after first block is parsed in the program; that is; if any call to \mbox{\hyperlink{group__misc__functions_ga11da5fd06dcfa57a48a5381268a52086}{parse()}} or \mbox{\hyperlink{class_qore_1_1_program_ad59f1b6ce7adaa693086e1b858cbe896}{Qore\+::\+Program\+::parse()}} is made in an existing program (where a top-\/level block already exists), and an attempt to declare a new top-\/level local variable is made, then a {\ttfamily ILLEGAL-\/\+TOP-\/\+LEVEL-\/\+LOCAL-\/\+VARIABLE} parse exception will be raised. Access to global variables in qore is wrapped in mutual-\/exclusion locks to guarantee safe access to global variable data in a multithreaded context. Local variables are thread-\/local and therefore not locked, except when referenced in a \mbox{\hyperlink{expressions_closure}{closure}} or when a \mbox{\hyperlink{lvalue_references}{reference}} is taken of them, in which case the local variable\textquotesingle{}s scope is extended to that of the \mbox{\hyperlink{expressions_closure}{closure\textquotesingle{}s}} or the \mbox{\hyperlink{lvalue_references}{reference\textquotesingle{}s}}, and all accesses to the bound local variable are made within mutual-\/exclusion locks as these variables may be used in multithreaded contexts. An alternative to global thread-\/local variables is offered by the \mbox{\hyperlink{group__threading__functions_ga496d14c02dcc992bf82fefbfe6a0d1ca}{save\+\_\+thread\+\_\+data()}} and \mbox{\hyperlink{group__threading__functions_ga1bf3fa656c5e803e9453a5ed84fd556c}{get\+\_\+thread\+\_\+data()}} functions (documented in \mbox{\hyperlink{group__threading__functions}{Threading Functions}}).\hypertarget{threading_thread_synchronization}{}\doxysection{Thread Management and Inter-\/\+Thread Communication}\label{threading_thread_synchronization} \label{threading_synchronized}% \Hypertarget{threading_synchronized}% \begin{DoxyParagraph}{synchronized} The {\ttfamily {\bfseries{synchronized}}} keyword can be used before function or class method definitions in order to guarantee that the function or method call will only be executed in one thread at a time. As in Java, this keyword can also be used safely with recursive functions and methods (internally a recursive mutual exclusion lock that participates in Qore\textquotesingle{}s deadlock detection framework is used to guarantee thread-\/exclusivity and allow recursion).~\newline ~\newline {\ttfamily {\bfseries{synchronized}}} functions have a dedicated reentrant lock associated with the function, while {\ttfamily {\bfseries{synchronized}}} normal class methods share a reentrant lock associated with the object, and a {\ttfamily {\bfseries{synchronized}}} static class methods share a reentrant lock associated with the class itself. \end{DoxyParagraph} \begin{DoxyParagraph}{Classes Useful With Threading} The following classes are useful when developing multi-\/threaded Qore programs\+:~\newline \tabulinesep=1mm \begin{longtabu}spread 0pt [c]{*{2}{|X[-1]}|} \hline {\bfseries{Class}} &{\bfseries{Description}} \\\cline{1-2} \mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_thread_resource}{Abstract\+Thread\+Resource}} &Allows Qore user code to implement thread resources \\\cline{1-2} \mbox{\hyperlink{class_qore_1_1_thread_1_1_auto_gate}{Auto\+Gate}} &A helper class to automatically exit \mbox{\hyperlink{class_qore_1_1_thread_1_1_gate}{Gate}} locks when the \mbox{\hyperlink{class_qore_1_1_thread_1_1_auto_gate}{Auto\+Gate}} object is deleted \\\cline{1-2} \mbox{\hyperlink{class_qore_1_1_thread_1_1_auto_lock}{Auto\+Lock}} &A helper class to automatically release \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex}{Mutex}} locks when the \mbox{\hyperlink{class_qore_1_1_thread_1_1_auto_lock}{Auto\+Lock}} object is deleted \\\cline{1-2} \mbox{\hyperlink{class_qore_1_1_thread_1_1_auto_read_lock}{Auto\+Read\+Lock}} &A helper class to automatically release read locks when the \mbox{\hyperlink{class_qore_1_1_thread_1_1_auto_read_lock}{Auto\+Read\+Lock}} object is deleted \\\cline{1-2} \mbox{\hyperlink{class_qore_1_1_thread_1_1_auto_write_lock}{Auto\+Write\+Lock}} &A helper class to automatically release read locks when the \mbox{\hyperlink{class_qore_1_1_thread_1_1_auto_read_lock}{Auto\+Write\+Lock}} object is deleted \\\cline{1-2} \mbox{\hyperlink{class_qore_1_1_thread_1_1_condition}{Condition}} &Allows Qore programs to block until a certain condition becomes true \\\cline{1-2} \mbox{\hyperlink{class_qore_1_1_thread_1_1_counter}{Counter}} &A blocking counter class \\\cline{1-2} \mbox{\hyperlink{class_qore_1_1_thread_1_1_gate}{Gate}} &A recursive thread lock \\\cline{1-2} \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex}{Mutex}} &A mutual-\/exclusion thread lock \\\cline{1-2} \mbox{\hyperlink{class_qore_1_1_thread_1_1_queue}{Queue}} &A thread-\/safe, blocking queue class (useful for message passing) \\\cline{1-2} \mbox{\hyperlink{class_qore_1_1_thread_1_1_r_w_lock}{RWLock}} &A read-\/write thread lock \\\cline{1-2} \mbox{\hyperlink{class_qore_1_1_thread_1_1_sequence}{Sequence}} &A simple, thread-\/atomic sequence object (increment-\/only) \\\cline{1-2} \mbox{\hyperlink{class_qore_1_1_thread_1_1_thread_pool}{Thread\+Pool}} &A flexible, dynamically scalable thread pool \\\cline{1-2} \end{longtabu} \end{DoxyParagraph} \begin{DoxyParagraph}{Functions Useful With Threading} The following functions assist writing safe and efficient multi-\/threaded Qore programs\+:~\newline \tabulinesep=1mm \begin{longtabu}spread 0pt [c]{*{2}{|X[-1]}|} \hline {\bfseries{Function}} &{\bfseries{Description}} \\\cline{1-2} \mbox{\hyperlink{group__threading__functions_ga67572bb3364b4af9d37226948fb680c5}{delete\+\_\+all\+\_\+thread\+\_\+data()}} &Deletes the entire thread-\/local data hash \\\cline{1-2} \mbox{\hyperlink{group__threading__functions_ga7fecb4c50726c994a9cdaf1d3284e5b4}{delete\+\_\+thread\+\_\+data()}} &Delete the value of a key in the thread-\/local data hash \\\cline{1-2} \mbox{\hyperlink{group__threading__functions_ga648b002d4fc96c5cfa78ba558b3d5538}{get\+\_\+all\+\_\+thread\+\_\+data()}} &Retrieves the entire thread-\/local hash \\\cline{1-2} \mbox{\hyperlink{group__threading__functions_ga1bf3fa656c5e803e9453a5ed84fd556c}{get\+\_\+thread\+\_\+data()}} &Retrieves a thread-\/local value based on a key \\\cline{1-2} \mbox{\hyperlink{group__threading__functions_ga95ed8e572309b44b3f5b49673238c3e6}{gettid()}} &Gets the thread\textquotesingle{}s TID (thread identifier) \\\cline{1-2} \mbox{\hyperlink{group__threading__functions_gafa1c0f9e429a945b66fb261c7fa1b5bd}{mark\+\_\+thread\+\_\+resources()}} &sets a checkpoint for throwing thread resource exceptions \\\cline{1-2} \mbox{\hyperlink{group__threading__functions_ga4bffba0876346fe5233ed4f5161c90d0}{num\+\_\+threads()}} &Returns the number of running threads \\\cline{1-2} \mbox{\hyperlink{group__threading__functions_gadc994316e54fdf50111018de9bd15dc6}{remove\+\_\+thread\+\_\+resource()}} &removes a thread resource from the current thread \\\cline{1-2} \mbox{\hyperlink{group__threading__functions_ga496d14c02dcc992bf82fefbfe6a0d1ca}{save\+\_\+thread\+\_\+data()}} &Saves a thread-\/local value against a key \\\cline{1-2} \mbox{\hyperlink{group__threading__functions_gae83c32576b59a1ecfa906d9b3c3af557}{set\+\_\+thread\+\_\+init()}} &Sets a \mbox{\hyperlink{expressions_closure}{closure}} or \mbox{\hyperlink{expressions_call_reference}{call reference}} to run every time a new thread is started in a \mbox{\hyperlink{class_qore_1_1_program}{Program}} object \\\cline{1-2} \mbox{\hyperlink{group__threading__functions_ga1a1fbc371cfc8885ed78e4bff25d35b1}{set\+\_\+thread\+\_\+resource()}} &sets a thread resource against the current thread \\\cline{1-2} \mbox{\hyperlink{group__threading__functions_ga113081673d536fc7bae33d2ffe523893}{thread\+\_\+list()}} &Returns a list of TIDs of running threads \\\cline{1-2} \mbox{\hyperlink{group__threading__functions_ga421dca39ccb55b191d5d09fd98c2075a}{throw\+\_\+thread\+\_\+resource\+\_\+exceptions()}} &runs thread-\/resource cleanup routines and throws the associated exceptions \\\cline{1-2} \mbox{\hyperlink{group__threading__functions_ga4e62409b8a1b414276d033267e7299e4}{throw\+\_\+thread\+\_\+resource\+\_\+exceptions\+\_\+to\+\_\+mark()}} &runs thread-\/resource cleanup routines and throws the associated exceptions to the last mark and clears the mark \\\cline{1-2} \end{longtabu} \end{DoxyParagraph} \hypertarget{threading_thread_resources}{}\doxysection{Thread Resources}\label{threading_thread_resources} Qore supports a concept called thread resources; thread resources are resources that belong to a particular thread and that require some sort of cleanup of the resource in case the thread is exited without releasing the resource. Examples of thread resources in Qore are as follows\+: \begin{DoxyItemize} \item \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex}{Mutex}}\+: when a lock is acquired, the lock is tracked as a thread resource. If the thread is exited without releasing the lock, the \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex}{Mutex}} thread resource cleanup routine is executed which releases the lock and throws a user-\/friendly exception explaining what happened. When the lock is released, the thread resource is removed. \item \mbox{\hyperlink{class_qore_1_1_thread_1_1_r_w_lock}{RWLock}}\+: read-\/write locks are treated as thread resources in the same way described for \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex}{Mutex}} locks \item \mbox{\hyperlink{class_qore_1_1_thread_1_1_gate}{Gate}}\+: gate locks are treated as thread resources in the same way described for \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex}{Mutex}} locks \item \mbox{\hyperlink{class_qore_1_1_s_q_l_1_1_datasource}{Datasource}}\+: the transaction lock is handled as a thread resource; if a thread exits holding the transaction lock, the \mbox{\hyperlink{class_qore_1_1_s_q_l_1_1_datasource}{Datasource}} cleanup routine is executed; this will rollback the transaction (freeing the transaction lock) and throw an appropriate exception. \item \mbox{\hyperlink{class_qore_1_1_s_q_l_1_1_datasource_pool}{Datasource\+Pool}}\+: datasource allocations are handled as a thread resources; if a thread exits without releasing the connection, the \mbox{\hyperlink{class_qore_1_1_s_q_l_1_1_datasource_pool}{Datasource\+Pool}} cleanup routine is executed; this will rollback the transaction (releasing the dtasource connection back to the pool) and throw an appropriate exception. \end{DoxyItemize} User classes can implement their own thread resource handling by subclassing \mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_thread_resource}{Abstract\+Thread\+Resource}} (implementing custom cleanup code in the \mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_thread_resource_a0431f7384991eaf6900ee3a952b57f87}{Abstract\+Thread\+Resource\+::cleanup()}} method) and then calling\+: \begin{DoxyItemize} \item \mbox{\hyperlink{group__threading__functions_ga1a1fbc371cfc8885ed78e4bff25d35b1}{set\+\_\+thread\+\_\+resource()}}\+: to set the resource against the thread \item \mbox{\hyperlink{group__threading__functions_gadc994316e54fdf50111018de9bd15dc6}{remove\+\_\+thread\+\_\+resource()}}\+: to remove the resource from the thread \end{DoxyItemize} If the thread is exited or one of the thread resource cleanup functions is called while the thread resource is set, then the \mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_thread_resource_a0431f7384991eaf6900ee3a952b57f87}{Abstract\+Thread\+Resource\+::cleanup()}} method is called, which should cleanup the thread resource and normally throw a user-\/friendly exception describing the error, the cleanup actions takenm and how to prevent it in the future. The thread-\/resource cleanup functions are\+: \begin{DoxyItemize} \item \mbox{\hyperlink{group__threading__functions_ga421dca39ccb55b191d5d09fd98c2075a}{throw\+\_\+thread\+\_\+resource\+\_\+exceptions()}}\+: runs thread-\/resource cleanup routines explicitly \item \mbox{\hyperlink{group__threading__functions_ga4e62409b8a1b414276d033267e7299e4}{throw\+\_\+thread\+\_\+resource\+\_\+exceptions\+\_\+to\+\_\+mark()}}\+: runs thread-\/resource cleanup routines for all thread resources set since the last call to \mbox{\hyperlink{group__threading__functions_gafa1c0f9e429a945b66fb261c7fa1b5bd}{mark\+\_\+thread\+\_\+resources()}} explicitly \end{DoxyItemize} \begin{DoxySeeAlso}{See also} \mbox{\hyperlink{class_qore_1_1_thread_1_1_abstract_thread_resource}{Abstract\+Thread\+Resource}} for an example of custom thread resource handling \end{DoxySeeAlso} \hypertarget{threading_deadlocks}{}\doxysection{Deadlocks}\label{threading_deadlocks} Qore supports deadlock detection in complex locking scenarios and will throw a {\ttfamily THREAD-\/\+DEADLOCK} exception rather than allow an operation to be performed that would cause a deadlock. Deadlock detection is implemented for internal locking (global variable and object access), \mbox{\hyperlink{threading_synchronized}{synchronized}} methods and functions, etc, as well as for all Qore threading classes. Qore can only detect deadlocks when a lock resource acquired by one thread is required by another who holds a lock that the first thread also needs. Other errors such as forgetting to unlock a global lock and trying to acquire that lock in another thread cannot be differentiated from valid use of threading primitives and will result in a process that never terminates (a deadlocked process). However, common threading errors such as trying to lock the same \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex}{Mutex}} twice in the same thread without unlocking it between the two \mbox{\hyperlink{class_qore_1_1_thread_1_1_mutex_a0bb3432456ccdf0cfb1523429b5b4141}{Mutex\+::lock()}} calls are caught in Qore and exceptions are thrown. Additionally, locks are tracked as thread resources, so if a thread terminates while holding a lock, an exception will be thrown and the lock will be automatically released.