Add a lot more documentation to STM and structure it better #302

1Jajen1 · 2020-11-13T12:38:56Z

So after seeing the rendered api docs for STM I wasn't quite satisfied. It was really hard to see which methods worked on which datatype and what the datatypes actually did.

This hopefully addresses that issue by documenting the datatypes with the methods used to operate on them. It also adds a ton of simple examples and changes/adds a few operator overload methods to be more like the stdlib collections.

Edit: This is 95-99% documentation btw^^ So don't be scared by +2000 here 🙈

1Jajen1 · 2020-11-13T12:40:10Z

Oh and also: Is there a place in the arrow-fx docs sidebar that we can feature STM in? Apidocs is ok-ish but adding it to like datatypes as well would be a bit better imo. Just not sure it fits there.

nomisRev · 2020-11-13T12:58:00Z

@1Jajen1 need to make some time to go through this, but feel free to restructure the Arrow Fx website a bit to make room for STM in the sidebar. Perhaps we need to relocate data types under an Arrow Fx Coroutines specific section?
We might also want to make room for more modules later on in a similar style.

https://github.com/arrow-kt/arrow-site/blob/master/docs/_data/sidebar-fx.yml

1Jajen1 · 2020-11-13T13:08:15Z

We might also want to make room for more modules later on in a similar style.

Likely as this will apply to Stream as well.

I'll try to think of something, but as of now I don't have a good idea what the category for STM (or Stream) should be...

nomisRev · 2020-11-13T13:27:25Z

We could change the Data types section to Arrow Fx Coroutines, and we can add a section for STM and Stream?
I am working on the split of Streams atm ;)

No clue how this got in there

nomisRev

Great addition to the docs. Some suggestions, which leads to a bit to duplication but I think that's okay!

arrow-fx-stm/src/main/kotlin/arrow/fx/stm/STM.kt

arrow-fx-stm/src/main/kotlin/arrow/fx/stm/TMVar.kt

arrow-fx-stm/src/main/kotlin/arrow/fx/stm/TMap.kt

arrow-fx-stm/src/main/kotlin/arrow/fx/stm/TMVar.kt

arrow-fx-stm/src/main/kotlin/arrow/fx/stm/TQueue.kt

arrow-fx-stm/src/main/kotlin/arrow/fx/stm/TSet.kt

Co-authored-by: Simon Vergauwen <nomisRev@users.noreply.github.com>

At least I think this will fix it ^^

Also use suspend fun main for all examples except the main ones

nomisRev · 2020-11-21T10:04:58Z

A second review is needed @arrow-kt/maintainers

raulraja

This is great, thanks so much @1Jajen1 and @nomisRev for taking the time and reviewing. I requested some changes regarding type names and operator names to make it closer to our efforts to be inline with the std lib semantics and make some types like TSem more exploit if possible.

raulraja · 2020-11-26T19:06:25Z

arrow-fx-stm/src/main/kotlin/arrow/fx/stm/TMap.kt

+ *  well distributed the hash function is), it also means that structural changes can be isolated and thus do not increase contention with
+ *  other transactions. This effectively means concurrent access to different values is unlikely to interfere with each other.
+ *
+ * > Hash conflicts are resolved by chaining.


What does it mean by chaining?

There are two ways to to resolve hash conflicts:

Either replace the value and assume hashes are unique

Or put them in a collection and iterate through them on lookups

Chaining here refers to chaining it to the end of the leaf array, I've heard and seen it used in this context while I did a bit of research on how Hamt structures work so I just used it here.

arrow-fx-stm/src/main/kotlin/arrow/fx/stm/TMap.kt

raulraja · 2020-11-26T19:10:48Z

arrow-fx-stm/src/main/kotlin/arrow/fx/stm/TQueue.kt

+ *   val tq = TQueue.new<Int>()
+ *   atomically {
+ *     tq.write(0)
+ *     tq.filter { it != 0 }


filter as a name is confusing if it does not return a new queue as users may be used ro. Is there a better name for this op?

I honestly have no idea, it really does filter, so dunno. Actually I really dislike the filter as an api because it a) increases contention (accesses both TVars) and b) it has a weird/different api as you mentioned.

