From a6ce5c4b1d82870f5db7063680698cebb4ffe156 Mon Sep 17 00:00:00 2001 From: Pierre Ossman Date: Sun, 9 Apr 2006 19:31:09 +0000 Subject: Big documentation update. Describe the client API in a more tutorial like manner. git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@667 fefdeb5f-60dc-0310-8127-8f9354f1896f --- src/polyp/mainloop.h | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) (limited to 'src/polyp/mainloop.h') diff --git a/src/polyp/mainloop.h b/src/polyp/mainloop.h index d0a40914..c06b47d0 100644 --- a/src/polyp/mainloop.h +++ b/src/polyp/mainloop.h @@ -27,6 +27,41 @@ PA_C_DECL_BEGIN +/** \page mainloop Mainloop + * + * \section overv_sec Overview + * + * The built-in main loop implementation is based on the poll() system call. + * It supports the functions defined in the main loop abstraction and very + * little else. + * + * The main loop is created using pa_mainloop_new() and destroyed using + * pa_mainloop_free(). To get access to the main loop abstraction, + * pa_mainloop_get_api() is used. + * + * \section iter_sec Iteration + * + * The main loop is designed around the concept of iterations. Each iteration + * consists of three steps that repeat during the application's entire + * lifetime: + * + * -# Prepare - Dispatch deferred events, build a list of file descriptors + * that need to be monitored and calculate the next timeout. + * -# Poll - Execute the actuall poll() system call. + * -# Dispatch - Dispatch any timeouts and file descriptors that have fired. + * + * When using the main loop, the application can either execute each + * iteration, one at a time, using pa_mainloop_iterate(), or let the library + * iterate automatically using pa_mainloop_run(). + * + * \section thread_sec Threads + * + * The main loop functions are designed to be thread safe, but the objects + * are not. What this means is that multiple main loops can be used, but only + * one object per thread. + * + */ + /** \file * * A minimal main loop implementation based on the C library's poll() -- cgit