<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<title>PulseAudio: Threaded Main Loop</title>
<link href="tabs.css" rel="stylesheet" type="text/css">
<link href="doxygen.css" rel="stylesheet" type="text/css">
</head><body>
<!-- Generated by Doxygen 1.5.8 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="main.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li><a href="examples.html"><span>Examples</span></a></li>
</ul>
</div>
<div class="navpath"><a class="el" href="main.html">main</a> » <a class="el" href="async.html">Asynchronous API</a>
</div>
</div>
<div class="contents">
<h1><a class="anchor" name="threaded_mainloop">Threaded Main Loop </a></h1><h2><a class="anchor" name="overv_sec">
Overview</a></h2>
The threaded main loop implementation is a special version of the primary main loop implementation (see <a class="el" href="mainloop.html">Main Loop</a>). For the basic design, see its documentation.<p>
The added feature in the threaded main loop is that it spawns a new thread that runs the real main loop. This allows a synchronous application to use the asynchronous API without risking to stall the PulseAudio library.<h2><a class="anchor" name="creat_sec">
Creation</a></h2>
A pa_threaded_mainloop object is created using <a class="el" href="thread-mainloop_8h.html#3b8bf5f49d7eb9d6fe6ea008eb6482f2" title="Allocate a new threaded main loop object.">pa_threaded_mainloop_new()</a>. This will only allocate the required structures though, so to use it the thread must also be started. This is done through <a class="el" href="thread-mainloop_8h.html#2faf4ddb9a94f74d6e7ef80843e73d30" title="Start the event loop thread.">pa_threaded_mainloop_start()</a>, after which you can start using the main loop.<h2><a class="anchor" name="destr_sec">
Destruction</a></h2>
When the PulseAudio connection has been terminated, the thread must be stopped and the resources freed. Stopping the thread is done using <a class="el" href="thread-mainloop_8h.html#2a017a59832e81a44aa8989c403fb70e" title="Terminate the event loop thread cleanly.">pa_threaded_mainloop_stop()</a>, which must be called without the lock (see below) held. When that function returns, the thread is stopped and the pa_threaded_mainloop object can be freed using <a class="el" href="thread-mainloop_8h.html#00afff8173668f12e19d574cd4e4134b" title="Free a threaded main loop object.">pa_threaded_mainloop_free()</a>.<h2><a class="anchor" name="lock_sec">
Locking</a></h2>
Since the PulseAudio API doesn't allow concurrent accesses to objects, a locking scheme must be used to guarantee safe usage. The threaded main loop API provides such a scheme through the functions <a class="el" href="thread-mainloop_8h.html#2fd002f510ed24cabacb63a26bf4c977" title="Lock the event loop object, effectively blocking the event loop thread from processing...">pa_threaded_mainloop_lock()</a> and <a class="el" href="thread-mainloop_8h.html#b2b2beaa3a66135da67d61db211f0829" title="Unlock the event loop object, inverse of pa_threaded_mainloop_lock().">pa_threaded_mainloop_unlock()</a>.<p>
The lock is recursive, so it's safe to use it multiple times from the same thread. Just make sure you call <a class="el" href="thread-mainloop_8h.html#b2b2beaa3a66135da67d61db211f0829" title="Unlock the event loop object, inverse of pa_threaded_mainloop_lock().">pa_threaded_mainloop_unlock()</a> the same number of times you called <a class="el" href="thread-mainloop_8h.html#2fd002f510ed24cabacb63a26bf4c977" title="Lock the event loop object, effectively blocking the event loop thread from processing...">pa_threaded_mainloop_lock()</a>.<p>
The lock needs to be held whenever you call any PulseAudio function that uses an object associated with this main loop. Make sure you do not hold on to the lock more than necessary though, as the threaded main loop stops while the lock is held.<p>
Example:<p>
<div class="fragment"><pre class="fragment"> <span class="keywordtype">void</span> my_check_stream_func(<a class="code" href="thread-mainloop_8h.html#40393b9b64dc8213bcd5f017344baf74" title="An opaque threaded main loop object.">pa_threaded_mainloop</a> *m, <a class="code" href="stream_8h.html#960d798980692a2ff01e5a70553d4f29" title="An opaque stream for playback or recording.">pa_stream</a> *s) {
<a class="code" href="def_8h.html#112cf6dbe9ac5554fddc8da251797477" title="The state of a stream.">pa_stream_state_t</a> state;
<a class="code" href="thread-mainloop_8h.html#2fd002f510ed24cabacb63a26bf4c977" title="Lock the event loop object, effectively blocking the event loop thread from processing...">pa_threaded_mainloop_lock</a>(m);
state = <a class="code" href="stream_8h.html#b1da38d494d6485e35f0715f40dff0ab" title="Return the current state of the stream.">pa_stream_get_state</a>(s);
<a class="code" href="thread-mainloop_8h.html#b2b2beaa3a66135da67d61db211f0829" title="Unlock the event loop object, inverse of pa_threaded_mainloop_lock().">pa_threaded_mainloop_unlock</a>(m);
<span class="keywordflow">if</span> (state == <a class="code" href="def_8h.html#71341d6e189549fc0bd25ab669016df91e72fb989b308e2317c0b0949afe5446" title="The stream is established, you may pass audio data to it now.">PA_STREAM_READY</a>)
printf(<span class="stringliteral">"Stream is ready!"</span>);
<span class="keywordflow">else</span>
printf(<span class="stringliteral">"Stream is not ready!"</span>);
}
</pre></div><h2><a class="anchor" name="cb_sec">
Callbacks</a></h2>
Callbacks in PulseAudio are asynchronous, so they require extra care when using them together with a threaded main loop.<p>
The easiest way to turn the callback based operations into synchronous ones, is to simply wait for the callback to be called and continue from there. This is the approach chosen in PulseAudio's threaded API.<h3><a class="anchor" name="basic_subsec">
Basic callbacks</a></h3>
For the basic case, where all that is required is to wait for the callback to be invoked, the code should look something like this:<p>
Example:<p>
<div class="fragment"><pre class="fragment"> <span class="keyword">static</span> <span class="keywordtype">void</span> my_drain_callback(<a class="code" href="stream_8h.html#960d798980692a2ff01e5a70553d4f29" title="An opaque stream for playback or recording.">pa_stream</a> *s, <span class="keywordtype">int</span> success, <span class="keywordtype">void</span> *userdata) {
<a class="code" href="thread-mainloop_8h.html#40393b9b64dc8213bcd5f017344baf74" title="An opaque threaded main loop object.">pa_threaded_mainloop</a> *m;
m = userdata;
assert(m);
<a class="code" href="thread-mainloop_8h.html#d253b70911af81c04417793841a15766" title="Signal all threads waiting for a signalling event in pa_threaded_mainloop_wait()...">pa_threaded_mainloop_signal</a>(m, 0);
}
<span class="keywordtype">void</span> my_drain_stream_func(<a class="code" href="thread-mainloop_8h.html#40393b9b64dc8213bcd5f017344baf74" title="An opaque threaded main loop object.">pa_threaded_mainloop</a> *m, <a class="code" href="stream_8h.html#960d798980692a2ff01e5a70553d4f29" title="An opaque stream for playback or recording.">pa_stream</a> *s) {
<a class="code" href="operation_8h.html#5614a07f2e7a129e4cb16596ed452a0c" title="An asynchronous operation object.">pa_operation</a> *o;
<a class="code" href="thread-mainloop_8h.html#2fd002f510ed24cabacb63a26bf4c977" title="Lock the event loop object, effectively blocking the event loop thread from processing...">pa_threaded_mainloop_lock</a>(m);
o = <a class="code" href="stream_8h.html#8d263f188073f244b3820f3f50db4ba5" title="Drain a playback stream.">pa_stream_drain</a>(s, my_drain_callback, m);
assert(o);
<span class="keywordflow">while</span> (<a class="code" href="operation_8h.html#cabeaea114e87658e1dadc214d7a2c35" title="Return the current status of the operation.">pa_operation_get_state</a>(o) == <a class="code" href="def_8h.html#c0a07dd2ef771a72d48e5ba2c56ac3bc9486b0f1b7da21dcc34f5cb3f7091c6f" title="The operation is still running.">PA_OPERATION_RUNNING</a>)
<a class="code" href="thread-mainloop_8h.html#c96d19260567d0406350f1b3a14c4bed" title="Wait for an event to be signalled by the event loop thread.">pa_threaded_mainloop_wait</a>(m);
<a class="code" href="operation_8h.html#8d2ef9bb2ff961ee31675882bf125227" title="Decrease the reference count by one.">pa_operation_unref</a>(o);
<a class="code" href="thread-mainloop_8h.html#b2b2beaa3a66135da67d61db211f0829" title="Unlock the event loop object, inverse of pa_threaded_mainloop_lock().">pa_threaded_mainloop_unlock</a>(m);
}
</pre></div><p>
The main function, my_drain_stream_func(), will wait for the callback to be called using <a class="el" href="thread-mainloop_8h.html#c96d19260567d0406350f1b3a14c4bed" title="Wait for an event to be signalled by the event loop thread.">pa_threaded_mainloop_wait()</a>.<p>
If your application is multi-threaded, then this waiting must be done inside a while loop. The reason for this is that multiple threads might be using <a class="el" href="thread-mainloop_8h.html#c96d19260567d0406350f1b3a14c4bed" title="Wait for an event to be signalled by the event loop thread.">pa_threaded_mainloop_wait()</a> at the same time. Each thread must therefore verify that it was its callback that was invoked.<p>
The callback, my_drain_callback(), indicates to the main function that it has been called using <a class="el" href="thread-mainloop_8h.html#d253b70911af81c04417793841a15766" title="Signal all threads waiting for a signalling event in pa_threaded_mainloop_wait()...">pa_threaded_mainloop_signal()</a>.<p>
As you can see, both <a class="el" href="thread-mainloop_8h.html#c96d19260567d0406350f1b3a14c4bed" title="Wait for an event to be signalled by the event loop thread.">pa_threaded_mainloop_wait()</a> may only be called with the lock held. The same thing is true for <a class="el" href="thread-mainloop_8h.html#d253b70911af81c04417793841a15766" title="Signal all threads waiting for a signalling event in pa_threaded_mainloop_wait()...">pa_threaded_mainloop_signal()</a>, but as the lock is held before the callback is invoked, you do not have to deal with that.<p>
The functions will not dead lock because the wait function will release the lock before waiting and then regrab it once it has been signaled. For those of you familiar with threads, the behaviour is that of a condition variable.<h3><a class="anchor" name="data_subsec">
Data callbacks</a></h3>
For many callbacks, simply knowing that they have been called is insufficient. The callback also receives some data that is desired. To access this data safely, we must extend our example a bit:<p>
<div class="fragment"><pre class="fragment"> <span class="keyword">static</span> <span class="keywordtype">int</span> *drain_result;
<span class="keyword">static</span> <span class="keywordtype">void</span> my_drain_callback(<a class="code" href="stream_8h.html#960d798980692a2ff01e5a70553d4f29" title="An opaque stream for playback or recording.">pa_stream</a>*s, <span class="keywordtype">int</span> success, <span class="keywordtype">void</span> *userdata) {
<a class="code" href="thread-mainloop_8h.html#40393b9b64dc8213bcd5f017344baf74" title="An opaque threaded main loop object.">pa_threaded_mainloop</a> *m;
m = userdata;
assert(m);
drain_result = &success;
<a class="code" href="thread-mainloop_8h.html#d253b70911af81c04417793841a15766" title="Signal all threads waiting for a signalling event in pa_threaded_mainloop_wait()...">pa_threaded_mainloop_signal</a>(m, 1);
}
<span class="keywordtype">void</span> my_drain_stream_func(<a class="code" href="thread-mainloop_8h.html#40393b9b64dc8213bcd5f017344baf74" title="An opaque threaded main loop object.">pa_threaded_mainloop</a> *m, <a class="code" href="stream_8h.html#960d798980692a2ff01e5a70553d4f29" title="An opaque stream for playback or recording.">pa_stream</a> *s) {
<a class="code" href="operation_8h.html#5614a07f2e7a129e4cb16596ed452a0c" title="An asynchronous operation object.">pa_operation</a> *o;
<a class="code" href="thread-mainloop_8h.html#2fd002f510ed24cabacb63a26bf4c977" title="Lock the event loop object, effectively blocking the event loop thread from processing...">pa_threaded_mainloop_lock</a>(m);
o = <a class="code" href="stream_8h.html#8d263f188073f244b3820f3f50db4ba5" title="Drain a playback stream.">pa_stream_drain</a>(s, my_drain_callback, m);
assert(o);
<span class="keywordflow">while</span> (<a class="code" href="operation_8h.html#cabeaea114e87658e1dadc214d7a2c35" title="Return the current status of the operation.">pa_operation_get_state</a>(o) == <a class="code" href="def_8h.html#c0a07dd2ef771a72d48e5ba2c56ac3bc9486b0f1b7da21dcc34f5cb3f7091c6f" title="The operation is still running.">PA_OPERATION_RUNNING</a>)
<a class="code" href="thread-mainloop_8h.html#c96d19260567d0406350f1b3a14c4bed" title="Wait for an event to be signalled by the event loop thread.">pa_threaded_mainloop_wait</a>(m);
<a class="code" href="operation_8h.html#8d2ef9bb2ff961ee31675882bf125227" title="Decrease the reference count by one.">pa_operation_unref</a>(o);
<span class="keywordflow">if</span> (*drain_result)
printf(<span class="stringliteral">"Success!"</span>);
<span class="keywordflow">else</span>
printf(<span class="stringliteral">"Bitter defeat..."</span>);
<a class="code" href="thread-mainloop_8h.html#254b0862e30845a4b0427a7a74b3db91" title="Accept a signal from the event thread issued with pa_threaded_mainloop_signal().">pa_threaded_mainloop_accept</a>(m);
<a class="code" href="thread-mainloop_8h.html#b2b2beaa3a66135da67d61db211f0829" title="Unlock the event loop object, inverse of pa_threaded_mainloop_lock().">pa_threaded_mainloop_unlock</a>(m);
}
</pre></div><p>
The example is a bit silly as it would probably have been easier to just copy the contents of success, but for larger data structures this can be wasteful.<p>
The difference here compared to the basic callback is the 1 sent to <a class="el" href="thread-mainloop_8h.html#d253b70911af81c04417793841a15766" title="Signal all threads waiting for a signalling event in pa_threaded_mainloop_wait()...">pa_threaded_mainloop_signal()</a> and the call to <a class="el" href="thread-mainloop_8h.html#254b0862e30845a4b0427a7a74b3db91" title="Accept a signal from the event thread issued with pa_threaded_mainloop_signal().">pa_threaded_mainloop_accept()</a>. What will happen is that <a class="el" href="thread-mainloop_8h.html#d253b70911af81c04417793841a15766" title="Signal all threads waiting for a signalling event in pa_threaded_mainloop_wait()...">pa_threaded_mainloop_signal()</a> will signal the main function and then stop. The main function is then free to use the data in the callback until <a class="el" href="thread-mainloop_8h.html#254b0862e30845a4b0427a7a74b3db91" title="Accept a signal from the event thread issued with pa_threaded_mainloop_signal().">pa_threaded_mainloop_accept()</a> is called, which will allow the callback to continue.<p>
Note that <a class="el" href="thread-mainloop_8h.html#254b0862e30845a4b0427a7a74b3db91" title="Accept a signal from the event thread issued with pa_threaded_mainloop_signal().">pa_threaded_mainloop_accept()</a> must be called some time between exiting the while loop and unlocking the main loop! Failure to do so will result in a race condition. I.e. it is not ok to release the lock and regrab it before calling <a class="el" href="thread-mainloop_8h.html#254b0862e30845a4b0427a7a74b3db91" title="Accept a signal from the event thread issued with pa_threaded_mainloop_signal().">pa_threaded_mainloop_accept()</a>.<h3><a class="anchor" name="async_subsec">
Asynchronous callbacks</a></h3>
PulseAudio also has callbacks that are completely asynchronous, meaning that they can be called at any time. The threading main loop API provides the locking mechanism to handle concurrent accesses, but nothing else. Applications will have to handle communication from the callback to the main program through some own system.<p>
The callbacks that are completely asynchronous are:<p>
<ul>
<li>State callbacks for contexts, streams, etc. </li>
<li>Subscription notifications </li>
</ul>
</div>
<hr size="1"><address style="text-align: right;"><small>Generated on Wed Sep 2 04:18:20 2009 for PulseAudio by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.8 </small></address>
</body>
</html>
distrib
>
Mandriva
>
2009.1
>
x86_64
>
media
>
main-testing
>
by-pkgid
>
187676b5433787923dfa2cdd6900c6cd
>
files
>
184
