Module Lwt_unix


module Lwt_unix: sig .. end
Cooperative system calls


This modules redefine system calls, as in the Unix module of the standard library, but mapped into cooperative ones, which will not block the program, letting other threads run.

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

Moreover all sleeping threads returned by function of this modules are cancelable, this means that 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.

More precisely, assuming that you have two file descriptor fd1 and fd2 and you want to read something from fd1 or exclusively from fd2, and fail with an exception if a timeout of 1 second expires, without reading anything from fd1 and fd2, even if they become readable in the future.

Then you can do:

      Lwt.select [Lwt_unix.timeout 1.0; read fd1 buf1 ofs1 len1; read fd2 buf2 ofs2 len2]
    

In this case it is guaranteed that exactly one of the three operations will completes, and other will just 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

Sleeping

val sleep : float -> unit Lwt.t
sleep d is a threads which remain suspended for d seconds and then terminates.
val yield : unit -> unit Lwt.t
yield () is a threads which 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 which will yield every timeout seconds.
exception Timeout
Exception raised by timeout operations
val timeout : float -> 'a Lwt.t
timeout d is a threads which remain suspended for d seconds then fail with Lwt_unix.Timeout
val with_timeout : float -> (unit -> 'a Lwt.t) -> 'a Lwt.t
with_timeout d f is a short-hand for:

        Lwt.select [Lwt_unix.timeout d; f ()]
      


Operation on file-descriptors

type file_descr 
The abstract type for file descriptors. A Lwt file descriptor is a pair of a unix file descriptor (of type Unix.file_descr) and a state.

A file descriptor may be:



type state =
| Open (*The file descriptor is opened*)
| Closed (*The file descriptor has been closed by Lwt_unix.close. It must not be used for any operation.*)
| Aborted of exn (*The file descriptor has been aborted, the only operation possible is Lwt_unix.close, all others will fail.*)
State of a file descriptor
val state : file_descr -> state
state fd returns the state of fd
val openfile : string -> Unix.open_flag list -> Unix.file_perm -> file_descr
Wrapper for Unix.openfile
val unix_file_descr : file_descr -> Unix.file_descr
Returns the underlying unix file descriptor. It always succeed, even if the file descriptor's state is not Open.
val of_unix_file_descr : Unix.file_descr -> file_descr
Creates a lwt file descriptor from a unix one. It has the side effect of putting it into non-blocking mode
val of_unix_file_descr_blocking : Unix.file_descr -> file_descr
Normally Lwt_unix uses file descriptors in non-blocking mode, but in certain cases, like for standard descriptors (Lwt_unix.stdin, Lwt_unix.stdout and Lwt_unix.stderr) we do not want that.

This function do not modify the file descritpor flags but other operations involving it may be a bit less efficient, since Lwt_unix will always check that the file descriptor is ready before using it.

Note: this is not 100% safe to use file descriptors in blocking mode, so you should avoid doing it.

val blocking : file_descr -> bool
blocking fd returns whether fd is used in blocking or non-blocking mode.
val set_blocking : file_descr -> bool -> unit
set_blocking fd b puts fd in blocking or non-blocking mode.
val abort : file_descr -> exn -> unit
abort fd exn makes all current and further uses of the file descriptor fail with the given exception. This put the file descriptor into the Aborted state.

If the file descrptor is closed, this does nothing, if it is aborted, this replace the abort exception by exn.

val close : file_descr -> unit
Close a file descriptor. This close the underlying unix file descriptor and set its state to Closed
val set_close_on_exec : file_descr -> unit
Wrapper for Unix.set_close_on_exec
val clear_close_on_exec : file_descr -> unit
Wrapper for Unix.clear_close_on_exec
val fchmod : file_descr -> Unix.file_perm -> unit
Wrapper for Unix.fchmod
val fchown : file_descr -> int -> int -> unit
Wrapper for Unix.fchown
val dup : file_descr -> file_descr
Wrapper for Unix.dup
val dup2 : file_descr -> file_descr -> unit
Wrapper for Unix.dup2
val lockf : file_descr -> Unix.lock_command -> int -> unit
Wrapper for Unix.lockf

Standard instances

val stdin : file_descr
The standard file descriptor for input. This one is usually a terminal is the program is started from a terminal.
val stdout : file_descr
The standard file descriptor for output
val stderr : file_descr
The standard file descriptor for printing error messages

Reading/writing

val read : file_descr -> string -> int -> int -> int Lwt.t
read fd buf ofs len has the same semantic as Unix.read, but is cooperative
val write : file_descr -> string -> int -> int -> int Lwt.t
read fd buf ofs len has the same semantic as Unix.write, but is cooperative
val wait_read : file_descr -> unit Lwt.t
waits (without blocking other threads) until there is something to read on the file descriptor
val wait_write : file_descr -> unit Lwt.t
waits (without blocking other threads) until it is possible to write on the file descriptor

Pipes

val pipe : unit -> file_descr * file_descr
pipe () creates pipe using Unix.pipe and returns two lwt file descriptors created from unix file_descriptor
val pipe_in : unit -> file_descr * Unix.file_descr
pipe_in () is the same as Lwt_unix.pipe but maps only the unix file descriptor for reading into a lwt one. The second is not put into non-blocking mode. You usually want to use this before forking to receive data from the child process.
val pipe_out : unit -> Unix.file_descr * file_descr
pipe_out () is the inverse of Lwt_unix.pipe_in. You usually want to use this before forking to send data to the child process

Random access

val lseek : file_descr -> int -> Unix.seek_command -> int
Wrapper for Unix.lseek
val ftruncate : file_descr -> int -> unit
Wrapper for Unix.ftruncate

Miscellaneous wrappers

val fstat : file_descr -> Unix.stats
Wrapper for Unix.fstat
val isatty : file_descr -> bool
Wrapper for Unix.isatty
module LargeFile: sig .. end

Signals

type signal_handler_id 
Id of a signal handler, used to cancel it
val on_signal : int -> (int -> unit) -> signal_handler_id
on_signal signum f calls f each time the signal with numnber signum is received by the process. It returns a signal handler identifier which can be used to stop monitoring signum.
val disable_signal_handler : signal_handler_id -> unit
Stops receiving this signal

Directories

type dir_handle 
The type of descriptors over opened directories.
val opendir : string -> dir_handle
Open a descriptor on a directory
val readdir : dir_handle -> string Lwt.t
Return the next entry in a directory.
Raises End_of_file when the end of the directory has been reached.
val rewinddir : dir_handle -> unit
Reposition the descriptor to the beginning of the directory
val closedir : dir_handle -> unit
Close a directory descriptor.

Processes


type resource_usage = {
   ru_utime : float; (*User time used*)
   ru_stime : float; (*System time used*)
}
Resource usages
val wait : unit -> (int * Unix.process_status) Lwt.t
Wrapper for Unix.wait
val waitpid : Unix.wait_flag list -> int -> (int * Unix.process_status) Lwt.t
Wrapper for Unix.waitpid
val wait4 : Unix.wait_flag list ->
int -> (int * Unix.process_status * resource_usage) Lwt.t
wait4 flags pid returns (pid, status, rusage) where (pid, status) is the same result as Unix.waitpid flags pid, and rusage contains accounting information about the child.
val has_wait4 : bool
Whether the wait4 system call is available on this system. If it is not, them wait4 will always returns { utime = 0.0; stime = 0.0 } as resource usages.
val system : string -> Unix.process_status Lwt.t
Wrapper for Unix.system

Sockets

val socket : Unix.socket_domain -> Unix.socket_type -> int -> file_descr
socket domain type proto is the same as Unix.socket but maps the result into a lwt file descriptor
val socketpair : Unix.socket_domain ->
Unix.socket_type -> int -> file_descr * file_descr
Wrapper for Unix.socketpair
val bind : file_descr -> Unix.sockaddr -> unit
Wrapper for Unix.bind
val listen : file_descr -> int -> unit
Wrapper for Unix.listen
val accept : file_descr -> (file_descr * Unix.sockaddr) Lwt.t
Wrapper for Unix.accept
val accept_n : file_descr ->
int -> (file_descr * Unix.sockaddr) list Lwt.t
accept_n fd count accepts up to count connection in one time.

accept_n has the advantage of improving performances. If you want a more detailed description, you can have a look at:

Acceptable strategies for improving web server performance

val connect : file_descr -> Unix.sockaddr -> unit Lwt.t
Wrapper for Unix.connect
val shutdown : file_descr -> Unix.shutdown_command -> unit
Wrapper for Unix.shutdown
val getsockname : file_descr -> Unix.sockaddr
Wrapper for Unix.getsockname
val getpeername : file_descr -> Unix.sockaddr
Wrapper for Unix.getpeername

Socket options

val getsockopt : file_descr -> Unix.socket_bool_option -> bool
Wrapper for Unix.getsockopt
val setsockopt : file_descr -> Unix.socket_bool_option -> bool -> unit
Wrapper for Unix.setsockopt
val getsockopt_int : file_descr -> Unix.socket_int_option -> int
Wrapper for Unix.getsockopt_int
val setsockopt_int : file_descr -> Unix.socket_int_option -> int -> unit
Wrapper for Unix.setsockopt_int
val getsockopt_optint : file_descr -> Unix.socket_optint_option -> int option
Wrapper for Unix.getsockopt_optint
val setsockopt_optint : file_descr -> Unix.socket_optint_option -> int option -> unit
Wrapper for Unix.setsockopt_optint
val getsockopt_float : file_descr -> Unix.socket_float_option -> float
Wrapper for Unix.getsockopt_float
val setsockopt_float : file_descr -> Unix.socket_float_option -> float -> unit
Wrapper for Unix.setsockopt_float
val getsockopt_error : file_descr -> Unix.error option
Wrapper for Unix.getsockopt_error

type credentials = {
   cred_pid : int;
   cred_uid : int;
   cred_gid : int;
}
val get_credentials : file_descr -> credentials
get_credentials fd returns credential informations from the given socket.

receive/send messages

val recv : file_descr ->
string -> int -> int -> Unix.msg_flag list -> int Lwt.t
Wrapper for Unix.recv
val recvfrom : file_descr ->
string -> int -> int -> Unix.msg_flag list -> (int * Unix.sockaddr) Lwt.t
Wrapper for Unix.recvfrom
val send : file_descr ->
string -> int -> int -> Unix.msg_flag list -> int Lwt.t
Wrapper for Unix.send
val sendto : file_descr ->
string -> int -> int -> Unix.msg_flag list -> Unix.sockaddr -> int Lwt.t
Wrapper for Unix.sendto

type io_vector = {
   iov_buffer : string;
   iov_offset : int;
   iov_length : int;
}
An io-vector. Used by Lwt_unix.recv_msg and Lwt_unix.send_msg.
val io_vector : buffer:string -> offset:int -> length:int -> io_vector
Creates an io-vector
val recv_msg : socket:file_descr ->
io_vectors:io_vector list -> (int * Unix.file_descr list) Lwt.t
recv_msg ~socket ~io_vectors receives data into a list of io-vectors, plus any file-descriptors that may accompany the message.
val send_msg : socket:file_descr ->
io_vectors:io_vector list -> fds:Unix.file_descr list -> int Lwt.t
send_msg ~socket ~io_vectors ~fds sends data from a list of io-vectors, accompanied with a list of file-descriptor.

Terminal interface

val tcgetattr : file_descr -> Unix.terminal_io
Wrapper for Unix.tcgetattr
val tcsetattr : file_descr -> Unix.setattr_when -> Unix.terminal_io -> unit
Wrapper for Unix.tcsetattr
val tcdrain : file_descr -> unit
Wrapper for Unix.tcdrain
val tcflush : file_descr -> Unix.flush_queue -> unit
Wrapper for Unix.tcflush
val tcflow : file_descr -> Unix.flow_action -> unit
Wrapper for Unix.tcflow

Low-level interaction

type watchers 
Type of a set of watchers, i.e. a set of action waiting for a file descriptor to be readable/writable.
exception Retry
If an action raises Lwt_unix.Retry, it will be requeued until the file descriptor becomes readable/writable again.
exception Retry_read
If an action raises Lwt_unix.Retry_read, it will be requeued until the file descriptor becomes readable.
exception Retry_write
If an action raises Lwt_unix.Retry_read, it will be requeued until the file descriptor becomes writables.
val inputs : watchers
The set of action waiting for a file descriptor to become readable
val outputs : watchers
The set of action waiting for a file descriptor to become writable
val wrap_syscall : watchers -> file_descr -> (unit -> 'a) -> 'a Lwt.t
wrap_syscall set fd action wrap an action on a file descriptor. It tries to execture action, and if it can not be performed immediately without blocking, it is registered for latter.

In the latter case, if the thread is canceled, action is removed from set.

val check_descriptor : file_descr -> unit
check_descriptor fd raise an exception if fd is not in the state Open
val register_action : watchers -> file_descr -> (unit -> 'a) -> 'a Lwt.t
register_action set fd action registers action on fd. When fd becomes readable/writable action is called.

Note: