The unpac monorepo manager self-hosting as a monorepo using unpac
Merge pull request #126 from avsm/prep-27
prepare v2.7.0 release, improve docstrings
authored by
Anil Madhavapeddy
and committed by
GitHub
cbd959cf
7875253a
+225
-36
+15
-1
CHANGES.md
+15
-1
CHANGES.md
···
1
+
## v2.7.0
2
+
3
+
- Fix use-after-free data race in CQE handlers (@avsm #124, reported #123 by @polytypic).
4
+
5
+
- Add socket bind and listen operations (@avsm #118).
6
+
7
+
- Update liburing to 2.7 (@avsm #118).
8
+
9
+
- Add `Uring.Setup_flags` module (@talex5 #122).
10
+
11
+
- Clean up configurator code and update primitives.h (@talex5 #121).
12
+
13
+
- Add `mkdirat` operation (@patricoferris #120).
14
+
1
15
## v0.9
2
16
3
17
- Fix statx constant fallback values, and fix with musl 1.2.5 (@alyssais #114).
4
18
5
-
- Add Uring.sqe_ready (@talex5 #115).
19
+
- Add `Uring.sqe_ready` (@talex5 #115).
6
20
7
21
## v0.8
8
22
+210
-35
lib/uring/uring.mli
+210
-35
lib/uring/uring.mli
···
84
84
val create : ?flags:Setup_flags.t -> ?polling_timeout:int -> queue_depth:int -> unit -> 'a t
85
85
(** [create ~queue_depth] will return a fresh Io_uring structure [t].
86
86
Initially, [t] has no fixed buffer. Use {!set_fixed_buffer} if you want one.
87
+
88
+
The [queue_depth] determines the size of the submission queue (SQ) and completion
89
+
queue (CQ) rings. The kernel may round this up to the next power of 2. The actual
90
+
size allocated can be checked with {!queue_depth}.
91
+
92
+
@param flags Setup flags to configure ring behavior (see {!Setup_flags})
87
93
@param polling_timeout If given, use polling mode with the given idle timeout (in ms).
88
-
This requires privileges. *)
94
+
This requires elevated privileges and enables {!Setup_flags.iopoll}.
95
+
@raise Unix.Unix_error if the io_uring_setup system call fails *)
89
96
90
97
val queue_depth : 'a t -> int
91
98
(** [queue_depth t] returns the total number of submission slots for the uring [t] *)
92
99
93
100
val exit : 'a t -> unit
94
101
(** [exit t] will shut down the uring [t]. Any subsequent requests will fail.
95
-
@raise Invalid_argument if there are any requests in progress *)
102
+
103
+
This closes the io_uring file descriptor and unmaps the memory rings.
104
+
After calling this, the ring cannot be used again.
105
+
106
+
@raise Invalid_argument if there are any requests in progress. Check with
107
+
{!active_ops} to ensure all operations have completed. *)
96
108
97
109
(** {2 Fixed buffers}
98
110
···
103
115
val set_fixed_buffer : 'a t -> Cstruct.buffer -> (unit, [> `ENOMEM]) result
104
116
(** [set_fixed_buffer t buf] sets [buf] as the fixed buffer for [t].
105
117
106
-
You will normally want to wrap this with {!Region.alloc} or similar
107
-
to divide the buffer into chunks.
118
+
Fixed buffers allow zero-copy I/O operations using {!read_fixed} and {!write_fixed}.
119
+
The kernel pins the buffer in memory, avoiding the need to map user pages for each I/O.
120
+
You will normally want to wrap this with {!Region.alloc} or similar to divide the
121
+
buffer into chunks.
108
122
109
123
If [t] already has a buffer set, the old one will be removed.
110
124
111
-
Returns [`ENOMEM] if insufficient kernel resources are available
112
-
or the caller's RLIMIT_MEMLOCK resource limit would be exceeded.
113
-
125
+
@return [Ok ()] on success, or [Error `ENOMEM] if:
126
+
- Insufficient kernel resources are available
127
+
- The caller's RLIMIT_MEMLOCK resource limit would be exceeded
128
+
- The buffer is too large to pin in memory
114
129
@raise Invalid_argument if there are any requests in progress *)
115
130
116
131
val buf : 'a t -> Cstruct.buffer
···
121
136
122
137
val noop : 'a t -> 'a -> 'a job option
123
138
(** [noop t d] submits a no-op operation to uring [t]. The user data [d] will be
124
-
returned by {!wait} or {!peek} upon completion. *)
139
+
returned by {!wait} or {!get_cqe_nonblocking} upon completion.
140
+
141
+
This operation does nothing but can be useful for testing the ring, waking up
142
+
a thread waiting on completions, or as a barrier when used with IO_LINK.
143
+
The completion will have [result = 0] on success.
144
+
145
+
@return [None] if the submission queue is full; otherwise [Some job] *)
125
146
126
147
(** {2 Timeout} *)
127
148
···
133
154
val timeout: ?absolute:bool -> 'a t -> clock -> int64 -> 'a -> 'a job option
134
155
(** [timeout t clock ns d] submits a timeout request to uring [t].
135
156
136
-
[absolute] denotes how [clock] and [ns] relate to one another. Default value is [false]
157
+
The timeout will trigger after the specified time has elapsed. When the timeout
158
+
expires, the completion's [result] will be negative with an [ETIME] error indicating
159
+
timeout. The timeout can be cancelled using {!cancel} before it triggers.
137
160
138
-
[ns] is the timeout time in nanoseconds *)
161
+
@param absolute If [false] (default), [ns] is relative to the current time.
162
+
If [true], [ns] is an absolute time value according to [clock]
163
+
@param clock The clock source: {!Boottime} (suspend-aware) or {!Realtime} (wall-clock)
164
+
@param ns The timeout duration in nanoseconds (relative) or absolute time
165
+
@return [None] if the submission queue is full; otherwise [Some job] *)
139
166
140
167
(** Flags that can be passed to {!openat2}. *)
141
168
module Open_flags : sig
···
336
363
337
364
val poll_add : 'a t -> Unix.file_descr -> Poll_mask.t -> 'a -> 'a job option
338
365
(** [poll_add t fd mask d] will submit a [poll(2)] request to uring [t].
339
-
It completes and returns [d] when an event in [mask] is ready on [fd]. *)
366
+
It completes and returns [d] when an event in [mask] is ready on [fd].
367
+
This is an asynchronous version of poll(2). The operation will complete when
368
+
any of the requested events occur on the file descriptor.
369
+
370
+
The completion's [result] field contains:
371
+
- On success: The bitwise OR of events that occurred (always a subset of [mask])
372
+
- On error: A negative error code
373
+
374
+
@param fd File descriptor to monitor
375
+
@param mask Bitwise OR of events to monitor (see {!Poll_mask})
376
+
@return [None] if the submission queue is full; otherwise [Some job] *)
340
377
341
378
type offset := Optint.Int63.t
342
379
(** For files, give the absolute offset, or use [Optint.Int63.minus_one] for the current position.
···
346
383
(** [read t ~file_offset fd buf d] will submit a [read(2)] request to uring [t].
347
384
It reads from absolute [file_offset] on the [fd] file descriptor and writes
348
385
the results into the memory pointed to by [buf]. The user data [d] will
349
-
be returned by {!wait} or {!peek} upon completion. *)
386
+
be returned by {!wait} or {!get_cqe_nonblocking} upon completion.
387
+
388
+
The completion's [result] field contains the number of bytes read on success,
389
+
0 for end-of-file, or a negative error code on failure.
390
+
391
+
@param file_offset Use {!Optint.Int63.minus_one} for current file position,
392
+
or a specific offset for files. For sockets, use {!Optint.Int63.zero}
393
+
@return [None] if the submission queue is full; otherwise [Some job] *)
350
394
351
395
val write : 'a t -> file_offset:offset -> Unix.file_descr -> Cstruct.t -> 'a -> 'a job option
352
396
(** [write t ~file_offset fd buf d] will submit a [write(2)] request to uring [t].
353
397
It writes to absolute [file_offset] on the [fd] file descriptor from the
354
398
the memory pointed to by [buf]. The user data [d] will be returned by
355
-
{!wait} or {!peek} upon completion. *)
399
+
{!wait} or {!get_cqe_nonblocking} upon completion.
400
+
401
+
The completion's [result] field contains the number of bytes written on success,
402
+
or a negative error code on failure. Note that a short write (less than the
403
+
buffer size) is not an error.
404
+
405
+
@param file_offset Use {!Optint.Int63.minus_one} for current file position,
406
+
or a specific offset for files. For sockets, use {!Optint.Int63.zero}
407
+
@return [None] if the submission queue is full; otherwise [Some job] *)
356
408
357
409
val iov_max : int
358
-
(** The maximum length of the list that can be passed to [readv] and similar. *)
410
+
(** The maximum length of the list that can be passed to {!readv} and {!writev}. *)
359
411
360
412
val readv : 'a t -> file_offset:offset -> Unix.file_descr -> Cstruct.t list -> 'a -> 'a job option
361
413
(** [readv t ~file_offset fd iov d] will submit a [readv(2)] request to uring [t].
362
414
It reads from absolute [file_offset] on the [fd] file descriptor and writes
363
415
the results into the memory pointed to by [iov]. The user data [d] will
364
-
be returned by {!wait} or {!peek} upon completion.
416
+
be returned by {!wait} or {!get_cqe_nonblocking} upon completion.
417
+
418
+
This performs a vectored read, reading data into multiple buffers in a single
419
+
operation. The completion's [result] field contains the total number of bytes
420
+
read across all buffers, or a negative error code.
365
421
366
-
Requires [List.length iov <= Uring.iov_max] *)
422
+
@param file_offset File offset (see {!type:offset} for special values)
423
+
@param iov List of buffers to read into
424
+
@return [None] if the submission queue is full; otherwise [Some job]
425
+
@raise Invalid_argument if [List.length iov > Uring.iov_max] *)
367
426
368
427
val writev : 'a t -> file_offset:offset -> Unix.file_descr -> Cstruct.t list -> 'a -> 'a job option
369
428
(** [writev t ~file_offset fd iov d] will submit a [writev(2)] request to uring [t].
370
429
It writes to absolute [file_offset] on the [fd] file descriptor from the
371
430
the memory pointed to by [iov]. The user data [d] will be returned by
372
-
{!wait} or {!peek} upon completion.
431
+
{!wait} or {!get_cqe_nonblocking} upon completion.
432
+
433
+
This performs a vectored write, writing data from multiple buffers in a single
434
+
operation. The completion's [result] field contains the total number of bytes
435
+
written from all buffers, or a negative error code.
373
436
374
-
Requires [List.length iov <= Uring.iov_max] *)
437
+
@param file_offset File offset (see {!type:offset} for special values)
438
+
@param iov List of buffers to write from
439
+
@return [None] if the submission queue is full; otherwise [Some job]
440
+
@raise Invalid_argument if [List.length iov > Uring.iov_max] *)
375
441
376
442
val read_fixed : 'a t -> file_offset:offset -> Unix.file_descr -> off:int -> len:int -> 'a -> 'a job option
377
443
(** [read t ~file_offset fd ~off ~len d] will submit a [read(2)] request to uring [t].
···
395
461
396
462
val splice : 'a t -> src:Unix.file_descr -> dst:Unix.file_descr -> len:int -> 'a -> 'a job option
397
463
(** [splice t ~src ~dst ~len d] will submit a request to copy [len] bytes from [src] to [dst].
398
-
The operation returns the number of bytes transferred, or 0 for end-of-input.
399
-
The result is [EINVAL] if the file descriptors don't support splicing. *)
464
+
465
+
This is a zero-copy data transfer between two file descriptors. At least one
466
+
must be a pipe. Data is moved without copying between kernel and user space.
467
+
468
+
The completion's [result] field contains the number of bytes transferred on success,
469
+
0 for end-of-input, or a negative error code.
470
+
471
+
@param src Source file descriptor (can be a regular file or pipe)
472
+
@param dst Destination file descriptor (can be a regular file or pipe)
473
+
@param len Maximum number of bytes to transfer
474
+
@return [None] if the submission queue is full; otherwise [Some job] *)
400
475
401
476
module Statx : sig
402
477
type t
···
596
671
(or the current directory if [fd] is not given). *)
597
672
598
673
val bind : 'a t -> Unix.file_descr -> Unix.sockaddr -> 'a -> 'a job option
599
-
(** [bind t fd addr d] will submit a request to bind [fd] to [addr]. *)
674
+
(** [bind t fd addr d] will submit a request to bind socket [fd] to network address [addr].
675
+
676
+
This is an asynchronous version of bind(2). The socket should typically be created
677
+
with [Unix.SOCK_NONBLOCK] to work well with io_uring. The completion will have
678
+
[result = 0] on success, or a negative error code on failure.
679
+
680
+
@return [None] if the submission queue is full; otherwise [Some job] *)
600
681
601
682
val listen : 'a t -> Unix.file_descr -> int -> 'a -> 'a job option
602
-
(** [listen t fd backlog d] will submit a request to listen on [fd] with [backlog] maximum pending connections. *)
683
+
(** [listen t fd backlog d] will submit a request to mark socket [fd] as passive,
684
+
ready to accept incoming connections.
685
+
686
+
This is an asynchronous version of listen(2). The [backlog] parameter defines
687
+
the maximum length of the queue of pending connections. If a connection request
688
+
arrives when the queue is full, the client may receive an ECONNREFUSED error.
689
+
The completion will have [result = 0] on success.
690
+
691
+
@param fd Socket file descriptor (must be already bound with {!bind})
692
+
@param backlog Maximum number of pending connections (often capped by system limits)
693
+
@return [None] if the submission queue is full; otherwise [Some job]
694
+
@raise Invalid_argument if [fd] is not a socket *)
603
695
604
696
val connect : 'a t -> Unix.file_descr -> Unix.sockaddr -> 'a -> 'a job option
605
-
(** [connect t fd addr d] will submit a request to connect [fd] to [addr]. *)
697
+
(** [connect t fd addr d] will submit a request to connect socket [fd] to [addr].
698
+
699
+
This is an asynchronous version of connect(2). For non-blocking sockets,
700
+
the operation may initially return an error indicating the connection is
701
+
in progress, then completes with [result = 0] when established or a
702
+
negative error code on failure.
703
+
704
+
@return [None] if the submission queue is full; otherwise [Some job] *)
606
705
607
706
(** Holder for the peer's address in {!accept}. *)
608
707
module Sockaddr : sig
···
615
714
val accept : 'a t -> Unix.file_descr -> Sockaddr.t -> 'a -> 'a job option
616
715
(** [accept t fd addr d] will submit a request to accept a new connection on [fd].
617
716
The new FD will be configured with [SOCK_CLOEXEC].
618
-
The remote address will be stored in [addr]. *)
717
+
The remote address will be stored in [addr].
718
+
719
+
This is an asynchronous version of accept4(2) with SOCK_CLOEXEC flag.
720
+
The completion's [result] field contains the new file descriptor on success,
721
+
or a negative error code on failure.
722
+
723
+
@param fd Listening socket (must have called {!listen} first)
724
+
@param addr Pre-allocated storage for the peer address (create with {!Sockaddr.create})
725
+
@return [None] if the submission queue is full; otherwise [Some job] *)
619
726
620
727
val close : 'a t -> Unix.file_descr -> 'a -> 'a job option
728
+
(** [close t fd d] will submit a request to close file descriptor [fd].
729
+
730
+
This is an asynchronous version of close(2). The completion's [result]
731
+
field will be 0 on success or a negative error code.
732
+
733
+
Note: Even on error, the file descriptor is considered closed and should
734
+
not be used again. The descriptor will not be reused until the operation
735
+
completes.
736
+
737
+
@return [None] if the submission queue is full; otherwise [Some job] *)
621
738
622
739
val cancel : 'a t -> 'a job -> 'a -> 'a job option
623
740
(** [cancel t job d] submits a request to cancel [job].
624
-
The cancel job itself returns 0 on success, or [ENOTFOUND]
625
-
if [job] had already completed by the time the kernel processed the cancellation request.
626
-
@raise Invalid_argument if the job has already been returned by e.g. {!wait}. *)
741
+
742
+
Cancellation is asynchronous - the original operation may still complete
743
+
before the cancellation takes effect. Both the original operation and the
744
+
cancel operation will generate completion events.
745
+
746
+
@param job The job handle returned when the operation was submitted
747
+
@return [None] if the submission queue is full; otherwise [Some cancel_job]
748
+
@raise Invalid_argument if the job has already been collected by {!wait} or {!get_cqe_nonblocking} *)
627
749
628
750
module Msghdr : sig
629
751
type t
···
645
767
(** [send_msg t fd buffs d] will submit a [sendmsg(2)] request. The [Msghdr] will be constructed
646
768
from the FDs ([fds]), address ([dst]) and buffers ([buffs]).
647
769
648
-
Requires [List.length buffs <= Uring.iov_max]
770
+
This is useful for:
771
+
- Sending to unconnected sockets (UDP) with [dst]
772
+
- Sending file descriptors over Unix domain sockets with [fds]
773
+
- Scatter-gather I/O with multiple buffers
649
774
650
-
@param dst Destination address.
651
-
@param fds Extra file descriptors to attach to the message. *)
775
+
The completion's [result] field contains the number of bytes sent on success,
776
+
or a negative error code.
777
+
778
+
@param dst Destination address for unconnected sockets
779
+
@param fds File descriptors to send via SCM_RIGHTS (Unix domain sockets only)
780
+
@return [None] if the submission queue is full; otherwise [Some job]
781
+
@raise Invalid_argument if [List.length buffs > Uring.iov_max] *)
652
782
653
783
val recv_msg : 'a t -> Unix.file_descr -> Msghdr.t -> 'a -> 'a job option
654
784
(** [recv_msg t fd msghdr d] will submit a [recvmsg(2)] request. If the request is
655
-
successful then the [msghdr] will contain the sender address and the data received. *)
785
+
successful then the [msghdr] will contain the sender address and the data received.
786
+
787
+
This is useful for:
788
+
- Receiving from unconnected sockets (UDP) - sender address is stored
789
+
- Receiving file descriptors over Unix domain sockets
790
+
- Scatter-gather I/O with multiple buffers
791
+
792
+
The completion's [result] field contains the number of bytes received on success,
793
+
or a negative error code. Use {!Msghdr.get_fds} to retrieve any received file
794
+
descriptors.
795
+
796
+
@param msghdr Pre-allocated message header created with {!Msghdr.create}
797
+
@return [None] if the submission queue is full; otherwise [Some job] *)
656
798
657
799
val fsync : 'a t -> ?off:int64 -> ?len:int -> Unix.file_descr -> 'a -> 'a job option
658
800
(** [fsync t ?off ?len fd d] will submit an [fsync(2)] request, with the optional
659
801
offset [off] and length [len] specifying the subset of the file to perform the
660
-
synchronisation on. *)
802
+
synchronisation on.
803
+
804
+
This ensures that all file data and metadata are durably stored on disk.
805
+
The completion's [result] field will be 0 on success or a negative error code.
806
+
807
+
@param off Starting offset for sync range (requires kernel 5.2+)
808
+
@param len Length of range to sync; if both [off] and [len] are given,
809
+
only that range is synced (requires kernel 5.2+)
810
+
@return [None] if the submission queue is full; otherwise [Some job] *)
661
811
662
812
val fdatasync : 'a t -> ?off:int64 -> ?len:int -> Unix.file_descr -> 'a -> 'a job option
663
813
(** [fdatasync t ?off ?len fd d] will submit an [fdatasync(2)] request, with the optional
664
814
offset [off] and length [len] specifying the subset of the file to perform the
665
-
synchronisation on. *)
815
+
synchronisation on.
816
+
817
+
Like {!fsync} but only ensures file data (not metadata) is durably stored.
818
+
This can be more efficient when file metadata (permissions, timestamps) hasn't changed.
819
+
The completion's [result] field will be 0 on success or a negative error code.
820
+
821
+
@param off Starting offset for sync range (requires kernel 5.2+)
822
+
@param len Length of range to sync
823
+
@return [None] if the submission queue is full; otherwise [Some job] *)
666
824
667
825
(** {2 Probing}
668
826
···
704
862
705
863
val register_eventfd : 'a t -> Unix.file_descr -> unit
706
864
(** [register_eventfd t fd] will register an eventfd to the the uring [t].
707
-
See documentation for io_uring_register_eventfd *)
865
+
866
+
When a completion event is posted to the CQ ring, the eventfd will be signaled.
867
+
This allows integration with event loops like epoll/select. The eventfd should
868
+
be created with [Unix.eventfd] or similar.
869
+
870
+
Only one eventfd can be registered per ring. Registering a new one replaces
871
+
the previous registration.
872
+
873
+
@param fd An eventfd file descriptor
874
+
@raise Unix.Unix_error on registration failure *)
708
875
709
876
val error_of_errno : int -> Unix.error
710
877
(** [error_of_errno e] converts the error code [abs e] to a Unix error type. *)
711
878
712
879
val active_ops : _ t -> int
713
880
(** [active_ops t] returns the number of operations added to the ring (whether submitted or not)
714
-
for which the completion event has not yet been collected. *)
881
+
for which the completion event has not yet been collected.
882
+
883
+
This is useful for:
884
+
- Ensuring all operations complete before calling {!exit}
885
+
- Monitoring ring utilization
886
+
- Detecting potential ring overflow conditions
887
+
888
+
The count includes operations that are queued but not submitted, submitted
889
+
but not completed, and completed but not collected via {!wait} or {!get_cqe_nonblocking}. *)
715
890
716
891
val sqe_ready : _ t -> int
717
892
(** [sqe_ready t] is the number of unconsumed (if SQPOLL) or unsubmitted entries in the SQ ring. *)