Commit 969eefc8 authored by Bastien Nocera's avatar Bastien Nocera

lib: Add fpi_timeout API documentation

parent efee7262
......@@ -39,6 +39,7 @@
<part>
<title>Writing Drivers</title>
<xi:include href="xml/fpi-ssm.xml"/>
<xi:include href="xml/fpi-poll.xml"/>
</part>
<index id="api-index">
......
......@@ -162,3 +162,12 @@ fpi_ssm_get_user_data
fpi_ssm_get_error
fpi_ssm_get_cur_state
</SECTION>
<SECTION>
<INCLUDE>fpi-poll.h</INCLUDE>
<FILE>fpi-poll</FILE>
fpi_timeout
fpi_timeout_fn
fpi_timeout_add
fpi_timeout_cancel
</SECTION>
......@@ -64,6 +64,15 @@
* your main loop.
*/
/**
* SECTION:fpi-poll
* @title: Timeouts
*
* Helper functions to schedule a function call to be made after a timeout. This
* is useful to avoid making blocking calls while waiting for hardware to answer
* for example.
*/
/* this is a singly-linked list of pending timers, sorted with the timer that
* is expiring soonest at the head. */
static GSList *active_timers = NULL;
......@@ -93,9 +102,22 @@ static int timeout_sort_fn(gconstpointer _a, gconstpointer _b)
return 0;
}
/* A timeout is the asynchronous equivalent of sleeping. You create a timeout
/**
* fpi_timeout_add:
* @msec: the time before calling the function, in milliseconds (1/1000ths of a second)
* @callback: function to callback
* @data: data to pass to @callback
*
* A timeout is the asynchronous equivalent of sleeping. You create a timeout
* saying that you'd like to have a function invoked at a certain time in
* the future. */
* the future.
*
* Note that you should hold onto the return value of this function to cancel it
* use fpi_timeout_cancel(), otherwise the callback could be called while the driver
* is being torn down. %NULL is returned on failure.
*
* Returns: an #fpi_timeout structure
*/
struct fpi_timeout *fpi_timeout_add(unsigned int msec, fpi_timeout_fn callback,
void *data)
{
......@@ -129,6 +151,13 @@ struct fpi_timeout *fpi_timeout_add(unsigned int msec, fpi_timeout_fn callback,
return timeout;
}
/**
* fpi_timeout_cancel:
* @timeout: an #fpi_timeout structure
*
* Cancels a timeout scheduled with fpi_timeout_add(), and frees the
* @timeout structure.
*/
void fpi_timeout_cancel(struct fpi_timeout *timeout)
{
G_DEBUG_HERE();
......
......@@ -18,8 +18,20 @@
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*/
/**
* fpi_timeout_fn:
* @data: the data passed to fpi_timeout_add()
*
* The prototype of the callback function for fpi_timeout_add().
*/
typedef void (*fpi_timeout_fn)(void *data);
/**
* fpi_timeout:
*
* An opaque structure representing a scheduled function call, created with
* fpi_timeout_add().
*/
struct fpi_timeout;
struct fpi_timeout *fpi_timeout_add(unsigned int msec, fpi_timeout_fn callback,
void *data);
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment