DEV Community: Kevin Galligan

Ktor and Kotlin/Native

Kevin Galligan — Tue, 01 Sep 2020 20:07:01 +0000

Ktor and Kotlin/Native

The story of coroutines for Kotlin/Native has been complex for a while now, and with the news that the Kotlin/Native memory model will be changing, coroutines for Kotlin/Native will remain a complex story for some time.

Ktor is built around coroutines. The coroutines situation fundamentally affects how Ktor functions. There have been multiple moving targets in this story, which has created a lot of confusion and a number of bug reports that kind of cross over the same core issues.

In this post, I will attempt to add some clarity to the situation.

The Coroutines Situation

To be clear, when we're talking about "core
utines", we're generally talking about kotlinx.coroutines. It's technically a separate library, but I can't imagine a realistic situation where you'd actually use coroutines and not include kotlinx.coroutines.

Initially, kotlinx.coroutines for Kotlin/Native was single threaded. You could suspend execution, but not schedule work on different threads. This was due to Kotlin/Native's memory model.

Ktor was designed to run on this single-threaded model. Also, as far as I know on iOS, you would need to initiate Ktor calls from the main thread.

In late 2019, a draft PR emerged which allowed kotlinx.coroutines to communicate across threads. We'll call this the "MT" branch, for "multithreaded". From this branch, there have been parallel library releases. The current main release is '1.3.9' and the current multithreaded release is '1.3.9-native-mt'.

Unless something changes, the parallel branch and release model will likely stay the same for kotlinx.coroutines until the Kotlin/Native memory model update is complete.

Ktor

Until 1.4, Ktor was still designed to be run with the single-threaded version of kotlinx.coroutines. You could run it with the MT version, but you had to be very careful to keep the scope you were in to the main thread and make sure it was never frozen.

It's a little complicated to explain, and not super useful as it's now history, but here it is. Coroutines run in a scope, which has (among other things) a Dispatcher and a Job. When you change the Dispatcher to run code on another thread, that scope gets frozen. Once frozen, everything the Job holds will also be frozen. So, if you were doing something on a background thread in the same scope as something you were doing with Ktor, even if Ktor was only in the main thread, you'd get an InvalidMutabilityException.

I think one of the more confusing parts is that Ktor would work until you involved that scope in a background process, after which it would stop working.

To see this in action, watch the video.

To get around this, you either need to maintain a different scope for Ktor, and make sure it never got frozen, or isolate the Job. We did that with KaMPKit. It was a pretty ugly hack, but it worked.

Also, since Ktor depended on the non-MT version, you could unintentionally be using the non-MT version of kotlinx.coroutines even though your dependency configuration explicitly asked for it. You would need to specify that you wanted to use that version.

implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.3.9-native-mt") {
    version {
        strictly("1.3.9-native-mt")
    }
}

Kotlin and Ktor 1.4 release

The 1.4 release of Ktor actually fixes this issue. We didn't hear about it for a bit, but I think that was because the issue was confusing to a lot of folks. Although it's fixed for the MT branch, the situation has some further confusion, as the current release of Ktor pulls in the MT branch of kotlinx.coroutines. If your project expects the single-threaded version of kotlinx.coroutines, this situation can result in some unexpected behavior.

To experiment with Ktor in the different versions, you can check out our little sample app.

touchlab-lab / ktorcoroutines

Just showing ktor fix in 1.4.0

The master branch has 1.3.72 and shows the failure that was happening. The kotlin_140 branch has the updated versions and a functional Ktor sample.

Issues

Ktor needs to be run from the main thread. There are also issues with Ktor and testing, related to the threading restrictions. We'll be digging into this more at some point. Just be aware of it.

Also, Russell tells me there's a logging issue which I'm not even going to dig into right now because I want to publish this today…

TL;DR

Ktor and kotlinx.coroutines were not working well together on native before 1.4. Now they cooperate better. Using Ktor 1.4 will possibly pull in the MT branch of kotlinx.coroutines, so if your project is not designed for that, be aware that it's possibly an issue.

We've updated KaMP Kit to remove the hack we had put in. Ktor is now just regular Ktor

touchlab / KaMPKit

KaMP Kit by Touchlab is a collection of code and tools designed to get your mobile team started quickly with Kotlin Multiplatform.

Kotlin/Native Concurrency Changes…

Kevin Galligan — Mon, 20 Jul 2020 20:00:19 +0000

On the JetBrains Blog, Roman Elizarov just dropped a pretty big piece of news, if you're in the Kotlin/Native and Multiplatform world.

If you still have questions after reading this post and want our input, submit your KN concurrency questions and we’ll get back to you.

The explicitly thread-confined, "frozen" concurrency model, is changing.

I've been talking about this concurrency and runtime model for the past 2+ years. From a safety perspective, there's a lot to like. Unrestricted shared memory access is problematic, to put it mildly. Enforcing some rules at runtime means extra safety, and forces you to think about how your JVM code is architected. Maybe it could be done differently?

Of course, if I take a step back, I've done a lot of content explaining this model over the past couple of years. That would imply that, perhaps, it is difficult for developers to learn. It is certainly a unique model, and the fact that the JVM and Native live by different rules has been a source of some confusion indeed.

Unpacking The Post

I want to highlight some parts of the post and discuss them a bit.

The most important bit was in the TL;DR:

"Existing code will continue to work and will be supported."

It is important to stress that this post is talking about future changes, and that your Native code will be compatible with these future changes.

"To solve these problems, we've started working on an alternative memory manager for Kotlin/Native that would allow us to lift restrictions on object sharing in Kotlin/Native…"

This means the runtime-enforced thread-confinement model will be going away. There was some confusion about what "object sharing" meant. That's not just global objects. It's the full memory management model.

"We plan to introduce it in a way that is mostly compatible with existing code, so code that is currently working will continue to work."

"mostly compatible" might sound like a concern, but unless you have something really exotic going on, it should work fine. Freezing will still be there, but it'll be optional (like Javascript). The annotations will still have implementations, even if they no longer do anything.
Your code will continue to work, and in many cases, work faster.

"and we will be looking at ways to improve Kotlin's approach to working with immutable data in the whole Kotlin language, not just in Kotlin/Native."

This part is interesting. The fact that the JVM and Native worked differently at runtime was one of the biggest issues. Improving immutable data in the language, and applying that to concurrent best practices, sounds like a good thing, but we'll have to see what emerges.

"Meanwhile, we'll continue to support the existing memory manager, and we'll release multithreaded libraries for Kotlin/Native so you can develop your applications on top of them."

This is important. For our apps, we use the multithreaded coroutines branch. We're careful to use it in such a way as to avoid the potential memory leaks discussed in Roman's post, but it is a core part of the library ecosystem. There will be ongoing support for it.

What now?

Well, personally, I'm going to find other things to talk about at conferences :)

Other than that, not a whole lot changes right now. There's no timeline on the memory manager updates, but you can assume it'll be quite a while. This isn't a few months away. That means, for the foreseeable future, if you write Kotlin/Native code, you'll need to understand the frozen model and how to write code in it. All the stuff we've been talking about still applies.

KMP continues to mature as a platform, and the concurrent code you write for Native now will continue to work whenever these updates arrive.

I think we (Touchlab) may start producing content around how to accomplish certain tasks, rather than deeper explanations around the fundamentals ("frozen", etc). Tech recipes, basically. For example, how to use Flow and Sqldelight, how to handle networking in various scenarios, etc. You can mostly hide the details of the current memory model, and you can write code that will transition well when these changes do come.

So, not a whole lot changes right now, but changes certainly are coming. Ultimately, this will improve adoption, which is good for the ecosystem. I'm sure I'll have more to say down the road…

Debugging Kotlin on iOS with Xcode

Kevin Galligan — Thu, 19 Mar 2020 18:59:36 +0000

Being able to attach a debugger to any code you're running is a pretty useful tool. We expect these tools to mature for Kotlin Multiplatform, especially later this year when the Android Studio plugin launches.

For sharing Kotlin code with iOS projects, it would seem pretty important to be able to debug directly in Xcode. We built the Kotlin Xcode plugin to make that possible.

Plugins are no longer officially supported in Xcode, of course. However, they haven't been entirely disabled for source code formatting and custom languages. There are several of these out in the wild which are doing roughly the same thing. Color source code, and tell Xcode you can debug these files.

From there, Xcode just hooks into lldb, so as long as your source type supports lldb, you should be able to debug!

Installing

Installing the Xcode plugin is a little tricky. As plugins aren't officially supported, Xcode doesn't make the process easy, and it changed somewhat between v10 and v11. Follow the instructions in the readme.

Some things to note. If you have the plugin installed already, but it seems to have stopped working, you may need to completely remove the plugin and reinstall. That means close Xcode, open ~/Library/Developer/Xcode/Plug-ins/ and remove Kotlin.ideplugin, open Xcode again, close, and run setup.sh.

Why that happens is unknown, but that seems to solve the issue. We may eventually make an installer process to automate that, but we need more testing.

Configure Kotlin

Currently you'll need a dynamic framework to debug. We are working on getting debugging to work with static frameworks, but at present, that doesn't work right.

