Commit 56157696 authored by Bastien Nocera's avatar Bastien Nocera

Merge branch 'wip/hadess/fpi-timeout-docs' into 'master'

fpi_timeout API docs

See merge request !15
parents 1102d6e4 2946dabd
Pipeline #4110 passed with stage
in 2 minutes and 45 seconds
......@@ -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>
......@@ -135,7 +135,7 @@ struct uru4k_dev {
unsigned char powerup_hwstat;
int scanpwr_irq_timeouts;
struct fpi_timeout *scanpwr_irq_timeout;
fpi_timeout *scanpwr_irq_timeout;
int fwfixer_offset;
unsigned char fwfixer_value;
......
......@@ -106,7 +106,7 @@ struct vfs101_dev
int ignore_error;
/* Timeout */
struct fpi_timeout *timeout;
fpi_timeout *timeout;
/* Loop counter */
int counter;
......
......@@ -38,7 +38,7 @@ static void async_sleep_cb(void *data)
static void async_sleep(unsigned int msec, fpi_ssm *ssm)
{
struct fp_img_dev *dev = fpi_ssm_get_user_data(ssm);
struct fpi_timeout *timeout;
fpi_timeout *timeout;
/* Add timeout */
timeout = fpi_timeout_add(msec, async_sleep_cb, ssm);
......
......@@ -672,7 +672,7 @@ static void activate_loop(fpi_ssm *ssm)
struct fp_img_dev *dev = fpi_ssm_get_user_data(ssm);
struct vfs5011_data *data;
int r;
struct fpi_timeout *timeout;
fpi_timeout *timeout;
data = fpi_imgdev_get_user_data(dev);
......
......@@ -37,6 +37,7 @@
#include "fprint.h"
#include "fpi-ssm.h"
#include "fpi-poll.h"
#include "assembling.h"
#include "drivers/driver_ids.h"
......@@ -203,15 +204,6 @@ struct fp_img *fpi_img_new_for_imgdev(struct fp_img_dev *dev);
struct fp_img *fpi_img_resize(struct fp_img *img, size_t newsize);
struct fp_img *fpi_im_resize(struct fp_img *img, unsigned int w_factor, unsigned int h_factor);
/* polling and timeouts */
typedef void (*fpi_timeout_fn)(void *data);
struct fpi_timeout;
struct fpi_timeout *fpi_timeout_add(unsigned int msec, fpi_timeout_fn callback,
void *data);
void fpi_timeout_cancel(struct fpi_timeout *timeout);
void fpi_drvcb_open_complete(struct fp_dev *dev, int status);
void fpi_drvcb_close_complete(struct fp_dev *dev);
......
......@@ -341,13 +341,11 @@ int fpi_img_compare_print_data_to_gallery(struct fp_print_data *print,
struct fp_print_data **gallery, int match_threshold, size_t *match_offset);
struct fp_img *fpi_im_resize(struct fp_img *img, unsigned int w_factor, unsigned int h_factor);
/* polling and timeouts */
/* polling */
void fpi_poll_init(void);
void fpi_poll_exit(void);
typedef void (*fpi_timeout_fn)(void *data);
void fpi_drvcb_open_complete(struct fp_dev *dev, int status);
void fpi_drvcb_close_complete(struct fp_dev *dev);
......
......@@ -20,6 +20,7 @@
#define FP_COMPONENT "poll"
#include "fp_internal.h"
#include "fpi-poll.h"
#include <config.h>
#include <errno.h>
......@@ -63,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;
......@@ -79,8 +89,8 @@ struct fpi_timeout {
static int timeout_sort_fn(gconstpointer _a, gconstpointer _b)
{
struct fpi_timeout *a = (struct fpi_timeout *) _a;
struct fpi_timeout *b = (struct fpi_timeout *) _b;
fpi_timeout *a = (fpi_timeout *) _a;
fpi_timeout *b = (fpi_timeout *) _b;
struct timeval *tv_a = &a->expiry;
struct timeval *tv_b = &b->expiry;
......@@ -92,15 +102,28 @@ 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. */
struct fpi_timeout *fpi_timeout_add(unsigned int msec, fpi_timeout_fn callback,
* 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
*/
fpi_timeout *fpi_timeout_add(unsigned int msec, fpi_timeout_fn callback,
void *data)
{
struct timespec ts;
struct timeval add_msec;
struct fpi_timeout *timeout;
fpi_timeout *timeout;
int r;
fp_dbg("in %dms", msec);
......@@ -128,7 +151,14 @@ struct fpi_timeout *fpi_timeout_add(unsigned int msec, fpi_timeout_fn callback,
return timeout;
}
void fpi_timeout_cancel(struct fpi_timeout *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(fpi_timeout *timeout)
{
G_DEBUG_HERE();
active_timers = g_slist_remove(active_timers, timeout);
......
/*
* Polling/timing management
* Copyright (C) 2008 Daniel Drake <dsd@gentoo.org>
* Copyright (C) 2018 Bastien Nocera <hadess@hadess.net>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* 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().
*/
typedef struct fpi_timeout fpi_timeout;
fpi_timeout *fpi_timeout_add(unsigned int msec, fpi_timeout_fn callback,
void *data);
void fpi_timeout_cancel(fpi_timeout *timeout);
......@@ -6,9 +6,10 @@ libfprint_sources = [
'data.c',
'fpi-ssm.c',
'fpi-ssm.h',
'fpi-poll.h',
'fpi-poll.c',
'img.c',
'imgdev.c',
'poll.c',
'sync.c',
'assembling.c',
'assembling.h',
......
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