From 9299ff7e775bb6311af09a02f43745bfb7760fae Mon Sep 17 00:00:00 2001 From: Mathieu Barbin Date: Sun, 5 Jan 2025 18:44:42 +0100 Subject: [PATCH 1/4] Fix doc section id --- lib/miou.mli | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/miou.mli b/lib/miou.mli index eea1964..d97996e 100644 --- a/lib/miou.mli +++ b/lib/miou.mli @@ -332,7 +332,7 @@ Exception: Miou.Still_has_children. ]} - {4:rule-2 Rule 2, only await for direct children.} + {4:rule_2 Rule 2, only await for direct children.} You can only await for your direct children. Transferring a promise to another task so that it can await for it is illegal: @@ -682,7 +682,7 @@ val care : 'a orphans -> 'a t option option that promise in an orphanage. So, if [care] is used elsewhere than in the promise, an exception is raised to warn the user of a misuse of [care]. Indeed, the child returned by care can only be awaited ({!await}) by its - direct parent (in reference to {{!section:rule-2}our second rule}). *) + direct parent (in reference to {{!section:rule_2}our second rule}). *) val length : _ orphans -> int (** [length orphans] returns the number of remaining tasks. *) From 9642464d47e1ff5d44ee7b6dd16b1b1c9012d47d Mon Sep 17 00:00:00 2001 From: Mathieu Barbin Date: Sun, 5 Jan 2025 18:45:25 +0100 Subject: [PATCH 2/4] Fix doc links warnings --- lib/miou.mli | 6 +++--- lib/miou_state.mli | 11 ++++++----- lib/miou_unix.mli | 18 +++++++++--------- lib/miou_vector.mli | 10 +++++----- 4 files changed, 23 insertions(+), 22 deletions(-) diff --git a/lib/miou.mli b/lib/miou.mli index d97996e..efcbcee 100644 --- a/lib/miou.mli +++ b/lib/miou.mli @@ -420,8 +420,8 @@ The advantage of making suspension points local to domains is that the domain is solely responsible for these points and there are no inter-domain transfer mechanisms for managing system events. For the example, - {!module:Domain.DLS} can be used for a table of current events in each - domain. + {!module:Stdlib.Domain.DLS} can be used for a table of current events in + each domain. {[ let get, set = @@ -1172,7 +1172,7 @@ module Mutex : sig will restart. The mutex must have been previously locked by the thread that calls {!val:unlock}. - @raise Sysy_error + @raise Sys_error was not raised when unlocking an unlocked mutex or when unlocking a mutex from a different task. *) diff --git a/lib/miou_state.mli b/lib/miou_state.mli index 16f93a3..3c46d38 100644 --- a/lib/miou_state.mli +++ b/lib/miou_state.mli @@ -16,7 +16,7 @@ type error = exn * Printexc.raw_backtrace In the case of a suspension, the user can "continue" the execution via what is expected by the associated effect. Note that {!val:once} can only be used {b once} on a given value {!type:t} (otherwise, an exception - {!exception:Continuation_already_resumed} is raised by OCaml). *) + {!exception:Effect.Continuation_already_resumed} is raised by OCaml). *) type 'a t = private | Finished of ('a, error) result | Suspended : ('a, 'b) continuation * 'a Effect.t -> 'b t @@ -60,8 +60,9 @@ val once : perform:perform -> 'a t -> 'a t val fail : backtrace:Printexc.raw_backtrace -> exn:exn -> 'a t -> 'a t (** [fail ~exn state] discontinues the given state with the given exception. It always return [Finished (Error exn)]. If the given state was already resumed - elsewhere, this function traps the exception [Continuation_already_resumed] - and return [Finished (Error exn)]. *) + elsewhere, this function traps the exception + {!exception:Effect.Continuation_already_resumed} and return + [Finished (Error exn)]. *) val pure : ('a, error) result -> 'a t (** [pure value] returns [Finished value]. *) @@ -72,8 +73,8 @@ val run : quanta:int -> perform:perform -> 'a t -> 'a t nothing), even though there may be a few {i quanta} left, the function returns the last state obtained. - The same applies to {!val:yield}, except that the continuation has burnt - itself out. In other words, {!val:yield} is equivalent to + The same applies to {!val:Miou.yield}, except that the continuation has + burnt itself out. In other words, {!val:Miou.yield} is equivalent to [send (); interrupt] but costs only one {i quanta}. *) (**/**) diff --git a/lib/miou_unix.mli b/lib/miou_unix.mli index d252f61..f092543 100644 --- a/lib/miou_unix.mli +++ b/lib/miou_unix.mli @@ -69,10 +69,10 @@ val read : file_descr -> ?off:int -> ?len:int -> bytes -> int [0]). It returns the actual number of characters read, between 0 and [len] (inclusive). - @raise Unix_error + @raise Unix.Unix_error raised by the system call {!val:Unix.read}. The function handles - {!val:Unix.EINTR}, {!val:Unix.EAGAIN} and {!val:Unix.EWOULDBLOCK} - exceptions and redo the system call. + {!constructor:Unix.EINTR}, {!constructor:Unix.EAGAIN} and + {!constructor:Unix.EWOULDBLOCK} exceptions and redo the system call. @raise Invalid_argument if [off] and [len] do not designate a valid range of [buf] *) @@ -83,10 +83,10 @@ val really_read : file_descr -> ?off:int -> ?len:int -> bytes -> unit in byte sequence [buf], starting at position [off] in [buf] (defaults to [0]). If [len = 0], [really_read] does nothing. - @raise Unix_error + @raise Unix.Unix_error raised by the system call {!val:Unix.read}. The function handles - {!val:Unix.EINTR}, {!val:Unix.EAGAIN} and {!val:Unix.EWOULDBLOCK} - exceptions and redo the system call. + {!constructor:Unix.EINTR}, {!constructor:Unix.EAGAIN} and + {!constructor:Unix.EWOULDBLOCK} exceptions and redo the system call. @raise End_of_file if {!val:Unix.read} returns [0] before [len] characters have been read. @@ -99,10 +99,10 @@ val write : file_descr -> ?off:int -> ?len:int -> string -> unit [String.length str - off]) from byte sequence [buf], starting at offset [off] (defaults to [0]), to the given file-descriptor [fd]. - @raise Unix_error + @raise Unix.Unix_error raised by the system call {!val:Unix.read}. The function handles - {!val:Unix.EINTR}, {!val:Unix.EAGAIN} and {!val:Unix.EWOULDBLOCK} - exceptions and redo the system call. + {!constructor:Unix.EINTR}, {!constructor:Unix.EAGAIN} and + {!constructor:Unix.EWOULDBLOCK} exceptions and redo the system call. @raise Invalid_argument if [off] and [len] do not designate a valid range of [buf] *) diff --git a/lib/miou_vector.mli b/lib/miou_vector.mli index 6bca401..a3ac9c3 100644 --- a/lib/miou_vector.mli +++ b/lib/miou_vector.mli @@ -28,9 +28,9 @@ Vectors provide an efficient implementation of stacks, with a better locality of reference than list-based implementations (such as standard library {!Stack}). A stack interface is provided, - similar to that of {!Stack} (though {!Vector.push} have arguments + similar to that of {!Stack} (though {!push} have arguments in the other way round). Inserting [n] elements with - {!Vector.push} has overall complexity O(n) i.e. each insertion has + {!push} has overall complexity O(n) i.e. each insertion has amortized constant time complexity. *) (*@ use List *) @@ -219,7 +219,7 @@ val map : dummy:'b -> 'a t -> ('a -> 'b) -> 'b t ensures forall i. 0 <= i < length a1.view -> a2.view[i] = f a1.view[i] *) val mapi : dummy:'b -> 'a t -> (int -> 'a -> 'b) -> 'b t -(** Same as {!Vector.map}, but the +(** Same as {!map}, but the function is applied to the index of the element as first argument, and the element itself as second argument. @@ -264,7 +264,7 @@ val iter : ('a -> unit) -> 'a t -> unit *) val iteri : (int -> 'a -> unit) -> 'a t -> unit -(** Same as {!Vector.iter}, but the +(** Same as {!iter}, but the function is applied to the index of the element as first argument, and the element itself as second argument. *) (*@ iteri f a @@ -272,7 +272,7 @@ val iteri : (int -> 'a -> unit) -> 'a t -> unit (** {2 Stack interface} - Contrary to standard library's {Stack}, module {Vector} uses less space + Contrary to standard library's {!Stack}, module [Vector] uses less space (between N and 2N words, instead of 3N) and has better data locality. *) val push: 'a t -> 'a -> unit From 8531415235012501b8d0d1662878c522f32aaeff Mon Sep 17 00:00:00 2001 From: Mathieu Barbin Date: Sun, 5 Jan 2025 18:45:52 +0100 Subject: [PATCH 3/4] Document exn [On_cancellation_raised] as uncatchable --- lib/miou.mli | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/miou.mli b/lib/miou.mli index efcbcee..456cf9d 100644 --- a/lib/miou.mli +++ b/lib/miou.mli @@ -1143,8 +1143,8 @@ val protect : [finally] raises an exception, then the exception {!Fun.Finally_raised} is raised instead. In the case of a cancellation, it invokes [finally ()] and then [on_cancellation ()] before the deletion of [fn ()]. If - [on_cancellation ()] raises an exception, then the exception - {!On_cancellation_raised} is raised instead. + [on_cancellation ()] raises an exception, then the "uncatchable" exception + [On_cancellation_raised] is raised instead. [on_cancellation] must {b not} use any effects. Using effects suspends execution and, in the case of cancellation, anything after the effect will From 39e3cdac41efd10117936dab43bb05ab8f6602a0 Mon Sep 17 00:00:00 2001 From: Calascibetta Romain Date: Tue, 7 Jan 2025 20:48:27 +0100 Subject: [PATCH 4/4] Yield, on miou_state.mli, refers to Operation.yield --- lib/miou_state.mli | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/miou_state.mli b/lib/miou_state.mli index 3c46d38..6b6103b 100644 --- a/lib/miou_state.mli +++ b/lib/miou_state.mli @@ -73,8 +73,8 @@ val run : quanta:int -> perform:perform -> 'a t -> 'a t nothing), even though there may be a few {i quanta} left, the function returns the last state obtained. - The same applies to {!val:Miou.yield}, except that the continuation has - burnt itself out. In other words, {!val:Miou.yield} is equivalent to + The same applies to {!val:Operation.yield}, except that the continuation has + burnt itself out. In other words, {!val:Operation.yield} is equivalent to [send (); interrupt] but costs only one {i quanta}. *) (**/**)