diff --git a/doc/libfprint-docs.xml b/doc/libfprint-docs.xml
index 8f8622d..c4e3445 100644
--- a/doc/libfprint-docs.xml
+++ b/doc/libfprint-docs.xml
@@ -39,6 +39,7 @@
Writing Drivers
+
diff --git a/doc/libfprint-sections.txt b/doc/libfprint-sections.txt
index 1f99e5a..91310b9 100644
--- a/doc/libfprint-sections.txt
+++ b/doc/libfprint-sections.txt
@@ -162,3 +162,12 @@ fpi_ssm_get_user_data
fpi_ssm_get_error
fpi_ssm_get_cur_state
+
+
+fpi-poll.h
+fpi-poll
+fpi_timeout
+fpi_timeout_fn
+fpi_timeout_add
+fpi_timeout_cancel
+
diff --git a/libfprint/drivers/uru4000.c b/libfprint/drivers/uru4000.c
index fddd411..cad94fa 100644
--- a/libfprint/drivers/uru4000.c
+++ b/libfprint/drivers/uru4000.c
@@ -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;
diff --git a/libfprint/drivers/vfs101.c b/libfprint/drivers/vfs101.c
index d57b4fc..a2ac6b9 100644
--- a/libfprint/drivers/vfs101.c
+++ b/libfprint/drivers/vfs101.c
@@ -106,7 +106,7 @@ struct vfs101_dev
int ignore_error;
/* Timeout */
- struct fpi_timeout *timeout;
+ fpi_timeout *timeout;
/* Loop counter */
int counter;
diff --git a/libfprint/drivers/vfs301.c b/libfprint/drivers/vfs301.c
index 403bd36..66806ae 100644
--- a/libfprint/drivers/vfs301.c
+++ b/libfprint/drivers/vfs301.c
@@ -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);
diff --git a/libfprint/drivers/vfs5011.c b/libfprint/drivers/vfs5011.c
index f1e3d99..93deb05 100644
--- a/libfprint/drivers/vfs5011.c
+++ b/libfprint/drivers/vfs5011.c
@@ -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);
diff --git a/libfprint/drivers_api.h b/libfprint/drivers_api.h
index 02fe43c..cba678a 100644
--- a/libfprint/drivers_api.h
+++ b/libfprint/drivers_api.h
@@ -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);
diff --git a/libfprint/fp_internal.h b/libfprint/fp_internal.h
index 48a2518..9aa03f2 100644
--- a/libfprint/fp_internal.h
+++ b/libfprint/fp_internal.h
@@ -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);
diff --git a/libfprint/poll.c b/libfprint/fpi-poll.c
similarity index 89%
rename from libfprint/poll.c
rename to libfprint/fpi-poll.c
index 615ba40..5c6fc96 100644
--- a/libfprint/poll.c
+++ b/libfprint/fpi-poll.c
@@ -20,6 +20,7 @@
#define FP_COMPONENT "poll"
#include "fp_internal.h"
+#include "fpi-poll.h"
#include
#include
@@ -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);
diff --git a/libfprint/fpi-poll.h b/libfprint/fpi-poll.h
new file mode 100644
index 0000000..34c2520
--- /dev/null
+++ b/libfprint/fpi-poll.h
@@ -0,0 +1,38 @@
+/*
+ * Polling/timing management
+ * Copyright (C) 2008 Daniel Drake
+ * Copyright (C) 2018 Bastien Nocera
+ *
+ * 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);
diff --git a/libfprint/meson.build b/libfprint/meson.build
index 0a9ed02..c6d1ac9 100644
--- a/libfprint/meson.build
+++ b/libfprint/meson.build
@@ -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',