libevent.mli

   1 (***********************************************************************)
   2 (* The ocaml-event library                                             *)
   3 (*                                                                     *)
   4 (* Copyright 2002, 2003, 2004 Maas-Maarten Zeeman. All rights reserved *)
   5 (* Copyright 2010 ygrek                                                *)
   6 (* See LICENCE for details.                                            *)
   7 (***********************************************************************)
   8
   9
  10 (** The Ocaml Event library provides an interface to the event API.
  11
  12     The event API provides a mechanism to execute a function when a
  13     specific event on a file descriptor occurs or after a given time
  14     has passed.
  15
  16     This library is a wrapper of the libevent API made by Nils
  17     Provos. For more information about this library see:
  18     http://libevent.org
  19
  20     Currently, libevent supports kqueue(2), select(2), poll(2) and
  21     epoll(4). Support for /dev/poll is planned.
  22
  23     @author Maas-Maarten Zeeman
  24 *)
  25
  26 (** The type of events *)
  27 type event
  28
  29 (** The type of event base *)
  30 type event_base
  31
  32 (** The possible event types *)
  33 type event_flags =
  34     TIMEOUT (** A timeout occurred. *)
  35   | READ    (** A read is possible. *)
  36   | WRITE   (** A write operation is possible. *)
  37   | SIGNAL  (** A signal occurred. *)
  38
  39 type event_callback = Unix.file_descr -> event_flags -> unit
  40 (** The type of event callbacks *)
  41
  42 (** {5 Basic Libevent Operations} *)
  43
  44 val create : unit -> event
  45 (** Create a new empty event *)
  46
  47 val fd : event -> Unix.file_descr
  48 (** [fd event] returns the file descriptor associated with the event *)
  49
  50 val signal : event -> int
  51 (** [signal event] returns the signal associated with the event *)
  52
  53 val set : event_base -> event ->
  54   Unix.file_descr -> event_flags list -> persist:bool -> event_callback -> unit
  55 (** [set events event fd type persist callback] initializes the event for use with [events]. The
  56     flag [persist] makes an event persitent until {!Libevent.del} is
  57     called. Event can be [set] multiple times, only the last one will be active *)
  58
  59 val set_timer : event_base -> event -> persist:bool -> (unit -> unit) -> unit
  60 (** [set_timer events event persist callback] initializes timer. Flag [persist]
  61     makes the timer periodic until {!Libevent.del} is called. *)
  62
  63 val set_signal : event_base -> event ->
  64   signal:int -> persist:bool -> event_callback -> unit
  65 (** [set_signal event signal persist callback] initializes the event. The
  66     flag [persist] makes an event persistent until {!Libevent.del} is
  67     called. *)
  68
  69 val add : event -> float option -> unit
  70 (** [add event timeout] makes the [event] pending - schedules the execution
  71     of the function specified with {!Libevent.set}, or in at least the
  72     time specified in the [timeout]. If [timeout] is [None], no
  73     timeout occures, and the function will only be called if a
  74     matching event occurs on the file descriptor. Addition of the already
  75     scheduled (added) event will reschedule the timeout. *)
  76
  77 val del : event -> unit
  78 (** Delete the event. After event was deleted it should be first
  79     reinitialized with [set] before next [add]. *)
  80
  81 val pending : event -> event_flags list -> bool
  82 (** @return whether event is in the pending state for the given type of events,
  83     i.e. whether it was [add]ed *)
  84
  85 val activate : event -> event_flags list -> unit
  86 (** make an event active, so that the corresponding callback is run. Event may be in
  87     pending or non-pending state *)
  88
  89 (** {5 Process Events} *)
  90
  91 val dispatch : event_base -> unit
  92 (** In order to process events, an application needs to call dispatch. This
  93  *  function only returns on error, and should replace the event core of the
  94  *  application
  95  *)
  96
  97 type loop_flags =
  98     ONCE
  99   | NONBLOCK
 100 val loop : event_base -> loop_flags -> unit
 101 (** Provides an interface for single pass execution of pending events *)
 102
 103 val init : unit -> event_base
 104 (** Initialize event base. *)
 105
 106 val reinit : event_base -> unit
 107 (** Reinitialize event base (use after fork) *)
 108
 109 val free : event_base -> unit
 110 (** destroy event base *)
 111
 112 (** Compatibility *)
 113 module Global : sig
 114
 115 val base : event_base
 116 val init : unit -> unit
 117
 118 val set : event -> Unix.file_descr -> event_flags list -> persist:bool -> event_callback -> unit
 119 val dispatch : unit -> unit
 120 val loop : loop_flags -> unit
 121
 122 end