Up  Next

Module Fd

module Fd: Fd
module Kind: sig .. end
type t 
val info : t -> Core.Std.Info.t
val to_string : t -> string
to_string t returns a pretty sexp of the representation of t
val create : Kind.t -> Core.Unix.File_descr.t -> Core.Std.Info.t -> t
create kind file_descr creates a new t of the underlying kind and file descriptor.

We thought about using fstat() rather than requiring the user to supply the kind. But fstat can block, which would require putting this in a thread, which has some consequences, and it isn't clear that it gets us that much. Also, create is mostly used within the Async implementation -- clients shouldn't need it unless they are mixing Async and non-Async code.

val kind : t -> Kind.t
kind t returns the kind of file descriptor that t is.
val supports_nonblock : t -> bool
supports_nonblock t returns true if t supports nonblocking system calls.
val clear_nonblock : t -> unit
clear_nonblock t clears the ``non-blocking'' flag on t and causes and causes async to treat the fd as though it doesn't support nonblocking I/O. This is useful for applications that want to share a file descriptor between async and non-async code and want to avoid EWOULDBLOCK or EAGAIN being seen by the non-async code, which would then cause a Sys_blocked_io exception.

clear_nonblock t has no effect if not (supports_nonblock t).

val close : ?should_close_file_descriptor:bool -> t -> unit Import.Deferred.t
close t prevents further use of t, and closes the underlying file descriptor once all the current uses are finished. The result of close becomes determined once the underlying file descriptor has been closed, i.e. once the close() system call returns. It is ok to call close multiple times on the same t; calls subsequent to the initial call will have no effect, but will return the same deferred as the original call.

In some situations, one may need to cause async to release an fd that it is managing without closing the underlying file descriptor. In that case, one should supply ~should_close_file_descriptor:false, which will skip the underlying close() system call.

close_finished t becomes determined after the close() system call on t's underlying file descriptor returns. close_finished differs from close in that it does not have the side effect of initiating a close.

is_closed t returns true iff close t has been called.

