Module Eio_fs_unix.BatchSource

Confined directory operations, many to one system-thread hop.

Eio.Path makes one system-thread hop per operation, which dominates the cost of writing a large tree of small files. A batch runs a list of operations beneath one directory in a single hop and answers each one separately.

Every path is relative to the batch's directory. Native directories resolve one component at a time with openat(O_DIRECTORY | O_NOFOLLOW), as eio_posix resolves a path where the kernel has no RESOLVE_BENEATH. The confinement is stricter than Eio.Path's: an absolute path, an empty, . or .. component, a NUL byte, or a symbolic link before the last component is refused, never followed, so no operation reaches outside the directory. Descriptorless backends hold each Eio parent capability and verify its identity before descending. The last component is never followed either. The directories a run opens are held for the run only.

Sourcetype t

The type for a directory that batches run beneath.

Sourceval v : sw:Eio.Switch.t -> _ Eio.Path.t -> t

v ~sw dir opens dir, resolved by Eio.Path's own confinement, and holds it until sw finishes. A wrapper of Eio_fs_chaos observes the open and the batch then runs beneath the directory it wraps. An already-open directory is held through its dot entry, without an empty open pathname. Descriptorless backends use Eio operations through held parent capabilities.

  • raises Eio.Io

    when dir cannot be opened as a directory.

Sourcetype op =
  1. | Mkdir of {
    1. path : string;
    2. perm : int;
    }
    (*

    mkdirat(2) with perm, subject to the umask.

    *)
  2. | Create of {
    1. path : string;
    2. perm : int;
    3. contents : string;
    }
    (*

    openat(2) with O_CREAT | O_EXCL | O_NOFOLLOW, every byte of contents written, then fchmod(2) to perm, so the umask does not apply. A failed write leaves the file holding what was written.

    *)
  3. | Rename of {
    1. src : string;
    2. dst : string;
    }
    (*

    renameat(2); both paths are confined.

    *)
  4. | Lstat of string
    (*

    fstatat(2) with AT_SYMLINK_NOFOLLOW.

    *)

The type for batch operations, each named after the system call that performs it beneath a native directory.

Sourcetype outcome =
  1. | Done
    (*

    Every operation but Lstat answers this.

    *)
  2. | Stat of Eio.File.Stat.t
    (*

    What Lstat answers.

    *)

The type for the results of operations that succeeded.

Sourcetype error = [
  1. | `Refused of string
    (*

    The path names nothing beneath the directory; the string says why.

    *)
  2. | `Unix of Unix.error * string * string
    (*

    The system call failed: its error, its name and its argument.

    *)
]

The type for the errors of operations that failed.

Sourceval pp_error : error Fmt.t

pp_error formats an error for logs and test failures.

Sourceval run : t -> op list -> (outcome, error) result list

run t ops performs ops in order, in one system-thread hop, and is their results in the same order. An operation that fails does not stop the ones after it. An empty ops is [] and makes no hop.