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 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
Unix.handle_unix_error
but catches lwt-level
exceptionsval 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
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 openfile : string -> Unix.open_flag list -> Unix.file_perm -> file_descr
Unix.openfile
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 clear_close_on_exec : file_descr -> unit
Unix.clear_close_on_exec
val fchmod : file_descr -> Unix.file_perm -> unit
Unix.fchmod
val fchown : file_descr -> int -> int -> unit
Unix.fchown
val dup : file_descr -> file_descr
Unix.dup
val dup2 : file_descr -> file_descr -> unit
Unix.dup2
val lockf : file_descr -> Unix.lock_command -> int -> unit
Unix.lockf
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 lseek : file_descr -> int -> Unix.seek_command -> int
Unix.lseek
val ftruncate : file_descr -> int -> unit
Unix.ftruncate
val fstat : file_descr -> Unix.stats
Unix.fstat
val isatty : file_descr -> bool
Unix.isatty
module LargeFile:sig
..end
type
signal_handler_id
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
type
dir_handle
val opendir : string -> dir_handle
val readdir : dir_handle -> string Lwt.t
End_of_file
when the end of the directory has been reached.val rewinddir : dir_handle -> unit
val closedir : dir_handle -> unit
type
resource_usage = {
|
ru_utime : |
(* | User time used | *) |
|
ru_stime : |
(* | System time used | *) |
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 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
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
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 getsockname : file_descr -> Unix.sockaddr
Unix.getsockname
val getpeername : file_descr -> Unix.sockaddr
Unix.getpeername
val getsockopt : file_descr -> Unix.socket_bool_option -> bool
Unix.getsockopt
val setsockopt : file_descr -> Unix.socket_bool_option -> bool -> unit
Unix.setsockopt
val getsockopt_int : file_descr -> Unix.socket_int_option -> int
Unix.getsockopt_int
val setsockopt_int : file_descr -> Unix.socket_int_option -> int -> unit
Unix.setsockopt_int
val getsockopt_optint : file_descr -> Unix.socket_optint_option -> int option
Unix.getsockopt_optint
val setsockopt_optint : file_descr -> Unix.socket_optint_option -> int option -> unit
Unix.setsockopt_optint
val getsockopt_float : file_descr -> Unix.socket_float_option -> float
Unix.getsockopt_float
val setsockopt_float : file_descr -> Unix.socket_float_option -> float -> unit
Unix.setsockopt_float
val getsockopt_error : file_descr -> Unix.error option
Unix.getsockopt_error
type
credentials = {
|
cred_pid : |
|
cred_uid : |
|
cred_gid : |
val get_credentials : file_descr -> credentials
get_credentials fd
returns credential informations from the
given socket.val recv : file_descr ->
string -> int -> int -> Unix.msg_flag list -> int Lwt.t
Unix.recv
val recvfrom : file_descr ->
string -> int -> int -> Unix.msg_flag list -> (int * Unix.sockaddr) Lwt.t
Unix.recvfrom
val send : file_descr ->
string -> int -> int -> Unix.msg_flag list -> int Lwt.t
Unix.send
val sendto : file_descr ->
string -> int -> int -> Unix.msg_flag list -> Unix.sockaddr -> int Lwt.t
Unix.sendto
type
io_vector = {
|
iov_buffer : |
|
iov_offset : |
|
iov_length : |
val io_vector : buffer:string -> offset:int -> length:int -> 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.val tcgetattr : file_descr -> Unix.terminal_io
Unix.tcgetattr
val tcsetattr : file_descr -> Unix.setattr_when -> Unix.terminal_io -> unit
Unix.tcsetattr
val tcdrain : file_descr -> unit
Unix.tcdrain
val tcflush : file_descr -> Unix.flush_queue -> unit
Unix.tcflush
val tcflow : file_descr -> Unix.flow_action -> unit
Unix.tcflow
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