Module Lwt_unix

module Lwt_unix : sig..end

Cooperative system calls


This modules maps system calls, like those of the standard library's Unix module, to cooperative ones, which will not block the program.

The semantics of all operations is the following: if the action (for example reading from a file descriptor) can be performed immediately, it is done and returns immediately, otherwise it returns a sleeping thread which is woken up when the operation completes.

Most operations on sockets and pipes (on Windows it is only sockets) are cancelable, meaning you can cancel them with Lwt.​cancel. For example if you want to read something from a file descriptor with a timeout, you can cancel the action after the timeout and the reading will not be performed if not already done.

For example, consider that you have two sockets sock1 and sock2. You want to read something from sock1 or exclusively from sock2 and fail with an exception if a timeout of 1 second expires, without reading anything from sock1 and sock2, even if they become readable in the future.

Then you can do:

Lwt.pick
      [Lwt_unix.timeout 1.0;
       read sock1 buf1 ofs1 len1;
       read sock2 buf2 ofs2 len2]

In this case, it is guaranteed that exactly one of the three operations will complete, and the others will be cancelled.

val handle_unix_error : ('a -> 'b Lwt.t) -> 'a -> 'b Lwt.t

Same as Unix.handle_unix_error but catches lwt-level exceptions

Configuration

type async_method =  | Async_none(* <<div class="odocwiki_info"|~System calls are made synchronously~, and may block the
          entire program~.
>> *) | Async_detach(* <<div class="odocwiki_info"|~System calls are made in another system thread~, thus without
          blocking other ~Lwt threads~. ~The drawback is that it may
          degrade performance in some cases~.


          ~This is the default~.
>> *) | Async_switch(* <<div class="odocwiki_info"|~System calls are made in the main thread~, and if one blocks
          the execution continue in another system thread~. ~This method
          is the most efficient~, also you will get better performance
          if you force all threads to run on the same cpu~. ~On linux
          this can be done by using the command <<span class="odocwiki_inlinecode"|taskset>>~.


          ~Note that this method is still experimental~.
>> *)

For system calls that cannot be made asynchronously, Lwt uses one of the following method:

val default_async_method : unit -> async_method

Returns the default async method.

This can be initialized using the environment variable "LWT_ASYNC_METHOD" with possible values "none", "detach" and "switch".

val set_default_async_method : async_method -> unit

Sets the default async method.

val async_method : unit -> async_method

async_method () returns the async method used in the current thread.

val async_method_key : async_method Lwt.key

The key for storing the local async method.

val with_async_none : (unit -> 'a) -> 'a

with_async_none f is a shorthand for:

Lwt.with_value async_method_key (Some Async_none) f
val with_async_detach : (unit -> 'a) -> 'a

with_async_detach f is a shorthand for:

Lwt.with_value async_method_key (Some Async_detach) f
val with_async_switch : (unit -> 'a) -> 'a

with_async_switch f is a shorthand for:

Lwt.with_value async_method_key (Some Async_switch) f

Sleeping

val sleep : float -> unit Lwt.t

sleep d is a thread that remains suspended for d seconds and then terminates.

val yield : unit -> unit Lwt.t

yield () is a thread that suspends itself and then resumes as soon as possible and terminates.

val auto_yield : float -> unit -> unit Lwt.t

auto_yield timeout returns a function f that will yield every timeout seconds.

exception Timeout

Exception raised by timeout operations

val timeout : float -> 'a Lwt.t

timeout d is a thread that remains suspended for d