Skip to content

Commit f03bb69

Browse files
committed
Note and test that certain operations are not cancelable
This can help to simplify and optimize code in some cases as these operations are often used in finalizers.
1 parent e0ba28b commit f03bb69

File tree

3 files changed

+39
-3
lines changed

3 files changed

+39
-3
lines changed

lib/picos_std.sync/picos_std_sync.mli

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,8 @@ module Mutex : sig
5959
val unlock : ?checked:bool -> t -> unit
6060
(** [unlock mutex] unlocks the mutex.
6161
62+
ℹ️ This operation is not cancelable.
63+
6264
@raise Sys_error if the mutex was locked by another fiber. If
6365
[~checked:false] was specified for some previous operation on the mutex
6466
the exception may or may not be raised. *)
@@ -128,6 +130,8 @@ module Semaphore : sig
128130
val release : t -> unit
129131
(** [release semaphore] increments the count of the semaphore.
130132
133+
ℹ️ This operation is not cancelable.
134+
131135
@raise Sys_error in case the count would overflow. *)
132136

133137
val acquire : t -> unit
@@ -154,7 +158,9 @@ module Semaphore : sig
154158
[initial] is [true] and count of [0] otherwise. *)
155159

156160
val release : t -> unit
157-
(** [release semaphore] sets the count of the semaphore to [1]. *)
161+
(** [release semaphore] sets the count of the semaphore to [1].
162+
163+
ℹ️ This operation is not cancelable. *)
158164

159165
val acquire : t -> unit
160166
(** [acquire semaphore] waits until the count of the semaphore is [1] and
@@ -259,6 +265,8 @@ module Latch : sig
259265
invalid_arg "zero count"
260266
]}
261267
268+
ℹ️ This operation is not cancelable.
269+
262270
@raise Invalid_argument in case the count of the latch is zero. *)
263271

264272
val try_incr : t -> bool
@@ -309,7 +317,9 @@ module Ivar : sig
309317
(** [try_poison_at ivar exn bt] attempts to poison the incremental variable
310318
with the specified exception and backtrace. Returns [true] on success and
311319
[false] in case the variable had already been poisoned or assigned a
312-
value. *)
320+
value.
321+
322+
ℹ️ This operation is not cancelable. *)
313323

314324
val try_poison : ?callstack:int -> 'a t -> exn -> bool
315325
(** [try_poison ivar exn] is equivalent to
@@ -364,7 +374,9 @@ module Stream : sig
364374
val poison_at : 'a t -> exn -> Printexc.raw_backtrace -> unit
365375
(** [poison_at stream exn bt] marks the stream as poisoned at the current
366376
position, which means that subsequent attempts to {!push} to the [stream]
367-
will raise the given exception with backtrace. *)
377+
will raise the given exception with backtrace.
378+
379+
ℹ️ This operation is not cancelable. *)
368380

369381
val poison : ?callstack:int -> 'a t -> exn -> unit
370382
(** [poison stream exn] is equivalent to

test/dune

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,7 @@
5959
(run %{test} -- "Lazy" 1)
6060
(run %{test} -- "Semaphore" 0)
6161
(run %{test} -- "Semaphore" 1)
62+
(run %{test} -- "Non-cancelable ops" 0)
6263
(run %{test} -- "Mutex and Condition" 0)
6364
(run %{test} -- "Mutex and Condition" 1)
6465
(run %{test} -- "Mutex and Condition" 2))))

test/test_sync.ml

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -287,6 +287,26 @@ let test_event_basics () =
287287
| exception Exit -> ()
288288
end
289289

290+
let test_non_cancelable_ops () =
291+
Test_scheduler.run @@ fun () ->
292+
let ivar = Ivar.create () in
293+
let stream = Stream.create () in
294+
let latch = Latch.create 1 in
295+
let mutex = Mutex.create () in
296+
let counting = Semaphore.Counting.make 0 in
297+
let binary = Semaphore.Binary.make false in
298+
Flock.join_after @@ fun () ->
299+
Mutex.lock ~checked:(Random.bool ()) mutex;
300+
Flock.terminate ();
301+
try
302+
Ivar.poison ivar Exit;
303+
Stream.poison stream Exit;
304+
Latch.decr latch;
305+
Mutex.unlock ~checked:(Random.bool ()) mutex;
306+
Semaphore.Counting.release counting;
307+
Semaphore.Binary.release binary
308+
with _ -> assert false
309+
290310
let () =
291311
try
292312
[
@@ -308,6 +328,9 @@ let () =
308328
Alcotest.test_case "cancelation" `Quick test_lazy_cancelation;
309329
] );
310330
("Event", [ Alcotest.test_case "basics" `Quick test_event_basics ]);
331+
( "Non-cancelable ops",
332+
[ Alcotest.test_case "are not canceled" `Quick test_non_cancelable_ops ]
333+
);
311334
]
312335
|> Alcotest.run ~and_exit:false "Picos_sync";
313336
!msgs |> List.iter (Printf.eprintf "%s\n%!")

0 commit comments

Comments
 (0)