Qore Programming Language - C/C++ Library  1.0.11
qore_thread.h
Go to the documentation of this file.
1 /* -*- mode: c++; indent-tabs-mode: nil -*- */
2 /*
3  qore_thread.h
4 
5  POSIX thread library for Qore
6 
7  Qore Programming Language
8 
9  Copyright (C) 2003 - 2020 Qore Technologies, s.r.o.
10 
11  Permission is hereby granted, free of charge, to any person obtaining a
12  copy of this software and associated documentation files (the "Software"),
13  to deal in the Software without restriction, including without limitation
14  the rights to use, copy, modify, merge, publish, distribute, sublicense,
15  and/or sell copies of the Software, and to permit persons to whom the
16  Software is furnished to do so, subject to the following conditions:
17 
18  The above copyright notice and this permission notice shall be included in
19  all copies or substantial portions of the Software.
20 
21  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
22  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
23  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
24  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
25  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
26  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
27  DEALINGS IN THE SOFTWARE.
28 
29  Note that the Qore library is released under a choice of three open-source
30  licenses: MIT (as above), LGPL 2+, or GPL 2+; see README-LICENSE for more
31  information.
32 */
33 
34 #ifndef _QORE_QORE_THREAD_H
35 #define _QORE_QORE_THREAD_H
36 
41 #include <cstdio>
42 #include <pthread.h>
43 
44 #include <functional>
45 
46 class QoreProgram;
47 class AbstractQoreZoneInfo;
48 class ThreadCleanupNode;
50 
52 typedef void (*qtdest_t)(void *);
53 
55 typedef void (*qtrdest_t)(void *, ExceptionSink *);
56 
58 typedef void (*q_thread_t)(ExceptionSink* xsink, void* arg);
59 
61 
67 DLLEXPORT bool is_valid_qore_thread();
68 
70 DLLEXPORT int gettid() noexcept;
71 
73 
75 DLLEXPORT int q_gettid() noexcept;
76 
78 DLLEXPORT QoreProgram* getProgram();
79 
81 DLLEXPORT const AbstractQoreZoneInfo* currentTZ();
82 
84 
87 
89 
93 
95 
99 
101 
104 DLLEXPORT void set_thread_resource(const ResolvedCallReferenceNode* rcr, const QoreValue arg);
105 
107 
113 
114 #if 0
116 
122 DLLEXPORT void set_thread_resource_id(q_trid_t trid, AbstractThreadResource *atr);
123 
125 
130 DLLEXPORT int remove_thread_resource_id(q_trid_t trid);
131 
133 
136 DLLEXPORT bool check_thread_resource_id(q_trid_t trid);
137 #endif
138 
141 
143 
151 private:
152  static ThreadCleanupNode *head;
153 
154 public:
155  DLLLOCAL ThreadCleanupList();
156  DLLLOCAL ~ThreadCleanupList();
157  DLLLOCAL void exec();
158 
160 
163  DLLEXPORT void push(qtdest_t func, void *arg);
164 
166 
168  DLLEXPORT void pop(bool exec = true);
169 };
170 
172 DLLEXPORT extern ThreadCleanupList tclist;
173 
177 #define QFT_OK 0
178 #define QFT_ERROR -1
179 #define QFT_REGISTERED -2
181 
183 
199 
201 
211 
213 
218 
220 
227 
229 
235 DLLEXPORT int q_register_reserved_foreign_thread(int tid);
236 
238 
243 
245 
253 int q_start_thread(ExceptionSink* xsink, q_thread_t f, void* arg = nullptr);
254 
256 
259 public:
261 
267 
269 
272  DLLEXPORT explicit QoreForeignThreadHelper(int tid);
273 
275 
280 
282  DLLEXPORT operator bool() const;
283 
284 protected:
285  class qore_foreign_thread_priv* priv;
286 
287 private:
288  DLLLOCAL QoreForeignThreadHelper& operator=(const QoreForeignThreadHelper&) = delete;
289  DLLLOCAL QoreForeignThreadHelper(const QoreForeignThreadHelper&) = delete;
290  DLLLOCAL void* operator new(size_t) = delete;
291 };
292 
293 typedef std::function<void(void*)> q_thread_local_destructor;
294 
296 
298 struct q_user_tld {
299  void* data;
300  q_thread_local_destructor destructor;
301 
302  DLLLOCAL q_user_tld(void* data, q_thread_local_destructor destructor);
303  DLLLOCAL q_user_tld(q_user_tld&& old) = default;
304  DLLLOCAL q_user_tld(const q_user_tld& old) = default;
305  DLLLOCAL q_user_tld& operator=(const q_user_tld& other) = default;
306 };
307 
309 
312 
314 
318 DLLEXPORT void q_save_thread_local_data(int key, void* data, q_thread_local_destructor destructor = nullptr);
319 
321 
325 DLLEXPORT void* q_swap_thread_local_data(int key, void* new_data, q_thread_local_destructor destructor = nullptr, bool run_destructor = true);
326 
328 
332 DLLEXPORT void* q_get_thread_local_data(int key);
333 
335 
344 
346 
356 DLLEXPORT int q_remove_thread_local_data(int key, q_user_tld& data, bool run_destructor = true);
357 
358 #endif // ifndef _QORE_THREAD_H
base class for saving data using Qore's thread resource management system
Definition: AbstractThreadResource.h:51
container for holding Qore-language exception information and also for registering a "thread_exit" ca...
Definition: ExceptionSink.h:48
use this class to temporarily register and deregister a foreign thread to allow Qore code to be execu...
Definition: qore_thread.h:258
DLLEXPORT ~QoreForeignThreadHelper()
deregisters the current thread
DLLEXPORT QoreForeignThreadHelper()
registers the current thread as a foreign thread
supports parsing and executing Qore-language code, reference counted, dynamically-allocated only
Definition: QoreProgram.h:127
base class for resolved call references
Definition: CallReferenceNode.h:109
list of functions to be run when a thread ends; required for some external libraries that require exp...
Definition: qore_thread.h:150
DLLEXPORT void push(qtdest_t func, void *arg)
must only be called in the module initialization function
DLLEXPORT void pop(bool exec=true)
must only be called in the module destructor/deletion function
unsigned q_trid_t
type for thread resource IDs (unique within a single running qore library process)
Definition: common.h:455
DLLEXPORT int q_register_reserved_foreign_thread(int tid)
registers a foreign qore thread as a Qore thread with a reserved TID
DLLEXPORT bool check_thread_resource(AbstractThreadResource *atr)
check if a thread resouce has been saved
DLLEXPORT int q_release_reserved_foreign_thread_id(int tid)
releases a TID reserved with q_reserve_foreign_thread_id()
DLLEXPORT q_trid_t qore_get_trid()
get a thread resource ID
DLLEXPORT void * q_get_thread_local_data(int key)
returns thread-local data
DLLEXPORT int q_reserve_foreign_thread_id()
reserves a thread ID for later registration and returns the TID reserved; use q_release_reserved_fore...
DLLEXPORT QoreProgram * getProgram()
returns the current QoreProgram
DLLEXPORT int q_get_unique_thread_local_data_key()
returns a unique ID to use with thread_local_data APIs
void(* q_thread_t)(ExceptionSink *xsink, void *arg)
pointer to a function that can be started with q_start_thread()
Definition: qore_thread.h:58
DLLEXPORT int q_remove_thread_local_data(int key, q_user_tld &data, bool run_destructor=true)
returns and removes thread-local data
DLLEXPORT q_user_tld * q_get_thread_local_data_all(int key)
returns thread-local data
DLLEXPORT void q_save_thread_local_data(int key, void *data, q_thread_local_destructor destructor=nullptr)
saves thread-local data
DLLEXPORT int q_deregister_foreign_thread()
deregisters the current thread as a foreign 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...
DLLEXPORT int q_register_foreign_thread()
registers the current thread as a Qore 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
void(* qtrdest_t)(void *, ExceptionSink *)
pointer to a qore thread resource destructor function
Definition: qore_thread.h:55
DLLEXPORT int q_deregister_reserved_foreign_thread()
deregisters a foreign qore thread but retains the TID as reserved
DLLEXPORT int gettid() noexcept
DLLEXPORT ThreadCleanupList tclist
the interface to the thread cleanup list
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
DLLEXPORT void set_thread_resource(AbstractThreadResource *atr)
save a resource against a thread for thread resource handling
DLLEXPORT const AbstractQoreZoneInfo * currentTZ()
returns the current local time zone, note that if 0 = UTC
DLLEXPORT int remove_thread_resource(AbstractThreadResource *atr)
remove the resource from the thread resource list for the current thread
DLLEXPORT int q_gettid() noexcept
returns the current TID number
void(* qtdest_t)(void *)
pointer to a qore thread destructor function
Definition: qore_thread.h:52
The main value class in Qore, designed to be passed by value.
Definition: QoreValue.h:267
data structure for user thread-local data
Definition: qore_thread.h:298