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 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 : event_base -> event
  44 (** Create a new empty event for use with event_base *)
  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 ->
  53   Unix.file_descr -> event_flags list -> persist:bool -> event_callback -> unit
  54 (** [set event fd type persist callback] initializes the event. 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 -> persist:bool -> (unit -> unit) -> unit
  59 (** [set_timer event persist callback] initializes timer. Flag [persist]
  60     makes the timer periodic, until {!Libevent.del} is called. *)
  61
  62 val set_signal : 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 *)
  78
  79 (* Not finished *)
  80 (* val pending : event -> event_flags list -> bool  *)
  81
  82 (** {5 Process Events} *)
  83
  84 val dispatch : event_base -> unit
  85 (** In order to process events, an application needs to call dispatch. This
  86  *  function only returns on error, and should replace the event core of the
  87  *  application
  88  *)
  89
  90 type loop_flags =
  91     ONCE
  92   | NONBLOCK
  93 val loop : event_base -> loop_flags -> unit
  94 (** Provides an interface for single pass execution of pending events *)
  95
  96 val init : unit -> event_base
  97 (** Initialize event base. *)
  98
  99 val reinit : event_base -> unit
 100 (** Reinitialize event base (use after fork) *)
 101
 102 val free : event_base -> unit
 103 (** destroy event base *)
 104
 105 (** Compatibility *)
 106 module Global : sig
 107
 108 val base : event_base
 109 val init : unit -> unit
 110
 111 val create : unit -> event
 112 val dispatch : unit -> unit
 113 val loop : loop_flags -> unit
 114
 115 end
 116