If you aren't using the Kotlin Cocoapods plugin, you should have a dynamic framework by default. If you are using the Cocoapods plugin, that generates static frameworks, and there's no way to disable that directly. We've forked the Cocoapods plugin so you can generate dynamic frameworks for Kotlin with Cocoapods.

touchlab / KotlinCocoapods

For a live example, there's a PR to KaMP Kit pending to enable debugging.

Some notes. You need to do a clean build to get changes to show up in Xcode. Not a full clean of Kotlin's build, but in Xcode, run "Clean Build Folder". We have an issue for this and will look into it.

Kotlin Files in Xcode

Previously we recommended to use our KotlinXcodeSync plugin to sync xcode with Kotlin files. As it turns out, there's a much easier way to see your Kotlin in Xcode. You can just add a folder reference, which will make the files available but won't try to compile them directly or put them in the app bundle.

We'll be deprecating the Xcode Sync gradle plugin, and writing up some better docs for all of this soon.

What's Next?

We're waiting on Kotlin 1.3.71 to finish pushing some libraries, and will be revisiting the dev tools and process at that point to streamline things a bit.

Reach Out

If your org is looking for expert support to get started on your KMP journey, of course, reach out!

Kotlin/Native - Isolated State

Kevin Galligan — Sun, 26 Jan 2020 19:40:27 +0000

In the previous post we discussed transferring state. I started there because recently several people posted in the Kotlin slack discussing DetachedObjectGraph.

In my particular journey from JVM to Kotlin/Native (or KN), I went through a phase I think many new KN devs go through. In the JVM I was used to sharing mutable state between threads, and I assumed I must retain that ability at all costs. DetachedObjectGraph is one of the first things I started to focus on.

It seems like interest in KMP has picked up considerably this first month of 2020, and so we've had a lot of questions about DetachedObjectGraph. I have found that DetachedObjectGraph is of limited value, and once I understood the KN state model, I found I never needed it.

You will, however, occasionally need mutable state between threads.

Stately Collections V1

Going back to mid/late 2018, we released Stately.

touchlab / Stately

Kotlin Multiplatform State Library

Along with atomics, locks, and some other concurrency support stuff, there was also a set of concurrent collection classes. These internally used AtomicRef to implement collections. That meant I actually implemented a linked list and a hash map from scratch with AtomicRef.

These collections work, but performance is bad, their implementation is basic, and their use is inflexible. Also, just FYI, AtomicRef can leak memory, so you need to clear these collections when you're done with them.

As it turns out, if you just keep your state isolated, you can implement concurrent collections in an almost trivial manner, with far better performance.

Stately Collections V2 (Isolated State)

The next version of Stately will have a class called IsolateState. You create an instance in a manner similar to how you interact with DetachedObjectGraph. Pass in a producer lambda. One critical difference. The value returned from that lambda cannot be frozen.

Once you create this instance of IsolateState, you interact with it by way of the access method. access takes a lambda, which takes one argument: the mutable state.

As an example, let's create a simple shared map:

object StateSample {
    val cacheMap = IsolateState { mutableMapOf<String, SomeData>() }
}

data class SomeData(val s: String)

cacheMap is a simple mutable map, with String keys and SomeData values.

To be clear, according to KN state rules, object StateSample is frozen, so cacheMap is also frozen. The state it contains, the result of mutableMapOf<String, SomeData>(), is not frozen, and can never be (we call ensureNeverFrozen() internally).

Getting to that state and doing stuff with it is easy:

fun doStuff(){
    StateSample.cacheMap.access {map -> 
        map.put("Hello", SomeData("World"))
    }
}

Getting values from the state is also straightforward:

fun readStuff(){
    val sd = StateSample.cacheMap.access { it.get("Hello") }
    println("sd: $sd, isFrozen: ${sd.isFrozen()}")
}

Note, the value returned from access will be frozen, as is anything captured and passed into access.

There will be a separate stately-iso-collections module, but because isolated state is so flexible, I'm not sure how necessary a full MutableMap implementation, for example, would be as opposed to just using access to get at the methods you need. I didn't want to clutter the middle of the post, but I've included the entire implementation of a MutableMap using IsolateState at the bottom. It really is bordering on trivial.

One of the more inflexible aspects of any concurrent collection is the lack of atomic operations. Calling size will return a value, but if you want to insert a value based on that result, you could have race conditions.

Take the following example:

fun racyInABadWay(fmap:HashMap<String, SomeData>){
    val size = fmap.size
    fmap.put("i $size", SomeData("data $size")) // <- may result in missed values
}

Assume fmap is a concurrent map from Stately v1 collections. Between the call to get size and the call to put a value, the size could change. Your put call will be invalid. You could fix this by creating a Lock instance that's associated with fmap, then passing them both around, but that's ugly.

Using IsolateState, this is again trivial.

fun atomicOperations(isoMap: IsolateState<MutableMap<String, SomeData>>){
    isoMap.access { map ->
        map.put("i ${map.size}", SomeData("data ${map.size}"))
    }
}

Under the hood, all access calls run on the same thread, so while your block is running, nothing can change the map. You can implement arbitrarily complex atomic operations.

Performace

Performance is kind of relative. Inserting 50k elements in a v1 Stately map vs v2 is pretty good.

    val times = 50_000
    val v1Time = measureTimeMillis {
        val fmap = frozenHashMap<String, SomeData>()
        repeat(times){c ->
            fmap.put("i $c", SomeData("data $c"))
        }
    }

    println("v1Time: $v1Time")

    val isoTime = measureTimeMillis {
        val isomap = IsolateState{ mutableMapOf<String, SomeData>()}
        repeat(times){c ->
            isomap.access { it.put("i $c", SomeData("data $c")) }
        }
    }

    println("isoTime: $isoTime")

The result:

v1Time: 13785
isoTime: 1937

Compared to using a regular MutableMap? Well, not as good.

    val normalTime = measureTimeMillis {
        val map = mutableMapOf<String, SomeData>()
        repeat(times){c ->
            map.put("i $c", SomeData("data $c"))
        }
    }

    println("normalTime: $normalTime")

isoTime: 1937
normalTime: 201

Of course, you're crossing thread contexts for each call to the IsolateState instance. There's a lot of overhead involved. Because IsolateState is inherently more flexible than a fixed concurrent map implementation, inserting in blocks is pretty easy to implement. The performance boost is dramatic.

    val isoBlockTime = measureTimeMillis {
        val isomap = IsolateState{ mutableMapOf<String, SomeData>()}
        val outerTimes = times / 1000
        repeat(outerTimes){ c ->
            val blockMap = mutableMapOf<String, SomeData>()
            repeat(1000){inner ->
                val putCount = (c * 1000) + inner
                blockMap.put("i $putCount", SomeData("data $putCount"))
            }

            isomap.access { it.putAll(blockMap) }
        }
    }

    println("isoBlockTime: $isoBlockTime")

normalTime: 201
isoBlockTime: 330

You've inserted 50k elements into a concurrent map structure in a time that's ~65% slower than a local mutable map. It's "slower", relatively, but that performance is fantastic all things considered. That's also without inline on any of the IsolateState methods, which may slightly improve the situation.

Can you insert in Stately v1's collections in blocks? Sure, but it's rigid, and because they're implemented with AtomicRef, the performance is dismal.

    val v1BlockTime = measureTimeMillis {
        val fmap = frozenHashMap<String, SomeData>()
        val outerTimes = times / 1000
        repeat(outerTimes){ c ->
            val blockMap = mutableMapOf<String, SomeData>()
            repeat(1000){inner ->
                val putCount = (c * 1000) + inner

                blockMap.put("i $putCount", SomeData("data $putCount"))
            }

            fmap.putAll(blockMap)
        }
    }

    println("v1BlockTime: $v1BlockTime")

It's the same as inserting values individually.

v1Time: 13785
isoTime: 1937
normalTime: 201
isoBlockTime: 330
v1BlockTime: 13623

To round out our timing comparison, if you use DetachedObjectGraph to insert 50k elements, things get much, much worse.

fun timeTest() {
    val times = 50_000
    val detachedTime = measureTimeMillis {
        val detachedMap = SharedDetachedObject { mutableMapOf<String, SomeData>() }
        detachedMap.freeze()
        repeat(times){c ->
            val sd = SomeData("data $c")
            detachedMap.access {
                it.put("i $c", sd)
            }
        }
    }

    println("detachedTime: $detachedTime")
}

detachedTime: 68334

That's about 35x slower than using IsolateState. It'll also get worse as the size grows because you lose the Big O advantage of a hash map. You could certainly optimize access to DetachedObjectGraph a bit, but what's the point?

In summary, use IsolateState for KMP concurrent state.

We've published an experimental version of Stately to try this out:

implementation "co.touchlab:stately-isolate:0.10.2"

The documentation hasn't been updated, but you can see samples here:

touchlab-lab / StatelyIsoStateSample

Stately IsolatedState sample

We should have a more formal version soon, pending community feedback.

Hiring!

Touchlab is hiring! Looking for Android-focused mobile developers, and also for experienced or very interested Kotlin Multiplatform devs. We really need to find a solid Android dev at this precise moment, though. Just FYI. Remote friendly (US-only, for now).

MutableMap Implementation

Here's the code for a MutableMap implemented with IsolateState. We're essentially just wrapping mutableMapOf<K, V>().

class IsoMutableMap<K, V>(producer: () -> MutableMap<K, V> = { mutableMapOf() })
    : IsolateState<MutableMap<K, V>>(createState(producer)), MutableMap<K, V> {
    override val size: Int
        get() = access { it.size }

    override fun containsKey(key: K): Boolean = access { it.containsKey(key) }
    override fun containsValue(value: V): Boolean = access { it.containsValue(value) }
    override fun get(key: K): V? = access { it.get(key) }
    override fun isEmpty(): Boolean = access { it.isEmpty() }
    override val entries: MutableSet<MutableMap.MutableEntry<K, V>>
        get() = access { IsoMutableSet(StateHolder(it.entries)) }
    override val keys: MutableSet<K>
        get() = access { IsoMutableSet(StateHolder(it.keys)) }
    override val values: MutableCollection<V>
        get() = access { IsoMutableCollection(StateHolder(it.values)) }
    override fun clear() = access { it.clear() }
    override fun put(key: K, value: V): V? = access { it.put(key, value) }
    override fun putAll(from: Map<out K, V>) = access { it.putAll(from) }
    override fun remove(key: K): V? = access { it.remove(key) }
}

open class IsoMutableCollection<T> internal constructor(stateHolder: StateHolder<MutableCollection<T>>) :
    IsolateState<MutableCollection<T>>(stateHolder), MutableCollection<T> {
    constructor(producer: () -> MutableCollection<T>) : this(createState(producer))
    override val size: Int
        get() = access { it.size }

    override fun contains(element: T): Boolean = access { it.contains(element) }
    override fun containsAll(elements: Collection<T>): Boolean = access { it.containsAll(elements) }
    override fun isEmpty(): Boolean = access { it.isEmpty() }
    override fun add(element: T): Boolean = access { it.add(element) }
    override fun addAll(elements: Collection<T>): Boolean = access { it.addAll(elements) }
    override fun clear() = access { it.clear() }
    override fun iterator(): MutableIterator<T> = access { IsoMutableIterator(StateHolder(it.iterator())) }
    override fun remove(element: T): Boolean = access { it.remove(element) }
    override fun removeAll(elements: Collection<T>): Boolean = access { it.removeAll(elements) }
    override fun retainAll(elements: Collection<T>): Boolean = access { it.retainAll(elements) }
}

class IsoMutableSet<T> internal constructor(stateHolder: StateHolder<MutableSet<T>>) :
    IsoMutableCollection<T>(stateHolder), MutableSet<T> {
    constructor(producer: () -> MutableSet<T> = { mutableSetOf() }) : this(createState(producer))
}

class IsoMutableIterator<T> internal constructor(stateHolder: StateHolder<MutableIterator<T>>) :
    IsolateState<MutableIterator<T>>(stateHolder), MutableIterator<T> {
    override fun hasNext(): Boolean = access { it.hasNext() }
    override fun next(): T = access { it.next() }
}

Kotlin/Native - Transferring State

Kevin Galligan — Sun, 26 Jan 2020 16:28:58 +0000

Kotlin/Native (KN) has special rules around state and concurrency. We cover them in usable detail in Practical Kotlin Native Concurrency and in more detail in KotlinConf 2019: Kotlin Native Concurrency Explained.

There are basically two rules. Mutable state can only be accessed by one thread at a time, and immutable state can be shared. When sharing state we freeze it, and mutable state generally stays thread confined. However, you can pass mutable state between threads. In all of my discussions, I mostly ignore that possibility, because it's fairly impractical and we don't use it anywhere (in production), but today we'll discuss it a bit.

Transferring State

In order to transfer mutable state between threads, you need to make sure there are no external references to it. The Worker.execute function and the DetachedObjectGraph constructor both take a producer function argument. The purpose of this function is to "produce" the state that you want to transfer, in such a way that all external references can be omitted.

That is the first complication and critical concept to understand. You'll often want to add mutable data to a DetachedObjectGraph from existing state, but this is syntactically difficult.

    @Test
    fun failLocal(){
        val d = Dat("Hello")
        assertFails {
            DetachedObjectGraph {d}
        }
    }

    data class Dat(val s:String)

The DetachedObjectGraph constructor takes a lambda producer argument. In it we try to return d, but d is still referenced from outside the lambda, specifically here in the local val d, so the transfer fails.

This case is overly simplistic. You can "solve" it with the following.

    @Test
    fun directReturn(){
        DetachedObjectGraph {Dat("Hello")}
    }

    data class Dat(val s:String)

The Dat instance returned from the producer has no external references, so you can transfer it. However, use your imagination and extrapolate how difficult it will be to maintain mutable state in a DetachedObjectGraph and pass it around. It quickly becomes impractical.

I would abbreviate DetachedObjectGraph with DOG, but DetachedObjectGraph is not your friend, and dogs are, so I will use the full name DetachedObjectGraph and clutter your visual space because we don't like them. Anyway...

You can build some managed access, with something like the following.

class SharedDetachedObject<T:Any>(producer: () -> T) {
    private val adog :AtomicReference<DetachedObjectGraph<Any>?>
    private val lock = Lock()

    init {
        val detachedObjectGraph = DetachedObjectGraph { producer() as Any }.freeze()
        adog = AtomicReference(detachedObjectGraph.freeze())
    }

    fun <R> access(block: (T) -> R): R = lock.withLock{
        val holder = FreezableAtomicReference<Any?>(null)
        val producer = { grabAccess(holder, block) as Any }
        adog.value = DetachedObjectGraph(TransferMode.SAFE, producer).freeze()
        val retult = holder.value!!
        holder.value = null
        retult as R
    }

    private fun <R> grabAccess(holder:FreezableAtomicReference<Any?>, block: (T) -> R):T{
        val attach = adog.value!!.attach()
        val t = attach as T
        holder.value = block(t)
        return t
    }

    fun clear(){
        adog.value?.attach()
    }
}

You can find this code in a new Stately branch.

This is somewhat complex to look at, but the concept is relatively simple. You create an instance of SharedDetachedObject with a producer, similar to the previous examples. The state returned is kept in a DetachedObjectGraph, and you can access that state with the access method. From that method you can return a value, although make absolutely sure it isn't the mutable state you're holding in the DetachedObjectGraph.

val detachedObject = SharedDetachedObject { mutableListOf("a", "b")}

repeat(50_000){rcount ->
    detachedObject.access {
        val element = "row $rcount"
        it.add(element)
        element
    }
}

The code above creates a mutable list that can be accessed in a shared way, from multiple threads. Anything leaving the access lambda that's still referenced from inside it should be frozen, of course (String gets special treatment in KN. It's always frozen).

OK! Transferring state may be syntactically messy, but it works, right! Sure, but there's another important consideration.

Performance

Transferring state requires that you inspect all of the state you want to transfer, to ensure nobody external is referencing it. All of the state. In the example above, that means on the last run, all 50k entries. Doing that isn't free.

Imagine a common use case. Building a HashMap cache. One of the primary benefits of a HashMap is read and write time. In the good case, they're constant time. Keeping a map in a DetachedObjectGraph sounds like a good idea, but each access of the map is followed by detaching so you can put it back in the DetachedObjectGraph for another thread to use. That turns constant time into linear time. A linear time hash map is a shitty hash map.

In our simple list case above, the time per-insert grows as the list gets larger.

We have a new set of concurrent/mutable state holders coming out for Stately. You can see the current branch here. In the next post we'll cover how to use the new state objects.

Hiring!

Kapture - Kotlin/Native State Capture

Kevin Galligan — Tue, 21 Jan 2020 19:27:33 +0000

Kotlin/Native state is different than what most Kotlin developers would be used to. To be shared between threads, state must be "frozen", which makes it immutable in the runtime.

For background on Kotlin/Native concurrency and state, see Practical Kotlin Native Concurrency.

Once the developer gets the general idea of how this works, it's not too complicated. However, capturing and freezing state unintentionally is a problem. Especially when combined with concurrency libraries.

Library Model

If you use the KN primitive Worker to implement concurrency, you'll need to be very explicit about state transfer or freezing.

In practice, few developers will use Worker directly. All current concurrency libraries opt to take a lambda argument that will be frozen, then run on another thread.

That makes concurrency in KN very simple. New developers often complain about the restrictions of the KN model, but KN forces you to rethink your architecture and be intentional about your mutable state. If you learn to work with the model, it's actually a good thing.

However, because lambdas can capture state, and freezing aggressively freezes everything it touches, you can easily wind up freezing state unintentionally. This can be very frustrating and lead to a lot of the beginner trouble with KN's model.

Take the following example:

class Product(val id:Long){
    fun saveOrder(order:Order){
        background {
            saveToDb(id, order)
        }
    }
}

I've been bitten by this problem on multiple occasions. The method background is going to take the lambda argument and freeze it, and run saveToDb(id, order) on another thread. That means id and order will be frozen.

