From 8d809854e2b19c2b7c27ab05e5d76b34e2a5cead Mon Sep 17 00:00:00 2001 From: Daniel Drake Date: Sun, 30 Mar 2008 22:19:00 +0100 Subject: [PATCH] Rename libusb_poll() to libusb_handle_events() --- TODO | 1 - examples/dpfp.c | 2 +- libusb/io.c | 62 +++++++++++++++++++++++++++++---------------------------- libusb/libusb.h | 4 ++-- libusb/sync.c | 4 ++-- 5 files changed, 37 insertions(+), 36 deletions(-) diff --git a/TODO b/TODO index f02ea3a..e0250ab 100644 --- a/TODO +++ b/TODO @@ -6,7 +6,6 @@ error codes fixme review review functionality missing over 0.1 endianness of control setup, issues when resubmitting transfers -rename poll to handle_events make libusb_get_pollfds return const? doxygen warnings make descriptor things const? diff --git a/examples/dpfp.c b/examples/dpfp.c index 00aaa73..6aa97a1 100644 --- a/examples/dpfp.c +++ b/examples/dpfp.c @@ -469,7 +469,7 @@ int main(void) sigaction(SIGQUIT, &sigact, NULL); while (!do_exit) { - r = libusb_poll(); + r = libusb_handle_events(); if (r < 0) goto out_deinit; } diff --git a/libusb/io.c b/libusb/io.c index e28b8e0..9c0d9bb 100644 --- a/libusb/io.c +++ b/libusb/io.c @@ -423,16 +423,17 @@ if (r == 0 && actual_length == sizeof(data)) { * points in time - namely processing the results of previously-submitted * transfers and invoking the user-supplied callback function. * - * This gives rise to the libusb_poll() function which your + * This gives rise to the libusb_handle_events() function which your * application must call into when libusb has work do to. This gives libusb * the opportunity to reap pending transfers, invoke callbacks, etc. * * The first issue to discuss here is how your application can figure out * when libusb has work to do. In fact, there are two naive options which * do not actually require your application to know this: - * -# Periodically call libusb_poll() in non-blocking mode at fixed short - * intervals from your main loop - * -# Repeatedly call libusb_poll() in blocking mode from a dedicated thread. + * -# Periodically call libusb_handle_events() in non-blocking mode at fixed + * short intervals from your main loop + * -# Repeatedly call libusb_handle_events() in blocking mode from a dedicated + * thread. * * The first option is plainly not very nice, and will cause unnecessary * CPU wakeups leading to increased power usage and decreased battery life. @@ -447,7 +448,7 @@ if (r == 0 && actual_length == sizeof(data)) { * button presses, mouse movements, network sockets, etc). You then add * libusb's file descriptors to your poll()/select() calls, and when activity * is detected on such descriptors you know it is time to call - * libusb_poll(). + * libusb_handle_events(). * * There is one final event handling complication. libusb supports * asynchronous transfers which time out after a specified time period, and @@ -492,14 +493,14 @@ if (r == 0 && actual_length == sizeof(data)) { // maybe fire off some initial async I/O while (user_has_not_requested_exit) - libusb_poll(); + libusb_handle_events(); // clean up and exit \endcode * * With such a simple main loop, you do not have to worry about managing - * sets of file descriptors or handling timeouts. libusb_poll() will handle - * those details internally. + * sets of file descriptors or handling timeouts. libusb_handle_events() will + * handle those details internally. * * \section pollmain The more advanced option * @@ -510,29 +511,30 @@ while (user_has_not_requested_exit) * * In addition to polling file descriptors for the other event sources, you * take a set of file descriptors from libusb and monitor those too. When you - * detect activity on libusb's file descriptors, you call libusb_poll_timeout() - * in non-blocking mode. + * detect activity on libusb's file descriptors, you call + * libusb_handle_events_timeout() in non-blocking mode. * * You must also consider the fact that libusb sometimes has to handle events * at certain known times which do not generate activity on file descriptors. * Your main loop must also consider these times, modify it's poll()/select() - * timeout accordingly, and track time so that libusb_poll_timeout() is called - * in non-blocking mode when timeouts expire. + * timeout accordingly, and track time so that libusb_handle_events_timeout() + * is called in non-blocking mode when timeouts expire. * * In pseudo-code, you want something that looks like: \code // initialise libusb libusb_get_pollfds() -while (user has not requested application exit): - libusb_get_next_timeout() +while (user has not requested application exit) { + libusb_get_next_timeout(); select(on libusb file descriptors plus any other event sources of interest, using a timeout no larger than the value libusb just suggested) - if (select() indicated activity on libusb file descriptors): - libusb_poll_timeout(0); - if (time has elapsed to or beyond the libusb timeout): - libusb_poll_timeout(0); - + if (select() indicated activity on libusb file descriptors) + libusb_handle_events_timeout(0); + if (time has elapsed to or beyond the libusb timeout) + libusb_handle_events_timeout(0); +} + // clean up and exit \endcode * @@ -782,7 +784,7 @@ API_EXPORTED int libusb_cancel_transfer_sync(struct libusb_transfer *transfer) itransfer->flags |= USBI_TRANSFER_SYNC_CANCELLED; while (itransfer->flags & USBI_TRANSFER_SYNC_CANCELLED) { - r = libusb_poll(); + r = libusb_handle_events(); if (r < 0) return r; } @@ -907,7 +909,7 @@ static int handle_timeouts(void) return 0; } -static int poll_io(struct timeval *tv) +static int handle_events(struct timeval *tv) { int r; int maxfd = 0; @@ -999,9 +1001,9 @@ static int poll_io(struct timeval *tv) * \returns 0 on success * \returns non-zero on error */ -API_EXPORTED int libusb_poll_timeout(struct timeval *tv) +API_EXPORTED int libusb_handle_events_timeout(struct timeval *tv) { - return poll_io(tv); + return handle_events(tv); } /** \ingroup poll @@ -1009,36 +1011,36 @@ API_EXPORTED int libusb_poll_timeout(struct timeval *tv) * timeout is currently hardcoded at 2 seconds but we may change this if we * decide other values are more sensible. For finer control over whether this * function is blocking or non-blocking, or the maximum timeout, use - * libusb_poll_timeout() instead. + * libusb_handle_events_timeout() instead. * * \returns 0 on success * \returns non-zero on error */ -API_EXPORTED int libusb_poll(void) +API_EXPORTED int libusb_handle_events(void) { struct timeval tv; tv.tv_sec = 2; tv.tv_usec = 0; - return poll_io(&tv); + return handle_events(&tv); } /** \ingroup poll * Determine the next internal timeout that libusb needs to handle. You only * need to use this function if you are calling poll() or select() or similar * on libusb's file descriptors yourself - you do not need to use it if you - * are calling libusb_poll() or a variant directly. + * are calling libusb_handle_events() or a variant directly. * * You should call this function in your main loop in order to determine how * long to wait for select() or poll() to return results. libusb needs to be * called into at this timeout, so you should use it as an upper bound on * your select() or poll() call. * - * When the timeout has expired, call into libusb_poll_timeout() (perhaps in - * non-blocking mode) so that libusb can handle the timeout. + * When the timeout has expired, call into libusb_handle_events_timeout() + * (perhaps in non-blocking mode) so that libusb can handle the timeout. * * This function may return 0 (success) and an all-zero timeval. If this is * the case, it indicates that libusb has a timeout that has already expired - * so you should call libusb_poll_timeout() or similar immediately. + * so you should call libusb_handle_events_timeout() or similar immediately. * * \param tv output location for a relative time against the current * clock in which libusb must be called into in order to process timeout events diff --git a/libusb/libusb.h b/libusb/libusb.h index 4d94224..2654ba3 100644 --- a/libusb/libusb.h +++ b/libusb/libusb.h @@ -866,8 +866,8 @@ struct libusb_pollfd { short events; }; -int libusb_poll_timeout(struct timeval *tv); -int libusb_poll(void); +int libusb_handle_events_timeout(struct timeval *tv); +int libusb_handle_events(void); int libusb_get_next_timeout(struct timeval *tv); struct libusb_pollfd **libusb_get_pollfds(void); diff --git a/libusb/sync.c b/libusb/sync.c index c59122e..b2b564d 100644 --- a/libusb/sync.c +++ b/libusb/sync.c @@ -94,7 +94,7 @@ API_EXPORTED int libusb_control_transfer(libusb_device_handle *dev_handle, } while (!completed) { - r = libusb_poll(); + r = libusb_handle_events(); if (r < 0) { libusb_cancel_transfer_sync(transfer); libusb_free_transfer(transfer); @@ -152,7 +152,7 @@ static int do_sync_bulk_transfer(struct libusb_device_handle *dev_handle, } while (!completed) { - r = libusb_poll(); + r = libusb_handle_events(); if (r < 0) { libusb_cancel_transfer_sync(transfer); libusb_free_transfer(transfer); -- 2.7.4