[polypaudio-commits] r892 - in /trunk/src/polyp: context.h polypaudio.h thread-mainloop.h
svnmailer-noreply at 0pointer.de
svnmailer-noreply at 0pointer.de
Wed May 17 04:07:17 PDT 2006
Author: ossman
Date: Wed May 17 13:07:16 2006
New Revision: 892
URL: http://0pointer.de/cgi-bin/viewcvs.cgi?rev=892&root=polypaudio&view=rev
Log:
Documentation for the threaded main loop API.
Modified:
trunk/src/polyp/context.h
trunk/src/polyp/polypaudio.h
trunk/src/polyp/thread-mainloop.h
Modified: trunk/src/polyp/context.h
URL: http://0pointer.de/cgi-bin/viewcvs.cgi/trunk/src/polyp/context.h?rev=892&root=polypaudio&r1=891&r2=892&view=diff
==============================================================================
--- trunk/src/polyp/context.h (original)
+++ trunk/src/polyp/context.h Wed May 17 13:07:16 2006
@@ -51,13 +51,17 @@
* pa_mainloop_api structure.
*
* To actually be able to use these functions, an implementation needs to
- * be coupled to the abstraction. There are two of these shipped with
+ * be coupled to the abstraction. There are three of these shipped with
* polypaudio, but any other can be used with a minimal ammount of work,
* provided it supports the three basic events listed above.
*
* The implementations shipped with polypaudio are:
*
* \li \subpage mainloop - A minimal but fast implementation based on poll().
+ * \li \subpage threaded_mainloop - A special version of the previous
+ * implementation where all of Polypaudio's
+ * internal handling runs in a separate
+ * thread.
* \li \subpage glib-mainloop - A wrapper around GLIB's main loop. Available
* for both GLIB 1.2 and GLIB 2.x.
*
Modified: trunk/src/polyp/polypaudio.h
URL: http://0pointer.de/cgi-bin/viewcvs.cgi/trunk/src/polyp/polypaudio.h?rev=892&root=polypaudio&r1=891&r2=892&view=diff
==============================================================================
--- trunk/src/polyp/polypaudio.h (original)
+++ trunk/src/polyp/polypaudio.h Wed May 17 13:07:16 2006
@@ -66,6 +66,11 @@
* based style or if you want to use the advanced features of the
* polypaudio API. A guide can be found in \subpage async.
*
+ * By using the built-in threaded main loop, it is possible to acheive a
+ * pseudo-synchronous API, which can be useful in synchronous applications
+ * where the simple API is insufficient. See the \ref async page for
+ * details.
+ *
* \section thread_sec Threads
*
* The polypaudio client libraries are not designed to be used in a
@@ -73,12 +78,12 @@
* safe.
*
* To use a the libraries in a threaded environment, you must assure that
- * all objects are only used in the same thread they were created in.
- * Normally, this means that all objects belonging to a single context
- * must be accessed from the same thread.
+ * all objects are only used in one thread at a time. Normally, this means
+ * that all objects belonging to a single context must be accessed from the
+ * same thread.
*
* The included main loop implementation is also not thread safe. Take care
- * to make sure event lists are not manipulated when any library code is
+ * to make sure event lists are not manipulated when any other code is
* using the main loop.
*
* \section pkgconfig pkg-config
Modified: trunk/src/polyp/thread-mainloop.h
URL: http://0pointer.de/cgi-bin/viewcvs.cgi/trunk/src/polyp/thread-mainloop.h?rev=892&root=polypaudio&r1=891&r2=892&view=diff
==============================================================================
--- trunk/src/polyp/thread-mainloop.h (original)
+++ trunk/src/polyp/thread-mainloop.h Wed May 17 13:07:16 2006
@@ -27,6 +27,207 @@
PA_C_DECL_BEGIN
+/** \page threaded_mainloop Threaded Main Loop
+ *
+ * \section overv_sec Overview
+ *
+ * The threaded main loop implementation is a special version of the primary
+ * main loop implementation (see \ref mainloop). For the basic design, see
+ * its documentation.
+ *
+ * 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 Polypaudio library.
+ *
+ * \section creat_sec Creation
+ *
+ * A pa_threaded_mainloop object is created using pa_threaded_mainloop_new().
+ * This will only allocate the required structures though, so to use it the
+ * thread must also be started. This is done through
+ * pa_threaded_mainloop_start(), after which you can start using the main loop.
+ *
+ * \section destr_sec Destruction
+ *
+ * When the Polypaudio connection has been terminated, the thread must be
+ * stopped and the resources freed. Stopping the thread is done using
+ * pa_threaded_mainloop_stop(), 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 pa_threaded_mainloop_free().
+ *
+ * \section lock_sec Locking
+ *
+ * Since the Polypaudio 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
+ * pa_threaded_mainloop_lock() and pa_threaded_mainloop_unlock().
+ *
+ * The lock is recursive, so it's safe to use it multiple times from the same
+ * thread. Just make sure you call pa_threaded_mainloop_unlock() the same
+ * number of times you called pa_threaded_mainloop_lock().
+ *
+ * The lock needs to be held whenever you call any Polypaudio 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.
+ *
+ * Example:
+ *
+ * \code
+ * void my_check_stream_func(pa_threaded_mainloop *m, pa_stream *s) {
+ * pa_stream_state_t state;
+ *
+ * pa_threaded_mainloop_lock(m);
+ *
+ * state = pa_stream_get_state(s);
+ *
+ * pa_threaded_mainloop_unlock(m);
+ *
+ * if (state == PA_STREAM_READY)
+ * printf("Stream is ready!");
+ * else
+ * printf("Stream is not ready!");
+ * }
+ * \endcode
+ *
+ * \section cb_sec Callbacks
+ *
+ * Callbacks in Polypaudio are asynchronous, so they require extra care when
+ * using them together with a threaded main loop.
+ *
+ * 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 Polypaudio's threaded API.
+ *
+ * \subsection basic_subsec Basic callbacks
+ *
+ * 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:
+ *
+ * Example:
+ *
+ * \code
+ * static void my_drain_callback(pa_stream*s, int success, void *userdata) {
+ * pa_threaded_mainloop *m;
+ *
+ * m = (pa_threaded_mainloop*)userdata;
+ * assert(m);
+ *
+ * pa_threaded_mainloop_signal(m, 0);
+ * }
+ *
+ * void my_drain_stream_func(pa_threaded_mainloop *m, pa_stream *s) {
+ * pa_operation *o;
+ *
+ * pa_threaded_mainloop_lock(m);
+ *
+ * o = pa_stream_drain(s, my_drain_callback, m);
+ * assert(o);
+ *
+ * while (pa_operation_get_state(o) != OPERATION_DONE)
+ * pa_threaded_mainloop_wait(m);
+ *
+ * pa_operation_unref(o);
+ *
+ * pa_threaded_mainloop_unlock(m);
+ * }
+ * \endcode
+ *
+ * The main function, my_drain_stream_func(), will wait for the callback to
+ * be called using pa_threaded_mainloop_wait().
+ *
+ * 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 pa_threaded_mainloop_wait() at the same time. Each thread must
+ * therefore verify that it was its callback that was invoked.
+ *
+ * The callback, my_drain_callback(), indicates to the main function that it
+ * has been called using pa_threaded_mainloop_signal().
+ *
+ * As you can see, both pa_threaded_mainloop_wait() may only be called with
+ * the lock held. The same thing is true for pa_threaded_mainloop_signal(),
+ * but as the lock is held before the callback is invoked, you do not have to
+ * deal with that.
+ *
+ * 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.
+ *
+ * \subsection data_subsec Data callbacks
+ *
+ * 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:
+ *
+ * \code
+ * static int *drain_result;
+ *
+ * static void my_drain_callback(pa_stream*s, int success, void *userdata) {
+ * pa_threaded_mainloop *m;
+ *
+ * m = (pa_threaded_mainloop*)userdata;
+ * assert(m);
+ *
+ * drain_result = &success;
+ *
+ * pa_threaded_mainloop_signal(m, 1);
+ * }
+ *
+ * void my_drain_stream_func(pa_threaded_mainloop *m, pa_stream *s) {
+ * pa_operation *o;
+ *
+ * pa_threaded_mainloop_lock(m);
+ *
+ * o = pa_stream_drain(s, my_drain_callback, m);
+ * assert(o);
+ *
+ * while (pa_operation_get_state(o) != OPERATION_DONE)
+ * pa_threaded_mainloop_wait(m);
+ *
+ * pa_operation_unref(o);
+ *
+ * if (*drain_result)
+ * printf("Success!");
+ * else
+ * printf("Bitter defeat...");
+ *
+ * pa_threaded_mainloop_accept(m);
+ *
+ * pa_threaded_mainloop_unlock(m);
+ * }
+ * \endcode
+ *
+ * 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.
+ *
+ * The difference here compared to the basic callback is the 1 sent to
+ * pa_threaded_mainloop_signal() and the call to
+ * pa_threaded_mainloop_accept(). What will happen is that
+ * pa_threaded_mainloop_signal() will signal the main function and then stop.
+ * The main function is then free to use the data in the callback until
+ * pa_threaded_mainloop_accept() is called, which will allow the callback
+ * to continue.
+ *
+ * Note that pa_threaded_mainloop_accept() 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 pa_threaded_mainloop_accept().
+ *
+ * \subsection async_subsec Asynchronous callbacks
+ *
+ * Polypaudio 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.
+ *
+ * The callbacks that are completely asynchronous are:
+ *
+ * \li State callbacks for contexts, streams, etc.
+ * \li Subscription notifications
+ */
+
/** \file
*
* A thread based event loop implementation based on pa_mainloop. The
More information about the pulseaudio-commits
mailing list