PERFORCE change 161854 for review

[Sylvestre Gallon]

http://perforce.freebsd.org/chv.cgi?CH=161854

Change 161854 by syl at 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 ,