package irmin-pack

  1. Overview
  2. Docs
package irmin-pack
Legend:
Library
Module
Module type
Parameter
Class
Class type

Low level IO abstraction. A typical implementation is unix. This abstraction is meant to be dead simple. Not a lot of documentation is required.

It is not resistant to race condictions. There should not be concurrent modifications of the files.

These functions are essentially invoking the underlying functions from Unix directly; there is no buffering for example.

type t

Errors

type misc_error = Unix.error * string * string

An abstract error type that contains the IO-backend specific errors. (e.g. Unix.error)

val misc_error_t : misc_error Irmin.Type.t
type create_error = [
  1. | `Io_misc of misc_error
  2. | `File_exists of string
]
type open_error = [
  1. | `Io_misc of misc_error
  2. | `No_such_file_or_directory
  3. | `Not_a_file
]
type read_error = [
  1. | `Io_misc of misc_error
  2. | `Read_out_of_bounds
  3. | `Closed
  4. | `Invalid_argument
]
type write_error = [
  1. | `Io_misc of misc_error
  2. | `Ro_not_allowed
  3. | `Closed
]
type close_error = [
  1. | `Io_misc of misc_error
  2. | `Double_close
]
type mkdir_error = [
  1. | `Io_misc of misc_error
  2. | `File_exists of string
  3. | `No_such_file_or_directory
  4. | `Invalid_parent_directory
]

Safe Functions

None of the functions in this section raise exceptions. They may however perform effects that are always continued.

Life Cycle

val create : path:string -> overwrite:bool -> (t, [> create_error ]) result
val open_ : path:string -> readonly:bool -> (t, [> open_error ]) result
val close : t -> (unit, [> close_error ]) result

Write Functions

val write_string : t -> off:Optint.Int63.t -> string -> (unit, [> write_error ]) result

write_string t ~off s writes s at offset in t.

val fsync : t -> (unit, [> write_error ]) result

fsync t persists to the file system the effects of previous create or write.

val move_file : src:string -> dst:string -> (unit, [> `Sys_error of string ]) result
val copy_file : src:string -> dst:string -> (unit, [> `Sys_error of string ]) result
val mkdir : string -> (unit, [> mkdir_error ]) result

Read Functions

val read_to_string : t -> off:Optint.Int63.t -> len:int -> (string, [> read_error ]) result

read_to_string t ~off ~len are the len bytes of t at off.

val read_all_to_string : t -> (string, [> `Io_misc of misc_error | `Closed ]) result

read_to_string t is the contents full contents of the file.

The individual pages are not guaranteed to be read atomically.

val read_size : t -> (Optint.Int63.t, [> read_error ]) result

read_size t is the number of bytes of the file handled by t.

This function is expensive in the unix implementation because it performs syscalls.

val size_of_path : string -> (Optint.Int63.t, [> `Io_misc of misc_error | `No_such_file_or_directory | `Not_a_file ]) result
val classify_path : string -> [> `File | `Directory | `No_such_file_or_directory | `Other ]

MISC.

val readonly : t -> bool
val path : t -> string
val page_size : int

Unsafe Functions

These functions are equivalents to exising safe ones, but using exceptions instead of the result monad for performances reasons.

val read_exn : t -> off:Optint.Int63.t -> len:int -> bytes -> unit

read_exn t ~off ~len b reads the len bytes of t at off to b.

Raises Errors.Pack_error and Errors.RO_not_allowed.

Also raises backend-specific exceptions (e.g. Unix.Unix_error for the unix backend).

val write_exn : t -> off:Optint.Int63.t -> len:int -> string -> unit

write_exn t ~off ~len b writes the first len bytes pf b to t at offset off.

Raises Errors.Pack_error and Errors.RO_not_allowed.

Also raises backend-specific exceptions (e.g. Unix.Unix_error for the unix backend).

val raise_misc_error : misc_error -> 'a
val catch_misc_error : (unit -> 'a) -> ('a, [> `Io_misc of misc_error ]) result
OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct