search

Kotlin / kotlinx-atomicfu

The idiomatic way to use atomic operations in Kotlin
Other
830 stars 56 forks source link

Improve README to clarify components of atomicfu #410

Open mgroth0 opened 3 months ago

mgroth0 commented 3 months ago

Based on the confusion I was having as a new user in https://github.com/Kotlin/kotlinx-atomicfu/issues/407 and https://github.com/Kotlin/kotlinx-atomicfu/issues/370, I want to propose an addition to the README that I think will help other new users.

I had considerable confusion setting up atomicfu for the first time in my projects. Finally, after re-reading the README multiple times and getting support from multiple discussions, I think I figured it all out. But it was way more difficult than it should have been, in my opionion. I actually think it took me hours just to figure out the different components, and without help I don't think I ever would have figured it out.

I think this should make sure to clarify which components provide boxed and unboxed version of the atomics. Also the different versions.

I am imagining a table with three columns like so:

org.jetbrains.kotlinx:atomicfu-gradle-plugin This is the gradle and compiler plugin. It uses compiler magic to inline ("unbox?") the atomics. It introuces additional restrictions on how the atomics can be used. 0.23.2
org.jetbrains.kotlinx:atomicfu This is the normal library. It is added automatically by the gradle and compiler plugin. If this is added alone without the gradle and compiler plugin, then atomics can be used as normal boxes. It might have slightly worse performance, but there are no special restrictions on how atomics can be used. 0.23.2
org.jetbrains.kotlin:atomicfu (I don't know what this is, but users should know not to mix it up with the "kotlinx" component as I did...) 2.0.0-Beta4
mvicsokolova commented 2 months ago

Thank you for your comment, it's very helpful 🙏🏻! I'm gonna review the description of all the library components and plugin application in the README before the next release.