From 221408cb345165ead334cbb4dbf3d39aa8e9d066 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Sat, 27 Jun 2020 13:55:09 -0600 Subject: [PATCH] reference: document possibility of spurious CAS failures An operation like `box-cas!` can fail spuriously on some platforms, such as ARM processors. Mention that in the documentation. The `box-cas!` and similar implementations could instead retry on spurious failure, and that would avoid potential problems with code tested on x86, where there's no spurious failure. In this case, though, it seems better to stick with the existing behavior and stay closer to the machine operation. --- pkgs/racket-doc/scribblings/reference/data.scrbl | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/pkgs/racket-doc/scribblings/reference/data.scrbl b/pkgs/racket-doc/scribblings/reference/data.scrbl index 5d9f8fab95..74b45cbd1d 100644 --- a/pkgs/racket-doc/scribblings/reference/data.scrbl +++ b/pkgs/racket-doc/scribblings/reference/data.scrbl @@ -120,10 +120,16 @@ boxes that are not @tech{impersonators}. @racketblock[ (and (eq? old (unbox loc)) (set-box! loc new) #t)] + except that @racket[box-cas!] can spuriously fail on some platforms. + That is, with low probability, the result can be @racket[#f] with the + value in @racket[box] left unchanged, even if @racket[box] contains + @racket[old]. + When Racket is compiled with support for @tech{futures}, - @racket[box-cas!] uses a hardware @emph{compare and set} operation. - Uses of @racket[box-cas!] be performed safely in a @tech{future} (i.e., - allowing the future thunk to continue in parallel). } + @racket[box-cas!] is guaranteed to use a hardware @emph{compare and + set} operation. Uses of @racket[box-cas!] be performed safely in a + @tech{future} (i.e., allowing the future thunk to continue in + parallel).} @; ---------------------------------------------------------------------- @include-section["hashes.scrbl"]