Maybe it makes sense to just 🔥 it.

Maybe applyFilter to highlight that it directly applies to the TQueue?

If you dislike the function, I am fine with removing it. It can always be re-added later, removing is harder 😁
I agree the name is a bit confusing.
Perhaps something along the line of remove/removeAll? That's a function found in the Kotlin Standard library but only available for mutable collections.

https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/remove.html
https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/remove-all.html

I think keeping it is fine, removeAll with a predicate is a really good name. It still has the problem of contention but it may have some actual use, so long as its used infrequently its perfectly fine.

arrow-fx-stm/src/main/kotlin/arrow/fx/stm/TSem.kt

1Jajen1 · 2020-11-26T20:37:11Z

I requested some changes regarding type names and operator names to make it closer to our efforts to be inline with the std lib semantics and make some types like TSem more exploit if possible.

Yes please, now is the perfect time to align the api, I took the names from the haskell libs and related so any change is fine by me. I'll do it in this pr if that is fine with you.

nomisRev

👌

PhBastiani · 2020-11-28T09:32:21Z

I'm starting to read the doc ... I'm impressed with the work you have done for Continuations & STM 👏

A README explaining the main functionalities would be useful to introduce the purpose of the module.

1Jajen1 · 2020-11-28T11:53:36Z

I'm starting to read the doc ... I'm impressed with the work you have done for Continuations & STM

A README explaining the main functionalities would be useful to introduce the purpose of the module.

Thanks for reading it 🙏

The README: Regarding the implementation or the api function? I suppose a readme describing how the implementation works ala fx-coroutines makes most sense as the rest should be in the docs^^

1Jajen1 · 2020-11-28T12:01:14Z

I'm starting to read the doc ... I'm impressed with the work you have done for Continuations & STM
A README explaining the main functionalities would be useful to introduce the purpose of the module.

Thanks for reading it pray

The README: Regarding the implementation or the api function? I suppose a readme describing how the implementation works ala fx-coroutines makes most sense as the rest should be in the docs^^

Either way I think its best left for another pr as this one is quite close to completion. For a general introduction to what STM can do the api docs for the STM interface and the documentation for atomically are the best start.

PhBastiani · 2020-11-28T17:50:40Z

Either way I think its best left for another pr as this one is quite close to completion. For a general introduction to what STM can do the api docs for the STM interface and the documentation for atomically are the best start.

We don't need a long README: a short introduction would be sufficient, as long as the reader is encouraged to read the STM class doc (I mean it is important to mark the main entry point of the API).

1Jajen1 · 2020-11-28T19:14:27Z

We don't need a long README: a short introduction would be sufficient, as long as the reader is encouraged to read the STM class doc (I mean it is important to mark the main entry point of the API).

Ah ok, I was confused by what exactly you were referring to. I'll add that in this pr, thanks for the suggestion! At some point I'll add a section to it which explains the internals as a sort of contribution guide like arrow-fx-coroutines does atm, but thats a later pr.

nomisRev · 2020-11-28T20:51:06Z

At some point I'll add a section to it which explains the internals as a sort of contribution guide like arrow-fx-coroutines does atm, but thats a later pr.
❤️

Very very simple way of pointing ppl towards to docs

1Jajen1 · 2020-11-29T01:07:30Z

Added a readme which contains a link to the STM interface api docs. We still need a section in the sidebar, but until I have a decent idea where, that can wait.

If there is nothing else I'll merge this pr later today 🎉

Add a lot more documentation to STM and structure it better

8049496

Merge branch 'master' into jo-stm-docs

2a4e130

Correct some confusing wording

5558d5c

No clue how this got in there

nomisRev approved these changes Nov 14, 2020

View reviewed changes

1Jajen1 and others added 7 commits November 14, 2020 14:38

Update arrow-fx-stm/src/main/kotlin/arrow/fx/stm/TMVar.kt

862818b

Co-authored-by: Simon Vergauwen <nomisRev@users.noreply.github.com>