Visually it looks like you're just freezing those two values. order might be a problem, because we don't know if the Order type should be frozen, but the real problem here is id is actually attached to Product. We wind up freezing the whole Product class.

Seeing what state is captured is not always obvious. That is relatively easy to determine with static analysis, and could be surfaced to the developer in the IDE.

However, not all state is problematic to freeze. In the simple example above, although Product is frozen, as presented, that's not a problem. There's nothing about Product that would be mutable anyway.

However, maybe it looked more like this:

class Product(val id:Long){

    var quantity:Int = 0

    fun saveOrder(order:Order){
        background {
            saveToDb(id, order)
        }
    }
}

Although perhaps not an architecturally good decision, the code above now has a real issue.

Kapture

Kapture is a code inspection Intellij plugin that finds "hot" functions, collects what state will be captured in the lambda arg(s), and evaluates if that state is problematic to freeze. If so, it'll create an error.

The inspection will add an issue to id, and hovering over it will pop up a summary of what's wrong and offer some fixes.

Education

The goal of Kapture is not simply to warn you of captured state. The options in the fix list will include links to documentation explaining the issue and potential best-practice approaches to refactoring your state architecture.

For example, in the scenario above, it's better to cross thread boundaries with a named function and use function parameters to avoid capturing the parent class.

class Product(val id:Long){

    var quantity:Int = 0

    fun saveOrder(order:Order){
        save(id, order)
    }

    private fun save(id: Long, order: Order) = background { saveToDb(id, order) }
}

Hot Functions

Hot functions are functions that take function arguments and may cross thread boundaries. There are some built-in functions that Kapture recognizes. These include withContext from corountines, and methods from Flow. You can also annotate your own with @FreezingBlockCall. This tells capture to treat block as special and look at it's captured state.

@FreezingBlockCall
fun <R> background(block: () -> R): R = block()

Sometimes a function won't actually cross a thread boundary at runtime, but it can be difficult to know for sure at compile time. Kapture, in general, leans conservative and will warn you of potential issues in ambiguous cases.

If you're in the main thread and call the following, you won't actually switch threads (and coroutines shouldn't freeze the lambda), but Kapture treats it as a potentially thread-crossing method anyway.


withContext(Dispatchers.Main){
    //What if you were already in the main thread?
}

Mutability Analysis

How do we determine if something is immutable? In summary, Kapture analyses the captured data. Everything has to be final and immutable.

For example, the following is OK:

data class SomeData(val s:String)

However, this is not:

data class SomeData(val s:Any)

The val s is of type Any, which is not final.

There are many other rules, including special classes. For example, anything from Sqldelight is considered safe to freeze, so those classes are ignored. On the other end, it's relatively easy to capture test classes, so even if your test class has nothing mutable, it'll be flagged as an issue.

class ProductTest{

    val db : DbHelper = inject()

    @Test
    fun heyTest() = background {
        db.whatever() // <- issue here
    }
}

You can override that, or anything, with @Freezeable.

@Freezeable
class ProductTest{

    val db : DbHelper = inject()

    @Test
    fun heyTest() = background {
        db.whatever()
    }
}

Kapture can also see some calls in the init block, so this would also work:

class ProductTest{
    init {
        freeze()
    }

    val db : DbHelper = inject()

    @Test
    fun heyTest() = background {
        db.whatever()
    }
}

There are a number of detailed inspections which you can read about in the docs, and more to be added to increase the accuracy. However, the important point to remember is if we can't reasonably verify that you can freeze some state, you'll get an error. It is intentionally conservative.

80/20

KN verifies frozen at runtime, which has been a criticism of the model. Doing this at compile-time, like Rust, would be great, but would require a significantly different language. There's only so much the compiler can know about what you're doing without those language changes.

Kapture operates under the "pretty good" model. It'll make pretty good guesses, and you can override it when it's wrong. "Pretty good" isn't a virtue for compilers, but for developer tools, it's a different story.

Evaluation

We're currently looking for private testers to give feedback. We'd like to know if this is actually useful in practice and if it helps explain how the KN state model works. Please sign up here for access.

http://go.touchlab.co/Kapture-Devto

Special Thanks

This idea was kind of a combination of some slides in my concurrency talk, and chats with Eugenio Marletti and Scott Pierce in and around the Kotlin Slack.

Practical Kotlin Native Concurrency Part 3

Kevin Galligan — Mon, 16 Dec 2019 20:37:50 +0000

Parts 1 and 2 set the conceptual stage for what we're going to do in Part 3: look at some actual concurrency libraries. We have one more conceptual tool to cover, then we'll go over 2 options for using coroutines in a production app, and discuss Reaktive: a reactive streams implementation.

Atomics

KN provides a set of Atomic classes that allow you to have mutable state within a frozen object. In general, it's a good idea to minimize Atomic usage in lieu of "better" architecture, but they can be very useful in cases. Also, when first exposed to KN's state architecture, it can take some time to rethink how architecture should be laid out, and Atomics can help bridge that gap.

We will be using KN's Atomic primitives directly, but in practice, you'll likely use a library. We publish Stately, but also Atomic-fu has recently added native support. On native they're similar, but on the jvm Atomic-fu has some optimizations and restrictions. You should make an informed decision on which to choose:

touchlab / Stately

Kotlin Multiplatform State Library

Kotlin / kotlinx-atomicfu

The idiomatic way to use atomic operations in Kotlin

Let's take a look at Atomics in action. We'll be using KN's atomics directly, but either of the two libraries above have equivalent definitions and use KN's atomics under the hood.

First, let's revert back to the master branch.

git checkout .
git checkout master

Atomic Primitives

KN provides a set of Atomic classes for integral values: AtomicInt and AtomicLong. Those are conceptually simple to use. Run atomicIntDemo()

fun atomicIntDemo(){
    val dc = AtomicDataCounter()
    dc.freeze()
    dc.ai.increment()
    println("dc $dc")
}

class AtomicDataCounter {
    val ai = AtomicInt(3)
}

AtomicDataCounter has an AtomicInt property. We freeze our instance of AtomicDataCounter, but can still change the AtomicInt value. You can do this from any thread. Run atomicThreadsDemo()

fun atomicThreadsDemo() {
    val dc = AtomicDataCounter()
    background {
        dc.ai.increment()
        println("dc ${dc.ai.value}, is frozen ${dc.isFrozen}")
    }
}

AtomicReference is more generally applicable, as it allows you to have an object reference that can be changed in a frozen object. The object held in the AtomicReference must itself be frozen.

fun atomicRefDemo() {
    val dr = AtomicDataReference().freeze()
    dr.ar.value = SomeData("Hello 🎸", 43).freeze()
    println("dr ${dr.ar.value}")
}

class AtomicDataReference {
    val ar = AtomicReference(SomeData("Hello 🚀", 32).freeze())
}

If you have global objects that need to have mutable state, this is a straightforward way to manage that state. Global objects visible to multiple threads need to be frozen, so atomics are necessary if you need to change anything. However, there are some things to keep in mind.

1) Atomic ref performance is obviously not going to be the same as regular mutable state. Freezing isn't free either. Heavy atomic use may not be a great idea if performance is a consideration.

2) AtomicReference currently should be cleared out if it's not a "forever" object. It is possible to leak memory otherwise. Not always, though. This is something we have on the list for a future blog post. However, the situation may be changing anyway, so this may not be an issue in the near future.

Coroutines

The current release version of kotlinx.coroutines operates in a single thread only. Jetbrains has done such a good job associating "concurrency" with "coroutines" that some people in the community confuse the situation to think KN doesn't support concurrency at all.

Fortunately, that situation is changing. There is a preview branch of kotlinx.coroutines that is functional, and we'll be walking through that. Because it's a preview, including it in a production app may be difficult because of library dependencies, not to mention potential bugs. In the interim there is CoroutineWorker from Autodesk, which provides a source-compatible (ish) implementation for common cases.

kotlinx.coroutines Multithreaded Preview

Kotlin / kotlinx.coroutines

Library support for Kotlin coroutines

~~Since this branch has not been officially released, you'll need to build kotlinx.coroutines locally.~~

Good News! There's another prebuilt preview release! You don't need to build locally, at least for now. Just update your sample code...

Our handy sample app should be updated as well. Again, clear out local changes, and update, but this time we'll also need to switch branches.

git checkout .
git pull
git fetch
git checkout mt_coroutines

This will check out the remote mt_coroutines branch. We've moved the coroutines sample to a separate branch because of the local kotlinx.coroutines dependency. It would fail if you hadn't done the local build.

Anyway, now we're ready to get started.

Just an FYI. This post is not a generalized intro to coroutines. We're assuming you understand the basics. We're going to discuss them in the context of native and native's state model only.

Overview

Some things to know specific to coroutines on native:

1) A coroutine is always bound to a single thread. The JVM may use a thread pool for processing. Not so in native.

2) You create a new threaded coroutine with newSingleThreadContext. Each is backed by it's own Worker (and therefore, it's own thread).

3) Dispatchers.Default is defined, and is a single Worker coroutine.

4) Dispatchers.Main is defined for Apple targets. The situation is more complex for Windows/Linux.

