First-impression notes on the API

[polytypic]

I guess kcas is still experimental and we can refine the API. I took a quick reading of the API (module signature) and I think it could use some work.

Here are my (non-exhaustive) first-impression notes on the API:

• Overall, on first impression, the API could perhaps use some reorganisation, either to subsections or to submodules, to more clearly separate operations on single refs, safe and unsafe operations on a single ref, and operations on multiple refs.
  • For example, the spec type t is on line 5, then there are other specs, the first introduction form val mk_cas is on line 17. Then there are two unrelated specs, and the first elimination form val commit is on line 29. I would suggest grouping specs on a single abstraction together.
• Why is there both Kcas.cas and Kcas.W1.cas?
  • Answer: W1 could be dropped as it essentially duplicates Atomic.
• The APIs of map and try_map could maybe use polymorphic variants:

  val try_map : 'a ref -> ('a -> 'a option) -> [ `Failed | `Aborted | `Success of 'a ]
  val map : 'a ref -> ('a -> 'a option) -> [ `Aborted | `Success of 'a ]

  (This should not have major negative impact on performance.)
• Backoff measured in milliseconds sounds excessive as modern CPUs can do incredible amount of work in a single millisecond.
• I would drop the separate module type Backoff = sig ... end as one can say module type of Backoff.