Up

module Lwt_engine

: sig

Lwt unix main loop engine

Events

#
type event

Type of events. An event represent a callback registered to be called when some event occurs.

#
val stop_event : event -> unit

stop_event event stops the given event.

#
val fake_event : event

Event which does nothing when stopped.

Event loop functions

#
val iter : bool -> unit

iter block performs one iteration of the main loop. If block is true the function must blocks until one event become available, otherwise it should just check for available events and return immediately.

#
val on_readable : Unix.file_descr -> (event -> unit) -> event

on_readable fd f calls f each time fd becomes readable.

#
val on_writable : Unix.file_descr -> (event -> unit) -> event

on_readable fd f calls f each time fd becomes writable.

#
val on_timer : float -> bool -> (event -> unit) -> event

on_timer delay repeat f calls f one time after delay seconds. If repeat is true then f is called each delay seconds, otherwise it is called only one time.

#
val readable_count : unit -> int

Returns the number of events waiting for a file descriptor to become readable.

#
val writable_count : unit -> int

Returns the number of events waiting for a file descriptor to become writable.

#
val timer_count : unit -> int

Returns the number of registered timers.

#
val fake_io : Unix.file_descr -> unit

Simulates activity on the given file descriptor.

Engines

An engine represent a set of functions used to register different kind of callbacks for different kind of events.

#
class virtual abstract :
#
method destroy : unit

Destroy the engine, remove all its events and free its associated resources.

#
method transfer : abstract -> unit

transfer engine moves all events from the current engine to engine. Note that timers are reset in the destination engine, i.e. if a timer with a delay of 2 seconds was registered 1 second ago it will occurs in 2 seconds in the destination engine.

Event loop methods

#
method virtual iter : bool -> unit
#
method on_readable : Unix.file_descr -> (event -> unit) -> event
#
method on_writable : Unix.file_descr -> (event -> unit) -> event
#
method on_timer : float -> bool -> (event -> unit) -> event
#
method fake_io : Unix.file_descr -> unit
#
method readable_count : int
#
method writable_count : int
#
method timer_count : int

Backend methods

Notes:

  • the callback passed to register methods is of type unit -> unit and not event -> unit
  • register methods returns a lazy value which unregister the event when forced
#
method private virtual cleanup : unit

Cleanup resources associated to the engine.

#
method private virtual register_readable : Unix.file_descr -> (unit -> unit) -> unit Lazy.t
#
method private virtual register_writable : Unix.file_descr -> (unit -> unit) -> unit Lazy.t
#
method private virtual register_timer : float -> bool -> (unit -> unit) -> unit Lazy.t

Abstract class for engines.

#
class type t =
inherit abstract
#
method iter : bool -> unit
#
method private cleanup : unit
#
method private register_readable : Unix.file_descr -> (unit -> unit) -> unit Lazy.t
#
method private register_writable : Unix.file_descr -> (unit -> unit) -> unit Lazy.t
#
method private register_timer : float -> bool -> (unit -> unit) -> unit Lazy.t

Type of engines.

Predefined engines

#
type ev_loop

Type of libev loops.

#
class libev :
inherit t
#
val loop : ev_loop

The libev loop used for this engine.

#
method loop : ev_loop

Returns loop.

Engine based on libev. If not compiled with libev support, the creation of the class will raise Lwt_sys.Not_available.

#
class select : t

Engine based on Unix.select.

#
class virtual select_based :
inherit t
#
method private virtual select : Unix.file_descr list -> Unix.file_descr list -> float -> Unix.file_descr list * Unix.file_descr list

select fds_r fds_w timeout waits for either:

  • one of the file descriptor of fds_r to become readable
  • one of the file descriptor of fds_w to become writable
  • timeout to expire

and returns the list of readable file descriptor and the list of writable file descriptors.

Abstract class for engines based on a select-like function.

#
class virtual poll_based :
inherit t
#
method private virtual poll : (Unix.file_descr * bool * bool) list -> float -> (Unix.file_descr * bool * bool) list

poll fds tiomeout, where fds is a list of tuples of the form (fd, check_readable, check_writable), waits for either:

  • one of the file descriptor with check_readable set to true to become readable
  • one of the file descriptor with check_writable set to true to become writable
  • timeout to expire

and returns the list of file descriptors with their readable and writable status.

Abstract class for engines based on a poll-like function.

The current engine

#
val get : unit -> t

get () returns the engine currently in use.

#
val set : ?transfer:bool -> ?destroy:bool -> t -> unit

set ?transfer ?destroy engine replaces the current engine by the given one.

If transfer is true (the default) all events from the current engine are transferred to the new one.

If destroy is true (the default) then the current engine is destroyed before being replaced.

end