See the kotlin-native-sharing.md for more detail.

You switch threads by switching the Dispatcher. In our examples we'll do this with withContext.

Something very important to understand:

If you are switching threads, all data captured will be frozen, and any return value will be frozen.

Let's look at a basic example. In SampleMacos.kt, find 5) Coroutines. Run basicBackgroundCoroutine().

fun basicBackgroundCoroutine() = runBlocking {
    println("(Coroutine) Is main thread $isMainThread")
    withContext(Dispatchers.Default) {
        println("(Coroutine) Is main thread $isMainThread")
    }
}

We create a coroutine context with runBlocking, then switch to a different thread with withContext(Dispatchers.Default). On the console we should see:

(Coroutine) Is main thread true
(Coroutine) Is main thread false

Easy!

Coroutines aren't magic. They follow the same state rules in native as everybody else. As mentioned, any captured state is frozen before it changes threads.

Run captureStateCoroutine()

fun captureStateCoroutine() = runBlocking {
    val sd = SomeData("Hello 🥶", 67)
    println("(Coroutine) Am I frozen? ${sd.isFrozen}")
    withContext(Dispatchers.Default) {
        println("(Coroutine) Am I frozen now? ${sd.isFrozen}")
    }
}

This is very similar to captureState() we ran in Part 2. When sd moves threads, it's frozen. We should see:

(Coroutine) Am I frozen? false
(Coroutine) Am I frozen now? true

Coroutines follow the same rules, and also have the same potential issues. Run captureTooMuchCoroutine()

fun captureTooMuchCoroutine() = runBlocking {
    val model = CountingModelCoroutine()
    model.increment()
    println("I have ${model.count}")

    model.increment()
    println("I have ${model.count}") //We won't get here
}

class CountingModelCoroutine {
    var count = 0

    suspend fun increment() {
        count++
        withContext(Dispatchers.Default) {
            saveToDb(count)
        }
    }

    private fun saveToDb(arg: Int) {
        //Do some db stuff
    }
}

Just like in captureTooMuch() from Part 2, the whole model gets frozen. How do we fix it? Surprise! Same solution. Run captureArgsCoroutine():

fun captureArgsCoroutine() = runBlocking {
    val model = CountingModelSaferCoroutine()
    model.increment()
    println("I have ${model.count}")

    model.increment()
    println("I have ${model.count}")
}

class CountingModelSaferCoroutine {
    var count = 0

    suspend fun increment() {
        count++
        saveToDb(count)
    }

    private suspend fun saveToDb(arg: Int) = withContext(Dispatchers.Default) {
        println("Doing db stuff with $arg, in main $isMainThread")
    }
}

Return Values

Unlike our simple background method, coroutines can return a method to your suspended caller. As mentioned, if the value being returned is crossing a thread, it'll be frozen. Run returnDataCoroutine():

fun returnDataCoroutine() = runBlocking {
    val sd = SomeData("Hello 🐶", 67)

    val result = makeData(sd)

    println("result: $result, is frozen ${result.isFrozen}")
}

private suspend fun makeData(sdIn: SomeData) = withContext(Dispatchers.Default) {
    SomeData("Hello again 🐶", sdIn.i + 55)
}

You should see:

result: SomeData(s=Hello again 🐶, i=122), is frozen true

When makeData is called, the main thread suspends while makeData runs in the background. When complete, the result is frozen, passed back to the caller and returned.

As mentioned, multithreaded kotlinx.coroutines is in preview, which makes it's use in production apps somewhat restricted today. However, if you want to play with things a bit more, and see Flow in action, check out the mt_coroutines branch from:

touchlab / DroidconKotlin

Kotlin Multiplatfom app for Droidcon Events

CoroutineWorker

CoroutineWorker from Autodesk is a library intended to let you use coroutines in KN across threads with syntax and semantics similar to what you'll use when kotlinx.coroutines with multiple threads is live.

Autodesk / coroutineworker

Kotlin Coroutine-based workers for native

Once again, let's revert and switch branches:

git checkout .
git pull
git fetch
git checkout coroutine_worker

You'll notice a very similar set of functions. In fact, everything we described above works basically the same. State captured is frozen, state returned is frozen. You call with withContext, although the dispatcher you pass is only used on the jvm.

Find 5) Coroutine Worker and run those methods in succession to verify they act the same.

For example, run captureStateCoroutine(). It is very similar to what we did with the MT coroutines preview, and behaves in a similar way.

fun captureStateCoroutine() = runBlocking {
    val sd = SomeData("Hello 🥶", 67)
    println("(Coroutine) Am I frozen? ${sd.isFrozen}")
    withContext(Dispatchers.Default) {
        println("(Coroutine) Am I frozen now? ${sd.isFrozen}")
    }
}

(Coroutine) Am I frozen? false
(Coroutine) Am I frozen now? true

We know of multiple teams using Coroutine Worker in production right now, and if the concurrency provided is sufficient, it's a great way to be source-ready for the full kotlinx.coroutines release.

Reaktive

Reaktive from Badoo is a reactive streams implementation for KMP, which includes KN support. If you are more of an RX fan vs Coroutines (if you get into that kind of debate), this is something you'll want to take a look at. We haven't done much since it was in preview, but will be taking a deeper look as part of our concurrency library review.

Just FYI, there's currently no macos build for Reaktive, so our sample needs to be run through Xcode.

badoo / Reaktive

Kotlin multi-platform implementation of Reactive Extensions

Let's reset our sample again:

git checkout .
git pull
git fetch
git checkout reaktive

The code should look reasonably familiar to somebody with RxJava experience. Let's do a basic sample that loads data in an I/O thread and returns it to the UI.

fun basicObservable(){
    observable<SomeData> { emitter ->
        println("From io thread, is main thread? ${isMainThread}")
        emitter.onNext(SomeData("arst", 43))
    }
        .subscribeOn(ioScheduler)
        .observeOn(mainScheduler)
        .threadLocal()
        .doOnBeforeNext { values += it } // Callback is not frozen, we can updated the mutable list
        .doOnBeforeFinally { isFinished = true } // Callback is not frozen, we can change the flag
        .subscribe {
            println("In main thread $isMainThread, is data frozen ${it.isFrozen}")
        }
}

We emit an instance of SomeData in the I/O thread and it winds up in the subscribe block. Data that chains through threads is frozen, as by now you'd probably expect.

To see this in action, uncomment basicObservable(), but to run it we need to do something different that before. Refresh gradle, and run the build task. This will take some time to run. After that, open iosApp/iosApp.xcworkspace in Xcode. Make sure it's iosApp.xcworkspace and not iosApp.xcodeproj. Once that is open, pick a simulator and run the project.

You should see the following output:

From io thread, is main thread? false
In main thread true, is data frozen true

Like with other libraries, you should be careful with state capture. Reaktive lives in the same state universe as everything else. Captured state will be frozen. Run willFreeze():


fun willFreeze(){
    val sd = SomeData("arst", 43)
    println("Frozen here? ${sd.isFrozen}")
    observable<SomeData> { emitter ->
        println("How about here? ${sd.isFrozen}")
        emitter.onNext(sd)
    }
        .subscribeOn(ioScheduler)
        .observeOn(mainScheduler)
        .threadLocal()
        .doOnBeforeNext { values += it } // Callback is not frozen, we can updated the mutable list
        .doOnBeforeFinally { isFinished = true } // Callback is not frozen, we can change the flag
        .subscribe {
            println("Obviously frozen here? ${sd.isFrozen}")
        }
}

On the output you'll see:

Frozen here? false
How about here? true
Obviously frozen here? true

We're not going to go super deep on Reaktive in this post, but it's definitely an interesting project for concurrency.

What's next?

This series is trying to avoid going too deep on the details and just explain enough for you to get started. If you want to go deeper and really understand what's happening, here are some other resources.

I gave a talk this year at Kotlinconf. It covers a lot of the same content, but also goes into worker and some info on architectural thinking.

Nikolay gave a talk at last year's Kotlinconf that goes into much deeper detail.

I wrote an earlier post series on the same topic. It is getting a bit old at this point, but it also explains deeper level topics.

Kotlin Native Stranger Threads. Episode 1 — Worker | by Kevin Galligan | Medium

Kevin Galligan ・ Jan 8, 2019 ・
Medium

Finally, the KN repo has some reference docs available. CONCURRENCY.md and IMMUTABILITY.md.

As mentioned in Part 1, this series of docs is part of our KMP evaluation kit. The goal of the starter kit is to kickstart your team's KMP evaluation. You can sign up for access to that here: https://go.touchlab.co/kampdevto

Practical Kotlin Native Concurrency Part 2

Kevin Galligan — Mon, 16 Dec 2019 17:52:55 +0000

Back in part 1, you learned a bit about KN's state rules, installed and ran Intellij, and ran some sample code. In part 2 we'll dig a little deeper.

First, update the sample! There may have been repo changes. Undo anything local and run git pull.

git checkout .
git pull

3) Global State

Before we get into actual concurrent code, lets chat a bit about global state. Some things in Kotlin can be referenced globally, from any thread. As a result, KN treats them with special rules.

