From owner-p4-projects@FreeBSD.ORG Sat May 9 19:41:31 2009 Return-Path: Delivered-To: p4-projects@freebsd.org Received: by hub.freebsd.org (Postfix, from userid 32767) id 13DB9106568A; Sat, 9 May 2009 19:41:31 +0000 (UTC) Delivered-To: perforce@FreeBSD.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id AEB62106567F for ; Sat, 9 May 2009 19:41:30 +0000 (UTC) (envelope-from syl@FreeBSD.org) Received: from repoman.freebsd.org (repoman.freebsd.org [IPv6:2001:4f8:fff6::29]) by mx1.freebsd.org (Postfix) with ESMTP id D77CE8FC0A for ; Sat, 9 May 2009 19:41:28 +0000 (UTC) (envelope-from syl@FreeBSD.org) Received: from repoman.freebsd.org (localhost [127.0.0.1]) by repoman.freebsd.org (8.14.3/8.14.3) with ESMTP id n49JfS22009916 for ; Sat, 9 May 2009 19:41:28 GMT (envelope-from syl@FreeBSD.org) Received: (from perforce@localhost) by repoman.freebsd.org (8.14.3/8.14.3/Submit) id n49JfSuY009914 for perforce@freebsd.org; Sat, 9 May 2009 19:41:28 GMT (envelope-from syl@FreeBSD.org) Date: Sat, 9 May 2009 19:41:28 GMT Message-Id: <200905091941.n49JfSuY009914@repoman.freebsd.org> X-Authentication-Warning: repoman.freebsd.org: perforce set sender to syl@FreeBSD.org using -f From: Sylvestre Gallon To: Perforce Change Reviews Cc: Subject: PERFORCE change 161854 for review X-BeenThere: p4-projects@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: p4 projects tree changes List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 09 May 2009 19:41:33 -0000 http://perforce.freebsd.org/chv.cgi?CH=161854 Change 161854 by syl@syl_atuin on 2009/05/09 19:41:00 Adding the poll/events stuff in the manpages. Affected files ... .. //depot/projects/soc2009/syl_usb/src/lib/libusb/libusb.3#3 edit .. //depot/projects/soc2009/syl_usb/src/lib/libusb/libusb10.3#3 edit Differences ... ==== //depot/projects/soc2009/syl_usb/src/lib/libusb/libusb.3#3 (text+ko) ==== ==== //depot/projects/soc2009/syl_usb/src/lib/libusb/libusb10.3#3 (text+ko) ==== @@ -24,8 +24,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD: src/lib/libusb/libusb.3,v 1.1 2009/03/10 15:49:43 thompsa Exp $ -.\" .Dd April 10, 2009 .Dt LIBUSB10 3 .Os @@ -359,6 +357,100 @@ LIBUSB_ERROR code on other failure. . .Pp +.Sh USB EVENTS +. +.Pp +.Ft int +.Fn libusb_try_lock_events "libusb_context *ctx" +Try to acquire the event handling lock. Returns 0 if the lock was obtained and 1 +if not. +. +.Pp +.Ft void +.Fn libusb_lock_events "libusb_context *ctx" +Acquire the event handling lock. This function is blocking. +. +.Pp +.Ft void +.Fn libusb_unlock_events "libusb_context *ctx" +Release the event handling lock. This will wake up any thread blocked +on libusb_wait_for_event(). +. +.Pp +.Ft int +.Fn libusb_event_handling_ok "libusb_context *ctx" +Determine if it still OK for this thread to be doing event handling. Returns 1 +if event handling can start or continue. Returns 0 if this thread must give up +the events lock. +. +.Pp +.Ft int +.Fn libusb_event_handler_active "libusb_context *ctx" +Determine if an active thread is handling events. Returns 1 if yes and 0 if there +are no threads currently handling events. +. +.Pp +.Ft void +.Fn libusb_lock_event_waiters "libusb_context *ctx" +Acquire the event_waiters lock. This lock is designed to be obtained under the +situation where you want to be aware when events are completed, but some other +thread is event handling so calling libusb_handle_events() is not allowed. +. +.Pp +.Ft void +.Fn libusb_unlock_event_waiters "libusb_context *ctx" +Release the event_waiters lock. +. +.Pp +.Ft int +.Fn libusb_wait_for_event "libusb_context *ctx" "struct timeval *tv" +Wait for another thread to signal completion of an event. Must be called +with the event waiters lock held, see libusb_lock_event_waiters(). This will +block until the timeout expires or a transfer completes or a thread releases +the event handling lock through libusb_unlock_events(). Returns 0 after a +transfer completes or another thread stops event handling, returns 1 if the +timeout expired. +. +.Pp +.Ft int +.Fn libusb_handle_events_timeout "libusb_context *ctx" "struct timeval *tv" +Handle any pending events by checking if timeouts have expired and by +checking the set of file descriptors for activity. Returns 0 on success, or a +LIBUSB_ERROR code on failure. +. +.Pp +.Ft int +.Fn libusb_handle_events "libusb_context *ctx" +Handle any pending events in blocking mode with a sensible timeout. Returns 0 +on success, returns a LIBUSB_ERROR code on failure. +. +.Pp +.Ft int +.Fn libusb_handle_events_locked "libusb_context *ctx" "struct timeval *tv" +Handle any pending events by polling file desciptors, without checking if +another threads are already doing so. Must be called with the event lock held. +. +.Pp +.Ft int +.Fn libusb_get_next_timeout "libusb_context *ctx" "struct timeval *tv" +Determine the next internal timeout that libusb needs to handle. Returns 0 +if there are no pending timeouts, 1 if a timeout was returned, or LIBUSB_ERROR +code on failure. +. +.Pp +.Ft void +.Fn libusb_set_pollfd_notifiers "libusb_context *ctx" "libusb_pollfd_added_cb added_cb" "libusb_pollfd_removed_cb remove_cb" "void *user_data" +Register notification functions for file descriptor additions/removals. +These functions will be invoked for every new or removed file descriptor +that libusb uses as an event source. +. +.Pp +.Ft const struct libusb_pollfd ** +.Fn libusb_get_pollfds "libusb_context *ctx" +Retrive a list of file descriptors that should be polled by your main loop as +libusb event sources. Returns a NULL-terminated list on success or NULL on failure. +. +.Pp .Sh SEE ALSO .Xr libusb 3 , .Xr usb2_core 4 ,