| Qore Programming Language - C/C++ Library 1.0.8

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;
49 class AbstractThreadResource;
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
86 DLLEXPORT void set_thread_resource(AbstractThreadResource* atr);
87
89
92 DLLEXPORT int remove_thread_resource(AbstractThreadResource* atr);
93
95
98 DLLEXPORT bool check_thread_resource(AbstractThreadResource* atr);
99
101
104 DLLEXPORT void set_thread_resource(const ResolvedCallReferenceNode* rcr, const QoreValue arg);
105
107
112 DLLEXPORT int remove_thread_resource(const ResolvedCallReferenceNode* rcr, ExceptionSink* xsink);
113
114 #if 0
115
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
140 DLLEXPORT q_trid_t qore_get_trid();
141
143
150 class ThreadCleanupList {
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
180
181
182
194 DLLEXPORT int q_register_foreign_thread();
195
197
206 DLLEXPORT int q_deregister_foreign_thread();
207
209
213 DLLEXPORT int q_reserve_foreign_thread_id();
214
216
222 DLLEXPORT int q_release_reserved_foreign_thread_id(int tid);
223
225
231 DLLEXPORT int q_register_reserved_foreign_thread(int tid);
232
234
238 DLLEXPORT int q_deregister_reserved_foreign_thread();
239
241
249 int q_start_thread(ExceptionSink* xsink, q_thread_t f, void* arg = nullptr);
250
252
254 class QoreForeignThreadHelper {
255 private:
257 DLLLOCAL QoreForeignThreadHelper& operator=(const QoreForeignThreadHelper&);
258 DLLLOCAL QoreForeignThreadHelper(const QoreForeignThreadHelper&);
259 DLLLOCAL void* operator new(size_t);
260
261 protected:
262 class qore_foreign_thread_priv* priv;
263
264 public:
266 DLLEXPORT QoreForeignThreadHelper();
267
269 DLLEXPORT explicit QoreForeignThreadHelper(int tid);
270
272 DLLEXPORT ~QoreForeignThreadHelper();
273 };
274
275 typedef std::function<void(void*)> q_thread_local_destructor;
276
278
280 struct q_user_tld {
281 void* data;
282 q_thread_local_destructor destructor;
283
284 DLLLOCAL q_user_tld(void* data, q_thread_local_destructor destructor);
285 DLLLOCAL q_user_tld(q_user_tld&& old) = default;
286 DLLLOCAL q_user_tld(const q_user_tld& old) = default;
287 DLLLOCAL q_user_tld& operator=(const q_user_tld& other) = default;
288 };
289
291
293 DLLEXPORT int q_get_unique_thread_local_data_key();
294
296
300 DLLEXPORT void q_save_thread_local_data(int key, void* data, q_thread_local_destructor destructor = nullptr);
301
303
307 DLLEXPORT void* q_swap_thread_local_data(int key, void* new_data, q_thread_local_destructor destructor = nullptr, bool run_destructor = true);
308
310
314 DLLEXPORT void* q_get_thread_local_data(int key);
315
317
325 DLLEXPORT q_user_tld* q_get_thread_local_data_all(int key);
326
328
338 DLLEXPORT int q_remove_thread_local_data(int key, q_user_tld& data, bool run_destructor = true);
339
340 #endif // ifndef _QORE_THREAD_H
qtdest_t
void(* qtdest_t)(void *)
pointer to a qore thread destructor function
Definition: qore_thread.h:52
AbstractThreadResource
base class for saving data using Qore&#39;s thread resource management system
Definition: AbstractThreadResource.h:51
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
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_fore...
ThreadCleanupList::pop
DLLEXPORT void pop(bool exec=true)
must only be called in the module destructor/deletion function
QoreForeignThreadHelper::~QoreForeignThreadHelper
DLLEXPORT ~QoreForeignThreadHelper()
deregisters the current thread if the registration was successful using either q_deregister_foreign_t...
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
gettid
DLLEXPORT int gettid() noexcept
check_thread_resource
DLLEXPORT bool check_thread_resource(AbstractThreadResource *atr)
check if a thread resouce has been saved
tclist
DLLEXPORT ThreadCleanupList tclist
the interface to the thread cleanup list
set_thread_resource
DLLEXPORT void set_thread_resource(AbstractThreadResource *atr)
save a resource against a thread for thread resource handling
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 ...
ThreadCleanupList::push
DLLEXPORT void push(qtdest_t func, void *arg)
must only be called in the module initialization function
remove_thread_resource
DLLEXPORT int remove_thread_resource(AbstractThreadResource *atr)
remove the resource from the thread resource list for the current thread
getProgram
DLLEXPORT QoreProgram * getProgram()
returns the current QoreProgram
q_deregister_foreign_thread
DLLEXPORT int q_deregister_foreign_thread()
deregisters the current thread as a foreign thread
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()
qtrdest_t
void(* qtrdest_t)(void *, ExceptionSink *)
pointer to a qore thread resource destructor function
Definition: qore_thread.h:55
q_trid_t
unsigned q_trid_t
type for thread resource IDs (unique within a single running qore library process) ...
Definition: common.h:455
QoreValue
The main value class in Qore, designed to be passed by value.
Definition: QoreValue.h:267
QoreProgram
supports parsing and executing Qore-language code, reference counted, dynamically-allocated only ...
Definition: QoreProgram.h:127
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
ExceptionSink
container for holding Qore-language exception information and also for registering a "thread_exit" ca...
Definition: ExceptionSink.h:48
QoreForeignThreadHelper::QoreForeignThreadHelper
DLLEXPORT QoreForeignThreadHelper()
registers the current thread as a foreign thread; the thread will be deregistered with q_deregister_f...
ThreadCleanupList
list of functions to be run when a thread ends; required for some external libraries that require exp...
Definition: qore_thread.h:150
q_thread_t
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
q_get_thread_local_data_all
DLLEXPORT q_user_tld * q_get_thread_local_data_all(int key)
returns thread-local data
ResolvedCallReferenceNode
base class for resolved call references
Definition: CallReferenceNode.h:109
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
q_register_foreign_thread
DLLEXPORT int q_register_foreign_thread()
registers the current thread as a Qore thread; returns QFT_OK (0) if the thread was successfully regi...
QoreForeignThreadHelper
use this class to temporarily register and deregister a foreign thread to allow Qore code to be execu...
Definition: qore_thread.h:254
qore_get_trid
DLLEXPORT q_trid_t qore_get_trid()
get a thread resource ID
q_deregister_reserved_foreign_thread
DLLEXPORT int q_deregister_reserved_foreign_thread()
deregisters a foreign qore thread but retains the TID as reserved
q_user_tld
data structure for user thread-local data
Definition: qore_thread.h:280
q_get_thread_local_data
DLLEXPORT void * q_get_thread_local_data(int key)
returns thread-local data
q_gettid
DLLEXPORT int q_gettid() noexcept
returns the current TID number
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
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...
currentTZ
DLLEXPORT const AbstractQoreZoneInfo * currentTZ()
returns the current local time zone, note that if 0 = UTC