1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>SWI-Prolog 7.3.6 Reference Manual: Section 9.6</title><link rel="home" href="index.html">
<link rel="contents" href="Contents.html">
<link rel="index" href="DocIndex.html">
<link rel="summary" href="summary.html">
<link rel="previous" href="thutil.html">
<link rel="next" href="mt-xpce.html">
<style type="text/css">
/* Style sheet for SWI-Prolog latex2html
*/
dd.defbody
{ margin-bottom: 1em;
}
dt.pubdef, dt.multidef
{ color: #fff;
padding: 2px 10px 0px 10px;
margin-bottom: 5px;
font-size: 18px;
vertical-align: middle;
overflow: hidden;
}
dt.pubdef { background-color: #0c3d6e; }
dt.multidef { background-color: #ef9439; }
.bib dd
{ margin-bottom: 1em;
}
.bib dt
{ float: left;
margin-right: 1.3ex;
}
pre.code
{ margin-left: 1.5em;
margin-right: 1.5em;
border: 1px dotted;
padding-top: 5px;
padding-left: 5px;
padding-bottom: 5px;
background-color: #f8f8f8;
}
div.navigate
{ text-align: center;
background-color: #f0f0f0;
border: 1px dotted;
padding: 5px;
}
div.title
{ text-align: center;
padding-bottom: 1em;
font-size: 200%;
font-weight: bold;
}
div.author
{ text-align: center;
font-style: italic;
}
div.abstract
{ margin-top: 2em;
background-color: #f0f0f0;
border: 1px dotted;
padding: 5px;
margin-left: 10%; margin-right:10%;
}
div.abstract-title
{ text-align: center;
padding: 5px;
font-size: 120%;
font-weight: bold;
}
div.toc-h1
{ font-size: 200%;
font-weight: bold;
}
div.toc-h2
{ font-size: 120%;
font-weight: bold;
margin-left: 2em;
}
div.toc-h3
{ font-size: 100%;
font-weight: bold;
margin-left: 4em;
}
div.toc-h4
{ font-size: 100%;
margin-left: 6em;
}
span.sec-nr
{
}
span.sec-title
{
}
span.pred-ext
{ font-weight: bold;
}
span.pred-tag
{ float: right;
padding-top: 0.2em;
font-size: 80%;
font-style: italic;
color: #fff;
}
div.caption
{ width: 80%;
margin: auto;
text-align:center;
}
/* Footnotes */
.fn {
color: red;
font-size: 70%;
}
.fn-text, .fnp {
position: absolute;
top: auto;
left: 10%;
border: 1px solid #000;
box-shadow: 5px 5px 5px #888;
display: none;
background: #fff;
color: #000;
margin-top: 25px;
padding: 8px 12px;
font-size: larger;
}
sup:hover span.fn-text
{ display: block;
}
/* Lists */
dl.latex
{ margin-top: 1ex;
margin-bottom: 0.5ex;
}
dl.latex dl.latex dd.defbody
{ margin-bottom: 0.5ex;
}
/* PlDoc Tags */
dl.tags
{ font-size: 90%;
margin-left: 5ex;
margin-top: 1ex;
margin-bottom: 0.5ex;
}
dl.tags dt
{ margin-left: 0pt;
font-weight: bold;
}
dl.tags dd
{ margin-left: 3ex;
}
td.param
{ font-style: italic;
font-weight: bold;
}
/* Index */
dt.index-sep
{ font-weight: bold;
font-size: +1;
margin-top: 1ex;
}
/* Tables */
table.center
{ margin: auto;
}
table.latex
{ border-collapse:collapse;
}
table.latex tr
{ vertical-align: text-top;
}
table.latex td,th
{ padding: 2px 1em;
}
table.latex tr.hline td,th
{ border-top: 1px solid black;
}
table.frame-box
{ border: 2px solid black;
}
</style>
</head>
<body style="background:white">
<div class="navigate"><a class="nav" href="index.html"><img src="home.gif" alt="Home"></a>
<a class="nav" href="Contents.html"><img src="index.gif" alt="Contents"></a>
<a class="nav" href="DocIndex.html"><img src="yellow_pages.gif" alt="Index"></a>
<a class="nav" href="summary.html"><img src="info.gif" alt="Summary"></a>
<a class="nav" href="thutil.html"><img src="prev.gif" alt="Previous"></a>
<a class="nav" href="mt-xpce.html"><img src="next.gif" alt="Next"></a>
</div>
<h2 id="sec:foreignthread"><a id="sec:9.6"><span class="sec-nr">9.6</span> <span class="sec-title">Multithreaded
mixed C and Prolog applications</span></a></h2>
<a id="sec:foreignthread"></a>
<p>All foreign code linked to the multithreading version of SWI-Prolog
should be thread-safe (<em>reentrant</em>) or guarded in Prolog using
<a id="idx:withmutex2:1813"></a><a class="pred" href="threadsync.html#with_mutex/2">with_mutex/2</a>
from simultaneous access from multiple Prolog threads. If you want to
write mixed multithreaded C and Prolog applications you should first
familiarise yourself with writing multithreaded applications in C (C++).
<p>If you are using SWI-Prolog as an embedded engine in a multithreaded
application you can access the Prolog engine from multiple threads by
creating an <em>engine</em> in each thread from which you call Prolog.
Without creating an engine, a thread can only use functions that do
<em>not</em> use the <code>term_t</code> type (for example <a class="func" href="foreigninclude.html#PL_new_atom()">PL_new_atom()</a>).
<p>The system supports two models. <a class="sec" href="foreignthread.html">Section
9.6.1</a> describes the original one-to-one mapping. In this schema a
native thread attaches a Prolog thread if it needs to call Prolog and
detaches it when finished, as opposed to the model from <a class="sec" href="foreignthread.html">section
9.6.2</a>, where threads temporarily use a Prolog engine.
<p><h3 id="sec:threadoneone"><a id="sec:9.6.1"><span class="sec-nr">9.6.1</span> <span class="sec-title">A
Prolog thread for each native thread (one-to-one)</span></a></h3>
<a id="sec:threadoneone"></a>
<p>In the one-to-one model, the thread that called <a class="func" href="foreigninclude.html#PL_initialise()">PL_initialise()</a>
has a Prolog engine attached. If another C thread in the system wishes
to call Prolog it must first attach an engine using <a class="func" href="foreignthread.html#PL_thread_attach_engine()">PL_thread_attach_engine()</a>
and call <a class="func" href="foreignthread.html#PL_thread_destroy_engine()">PL_thread_destroy_engine()</a>
after all Prolog work is finished. This model is especially suitable
with long running threads that need to do Prolog work regularly. See <a class="sec" href="foreignthread.html">section
9.6.2</a> for the alternative many-to-many model.
<dl class="latex">
<dt class="pubdef"><a id="PL_thread_self()"><var>int</var> <strong>PL_thread_self</strong>(<var></var>)</a></dt>
<dd class="defbody">
Returns the integer Prolog identifier of the engine or -1 if the calling
thread has no Prolog engine. This function is also provided in the
single-threaded version of SWI-Prolog, where it returns -2.</dd>
<dt class="pubdef"><a id="PL_unify_thread_id()"><var>int</var> <strong>PL_unify_thread_id</strong>(<var>term_t
t, int i</var>)</a></dt>
<dd class="defbody">
Unify <var>t</var> with the Prolog thread identifier for thread <var>i</var>.
Thread identifiers are normally returned from <a class="func" href="foreignthread.html#PL_thread_self()">PL_thread_self()</a>.
Returns -1 if the thread does not exist or the unification fails.</dd>
<dt class="pubdef"><a id="PL_thread_attach_engine()"><var>int</var> <strong>PL_thread_attach_engine</strong>(<var>const
PL_thread_attr_t *attr</var>)</a></dt>
<dd class="defbody">
Creates a new Prolog engine in the calling thread. If the calling thread
already has an engine the reference count of the engine is incremented.
The <var>attr</var> argument can be <code>NULL</code> to create a thread
with default attributes. Otherwise it is a pointer to a structure with
the definition below. For any field with value `0', the default is used.
The <code>cancel</code> field may be filled with a pointer to a function
that is called when <a class="func" href="foreigninclude.html#PL_cleanup()">PL_cleanup()</a>
terminates the running Prolog engines. If this function is not present
or returns <code>FALSE</code> pthread_cancel() is used. The <code>flags</code>
field defines the following flags:
<dl class="latex">
<dt><strong>PL_THREAD_NO_DEBUG</strong></dt>
<dd class="defbody">
If this flag is present, the thread starts in normal no-debug status. By
default, the debug status is inherited from the main thread.
</dd>
</dl>
<pre class="code">
typedef struct
{ unsigned long local_size; /* Stack sizes (Kbytes) */
unsigned long global_size;
unsigned long trail_size;
unsigned long argument_size;
char * alias; /* alias name */
int (*cancel)(int thread);
intptr_t flags;
} PL_thread_attr_t;
</pre>
<p>The structure may be destroyed after <a class="func" href="foreignthread.html#PL_thread_attach_engine()">PL_thread_attach_engine()</a>
has returned. On success it returns the Prolog identifier for the thread
(as returned by <a class="func" href="foreignthread.html#PL_thread_self()">PL_thread_self()</a>).
If an error occurs, -1 is returned. If this Prolog is not compiled for
multithreading, -2 is returned.</dd>
<dt class="pubdef"><a id="PL_thread_destroy_engine()"><var>int</var> <strong>PL_thread_destroy_engine</strong>(<var></var>)</a></dt>
<dd class="defbody">
Destroy the Prolog engine in the calling thread. Only takes effect if
<a class="func" href="foreignthread.html#PL_thread_destroy_engine()">PL_thread_destroy_engine()</a>
is called as many times as
<a class="func" href="foreignthread.html#PL_thread_attach_engine()">PL_thread_attach_engine()</a>
in this thread. Returns <code>TRUE</code> on success and <code>FALSE</code>
if the calling thread has no engine or this Prolog does not support
threads.
<p>Please note that construction and destruction of engines are
relatively expensive operations. Only destroy an engine if performance
is not critical and memory is a critical resource.</dd>
<dt class="pubdef"><a id="PL_thread_at_exit()"><var>int</var> <strong>PL_thread_at_exit</strong>(<var>void
(*function)(void *), void *closure, int global</var>)</a></dt>
<dd class="defbody">
Register a handle to be called as the Prolog engine is destroyed. The
handler function is called with one <code>void *</code> argument holding
<var>closure</var>. If <var>global</var> is <code>TRUE</code>, the
handler is installed
<em>for all threads</em>. Globally installed handlers are executed after
the thread-local handlers. If the handler is installed local for the
current thread only (<var>global</var> == <code>FALSE</code>) it is
stored in the same FIFO queue as used by <a id="idx:threadatexit1:1814"></a><a class="pred" href="threadcreate.html#thread_at_exit/1">thread_at_exit/1</a>.
</dd>
</dl>
<p><h3 id="sec:threadmanymany"><a id="sec:9.6.2"><span class="sec-nr">9.6.2</span> <span class="sec-title">Pooling
Prolog engines (many-to-many)</span></a></h3>
<a id="sec:threadmanymany"></a>
<p>In this model Prolog engines live as entities that are independent
from threads. If a thread needs to call Prolog it takes one of the
engines from the pool and returns the engine when done. This model is
suitable in the following identified cases:
<p>
<ul class="latex">
<li><i>Compatibility with the single-threaded version</i><br>
In the single-threaded version, foreign threads must serialise access to
the one and only thread engine. Functions from this section allow
sharing one engine among multiple threads.
<p>
<li><i>Many native threads with infrequent Prolog work</i><br>
Prolog threads are expensive in terms of memory and time to create and
destroy them. For systems that use a large number of threads that only
infrequently need to call Prolog, it is better to take an engine from a
pool and return it there.
<p>
<li><i>Prolog status must be handed to another thread</i><br>
This situation has been identified by Uwe Lesta when creating a .NET
interface for SWI-Prolog. .NET distributes work for an active internet
connection over a pool of threads. If a Prolog engine contains the state
for a connection, it must be possible to detach the engine from a thread
and re-attach it to another thread handling the same connection.
</ul>
<dl class="latex">
<dt class="pubdef"><a id="PL_create_engine()"><var>PL_engine_t</var> <strong>PL_create_engine</strong>(<var>PL_thread_attr_t
*attributes</var>)</a></dt>
<dd class="defbody">
Create a new Prolog engine. <var>attributes</var> is described with
<a class="func" href="foreignthread.html#PL_thread_attach_engine()">PL_thread_attach_engine()</a>.
Any thread can make this call after
<a class="func" href="foreigninclude.html#PL_initialise()">PL_initialise()</a>
returns success. The returned engine is not attached to any thread and
lives until <a class="func" href="foreignthread.html#PL_destroy_engine()">PL_destroy_engine()</a>
is used on the returned handle.
<p>In the single-threaded version this call always returns <code>NULL</code>,
indicating failure.</dd>
<dt class="pubdef"><a id="PL_destroy_engine()"><var>int</var> <strong>PL_destroy_engine</strong>(<var>PL_engine_t
e</var>)</a></dt>
<dd class="defbody">
Destroy the given engine. Destroying an engine is only allowed if the
engine is not attached to any thread or attached to the calling thread.
On success this function returns <code>TRUE</code>, on failure the
return value is <code>FALSE</code>.</dd>
<dt class="pubdef"><a id="PL_set_engine()"><var>int</var> <strong>PL_set_engine</strong>(<var>PL_engine_t
engine, PL_engine_t *old</var>)</a></dt>
<dd class="defbody">
Make the calling thread ready to use <var>engine</var>. If <var>old</var>
is non-<code>NULL</code> the current engine associated with the calling
thread is stored at the given location. If <var>engine</var> equals
<code>PL_ENGINE_MAIN</code> the initial engine is attached to the
calling thread. If <var>engine</var> is <code>PL_ENGINE_CURRENT</code>
the engine is not changed. This can be used to query the current engine.
This call returns
<code>PL_ENGINE_SET</code> if the engine was switched successfully,
<code>PL_ENGINE_INVAL</code> if <var>engine</var> is not a valid engine
handle and
<code>PL_ENGINE_INUSE</code> if the engine is currently in use by
another thread.
<p>Engines can be changed at any time. For example, it is allowed to
select an engine to initiate a Prolog goal, detach it and at a later
moment execute the goal from another thread. Note, however, that the
<code>term_t</code>, <code>qid_t</code> and <code>fid_t</code> types are
interpreted relative to the engine for which they are created. Behaviour
when passing one of these types from one engine to another is undefined.
<p>In the single-threaded version this call only succeeds if <var>engine</var>
refers to the main engine.
</dd>
</dl>
<p></body></html>
|