These are kind of weird. However, there are only 2 types of global state, so just remember the weirdness.

`object` is frozen

Any global object is frozen, but that instance can be shared and referenced from any thread.

Find 3) Global State in SampleMacos.kt and uncomment cantChangeThis().

fun cantChangeThis(){
    println("i ${DefaultGlobalState.i}")
    DefaultGlobalState.i++
    println("i ${DefaultGlobalState.i}") //We won't get here
}

object DefaultGlobalState{
    var i = 5
}

This will compile fine, but all global object instances are frozen by default, so you'll see your old friend InvalidMutabilityException.

If you need that state to be mutable you do have some options. You can use atomics, which we'll talk about later, but for now you can make that object thread local. That means each thread has it's own copy, and according to rule #1, mutable state == 1 thread.

Run canChangeThreadLocal().

fun canChangeThreadLocal(){
    println("i ${ThreadLocalGlobalState.i}")
    ThreadLocalGlobalState.i++
    println("i ${ThreadLocalGlobalState.i}")
}

@ThreadLocal
object ThreadLocalGlobalState{
    var i = 5
}

Notice the annotation @ThreadLocal. That tells the runtime that each thread has an instance defined. Running canChangeThreadLocal() will print

i 5
i 6

Keep in mind that if you were accessing ThreadLocalGlobalState from another thread, the value of i would be different.

Just an FYI. These rules apply to companion objects as well.

properties are main thread only

This is the "weird" rule. Global properties are neither thread local nor frozen. They are only visible to the main thread ¹. This will seem odd, but just keep it in mind.

To be clear, global functions are fine. We're just talking about global properties.

Run globalCounting()

fun globalCounting(){
    globalCounterData.i++
    println("count ${globalCounterData.i}")
    globalCounterData.i++
    println("count ${globalCounterData.i}")
}

var globalCounterData = SomeMutableData(33)

You'll see

count 34
count 35

We haven't explained how to leave the main thread yet, but as a quick preview to demonstrate that properties are main thread only, run globalCountingFail(). I won't show the code, but you'll get an exception:

kotlin.native.IncorrectDereferenceException: Trying to access top level value not marked as @ThreadLocal or @SharedImmutable from non-main thread
        at 0   KNConcurrencySamples.kexe   (blah blah blah)
        at 1   KNConcurrencySamples.kexe   (blah blah blah)
(etc)

Trying to access the top-level state fails².

You can annotate top-level state with either @ThreadLocal, which will give each thread a copy, or with @SharedImmutable, which will make that state frozen and shared. We'll skip the code for that, though, and move on.

Actual Concurrency

We're going to leave the main thread now. In other explanations, I start by going deep on Worker. Worker is KN's primary concurrency primitive. It's a job queue that has it's own private thread.

We won't be going over Worker. Assuming you are using a library to manage concurrency, you won't interact with Worker much, if at all. For a deeper understanding of what's happening, again I'd point you at my previous posts and talks, and if you're really curious, the JetBrains docs and videos go way into it.

Emerging Model

You can technically attempt to pass mutable state to other threads. In practice, KN concurrency libraries will freeze state when it goes between threads. This is true of the libraries we've been using internally, and the soon-to-be-released kotlinx.coroutines implementation.

In this post we'll create a simple background thread processor. In a later post, we'll look at the kotlix.coroutines preview.

4) Background

We've created a simple background task processor function to demonstrate crossing threads. The signature is this:

fun background(block: () -> Unit)

We're not going to walk through that code because it uses worker and requires understanding a bit more complexity than we need.

The important parts:

1) The argument is a function, which will be executed in another thread
2) That function argument itself will be frozen

Here is a basic example. Run basicBackground()

fun basicBackground(){
    println("Is main thread $isMainThread")
    background {
        println("Is main thread $isMainThread")
    }
}

We've also isMainThread, which will require you're doing this on a Mac unless we get a PR that enables other platform. Anyway, the function prints the following.

Is main thread true
Is main thread false

That gets us onto another thread to do work, but obviously doesn't do much. This next example will pass some state into the other thread.

This is very important to understand. If you were skimming the post, now is a good time to s l o w d o w n.

Run captureState():

fun captureState(){
    val sd = SomeData("Hello 🥶", 67)
    println("Am I frozen? ${sd.isFrozen}")
    background {
        println("Am I frozen now? ${sd.isFrozen}")
    }
}

This will print:

Am I frozen? false
Am I frozen now? true

It is very important to understand that function args can capture state, and when they are frozen, that state is also frozen.

As an alternate visualization, see below. When we call background, that function argument is frozen, and since it captures sd, which is a local val in the calling function, sd is also frozen.

Local values are easy to understand and deal with. Where this becomes more problematic, and triggers more controversy, is when unintended state is captured.

Run captureTooMuch()

We'll be using a more complex model class that has a number you can increment, and when you do, we push that value into a "database" in the background:

class CountingModel{
    var count = 0

    fun increment(){
        count++
        background {
            saveToDb(count)
        }
    }

    private fun saveToDb(arg:Int){
        //Do some db stuff
    }
}

Our function to use the model looks like this:

fun captureTooMuch(){
    val model = CountingModel()
    model.increment()
    println("I have ${model.count}")

    model.increment()
    println("I have ${model.count}") //We won't get here
}

What's the result? Our old friend, InvalidMutabilityException!

I have 1
Uncaught Kotlin exception: kotlin.native.concurrent.InvalidMutabilityException: mutation attempt of frozen sample.CountingModel@17e01008
        at 0   KNConcurrencySamples.kexe   (nah)
        at 1   KNConcurrencySamples.kexe   (meh)
(etc)

To help illustrate the issue here, consider captureTooMuchAgain()

fun captureTooMuchAgain(){
    val model = CountingModel()
    println("model is frozen ${model.isFrozen}")
    model.increment()
    println("model is frozen ${model.isFrozen}")
}

This prints

model is frozen false
model is frozen true

count is an instance var of CountingModel, so capturing count in that way will capture the whole model and freeze it.

To help avoid this, it is good practice to move thread-jumping code to another function, and only capture function arguments. Try captureArgs():

fun captureArgs(){
    val model = CountingModelSafer()
    model.increment()
    println("I have ${model.count}")

    model.increment()
    println("I have ${model.count}")
}

class CountingModelSafer{
    var count = 0

    fun increment(){
        count++
        saveToDb(count)
    }

    private fun saveToDb(arg:Int) = background {
        println("Doing db stuff with $arg, in main $isMainThread")
    }
}

Debugging

Going back to captureTooMuch(), we get the InvalidMutabilityException when we try to increment, but that's not super helpful. We want to know when/how our data got frozen in the first place. Obviously, in this example, it's not hard to track down, but in more complex examples it will be.

You can mark an object that should never be frozen with ensureNeverFrozen(). When freeze is happening, the runtime will throw an exception at the point of freezing. Run captureTooMuchSource()

fun captureTooMuchSource(){
    val model = CountingModel()
    model.ensureNeverFrozen()
    model.increment()
    println("I have ${model.count}") //We won't even get here
}

That will get us an exception that traces right back to the root issue:

Uncaught Kotlin exception: kotlin.native.concurrent.FreezingException: freezing of sample.CountingModel.$increment$lambda-0$FUNCTION_REFERENCE$2@7d601058 has failed, first blocker is sample.CountingModel@7d601008
        at 0   KNConcurrencySamples.kexe   (ugh)
        at 1   KNConcurrencySamples.kexe   (stuff)
(skip a few lines...)
        at 13  KNConcurrencySamples.kexe           0x00000001088c570d kfun:sample.background(kotlin.Function0<kotlin.Unit>) + 301 (/Users/kgalligan/temp/KNConcurrencySamples/src/macosMain/kotlin/sample/BackgroundSupport.kt:12:12)
        at 14  KNConcurrencySamples.kexe           0x00000001088c5102 kfun:sample.CountingModel.increment() + 258 (/Users/kgalligan/temp/KNConcurrencySamples/src/macosMain/kotlin/sample/Background.kt:35:9)
        at 15  KNConcurrencySamples.kexe           0x00000001088c547e kfun:sample.captureTooMuchSource() + 286 (/Users/kgalligan/temp/KNConcurrencySamples/src/macosMain/kotlin/sample/Background.kt:77:11)

The stack trace is a bit verbose, but you'll be able to walk back to the source issue.

End

That's a wrap for Part 2. In Part 3 we'll wrap up the primitives with atomics, then introduce various libraries you can use for concurrency in you applications.

I don't know for sure why they made that decision. However, I suspect it's because you can get into trouble. Early on, global vals were thread-local. If you create a Worker as a global, it'll start a new thread. That thread gets it's own Worker, which starts a new thread. Etc. Good times. KN no longer does this. ↩
Sort of? Apparently, simple integer data at least can be shared and mutable. Run globalCountingTil(). You'll need to add that method manually to main. It lets you edit a global Int. Not sure how why, but investigating. ↩

Practical Kotlin Native Concurrency

Kevin Galligan — Mon, 16 Dec 2019 17:51:17 +0000

One of the more confusing things about Kotlin Native (henceforth 'KN') for new developers is the state and concurrency model. In general, Kotlin developers come from the JVM, and expect everything to be the same. It is not.

