Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
sidkshatriya opened this issue May 4, 2023 · 1 comment
Open

Comments

@sidkshatriya
Copy link

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
Copy link
Collaborator

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants