module Lwt_unix:Cooperative system callssig
..end
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 concealable, 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 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.exception Timeout
val timeout : float -> 'a Lwt.t
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 ()]
type
file_descr
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 |
(* | The file descriptor has been aborted, the only operation
possible is Lwt_unix.close , all others will fail. | *) |
val state : file_descr -> state
state fd
returns the state of fd
val unix_file_descr : file_descr -> Unix.file_descr
Open
.val of_unix_file_descr : Unix.file_descr -> file_descr
val of_unix_file_descr_blocking : Unix.file_descr -> file_descr
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
Closed
val set_close_on_exec : file_descr -> unit
Unix.set_close_on_exec
val stdin : file_descr
val stdout : file_descr
val stderr : file_descr
val read : file_descr -> string -> int -> int -> int Lwt.t
read fd buf ofs len
has the same semantic as Unix.read
, but
is cooperativeval write : file_descr -> string -> int -> int -> int Lwt.t
read fd buf ofs len
has the same semantic as Unix.write
, but
is cooperativeval wait_read : file_descr -> unit Lwt.t
val wait_write : file_descr -> unit Lwt.t
val pipe : unit -> file_descr * file_descr
pipe ()
creates pipe using Unix.pipe
and returns two lwt file descriptors created from unix file_descriptorval 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 processval signal : int -> < event : int React.event; stop : unit >
signal signum
returns an object with a method event
which is
the event occuring each time the signal number signum
is
received by the running process.
The stop
method is used to tell Lwt that you are no longer
interessed in this event.
val wait : unit -> (int * Unix.process_status) Lwt.t
Unix.wait
val waitpid : Unix.wait_flag list -> int -> (int * Unix.process_status) Lwt.t
Unix.waitpid
val system : string -> Unix.process_status Lwt.t
Unix.system
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 descriptorval socketpair : Unix.socket_domain ->
Unix.socket_type -> int -> file_descr * file_descr
Unix.socketpair
val bind : file_descr -> Unix.sockaddr -> unit
Unix.bind
val listen : file_descr -> int -> unit
Unix.listen
val accept : file_descr -> (file_descr * Unix.sockaddr) Lwt.t
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.
count
are available, it returns
all of themcount
are available, it returns the next count
accept_n
has the advantage of improving performances. If you
want a more detailed description, you can have a look at:
val connect : file_descr -> Unix.sockaddr -> unit Lwt.t
Unix.connect
val shutdown : file_descr -> Unix.shutdown_command -> unit
Unix.shutdown
val setsockopt : file_descr -> Unix.socket_bool_option -> bool -> unit
Unix.setsockopt
type
watchers
exception Retry
Lwt_unix.Retry
, it will be requeued until the file descriptor becomes readable/writable again.exception Retry_read
Lwt_unix.Retry_read
, it will be requeued until the
file descriptor becomes readable.exception Retry_write
Lwt_unix.Retry_read
, it will be requeued until the
file descriptor becomes writables.val inputs : watchers
val outputs : watchers
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:
check_descriptor fd
before calling
register_action
Lwt_unix.wrap_syscall