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

fpi_timeout API docs

See merge request libfprint/libfprint!15

doc/libfprint-docs.xml

@@ -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">

doc/libfprint-sections.txt

@@ -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>

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;

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;

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);

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);
 

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);
 

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);
 

libfprint/fpi-poll.c

@@ -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);

libfprint/fpi-poll.h

@@ -0,0 +1,38 @@
+/*
+ * 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);

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',