This module exposes all the filesystem operations of libuv with an asynchronous (callback) interface. There is an additional submodule, Luv.File.Sync, which exposes all the same operations with a synchronous (direct) interface. So, for example, there are:
Luv.File.chmod :
string -> Mode.t list -> ((unit, Error.t) result -> unit) -> unit
Luv.File.Sync.chmod :
string -> Mode.t list -> (unit, Error.t) result
For filesystem operations, synchronous operations are generally faster, because most asynchronous operations have to be run in a worker thread. However, synchronous operations can block.
A general guideline is that if performance is not critical, or your code may be used to access a network filesystem, use asynchronous operations. The latter condition may be especially important if you are writing a library, and cannot readily predict whether it will be used to access a network file system or not.
Synchronous operations are typically best for internal applications and short scripts.
It is possible to run a sequence of synchronous operations without blocking the main thread by manually running them in a worker. This can be done in several ways:
By creating a thread manually with OCaml's standard Thread module.
This is only worthwhile if multiple synchronous operations will be done inside the worker thread. If the worker thread does only one operation, the performance is identical to the asynchronous API.
Note that this performance difference does not apply to other kinds of libuv operations. For example, unlike reading from a file, reading from the network asynchronously is very fast.
Types
type t
Files.
Roughly, on Unix, these correspond to OS file descriptors, and on Windows, these are HANDLEs wrapped in C runtime file descriptors.
The incoming data is written consecutively to into the given buffers. The number of bytes that the operation tries to read is the total length of the buffers.
If you have a buffer a ready, but would like to read less bytes than the length of the buffer, use Bigarray.Array1.sub or Luv.Buffer.sub to create a shorter view of the buffer.
If the ?file_offset argument is not specified, the read is done at the current offset into the file, and the file offset is updated. Otherwise, a positioned read is done at the given offset, and the file offset is not updated. See pread(3p).
End of file is indicated by Ok Unsigned.Size_t.zero. Note that this is different from Luv.Stream.read_start.
On Unix-like systems, this passes the file descriptor through unchanged. On Windows, a Luv.File.t is an C runtime library file descritpor. This function converts it to a HANDLE.
Returns the integer representation of a Luv.File.t.
Luv.File.t is defined as an integer file descriptor by libuv on all platforms at the moment. This is a convenience function for interoperability with Luv.Process, the API of which assumes that files are represented by integers.