Apply suggestions from review

8395e71

Fix missing Stacktrace

6435349

At least I think this will fix it ^^

Add a quick note on retry on how it affects other datastructures

9b55bf4

Merge branch 'master' into jo-stm-docs

be2467d

Remove arrow-fx-coroutines dep

e492c38

Also use suspend fun main for all examples except the main ones

Merge remote-tracking branch 'origin/jo-stm-docs' into jo-stm-docs

0a432ba

nomisRev requested a review from a team November 21, 2020 10:04

raulraja approved these changes Nov 26, 2020

View reviewed changes

1Jajen1 added 3 commits November 27, 2020 14:52

Rename TSem -> TSemaphore and use += instead of +

9414ebe

Also use TSem -> TSemaphore and some other minor problems

6d9e912

Filter -> RemoveAll and 🔥 FilterNot

56a0317

nomisRev approved these changes Nov 28, 2020

View reviewed changes

Add a README to the main repo

765993d

Very very simple way of pointing ppl towards to docs

1Jajen1 merged commit 642b442 into master Nov 29, 2020

1Jajen1 deleted the jo-stm-docs branch November 29, 2020 14:17

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add a lot more documentation to STM and structure it better #302

Add a lot more documentation to STM and structure it better #302

1Jajen1 commented Nov 13, 2020 •

edited

1Jajen1 commented Nov 13, 2020

nomisRev commented Nov 13, 2020

1Jajen1 commented Nov 13, 2020

nomisRev commented Nov 13, 2020

nomisRev left a comment

nomisRev commented Nov 21, 2020

raulraja left a comment

raulraja Nov 26, 2020

1Jajen1 Nov 26, 2020

raulraja Nov 26, 2020

1Jajen1 Nov 26, 2020 •

edited

1Jajen1 Nov 27, 2020

nomisRev Nov 27, 2020

1Jajen1 Nov 27, 2020

1Jajen1 commented Nov 26, 2020

nomisRev left a comment

PhBastiani commented Nov 28, 2020

1Jajen1 commented Nov 28, 2020 •

edited

1Jajen1 commented Nov 28, 2020

PhBastiani commented Nov 28, 2020 •

edited

1Jajen1 commented Nov 28, 2020

nomisRev commented Nov 28, 2020

1Jajen1 commented Nov 29, 2020

Add a lot more documentation to STM and structure it better #302

Add a lot more documentation to STM and structure it better #302

Conversation

1Jajen1 commented Nov 13, 2020 • edited

1Jajen1 commented Nov 13, 2020

nomisRev commented Nov 13, 2020

1Jajen1 commented Nov 13, 2020

nomisRev commented Nov 13, 2020

nomisRev left a comment

Choose a reason for hiding this comment

nomisRev commented Nov 21, 2020

raulraja left a comment

Choose a reason for hiding this comment

raulraja Nov 26, 2020

Choose a reason for hiding this comment

1Jajen1 Nov 26, 2020

Choose a reason for hiding this comment

raulraja Nov 26, 2020

Choose a reason for hiding this comment

1Jajen1 Nov 26, 2020 • edited

Choose a reason for hiding this comment

1Jajen1 Nov 27, 2020

Choose a reason for hiding this comment

nomisRev Nov 27, 2020

Choose a reason for hiding this comment

1Jajen1 Nov 27, 2020

Choose a reason for hiding this comment

1Jajen1 commented Nov 26, 2020

nomisRev left a comment

Choose a reason for hiding this comment

PhBastiani commented Nov 28, 2020

1Jajen1 commented Nov 28, 2020 • edited

1Jajen1 commented Nov 28, 2020

PhBastiani commented Nov 28, 2020 • edited

1Jajen1 commented Nov 28, 2020

nomisRev commented Nov 28, 2020

1Jajen1 commented Nov 29, 2020

1Jajen1 commented Nov 13, 2020 •

edited

1Jajen1 Nov 26, 2020 •

edited

1Jajen1 commented Nov 28, 2020 •

edited

PhBastiani commented Nov 28, 2020 •

edited