libevent.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 type of event base *)
  29 type event_base
  30
  31 (** The possible event types *)
  32 type event_flags =
  33     TIMEOUT (** A timeout occurred. *)
  34   | READ    (** A read is possible. *)
  35   | WRITE   (** A write operation is possible. *)
  36   | SIGNAL  (** A signal occurred. *)
  37
  38 type event_callback = Unix.file_descr -> event_flags -> unit
  39 (** The type of event callbacks *)
  40
  41 (** {5 Basic Libevent Operations} *)
  42
  43 val create : unit -> event
  44 (** Create a new empty event *)
  45
  46 val fd : event -> Unix.file_descr
  47 (** [fd event] returns the file descriptor associated with the event *)
  48
  49 val signal : event -> int
  50 (** [signal event] returns the signal associated with the event *)
  51
  52 val set : event_base -> event ->
  53   Unix.file_descr -> event_flags list -> persist:bool -> event_callback -> unit
  54 (** [set events event fd type persist callback] initializes the event for use with [events]. The
  55     flag [persist] makes an event persitent until {!Libevent.del} is
  56     called. Event can be [set] multiple times, only the last one will be active *)
  57
  58 val set_timer : event_base -> event -> persist:bool -> (unit -> unit) -> unit
  59 (** [set_timer events event persist callback] initializes timer. Flag [persist]
  60     makes the timer periodic, until {!Libevent.del} is called. *)
  61
  62 val set_signal : event_base -> event ->
  63   signal:int -> persist:bool -> event_callback -> unit
  64 (** [set_signal event signal persist callback] initializes the event. The
  65     flag [persist] makes an event persistent unit {!Libevent.del} is
  66     called. *)
  67
  68 val add : event -> float option -> unit
  69 (** [add event timeout] adds the [event] and schedules the execution
  70     of the function specified with {!Libevent.set}, or in at least the
  71     time specified in the [timeout]. If [timeout] is [None], no
  72     timeout occures, and the function will only be called if a
  73     matching event occurs on the file descriptor. Addition of the already
  74     scheduled (added) event will reschedule the timeout. *)
  75
  76 val del : event -> unit
  77 (** Delete the event. After event was deleted it should be first
  78     reinitialized with [set] before next [add]. *)
  79
  80 (* Not finished *)
  81 (* val pending : event -> event_flags list -> bool  *)
  82
  83 (** {5 Process Events} *)
  84
  85 val dispatch : event_base -> unit
  86 (** In order to process events, an application needs to call dispatch. This
  87  *  function only returns on error, and should replace the event core of the
  88  *  application
  89  *)
  90
  91 type loop_flags =
  92     ONCE
  93   | NONBLOCK
  94 val loop : event_base -> loop_flags -> unit
  95 (** Provides an interface for single pass execution of pending events *)
  96
  97 val init : unit -> event_base
  98 (** Initialize event base. *)
  99
 100 val reinit : event_base -> unit
 101 (** Reinitialize event base (use after fork) *)
 102
 103 val free : event_base -> unit
 104 (** destroy event base *)
 105
 106 (** Compatibility *)
 107 module Global : sig
 108
 109 val base : event_base
 110 val init : unit -> unit
 111
 112 val set : event -> Unix.file_descr -> event_flags list -> persist:bool -> event_callback -> unit
 113 val dispatch : unit -> unit
 114 val loop : loop_flags -> unit
 115
 116 end
 117