[Suggestion] Add some warnings related ref, mutable, IO to README
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, …). ...
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_commitcan 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
Locmodule 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.