However, although different, the model is conceptually simple. With practice, getting your head around it is not too difficult.

This post series is part of the KMP Starter Kit available here: https://go.touchlab.co/kampdevto

Why?

Languages like Java, C++, Swift/Objc, let multiple threads access the same state in an unrestricted fashion. It is up to you, the developer, to avoid doing bad things. Concurrency issues are unlike other programming issues in that they are often very difficult to reproduce. You won't see them locally, but in production, at load, they emerge.

Just because your tests pass does not mean your code is OK.

Not all languages are designed this way. Most familiar to developers would be Javascript. You can achieve some level of concurrency with Worker, but you can't reference and modify the same state at the same time. The language Rust is built for performance and safety. Concurrency management is designed into the language, so it is essentially like C++ minus the inherent risk of unrestricted shared state ¹.

KN has rules around how state is shared between threads. These rules exist for KN but not Kotlin JVM (henceforth KJ). However, a critical goal of Kotlin Multiplatform is that the various versions of Kotlin remain source-compatible. Changing the language itself to enforce concurrency (like Rust), while in some ways appealing, would break support for JS and JVM. Thus, the new rules for KN are implemented and enforced in the runtime.

Two Rules

The new rules are conceptually simple.

1) Mutable state == 1 thread

If your state is mutable, only one thread can "see" it at a time. We'll explain what that means later, but assume all state is "mutable", and if you aren't doing any concurrency, KN will feel pretty much the same as anything else you've written in Kotlin (except if you use a top-level property or companion object. See "Global State" in Part 2 for detail).

The goal of rule 1 is simple. If there's only 1 thread, you don't have concurrency issues. Technically this is referred to as "thread confinement". For native mobile and desktop UI developers, this should be familiar. You cannot change the UI from a background thread. KN has generalized that concept.

2) Immutable state == many threads

If state can't be changed, it can be shared between threads. This is also conceptually simple.

That's it. Two rules.

How that is implemented, and the implications, are obviously more involved, but the basic concepts underlying KN and concurrency are very simple.

Status

Just a quick sidebar on the status of KN and it's concurrency rules. The community has been growing over the past few years, and there is pressure to relax these rules to make the transition from KJ easier. That may continue over time, but not in a breaking way. That means, it's possible these rules will be relaxed a bit in 2020, but code written now will work. There is also pressure to keep these rules, and simply improve the onboarding experience. You could say I'm in that camp, hence this post. Anyway...

Code!!!

First, get the sample. To use the sample you'll need Intellij Community (or Ultimate) 2019.3 or higher.

Clone the sample repo:

touchlab / KNConcurrencySamples

Once cloned, open the sample project in Intellij.

1) Simple State

First we'll start with some basic state. Basic vars, mutating values. Not super interesting. Just showing how things work when you're not doing any concurrency.

Open the sample project in Intellij. Find SampleMacos.kt. In the main function there will be code that is commented out. Look for 1) Simple State and uncomment runSimpleState().

Over on the right of the IDE, find "Gradle", then in that window, find runDebugExecutableMacos and double-click.

This is a very basic sample. It is demonstrating that state which is in a single thread is mutable as usual.

fun runSimpleState(){
    val s = SimpleState()
    s.increment()
    s.increment()
    s.report()
    s.decrement()
    s.report()
}

class SimpleState{
    var count = 0

    fun increment(){
        count++
    }

    fun decrement(){
        count--
    }

    fun report(){
        println("My count $count")
    }
}

This will print:

My count 2
My count 1

Moving on...

2) Frozen State

All state is mutable unless it is frozen. Frozen state is a new concept for Kotlin, although it exists in some other languages. In KN, there is a function freeze() defined on all classes. When you call freeze(), that object and everything it touches is frozen and immutable.

Once frozen, state can be shared between threads, but it cannot be changed.

Look for "2) Frozen State" in the SampleMacos.kt. Uncomment freezeSomeState() and run it (by "run it" from now on I mean run runDebugExecutableMacos again).

fun freezeSomeState(){
    val sd = SomeData("Hello 🐶", 22)
    sd.freeze()

    println("Am I frozen? ${sd.isFrozen}")
}

data class SomeData(val s:String, val i:Int)

You should see

Am I frozen? true

Understand that your state is being changed at runtime. There is a flag on every object in KN that says if it is frozen or not, and for sd we have just flipped it to true.

Back in SampleMacos.kt, comment out any other uncommented method, and uncomment failChanges(). Run again.

This will fail with an exception. The output console in Intellij can be a little confusing to navigate. Make sure you click the top level to see the full output.

The code is as follows

fun failChanges(){
    val smd = SomeMutableData(3)
    smd.i++
    println("smd: $smd")

    smd.freeze()
    smd.i++
    println("smd: $smd") //We won't actually get here
}

data class SomeMutableData(var i:Int)

The output looks like this

smd: SomeMutableData(i=4)
Uncaught Kotlin exception: kotlin.native.concurrent.InvalidMutabilityException: mutation attempt of frozen sample.SomeMutableData@8b40c4b8
        at 0   KNConcurrencySamples.kexe  (yada yada)
        at 1   KNConcurrencySamples.kexe  (yada yada)
(etc)

The important points. Before we freeze the object, you can change the var value. After we freeze, if you try to change the value, it'll throw an exception. InvalidMutabilityException, to be precise.

InvalidMutabilityException is your new friend. You will probably not feel that way at first, but it is.

When you see InvalidMutabilityException, it means you are attempting to change some state that has been frozen. You probably did not want this state to be frozen, so your job will be to figure out why it was frozen. Remember, when you freeze something, everything it touches is frozen. We'll talk about this in detail later. All I can say from experience is, at first this will be somewhat confusing. Pretty soon it won't be. Just understand the system and the tools you can use to debug.

End

That's it for part one. We have installed the IDE, and run some basic sample functions. We have not written any concurrent code yet. Step one is simply understanding the basics.

These posts are intended to be a functional intro to concurrency on KN. We're going to skip over a lot and just present what you're likely to use day to day. If you'd like a deeper dive, check out Stranger Threads and my Kotlinconf talk.

Yes, I'm sure Rust is other things too, but in this context... ↩

Kotlin Native iOS Crash Reporting

Kevin Galligan — Tue, 26 Nov 2019 23:54:58 +0000

Crash reporting tools are critical to the success of any mobile product. Knowing when things fail, and how, is information you need to make sure things are running smoothly.

The Problem

Kotlin code running on iOS has an issue specific to the design differences between the JVM and iOS. The JVM and Kotlin rely on exceptions, while iOS really does not.

When a crash happens on Android in the JVM, an exception will bubble up until something catches it. If it makes its way to the default exception handler, the app generally "crashes", with maybe a report to a crash reporting library.

On iOS, without exception propagation, the system simply "crashes". The crash reporting tool will capture the state of the threads at that moment.

For Kotlin, this introduces a problem. To stay consistent with Kotlin on the JVM, exceptions propagate in the same way on iOS. At the border between Swift/Objc and Kotlin, uncaught exceptions will trigger a crash. Because of how iOS crashes work, that looks like this:

They all end with konan::abort(), which internally force-kills the app. For crash reporting, that isn't super useful.

You can add the stack trace in the crash report log as a string, but you may lose detail, and in any case, the errors won't be grouped by the stack trace.

Kotlin 1.3.60 introduces crash data being written to the iOS internal crash log and better symbolication support. You can get the crash data from the local device, if you have access to it, or Apple's developer site, but neither is ideal in many cases.

Introducing CrashKiOS

CrashKiOS (Crash reporting for Kotlin iOS) is a simple library that let's you send symbolicated crash reports to crash reporting systems like Crashlytics and Bugsnag. It leverages the crash data improvements in Kotlin 1.3.60, and uses the existing crash reporting API's.

The end result is crash reports that look more like this:

You can find setup and config details in the README.

How it Works

Conceptually, the way it works is we add a default exception handler to the Kotlin code, which will be triggered if an exception winds its way to the interface between Kotlin and Swift/Objc.

We define an open class that gets called from that default exception handler. That class is extended in Swift (or Objc), and the report is sent to the crash reporting system.

There are two basic options. Get the raw Throwable, or get the parts of the crash necessary to be sent to the crash reporting tool.



fun crash(t: Throwable)

fun crashParts(addresses: List<Long>, exceptionType: String, message: String)

In our current implementations, reports are all "handled errors", as there is no published way to send a custom fatal crash, but we'll be looking into ways to do that in the future.

For both Crashlytics and Bugsnag, rather than provide the stack trace as a string, we supply the code addresses, which are translated back to the source code lines by way of dsym files. For Crashlytics, that looks like the following.



class CrashlyticsCrashHandler: CrashkiosCrashHandler {
    override func crashParts(
        addresses: [KotlinLong],
        exceptionType: String,
        message: String) {
        let clsStackTrace = addresses.map {
            CLSStackFrame(address: UInt(truncating: $0))
        }

        Crashlytics.sharedInstance().recordCustomExceptionName(
            exceptionType,
            reason: message,
            frameArray: clsStackTrace
        )
    }
}

