liboevent.mli

   1 (***********************************************************************)
   2 (* The Ocaml Libevent library                                          *)
   3 (*                                                                     *)
   4 (* Copyright 2002, 2003, 2004 Maas-Maarten Zeeman. All rights          *)
   5 (* reserved. See LICENCE for details.                                  *)
   6 (***********************************************************************)
   7
   8
   9 (** The Ocaml Event library provides an interface to the event API.
  10
  11     The event API provides a mechanism to execute a function when a
  12     specific event on a file descriptor occurs or after a given time
  13     has passed.
  14
  15     This library is a wrapper of the libevent API made by Nils
  16     Provos. For more information about this library see:
  17     http://www.monkey.org/~provos/libevent.
  18
  19     Currently, libevent supports kqueue(2), select(2), poll(2) and
  20     epoll(4). Support for /dev/poll is planned.
  21
  22     @author Maas-Maarten Zeeman
  23 *)
  24
  25 (** The type of events *)
  26 type event
  27
  28 (** The possible event types *)
  29 type event_flags =
  30     TIMEOUT (** A timeout occurred. *)
  31   | READ    (** A read is possible. *)
  32   | WRITE   (** A write operation is possible. *)
  33   | SIGNAL  (** A signal occurred. *)
  34
  35 type event_callback = Unix.file_descr -> event_flags -> unit
  36 (** The type of event callbacks *)
  37
  38 (** {5 Basic Libevent Operations} *)
  39
  40 val create : unit -> event
  41 (** Create a new empty event *)
  42
  43 val fd : event -> Unix.file_descr
  44 (** [fd event] returns the file descriptor associated with the event *)
  45
  46 val signal : event -> int
  47 (** [signal event] returns the signal associated with the event *)
  48
  49 val set : event ->
  50   Unix.file_descr -> event_flags list -> persist:bool -> event_callback -> unit
  51 (** [set event fd type persist callback] initializes the event. The
  52     flag [persist] makes an event persitent until {!Libevent.del} is
  53     called. *)
  54
  55 val set_signal : event ->
  56   signal:int -> persist:bool -> event_callback -> unit
  57 (** [set_signal event signal persist callback] initializes the event. The
  58     flag [persist] makes an event persistent unit {!Libevent.del} is
  59     called. *)
  60
  61 val add : event -> float option -> unit
  62 (** [add event timeout] adds the [event] and schedules the execution
  63     of the function specified with {!Libevent.set}, or in at least the
  64     time specified in the [timeout]. If [timeout] is [None], no
  65     timeout occures, and the function will only be called if a
  66     matching event occurs on the file descriptor. *)
  67
  68 val del : event -> unit
  69 (** Del the event *)
  70
  71 val pending : event -> event_flags list -> bool
  72
  73 (** {5 Process Events} *)
  74
  75 val dispatch : unit -> unit
  76 (** In order to process events, an application needs to call dispatch. This
  77  *  function only returns on error, and should replace the event core of the
  78  *  application
  79  *)
  80
  81 type loop_flags =
  82     ONCE
  83   | NONBLOCK
  84 val loop : loop_flags -> unit
  85 (** Provides an interface for single pass execution of pending events *)
  86
  87 val init : unit -> unit
  88 (** Initialize libevent. Done automatically at startup, may be needed after fork *)
  89