The unpac monorepo manager self-hosting as a monorepo using unpac
add more ocamldoc for uring functions
Review from @talex5 and @patricoferris
+194
-20
+1
-1
vendor/opam/uring/lib/uring/heap.mli
+1
-1
vendor/opam/uring/lib/uring/heap.mli
···
32
32
33
33
val alloc : 'a t -> 'a -> extra_data:'b -> 'a entry
34
34
(** [alloc t a ~extra_data] adds the value [a] to [t] and returns a
35
-
pointer to that value, or raises {!Invalid_arg} if no extra space
35
+
pointer to that value, or raises [Invalid_argument] if no extra space
36
36
can be created for [t], or [t] has already been [release]d.
37
37
@param extra_data Prevent this from being GC'd until [free] is called. *)
38
38
-2
vendor/opam/uring/lib/uring/uring.ml
-2
vendor/opam/uring/lib/uring/uring.ml
+193
-17
vendor/opam/uring/lib/uring/uring.mli
+193
-17
vendor/opam/uring/lib/uring/uring.mli
···
14
14
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
15
15
*)
16
16
17
-
(** Io_uring interface. *)
17
+
(** Io_uring is an asynchronous I/O API for Linux that uses ring buffers
18
+
shared between the Linux kernel and userspace to provide an efficient
19
+
mechanism to batch requests that can be handled asynchronously and in
20
+
parallel. This module provides an OCaml interface to io_uring that
21
+
aims to provide a thin type-safe layer for use in higher-level interfaces.
22
+
@see <https://unixism.net/loti/what_is_io_uring.html#what-is-io-uring> What is Io_uring? *)
18
23
19
24
module Region = Region
20
25
···
69
74
70
75
(** {2 Timeout} *)
71
76
72
-
type clock = Boottime | Realtime
73
-
(** Represents Linux clocks. [Boottime] and [Realtime] represents OS clocks CLOCK_BOOTTIME
74
-
and CLOCK_REALTIME respectively. *)
77
+
(** Represents different Linux clocks. *)
78
+
type clock =
79
+
Boottime (** [CLOCK_BOOTTIME] is a suspend-aware monotonic clock *)
80
+
| Realtime (** [CLOCK_REALTIME] is a wallclock time clock that may be affected by discontinuous jumps *)
75
81
76
82
val timeout: ?absolute:bool -> 'a t -> clock -> int64 -> 'a -> 'a job option
77
83
(** [timeout t clock ns d] submits a timeout request to uring [t].
···
93
99
(** [mem x flags] is [true] iff [x] is a subset of [flags]. *)
94
100
end
95
101
96
-
(** Flags that can be passed to openat2. *)
102
+
(** Flags that can be passed to {!openat2}. *)
97
103
module Open_flags : sig
98
104
include FLAGS
99
105
100
-
val empty : t
101
106
val append : t
107
+
(** [append] repositions the file offset to the end of the file before
108
+
every write. This should be used with caution with io_uring.
109
+
@see <https://github.com/axboe/liburing/issues/32#issuecomment-1313220682> GitHub axboe/liburing#32 *)
110
+
102
111
val cloexec : t
112
+
(** [cloexec] enables the close-on-exec flag for the new fd. *)
113
+
103
114
val creat : t
115
+
(** [creat] implies that if the pathname does not exist, it is
116
+
created as a regular file. *)
117
+
104
118
val direct : t
119
+
(** [direct] disables the kernel buffer cache and performs IO
120
+
directly to and from the userspace buffers. *)
121
+
105
122
val directory : t
123
+
(** [directory] causes the open operation to fail if the target
124
+
is not a directory. *)
125
+
106
126
val dsync : t
127
+
(** [dsync] ensures that write operations on the file complete
128
+
according to the requirements of synchronised IO data integrity
129
+
completion. *)
130
+
107
131
val excl : t
108
-
val largefile : t
132
+
(** [excl] is used alongside {!creat} to ensure that the file
133
+
is created as a result of the {!openat2} call, and otherwise
134
+
fails with a {!Unix.EEXIST} exception. The only exception where
135
+
[excl] can be used without {!creat} is when attempting to open
136
+
block devices. If the block device is otherwise mounted, then
137
+
the open will fail with {!Unix.EBUSY}. *)
138
+
109
139
val noatime : t
140
+
(** [noatime] signals that the file access time should not be updated
141
+
when the file is read from. See {!Statx.atime_nsec}. *)
142
+
110
143
val noctty : t
144
+
(** [noctty] ensures that if the path refers to a tty, it will not
145
+
be assigned as the controlling terminal even if one is not present. *)
146
+
111
147
val nofollow : t
148
+
(** [nofollow] will cause the open to fail with {!Unix.ELOOP} if the
149
+
basename of the path is a symbolic link. *)
150
+
112
151
val nonblock : t
152
+
(** [nonblock] will open the file in non-blocking mode. *)
153
+
113
154
val path : t
155
+
(** [path] will obtain a fd that can only be used to either indicate
156
+
a location in a filesystem tree, or perform operations at the fd
157
+
level. The file is not opened, and so any IO operations on the file
158
+
will fail. [path] is only used with {!cloexec}, {!directory} and
159
+
{!nofollow}, and any other flags will be ignored. *)
160
+
114
161
val sync : t
162
+
(** [sync] ensures that write operations on the file complete
163
+
according to the requirements of synchronised IO file integrity
164
+
completion. *)
165
+
115
166
val tmpfile : t
167
+
(** [tmpfile] creates an anonymous temporary regular file. The pathname
168
+
must be a directory, within which an unnamed inode will be created.
169
+
If [tmpfile] is specified without {!excl}, then a subsequent
170
+
linkat call can move it permanently into the filesystem. *)
171
+
116
172
val trunc : t
173
+
(** [trunc] will set the file size to 0 if the file already exists
174
+
and is a regular file and is opened for writing. If the file
175
+
is a FIFO or terminal, then the flag is ignored. Use of [trunc]
176
+
on other file types is unspecified. *)
117
177
end
118
178
119
-
(** Flags that can be passed to openat2 to control path resolution. *)
179
+
(** Flags that can be passed to {!openat2} to control path resolution. *)
120
180
module Resolve : sig
121
181
include FLAGS
122
182
123
-
val empty : t
124
183
val beneath : t
184
+
(** [beneath] does not permit path resolution to succeed if any
185
+
component of the resolution is not a descendant of the directory
186
+
indicated by the [dirfd] passed to the open call. Absolute symbolic
187
+
links and absolute pathnames will be rejected.
188
+
189
+
For maximum compatiblity with future Linux kernels, the {!no_magiclinks}
190
+
flag should be specified along with this one. *)
191
+
125
192
val in_root : t
193
+
(** [in_root] treats the [dirfd] directory as the root directory while
194
+
resolving the pathname. Absolute symbolic links are interpreted
195
+
relative to the [dirfd]. If a prefix component of the pathname
196
+
equates to the [dirfd], then an immediately following [..] component
197
+
likewise equates to the [dirfd] (just as [/..] is traditionally
198
+
equivalent to [/]). An absolute pathname is interpreted relative to
199
+
the [dirfd].
200
+
201
+
For maximum compatiblity with future Linux kernels, the {!no_magiclinks}
202
+
flag should be specified along with this one. *)
203
+
126
204
val no_magiclinks : t
205
+
(** [no_magiclinks] disallows all magic-link resolution during path
206
+
resolution. Magic-links are symbolic link-like objects that are
207
+
usually found in the [/proc] filesystem. Unknowingly opening magic
208
+
links can be risky for some applications, notably those without a
209
+
controlling terminal or those within a containerised environment that
210
+
may provide an escape vector. *)
211
+
127
212
val no_symlinks : t
213
+
(** [no_symlinks] disallows the resolution of symbolic links during path
214
+
resolution, and implies the use of {!no_magiclinks}. If the basename
215
+
component of the pathname is a symlink, and [no_symlinks] is specified
216
+
along with {!Open_flags.path} and {!Open_flags.nofollow}, then a fd
217
+
referencing the symbolic link will be returned.
218
+
219
+
Note that the [no_symlinks] flag affects the treatment of symbolic links
220
+
in all of the components of pathname. This differs from the effect
221
+
of the {!Open_flags.nofollow} file creation flag, which affects the
222
+
handling of symbolic links only in the final component of the pathname. *)
223
+
128
224
val no_xdev : t
225
+
(** [no_xdev] disallows the traversal of mount points during path resolution,
226
+
including bind mounts The pathname must either be on the same mount as
227
+
the directory referred to by the [dirfd], or on the same mount as the
228
+
current working directory if [dirfd] is not specified. *)
229
+
129
230
val cached : t
231
+
(** [cached] makes the open operation fail unless all path components are
232
+
already present in the kernel lookup cache. Any revalidation or IO
233
+
needed to satisfy the lookup will result in a {!Unix.EAGAIN} error. *)
130
234
end
131
235
132
236
val openat2 : 'a t ->
···
241
345
]
242
346
243
347
val pp_kind : kind Fmt.t
348
+
(** [pp_kind kind] formats a human readable [kind] *)
244
349
245
350
val create : unit -> t
246
351
(** Use [create] to make a statx result buffer to pass to {! statx}. *)
···
248
353
module Flags : sig
249
354
include FLAGS
250
355
251
-
val empty : t
252
356
val empty_path : t
357
+
(** [empty_path] signals that if the pathname is an empty string
358
+
then operate on the file referred to by the [fd] (which can
359
+
refer to any type of file).
360
+
If [fd] is not specified then the call operates on the current
361
+
working directory. *)
362
+
253
363
val no_automount : t
364
+
(** [no_automount] signals that statx should not automount the basename
365
+
component of the path if it is an automount point.
366
+
This can be used in tools that scan directories to prevent
367
+
mass-automounting of a directory of automount points. *)
368
+
254
369
val symlink_nofollow : t
370
+
(** [symlink_nofollow] signals that if the path is a symbolic link,
371
+
then return information about the link itself. *)
372
+
255
373
val statx_sync_as_stat : t
374
+
(** [statx_sync_as_stat] is the filesystem-specific behaviour in
375
+
response to stat calls. *)
376
+
256
377
val statx_force_sync : t
378
+
(** [statx_force_sync] forces synchronisation with the server, if
379
+
the filesystem is a network-backed one. *)
380
+
257
381
val statx_dont_sync : t
382
+
(** [statx_dont_sync] signals that locally cached timestamps are
383
+
sufficient, if run on a network-backed filesystem. *)
258
384
end
259
385
260
386
module Attr : sig
261
387
include FLAGS
262
388
263
389
val compressed : t
390
+
(** The file is compressed by the filesystem. *)
391
+
264
392
val immutable : t
393
+
(** The file cannot be modified, as defined by chattr(1). *)
394
+
265
395
val append : t
396
+
(** The file can only be opened in append mode for writing.
397
+
See chattr(1). *)
398
+
266
399
val nodump : t
400
+
(** The file is not a candidate for backup when a backup
401
+
program scans the filesystem. *)
402
+
267
403
val encrypted : t
404
+
(** A key is required for the file to be encrypted by the
405
+
filesystem. *)
406
+
268
407
val verity : t
408
+
(** The file has fs-verity enabled. It cannot be written to,
409
+
and all reads from it will be verified against a
410
+
cryptographic hash that covers the entire file. *)
269
411
270
412
val dax : t
271
-
(** Since Linux 5.8 *)
413
+
(** The file is in the DAX (cpu direct access) state, which
414
+
minimises page-cache effects for both I/O and memory mappings
415
+
of this file.
416
+
@see <https://www.kernel.org/doc/Documentation/filesystems/dax.txt> Direct Access for Files
417
+
@since Linux 5.8 *)
272
418
273
419
val check : ?mask:Int64.t -> Int64.t -> t -> bool
274
420
(** [check ?mask attr t] will check if [t] is set in [attr].
···
278
424
end
279
425
280
426
module Mask : sig
427
+
(** The mask flags are used to tell the kernel which fields the {!statx} invocation
428
+
is interested in. You may wish to use {! Mask.check} on the returned {!Statx.t} to
429
+
verify the field has actually been filled in with a sensible value first.
430
+
In general, the kernel never refused values specified in the mask, but may choose
431
+
to not set the mask in the returned buffer from {!statx}. *)
432
+
281
433
include FLAGS
282
434
283
435
val type' : t
436
+
(** Retrieve the kind of file field, accessible afterwards via {!val:Statx.kind}. *)
437
+
284
438
val mode : t
439
+
(** Retrieve the permissions field, accessible afterwards via {!Statx.perm}. *)
440
+
285
441
val nlink : t
442
+
(** Retrieve the number of links field, accessible afterwards via {!Statx.nlink}. *)
443
+
286
444
val uid : t
445
+
(** Retrieve the user ID field, accessible afterwards via {!Statx.uid}. *)
446
+
287
447
val gid : t
448
+
(** Retrieve the group ID field, accessible afterwards via {!Statx.gid}. *)
449
+
288
450
val atime : t
451
+
(** Retrieve the last access field, accessible afterwards
452
+
via {!atime_nsec} and {!atime_sec}. *)
453
+
289
454
val mtime : t
455
+
(** Retrieve the last modification field, accessible afterwards
456
+
via {!mtime_nsec} and {!mtime_sec}. *)
457
+
290
458
val ctime : t
459
+
(** Retrieve the last status change field, accessible afterwards
460
+
via {!ctime_nsec} and {!ctime_sec}. *)
461
+
291
462
val ino : t
463
+
(** Retrieve the inode number, accessible afterwards via {!Statx.ino}. *)
464
+
292
465
val size : t
466
+
(** Retrieve the total size in bytes, accessible afterwards via {!Statx.size}. *)
467
+
293
468
val blocks : t
294
-
val basic_stats : t (** All of the above flags. *)
469
+
(** Retrieve the number of 512B blocks allocate, accessible afterwards via {!Statx.blocks}. *)
470
+
471
+
val basic_stats : t
472
+
(** Retrieve all of the above flags. *)
295
473
296
474
val btime : t
475
+
(** Retrieve the birthtime field, accessible afterwards via {!btime_nsec} and {!btime_sec}. *)
297
476
298
477
val mnt_id : t
299
-
(** As of Linux 5.8 *)
478
+
(** @since Linux 5.8 *)
300
479
301
480
val dioalign : t
302
-
(** As of Linux 6.1 *)
481
+
(** @since Linux 6.1 *)
303
482
304
483
val check : Int64.t -> t -> bool
305
484
(** [check mask t] checks if [t] is set in [mask]. *)
306
485
end
307
-
308
-
(** You may wish to use {! Mask.check} to verify the field has actually
309
-
been returned with a sensible value first. *)
310
486
311
487
val blksize : t -> Int64.t
312
488
val attributes : t -> Int64.t