clsStackTrace is a stack trace built from the code addresses. Both Crashlytics and Bugsnag can take that info and produce a stack trace. Presumably other crash reporting tools would work the same way.

Just FYI

The last couple stack lines are generally boilerplate exception initialization, which we strip out (the screenshot above was from an earlier version where those lines were left in). That logic may need more tweaking over time.

Currently, Kotlin debug builds give line numbers while release builds only provide function names. Hopefully we'll have better config for that after some more research.

We'll be making improvements over time as we learn more about how iOS deals with crash reports and how to better integrate with vaious crash reporting systems. If you'd like to add a different system, or have some ideas about how to improve support, please reach out (@kpgalligan on twitter, or find me in the Kotlin Slack).

Touchlab KMP Stuff!

Touchlab is publishing a Kotlin Multiplatform evaluation kit for orgs interested in the tech, called the KaMP Kit. You can get access by going to our signup form. Also, we're hiring mobile developers, in particular people experienced in or at least interested in multiplatform tech. See our careers page for more info.

Kotlin Native Coroutines Preview

Kevin Galligan — Fri, 15 Nov 2019 18:42:37 +0000

Very recently, a draft PR (#1648) landed in the kotlinx.coroutines github that will enable multithreaded coroutines in Kotlin Native (KN). This is a big deal for the technology, and a lot of people have been waiting for it. I tweeted a little screenshot, and just that got a fair bit of attention

// Detect dark theme var iframe = document.getElementById('tweet-1195083478825684992-99'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1195083478825684992&theme=dark" }

It is not a stretch to say a lot of developers have been waiting for this, as one of the tweet replies highlights:

// Detect dark theme var iframe = document.getElementById('tweet-1195376410522738688-361'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1195376410522738688&theme=dark" }

To be clear, as much as this is a good thing technically, I think it's a big deal psychologically. You could achieve concurrency before multithreaded coroutines, and there are certain to be issues as the implementation emerges. However, a lot of people were waiting for this. There are technical reasons people were waiting, but in a more general sense, it's a reality signal. Multithreaded Coroutines make Kotlin Native more "real". In the JVM world, coroutines have been dominating the conversation around concurrency, so the lack of "full" coroutines in native was a signal that it's wasn't ready, or not a priority. That is changing.

What does this mean? In short, a big block to adoption has been removed. There's a lot of library work around architecture and concurrency that hasn't been happening because those implementations would largely be obsolete once multithreaded coroutines emerged. That block has been removed. We should expect a lot of follow-on library work, tech talks, and blog posts. Shortly after that, a lot of production deployment.

In short, a big block to adoption has been removed.

There has also been uncertainty around the threading model. Going back to the summer, the Kotlin Native repo got an experimental addition. Relaxed mode. It essentially let you access shared memory just like you can in the JVM. Whether that is a good thing or not is a much longer debate (which I'll be talking about at Kotlinconf). However, a lot of the community assumed relaxed mode existed in preparation for multithreaded coroutines. If relaxed mode became popular, it would probably end strict mode, but it was unclear which way things would go. There was a lot of uncertainty.

The uncertainty around Kotlin Native's state model is gone. Multithreaded coroutines work within the strict state model of Kotlin Native. That means although relaxed mode may be supported in the future, it is not the primary direction of the platform. Strict mode is here to stay.

The uncertainty around Kotlin Native's state model is gone.

We are currently in the middle of November. PR #1648 is still working it's way through completion. I would assume there is some release by Kotlinconf, which is ~3 weeks away. Just in time for people taking holidays to poke around. I'd expect to see a bit of activity in the community before the new year.

We will be doing an update to the DroidconKotlin app, using a few new libraries and, of course, multithreaded coroutines. Hopefully, we'll have a version of that out before Droidcon SF, but if not, sometime in December.

This is also a good time to tell you about our KaMP Kit. We've been talking to orgs evaluating Kotlin Multiplatform who have had some trouble getting started. The platform is moving fast, and there's a lot of conflicting or outdated info out there on the web. The KaMP Kit is a set of starter repos and documentation to get you set up for success quickly. Our first version will be released in mid-December. Go here to sign up for early access.

Touchlab is hiring mobile engineers excited about Kotlin Multiplatform. We are a remote friendly org. Come check that out if interested.

Debugging Kotlin Native’s Compiler

Kevin Galligan — Sun, 26 May 2019 20:22:49 +0000

In order to add generics to header output in Kotlin Native, I had to kind of reverse engineer the Kotlin native compiler using a debugger 👎. Attaching a debugger to the Konan compiler requires a few steps, but is relatively straightforward.

Step 1: Build Kotlin Native

You’ll need to clone KN and make sure to create a branch pointing at the version you want to use. As the docs state, this will take at least an hour, and in my experience, that’s optimistic, but it’s generally a trouble free build. Just take a walk/nap.

Step 2: Create Sample Project

When you run into a compile issue, it may be in the context of a much larger application. While you could directly debug on that, I’d suggest making a minimal sample that surfaces the same issue. It’ll save you time.

Step 3: Config Sample Project

You need to point the sample project at your local Konan build, and tell the compiler you want to attach a debugger. Add the following to your gradle.properties:

org.jetbrains.kotlin.native.home=[Koltin Native Clone Dir]/dist
org.jetbrains.kotlin.native.jvmArgs=-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5006
Replace [Kotlin Native Clone Dir] with whatever dir you built KN in. That will tell the kotlin plugin to use that instead of the regular compiler and runtime. The second line makes the konan compiler wait for a remote debugger to connect.

Step 4: Config Remote Debugger (the easy part)

Open the Kotlin Native repo in Intellij (it’s a gradle project). Once that’s open, create a remote debugger config.

Edit Configurations

Add ‘Remote’

Set Port to 5006

If you look back to step 3, we set the port to 5006

org.jetbrains.kotlin.native.jvmArgs=-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5006
Make sure that’s set in your Remote config.

Step 5: Profit

Now go back to your test project and build it. I generally do that on the command line with ./gradlew build. You’ll get a message telling you to attach a debugger.

Go back to the Kotlin Native Intellij project and run the Remote config. It’ll attach and let the compiler run.

In my testing, I actually needed to debug a different task, so I’d need to attach the debugger twice. I’d see this back in the sample project…

So, while a little clunky, just attach again.

Also, don’t forget to add breakpoints in the compiler code, which is the point.

Running the test app and debugger together in a video (sorry about audio. Will redo with a real mic if there’s interest)

Debug Video

👎 There is some anti-debugger feelings out there in TDD land, but the idea that debuggers are bad practice completely ignores the discovery use case, which is huge. This is a fantastic example of that. I really dislike the “real developers don’t use debuggers” attitude. Just ranting a bit about that here. Anyway…

DEV Community: Kevin Galligan

Ktor and Kotlin/Native

Ktor and Kotlin/Native

The Coroutines Situation

Ktor

Kotlin and Ktor 1.4 release

touchlab-lab / ktorcoroutines

Just showing ktor fix in 1.4.0

Issues

TL;DR

touchlab / KaMPKit

KaMP Kit by Touchlab is a collection of code and tools designed to get your mobile team started quickly with Kotlin Multiplatform.

Kotlin/Native Concurrency Changes…

Unpacking The Post

What now?

Debugging Kotlin on iOS with Xcode

Installing

Configure Kotlin

touchlab / KotlinCocoapods

Kotlin Files in Xcode

What's Next?

Reach Out

Kotlin/Native - Isolated State

Stately Collections V1

touchlab / Stately

Kotlin Multiplatform State Library

Stately Collections V2 (Isolated State)

Performace

touchlab-lab / StatelyIsoStateSample

Stately IsolatedState sample

Hiring!

MutableMap Implementation

Kotlin/Native - Transferring State

Transferring State

Performance

Hiring!

Kapture - Kotlin/Native State Capture

Library Model

Kapture

Education

Hot Functions

Mutability Analysis

80/20

Evaluation

Special Thanks

Practical Kotlin Native Concurrency Part 3

Atomics

touchlab / Stately

Kotlin Multiplatform State Library

Kotlin / kotlinx-atomicfu

The idiomatic way to use atomic operations in Kotlin

Atomic Primitives

Coroutines

kotlinx.coroutines Multithreaded Preview

Kotlin / kotlinx.coroutines

Library support for Kotlin coroutines

Overview

Return Values

touchlab / DroidconKotlin

Kotlin Multiplatfom app for Droidcon Events

CoroutineWorker

Autodesk / coroutineworker

Kotlin Coroutine-based workers for native

Reaktive

badoo / Reaktive

Kotlin multi-platform implementation of Reactive Extensions

What's next?

Kotlin Native Stranger Threads. Episode 1 — Worker | by Kevin Galligan | Medium

Kevin Galligan ・ Jan 8, 2019 ・ Medium

Practical Kotlin Native Concurrency Part 2

3) Global State

object is frozen

properties are main thread only

Actual Concurrency

Emerging Model

4) Background

Debugging

End

Practical Kotlin Native Concurrency

Why?

Kevin Galligan ・ Jan 8, 2019 ・
Medium

`object` is frozen