Document compatability with @PublishedApi internal declarations, and those used in in-module inline functions

[rnett]

The docs state:

Declare atomic variables as private val or internal val. You can use just (public) val, but make sure they are not directly accessed outside of your Kotlin module (outside of the source set). Access to the atomic variable itself shall be encapsulated.

It would be nice to have it explicitly stated whether this includes @PublishedApi internal declarations, and whether the answer changes if the declaration is only used by in-module inline functions.

My understanding is that it's OK to use as long as it's only used via in-module inline functions, because the inlining inlines the processed IR, which has had the transformations applied. But it would be nice to confirm that.

[fzhinkin]

@rnett, thanks for bringing this question up!

@PublishedApi internal declarations are prohibited and an attempt to use them with IR transformations turned on (via kotlinx.atomicfu.enableJvmIrTransformation=true) will result in an error (before 2.2.0, it was a warning: https://youtrack.jetbrains.com/issue/KT-70982).

Unfortunately, the check is only enable for IR-transformations-mode and the potential problem is not reported otherwise. :(

Docs are definitely should be updated to explicitly state that.

[rnett]

Ah yeah, I see the error now. Is this sort of restriction likely to stick around once these atomics & transforms are moved into the stdlib/compiler? Because it's rather restrictive ATM - my use case is trying to have a public/@PublishedApi internal inline function that uses update of a "private" atomic, and only calls the (inlined) lambda parameter in the update (it's a budget ConcurrentHashMap's getOrPut using an atomic PersistentMap).