ocaml-multicore / kcas

Software Transactional Memory for OCaml
https://ocaml-multicore.github.io/kcas/
ISC License
108 stars 10 forks source link

[Suggestion] Add some warnings related ref, mutable, IO to README #57

Open sidkshatriya opened 1 year ago

sidkshatriya commented 1 year ago

Add some warnings on avoiding impure code, mutation operations within transactions to the README.md.

Here is some excerpted text written by @polytypic already that is a good start:

(From https://discuss.ocaml.org/t/ann-kcas-and-kcas-data-0-3-0-software-transactional-memory/12085/16)

Yes, when using kcas transactions, one should be aware of the fact that the transaction function may be called many times and transactional shared memory location accesses within the transaction may choose to raise exceptions to force the transaction to be retried later.

To be safe, kcas transactions should typically be pure (no use of refs or mutable, no IO, …). ...

polytypic commented 1 year ago

Just noting that documentation in the mli file that becomes part of the generated manual contains some relevant warnings:

Transactions should generally not perform arbitrary side-effects, because when a transaction is committed it may be attempted multiple times meaning that the side-effects are also performed multiple times. Xt.post_commit can be used to perform an action only once after the transaction has been committed succesfully.

WARNING: To make it clear, the operations provided by the Loc module for accessing individual shared memory locations do not implicitly go through the transaction mechanism and should generally not be used within transactions. There are advanced algorithms where one might, within a transaction, perform operations that do not get recorded into the transaction log. Using such techniques correctly requires expert knowledge and is not recommended for casual users.