/usr/share/doc/allegro5-doc/refman/threads.html is in allegro5-doc 2:5.0.10-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<meta name="generator" content="pandoc" />
<title>Threads</title>
<style type="text/css">code{white-space: pre;}</style>
<link rel="stylesheet" href="pandoc.css" type="text/css" />
<script type="text/javascript" src="autosuggest.js"></script>
<script type="text/javascript" src="search_index.js"></script>
</head>
<body>
<div class="sidebar">
<div>
<ul>
<li><a href="index.html"><strong>Contents</strong></a></li>
<li><a href="config.html">Configuration files</a></li>
<li><a href="display.html">Display</a></li>
<li><a href="events.html">Events</a></li>
<li><a href="file.html">File I/O</a></li>
<li><a href="fshook.html">Filesystem</a></li>
<li><a href="fixed.html">Fixed point math</a></li>
<li><a href="fullscreen_mode.html">Fullscreen modes</a></li>
<li><a href="graphics.html">Graphics</a></li>
<li><a href="joystick.html">Joystick</a></li>
<li><a href="keyboard.html">Keyboard</a></li>
<li><a href="memory.html">Memory</a></li>
<li><a href="monitor.html">Monitor</a></li>
<li><a href="mouse.html">Mouse</a></li>
<li><a href="path.html">Path</a></li>
<li><a href="state.html">State</a></li>
<li><a href="system.html">System</a></li>
<li><a href="threads.html">Threads</a></li>
<li><a href="time.html">Time</a></li>
<li><a href="timer.html">Timer</a></li>
<li><a href="transformations.html">Transformations</a></li>
<li><a href="utf8.html">UTF-8</a></li>
<li><a href="misc.html">Miscellaneous</a></li>
<li><a href="platform.html">Platform-specific</a></li>
<li><a href="direct3d.html">Direct3D</a></li>
<li><a href="opengl.html">OpenGL</a></li>
</ul>
<!-- The preceding blank line forces pandoc to terminate the list -->
</div>
<div>
<ul>
<li><a href="index.html#addons"><strong>Addons</strong></a></li>
<li><a href="audio.html">Audio addon</a></li>
<li><a href="acodec.html">Audio codecs</a></li>
<li><a href="color.html">Color addon</a></li>
<li><a href="font.html">Font addons</a></li>
<li><a href="image.html">Image I/O addon</a></li>
<li><a href="main.html">Main addon</a></li>
<li><a href="memfile.html">Memfile addon</a></li>
<li><a href="native_dialog.html">Native dialogs addon</a></li>
<li><a href="physfs.html">PhysicsFS addon</a></li>
<li><a href="primitives.html">Primitives addon</a></li>
</ul>
<!-- The preceding blank line forces pandoc to terminate the list -->
</div>
<div>
<ul>
<li><a href="index_all.html"><strong>Index</strong></a></li>
</ul>
<!-- The preceding blank line forces pandoc to terminate the list -->
</div>
<div class="searchbox">
<script type="text/javascript">
function on_search(index, control) {
// Note to self: the less-than sign must NOT converted to an entity!
// SCRIPT elements are special. The HTML validator gives bad advice.
for (i = 0; i < search_index.length; i++) {
if (search_index[i] == control.keywords[index]) {
break;
}
}
location.href = search_urls[i];
}
</script>
Search<br/> <input type="text" name="q" id="q" size="15" autocomplete="off"/><br/>
<script type="text/javascript"> new autosuggest("q", search_index, null, on_search); </script>
</div>
</div>
<div class="content">
<div id="header">
<h1 class="title">Threads</h1>
</div>
<div id="TOC">
<ul>
<li><a href="#allegro_thread">ALLEGRO_THREAD</a></li>
<li><a href="#allegro_mutex">ALLEGRO_MUTEX</a></li>
<li><a href="#allegro_cond">ALLEGRO_COND</a></li>
<li><a href="#al_create_thread">al_create_thread</a></li>
<li><a href="#al_start_thread">al_start_thread</a></li>
<li><a href="#al_join_thread">al_join_thread</a></li>
<li><a href="#al_set_thread_should_stop">al_set_thread_should_stop</a></li>
<li><a href="#al_get_thread_should_stop">al_get_thread_should_stop</a></li>
<li><a href="#al_destroy_thread">al_destroy_thread</a></li>
<li><a href="#al_run_detached_thread">al_run_detached_thread</a></li>
<li><a href="#al_create_mutex">al_create_mutex</a></li>
<li><a href="#al_create_mutex_recursive">al_create_mutex_recursive</a></li>
<li><a href="#al_lock_mutex">al_lock_mutex</a></li>
<li><a href="#al_unlock_mutex">al_unlock_mutex</a></li>
<li><a href="#al_destroy_mutex">al_destroy_mutex</a></li>
<li><a href="#al_create_cond">al_create_cond</a></li>
<li><a href="#al_destroy_cond">al_destroy_cond</a></li>
<li><a href="#al_wait_cond">al_wait_cond</a></li>
<li><a href="#al_wait_cond_until">al_wait_cond_until</a></li>
<li><a href="#al_broadcast_cond">al_broadcast_cond</a></li>
<li><a href="#al_signal_cond">al_signal_cond</a></li>
</ul>
</div>
<p>Allegro includes a simple cross-platform threading interface. It is a thin layer on top of two threading APIs: Windows threads and POSIX Threads (pthreads). Enforcing a consistent semantics on all platforms would be difficult at best, hence the behaviour of the following functions will differ subtly on different platforms (more so than usual). Your best bet is to be aware of this and code to the intersection of the semantics and avoid edge cases.</p>
<p>These functions are declared in the main Allegro header file:</p>
<pre><code>#include <allegro5/allegro.h></code></pre>
<h1 id="allegro_thread"><a href="#allegro_thread">ALLEGRO_THREAD</a></h1>
<pre><code>typedef struct ALLEGRO_THREAD ALLEGRO_THREAD;</code></pre>
<p>An opaque structure representing a thread.</p>
<h1 id="allegro_mutex"><a href="#allegro_mutex">ALLEGRO_MUTEX</a></h1>
<pre><code>typedef struct ALLEGRO_MUTEX ALLEGRO_MUTEX;</code></pre>
<p>An opaque structure representing a mutex.</p>
<h1 id="allegro_cond"><a href="#allegro_cond">ALLEGRO_COND</a></h1>
<pre><code>typedef struct ALLEGRO_COND ALLEGRO_COND;</code></pre>
<p>An opaque structure representing a condition variable.</p>
<h1 id="al_create_thread"><a href="#al_create_thread">al_create_thread</a></h1>
<pre><code>ALLEGRO_THREAD *al_create_thread(
void *(*proc)(ALLEGRO_THREAD *thread, void *arg), void *arg)</code></pre>
<p>Spawn a new thread which begins executing <code>proc</code>. The new thread is passed its own thread handle and the value <code>arg</code>.</p>
<p>Returns a pointer to the thread on success. Otherwise, returns NULL if there was an error.</p>
<p>See also: <a href="threads.html#al_start_thread">al_start_thread</a>, <a href="threads.html#al_join_thread">al_join_thread</a>.</p>
<h1 id="al_start_thread"><a href="#al_start_thread">al_start_thread</a></h1>
<pre><code>void al_start_thread(ALLEGRO_THREAD *thread)</code></pre>
<p>When a thread is created, it is initially in a suspended state. Calling <a href="threads.html#al_start_thread">al_start_thread</a> will start its actual execution.</p>
<p>Starting a thread which has already been started does nothing.</p>
<p>See also: <a href="threads.html#al_create_thread">al_create_thread</a>.</p>
<h1 id="al_join_thread"><a href="#al_join_thread">al_join_thread</a></h1>
<pre><code>void al_join_thread(ALLEGRO_THREAD *thread, void **ret_value)</code></pre>
<p>Wait for the thread to finish executing. This implicitly calls <a href="threads.html#al_set_thread_should_stop">al_set_thread_should_stop</a> first.</p>
<p>If <code>ret_value</code> is non-<code>NULL</code>, the value returned by the thread function will be stored at the location pointed to by <code>ret_value</code>.</p>
<p>See also: <a href="threads.html#al_set_thread_should_stop">al_set_thread_should_stop</a>, <a href="threads.html#al_get_thread_should_stop">al_get_thread_should_stop</a>, <a href="threads.html#al_destroy_thread">al_destroy_thread</a>.</p>
<h1 id="al_set_thread_should_stop"><a href="#al_set_thread_should_stop">al_set_thread_should_stop</a></h1>
<pre><code>void al_set_thread_should_stop(ALLEGRO_THREAD *thread)</code></pre>
<p>Set the flag to indicate <code>thread</code> should stop. Returns immediately.</p>
<p>See also: <a href="threads.html#al_join_thread">al_join_thread</a>, <a href="threads.html#al_get_thread_should_stop">al_get_thread_should_stop</a>.</p>
<h1 id="al_get_thread_should_stop"><a href="#al_get_thread_should_stop">al_get_thread_should_stop</a></h1>
<pre><code>bool al_get_thread_should_stop(ALLEGRO_THREAD *thread)</code></pre>
<p>Check if another thread is waiting for <code>thread</code> to stop. Threads which run in a loop should check this periodically and act on it when convenient.</p>
<p>Returns true if another thread has called <a href="threads.html#al_join_thread">al_join_thread</a> or <a href="threads.html#al_set_thread_should_stop">al_set_thread_should_stop</a> on this thread.</p>
<p>See also: <a href="threads.html#al_join_thread">al_join_thread</a>, <a href="threads.html#al_set_thread_should_stop">al_set_thread_should_stop</a>.</p>
<blockquote>
<p><em>Note:</em> We don't support forceful killing of threads.</p>
</blockquote>
<h1 id="al_destroy_thread"><a href="#al_destroy_thread">al_destroy_thread</a></h1>
<pre><code>void al_destroy_thread(ALLEGRO_THREAD *thread)</code></pre>
<p>Free the resources used by a thread. Implicitly performs <a href="threads.html#al_join_thread">al_join_thread</a> on the thread if it hasn't been done already.</p>
<p>Does nothing if <code>thread</code> is NULL.</p>
<p>See also: <a href="threads.html#al_join_thread">al_join_thread</a>.</p>
<h1 id="al_run_detached_thread"><a href="#al_run_detached_thread">al_run_detached_thread</a></h1>
<pre><code>void al_run_detached_thread(void *(*proc)(void *arg), void *arg)</code></pre>
<p>Runs the passed function in its own thread, with <code>arg</code> passed to it as only parameter. This is similar to calling <a href="threads.html#al_create_thread">al_create_thread</a>, <a href="threads.html#al_start_thread">al_start_thread</a> and (after the thread has finished) <a href="threads.html#al_destroy_thread">al_destroy_thread</a> - but you don't have the possibility of ever calling <a href="threads.html#al_join_thread">al_join_thread</a> on the thread any longer.</p>
<h1 id="al_create_mutex"><a href="#al_create_mutex">al_create_mutex</a></h1>
<pre><code>ALLEGRO_MUTEX *al_create_mutex(void)</code></pre>
<p>Create the mutex object (a mutual exclusion device). The mutex may or may not support "recursive" locking.</p>
<p>Returns the mutex on success or <code>NULL</code> on error.</p>
<p>See also: <a href="threads.html#al_create_mutex_recursive">al_create_mutex_recursive</a>.</p>
<h1 id="al_create_mutex_recursive"><a href="#al_create_mutex_recursive">al_create_mutex_recursive</a></h1>
<pre><code>ALLEGRO_MUTEX *al_create_mutex_recursive(void)</code></pre>
<p>Create the mutex object (a mutual exclusion device), with support for "recursive" locking. That is, the mutex will count the number of times it has been locked by the same thread. If the caller tries to acquire a lock on the mutex when it already holds the lock then the count is incremented. The mutex is only unlocked when the thread releases the lock on the mutex an equal number of times, i.e. the count drops down to zero.</p>
<p>See also: <a href="threads.html#al_create_mutex">al_create_mutex</a>.</p>
<h1 id="al_lock_mutex"><a href="#al_lock_mutex">al_lock_mutex</a></h1>
<pre><code>void al_lock_mutex(ALLEGRO_MUTEX *mutex)</code></pre>
<p>Acquire the lock on <code>mutex</code>. If the mutex is already locked by another thread, the call will block until the mutex becomes available and locked.</p>
<p>If the mutex is already locked by the calling thread, then the behaviour depends on whether the mutex was created with <a href="threads.html#al_create_mutex">al_create_mutex</a> or <a href="threads.html#al_create_mutex_recursive">al_create_mutex_recursive</a>. In the former case, the behaviour is undefined; the most likely behaviour is deadlock. In the latter case, the count in the mutex will be incremented and the call will return immediately.</p>
<p>See also: <a href="threads.html#al_unlock_mutex">al_unlock_mutex</a>.</p>
<p><strong>We don't yet have al_mutex_trylock.</strong></p>
<h1 id="al_unlock_mutex"><a href="#al_unlock_mutex">al_unlock_mutex</a></h1>
<pre><code>void al_unlock_mutex(ALLEGRO_MUTEX *mutex)</code></pre>
<p>Release the lock on <code>mutex</code> if the calling thread holds the lock on it.</p>
<p>If the calling thread doesn't hold the lock, or if the mutex is not locked, undefined behaviour results.</p>
<p>See also: <a href="threads.html#al_lock_mutex">al_lock_mutex</a>.</p>
<h1 id="al_destroy_mutex"><a href="#al_destroy_mutex">al_destroy_mutex</a></h1>
<pre><code>void al_destroy_mutex(ALLEGRO_MUTEX *mutex)</code></pre>
<p>Free the resources used by the mutex. The mutex should be unlocked. Destroying a locked mutex results in undefined behaviour.</p>
<p>Does nothing if <code>mutex</code> is <code>NULL</code>.</p>
<h1 id="al_create_cond"><a href="#al_create_cond">al_create_cond</a></h1>
<pre><code>ALLEGRO_COND *al_create_cond(void)</code></pre>
<p>Create a condition variable.</p>
<p>Returns the condition value on success or <code>NULL</code> on error.</p>
<h1 id="al_destroy_cond"><a href="#al_destroy_cond">al_destroy_cond</a></h1>
<pre><code>void al_destroy_cond(ALLEGRO_COND *cond)</code></pre>
<p>Destroy a condition variable.</p>
<p>Destroying a condition variable which has threads block on it results in undefined behaviour.</p>
<p>Does nothing if <code>cond</code> is <code>NULL</code>.</p>
<h1 id="al_wait_cond"><a href="#al_wait_cond">al_wait_cond</a></h1>
<pre><code>void al_wait_cond(ALLEGRO_COND *cond, ALLEGRO_MUTEX *mutex)</code></pre>
<p>On entering this function, <code>mutex</code> must be locked by the calling thread. The function will atomically release <code>mutex</code> and block on <code>cond</code>. The function will return when <code>cond</code> is "signalled", acquiring the lock on the mutex in the process.</p>
<p>Example of proper use:</p>
<pre><code>al_lock_mutex(mutex);
while (something_not_true) {
al_wait_cond(cond, mutex);
}
do_something();
al_unlock_mutex(mutex);</code></pre>
<p>The mutex should be locked before checking the condition, and should be rechecked <a href="threads.html#al_wait_cond">al_wait_cond</a> returns. <a href="threads.html#al_wait_cond">al_wait_cond</a> can return for other reasons than the condition becoming true (e.g. the process was signalled). If multiple threads are blocked on the condition variable, the condition may no longer be true by the time the second and later threads are unblocked. Remember not to unlock the mutex prematurely.</p>
<p>See also: <a href="threads.html#al_wait_cond_until">al_wait_cond_until</a>, <a href="threads.html#al_broadcast_cond">al_broadcast_cond</a>, <a href="threads.html#al_signal_cond">al_signal_cond</a>.</p>
<h1 id="al_wait_cond_until"><a href="#al_wait_cond_until">al_wait_cond_until</a></h1>
<pre><code>int al_wait_cond_until(ALLEGRO_COND *cond, ALLEGRO_MUTEX *mutex,
const ALLEGRO_TIMEOUT *timeout)</code></pre>
<p>Like <a href="threads.html#al_wait_cond">al_wait_cond</a> but the call can return if the absolute time passes <code>timeout</code> before the condition is signalled.</p>
<p>Returns zero on success, non-zero if the call timed out.</p>
<p>See also: <a href="threads.html#al_wait_cond">al_wait_cond</a></p>
<h1 id="al_broadcast_cond"><a href="#al_broadcast_cond">al_broadcast_cond</a></h1>
<pre><code>void al_broadcast_cond(ALLEGRO_COND *cond)</code></pre>
<p>Unblock all threads currently waiting on a condition variable. That is, broadcast that some condition which those threads were waiting for has become true.</p>
<p>See also: <a href="threads.html#al_signal_cond">al_signal_cond</a>.</p>
<blockquote>
<p><em>Note:</em> The pthreads spec says to lock the mutex associated with <code>cond</code> before signalling for predictable scheduling behaviour.</p>
</blockquote>
<h1 id="al_signal_cond"><a href="#al_signal_cond">al_signal_cond</a></h1>
<pre><code>void al_signal_cond(ALLEGRO_COND *cond)</code></pre>
<p>Unblock at least one thread waiting on a condition variable.</p>
<p>Generally you should use <a href="threads.html#al_broadcast_cond">al_broadcast_cond</a> but <a href="threads.html#al_signal_cond">al_signal_cond</a> may be more efficient when it's applicable.</p>
<p>See also: <a href="threads.html#al_broadcast_cond">al_broadcast_cond</a>.</p>
<p class="timestamp">
Allegro version 5.0.10
- Last updated: 2013-10-21 16:36:10 UTC
</p>
</div>
</body>
</html>
|