to_string t returns a pretty sexp of the representation of t
create ?support_nonblock 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.
If avoid_nonblock_if_possible, then Async will treat the file descriptor as blocking
if it can (more precisely, if it's not a bound socket).
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.
If should_close_file_descriptor is true, close_finished t becomes determined
after the close() system call on t's underlying file descriptor returns. If
should_close_file_descriptor is false, then close_finished becomes determined
immediately.
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.
close_started t becomes determined when close t is called.
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.
with_file_descr_exn is like with_file_descr except that it raises rather than
return `Already_closed or `Error.
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).
with_file_descr_deferred_exn is like with_file_descr_deferred, except that it
raises rather than return `Already_closed or `Error.
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.
syscall_result_exn t f a is like syscall_exn, except it does not allocate except
in exceptional cases. a is passed unchanged to f, and should be used to eliminate
allocations due to closure capture.
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_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.