val close_finished : t -> unit Import.Deferred.t
val is_closed : t -> bool
val with_close : t -> f:(t -> 'a Import.Deferred.t) -> 'a Import.Deferred.t
with_close t f applies f to t, returns the result of f, and closes t.
val is_open : t -> bool
is_open t is not (is_closed t)
val stdin : unit -> t
stdin, stdout, and stderr are wrappers around the standard Unix file descriptors.
val stdout : unit -> t
val stderr : unit -> t
val with_file_descr : ?nonblocking:bool ->
       t ->
       (Core.Unix.File_descr.t -> 'a) ->
       [ `Already_closed | `Error of exn | `Ok of 'a ]
with_file_descr t f runs f on the file descriptor underlying t, if is_open t, and returns `Ok or `Error according to f. If is_closed t, then it does not call f and returns `Already_closed.
val with_file_descr_exn : ?nonblocking:bool -> t -> (Core.Unix.File_descr.t -> 'a) -> 'a
with_file_descr_exn is like with_file_descr except that it raises rather than return `Already_closed or `Error.
val with_file_descr_deferred : t ->
       (Core.Unix.File_descr.t -> 'a Import.Deferred.t) ->
       [ `Already_closed | `Error of exn | `Ok of 'a ] Import.Deferred.t
with_file_descr_deferred t f runs f on the file descriptor underlying t, if is_open t, and returns `Ok or `Error according to f. If is_closed t, then it does not call f and returns `Already_closed. It ensures that the file descriptor underlying t is not closed until the result of f becomes determined (or f raises).
val interruptible_ready_to : t ->
       [ `Read | `Write ] ->
       interrupt:unit Import.Deferred.t ->
       [ `Bad_fd | `Closed | `Interrupted | `Ready ] Import.Deferred.t
interruptible_ready_to t read_write ~interrupt returns a deferred that will become determined when the file descriptor underlying t can be read from or written to without blocking, or when interrupt becomes determined.
val ready_to : t ->
       [ `Read | `Write ] -> [ `Bad_fd | `Closed | `Ready ] Import.Deferred.t
ready_to t read_write is like interruptible_ready_to, but without the possibility of interruption.
val interruptible_every_ready_to : t ->
       [ `Read | `Write ] ->
       interrupt:unit Import.Deferred.t ->
       ('a -> unit) ->
       'a -> [ `Bad_fd | `Closed | `Interrupted | `Unsupported ] Import.Deferred.t
interruptible_every_ready_to t read_write ~interrupt f a enqueus a job to run f a every time the file descriptor underlying t can be read from or written to without blocking and returns a deferred that will become determined when interrupt becomes determined or the file descriptor is closed.
val every_ready_to : t ->
       [ `Read | `Write ] ->
       ('a -> unit) -> 'a -> [ `Bad_fd | `Closed | `Unsupported ] Import.Deferred.t
every_ready_to t read_write f x is like interruptible_every_ready_to, but without the possibility of interruption.
val syscall : ?nonblocking:bool ->
       t ->
       (Core.Unix.File_descr.t -> 'a) ->
       [ `Already_closed | `Error of exn | `Ok of 'a ]
syscall t f runs Async_unix.syscall with f on the file descriptor underlying t, if is_open t, and returns `Ok or `Error according to f. If is_closed t, it does not call f and returns `Already_closed.
val syscall_exn : ?nonblocking:bool -> t -> (Core.Unix.File_descr.t -> 'a) -> 'a
syscall_exn t f is like syscall, except it raises rather than return `Already_closed or `Error.
val syscall_in_thread : t ->
       name:string ->
       (Core.Unix.File_descr.t -> 'a) ->
       [ `Already_closed | `Error of exn | `Ok of 'a ] Import.Deferred.t
syscall_in_thread t f runs In_thread.syscall with f on the file descriptor underlying t, if is_open t, and returns a deferred that becomes determined with `Ok or `Error when the system call completes. If is_closed t, it does not call f and returns `Already_closed.
val syscall_in_thread_exn : t ->
       name:string -> (Core.Unix.File_descr.t -> 'a) -> 'a Import.Deferred.t
syscall_in_thread_exn is like syscall_in_thread, except it raises rather than return `Already_closed or `Error.
val of_in_channel : Core.Std.In_channel.t -> Kind.t -> t
of_in_channel and of_out_channel create an fd from their underlying file descriptor.
val of_out_channel : Core.Std.Out_channel.t -> Kind.t -> t
val of_in_channel_auto : Core.Std.In_channel.t -> t Import.Deferred.t
of_in_channel_auto ic is just like of_in_channel, but uses fstat to determine the kind. It makes some assumptions about sockets, specifically it assumes that a socket is either listening, or connected to something (and it uses getsockopt to find out which). Don't pass an in_channel containing an unconnected non-listening socket.
val of_out_channel_auto : Core.Std.Out_channel.t -> t Import.Deferred.t
of_out_channel_auto ic is just like of_out_channel, but uses fstat to determine the kind. It makes some assumptions about sockets, specifically it assumes that a socket is either listening, or connected to something (and it uses getsockopt to find out which). Don't pass an in_channel containing an unconnected non listening socket.
val file_descr_exn : t -> Core.Unix.File_descr.t
file_descr_exn t returns the file descriptor underlying t, unless is_closed t, in which case it raises. One must be very careful when using this function, and should try not to, since any uses of the resulting file descriptor are unknown to the Fd module, and hence can violate the guarantee it is trying to enforce.
val to_int_exn : t -> int
to_int_exn t returns the the underlying file descriptor as an int. It has the same caveats as file_descr_exn.
val replace : t -> Kind.t -> Core.Std.Info.t -> unit
replace t kind is for internal use only, by Unix_syscalls. It is used when one wants to reuse a file descriptor in an fd with a new kind.
val ready_fold : t ->
       init:'a ->
       ?stop:unit Import.Deferred.t ->
       f:('a -> Core.Unix.File_descr.t -> 'a) ->
       [ `Read | `Write ] -> 'a Import.Deferred.t
ready_fold t ~init ~f folds f over t, handling EWOULDBLOCK/EAGAIN and EINTR by retrying when ready. The fold is terminated when t closes or by stop being determined, if ~stop is supplied.

By design this function does not return to the Async scheduler until t is no longer ready to transfer data. If you expect t to be ready for long periods at a time then you should use stop to avoid starving other Async jobs.

ready_fold raises if not (supports_nonblock t).

val sexp_of_t : t -> Sexplib.Sexp.t

to_string t returns a pretty sexp of the representation of t

create kind file_descr creates a new t of the underlying kind and file descriptor.

We thought about using fstat() rather than requiring the user to supply the kind. But fstat can block, which would require putting this in a thread, which has some consequences, and it isn't clear that it gets us that much. Also, create is mostly used within the Async implementation -- clients shouldn't need it unless they are mixing Async and non-Async code.

kind t returns the kind of file descriptor that t is.

supports_nonblock t returns true if t supports nonblocking system calls.

clear_nonblock t clears the ``non-blocking'' flag on t and causes and causes async to treat the fd as though it doesn't support nonblocking I/O. This is useful for applications that want to share a file descriptor between async and non-async code and want to avoid EWOULDBLOCK or EAGAIN being seen by the non-async code, which would then cause a Sys_blocked_io exception.

clear_nonblock t has no effect if not (supports_nonblock t).

close t prevents further use of t, and closes the underlying file descriptor once all the current uses are finished. The result of close becomes determined once the underlying file descriptor has been closed, i.e. once the close() system call returns. It is ok to call close multiple times on the same t; calls subsequent to the initial call will have no effect, but will return the same deferred as the original call.

In some situations, one may need to cause async to release an fd that it is managing without closing the underlying file descriptor. In that case, one should supply ~should_close_file_descriptor:false, which will skip the underlying close() system call.

close_finished t becomes determined after the close() system call on t's underlying file descriptor returns. close_finished differs from close in that it does not have the side effect of initiating a close.

is_closed t returns true iff close t has been called.

default is true

with_close t f applies f to t, returns the result of f, and closes t.

is_open t is not (is_closed t)

stdin, stdout, and stderr are wrappers around the standard Unix file descriptors.

with_file_descr t f runs f on the file descriptor underlying t, if is_open t, and returns `Ok or `Error according to f. If is_closed t, then it does not call f and returns `Already_closed.

default is false

with_file_descr_exn is like with_file_descr except that it raises rather than return `Already_closed or `Error.

default is false

with_file_descr_deferred t f runs f on the file descriptor underlying t, if is_open t, and returns `Ok or `Error according to f. If is_closed t, then it does not call f and returns `Already_closed. It ensures that the file descriptor underlying t is not closed until the result of f becomes determined (or f raises).

interruptible_ready_to t read_write ~interrupt returns a deferred that will become determined when the file descriptor underlying t can be read from or written to without blocking, or when interrupt becomes determined.

ready_to t read_write is like interruptible_ready_to, but without the possibility of interruption.

interruptible_every_ready_to t read_write ~interrupt f a enqueus a job to run f a every time the file descriptor underlying t can be read from or written to without blocking and returns a deferred that will become determined when interrupt becomes determined or the file descriptor is closed.

every_ready_to t read_write f x is like interruptible_every_ready_to, but without the possibility of interruption.

syscall t f runs Async_unix.syscall with f on the file descriptor underlying t, if is_open t, and returns `Ok or `Error according to f. If is_closed t, it does not call f and returns `Already_closed.

default is false

syscall_exn t f is like syscall, except it raises rather than return `Already_closed or `Error.

default is false

syscall_in_thread t f runs In_thread.syscall with f on the file descriptor underlying t, if is_open t, and returns a deferred that becomes determined with `Ok or `Error when the system call completes. If is_closed t, it does not call f and returns `Already_closed.

syscall_in_thread_exn is like syscall_in_thread, except it raises rather than return `Already_closed or `Error.

of_in_channel and of_out_channel create an fd from their underlying file descriptor.

of_in_channel_auto ic is just like of_in_channel, but uses fstat to determine the kind. It makes some assumptions about sockets, specifically it assumes that a socket is either listening, or connected to something (and it uses getsockopt to find out which). Don't pass an in_channel containing an unconnected non-listening socket.

of_out_channel_auto ic is just like of_out_channel, but uses fstat to determine the kind. It makes some assumptions about sockets, specifically it assumes that a socket is either listening, or connected to something (and it uses getsockopt to find out which). Don't pass an in_channel containing an unconnected non listening socket.

file_descr_exn t returns the file descriptor underlying t, unless is_closed t, in which case it raises. One must be very careful when using this function, and should try not to, since any uses of the resulting file descriptor are unknown to the Fd module, and hence can violate the guarantee it is trying to enforce.

to_int_exn t returns the the underlying file descriptor as an int. It has the same caveats as file_descr_exn.

replace t kind is for internal use only, by Unix_syscalls. It is used when one wants to reuse a file descriptor in an fd with a new kind.

ready_fold t ~init ~f folds f over t, handling EWOULDBLOCK/EAGAIN and EINTR by retrying when ready. The fold is terminated when t closes or by stop being determined, if ~stop is supplied.

By design this function does not return to the Async scheduler until t is no longer ready to transfer data. If you expect t to be ready for long periods at a time then you should use stop to avoid starving other Async jobs.

ready_fold raises if not (supports_nonblock t).

default is Deferred.never ()