Stately

by touchlab

touchlab / Stately

Kotlin Multiplatform State Library

233 Stars 16 Forks Last release: 2 months ago (1.1.0) Apache License 2.0 130 Commits 12 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Stately

Stately is a state utility library to facilitate state management in Kotlin Multiplatform.

Kotlin JVM has the same rules around concurrency and state that Java has. In essence, multiple threads can access shared state in an unrestricted fashion, and it is up to the developer to ensure safe concurrency. Kotlin/Native, on the other hand, introduces new restrictions around concurrent state access (more info). Additionally, Kotlin/JS lives in the Javascript threading world, which means just the one thread.

We publish all of our libraries to

mavenCentral()
, so make sure to add that repository.
repositories {
   mavenCentral()
}

Stately provides various modules to facilitate writing shared code within these different worlds.

stately-common

Kotlin/Native state adds some concepts that don't exist in either the JVM or JS, as well as the annotation @Throws.

stately-common
is very simple. It includes common definitions for
freeze()
,
isFrozen
, and
ensureNeverFrozen()
, and as mentioned
@Throws
. These definitions, 2 functions, a val, and an annotation, are often source-copied into other libraries.
stately-common
's sole purpose is to define these as minimally as possible, to be included in apps or other libraries.

On native, these values delegate or are typealiased to their platform definitions. In JS and the JVM, they do nothing.

Config

commonMain {
    dependencies {
        implementation 'co.touchlab:stately-common:1.0.x'
    }
}

stately-concurrency

stately-concurrency
includes some concurrency support classes. These include a set of
Atomicxxx
classes, a
Lock
, a
ThreadLocal
container, and a class
ThreadRef
that allows you to hold a thread id.

Much of the functionality of this module is similar to atomic-fu. They differ in some ways, so while they both cover much of the same ground, Stately's version still has some use.

ThreadRef
is unique to Stately. It allows you to capture a reference to the id of the thread in which it was created, and ask if the current thread is the same. Just FYI, it does not keep a reference to the actual thread. Just an id. Usage looks like this:
fun useRef(){
  val threadRef = ThreadRef()
  threadRef.same() // 

Config

commonMain {
    dependencies {
        implementation 'co.touchlab:stately-concurrency:1.0.x'
    }
}

stately-isolate

stately-isolate
creates mutable state in a special state thread, and restricts access to that state from the same thread. This allows the state held by an instance of
IsolateState
to remain mutable. State coming in and going out must be frozen, but the guarded state can change.

Read more about the design in this blog post.

The obvious use case is for collections. Example usage:

fun usage(){
    val cacheMap = IsolateState { mutableMapOf() }
    val key = "abc"
    val value = "123"
    cacheMap.access { it.put(key, value) }
    val valueString = cacheMap.access { it.get(key) }
    println(valueString) // 

The

cacheMap
above can be called from multiple threads. The lambda passed to the
access
method will be invoked on the same thread that the state was created on. Because it is a single thread, access is serialized and thread-safe.

You can create other instances of

IsolateState
by forking the parent instance.
fun usage(){
    val cacheMap = IsolateState { mutableMapOf() }
    val key = "abc"
    val value = "123"
    cacheMap.access { it.put(key, value) }

//Fork state
val entrySet = cacheMap.access { map -> 
    IsolateState(cacheMap.fork(map.entries)) 
}

val valueString = entrySet.access { entries -> entries.first().value }
println(valueString) // 

You can create a class that extends

IsolateState
and provides for simpler access.
class SimpleMap: IsolateState>({ mutableMapOf()})
{
    fun put(key:K, value:V):V? = access { it.put(key, value) }
    fun get(key: K):V? = access { it.get(key) }
}

stately-iso-collections
implements collections by extending
IsolateState
in this manner.

You must dispose of

IsolateState
instances to avoid memory leaks.
fun usage(){
    val cacheMap = IsolateState { mutableMapOf() }
    cacheMap.dispose()
}

Config

commonMain {
    dependencies {
        implementation 'co.touchlab:stately-isolate:1.0.x'
    }
}

stately-iso-collections

This is a set of mutable collections implemented with

IsolateState
. The set currently includes a
MutableSet
,
MutableList
,
MutableMap
, and an implementation of
ArrayDeque
that is being added to the Kotlin stdlib in 1.3.70.

Config

commonMain {
    dependencies {
        implementation 'co.touchlab:stately-iso-collections:1.0.x'
    }
}

stately-collections

A set of collections that can be shared and accessed between threads. This is pretty much deprecated, but we have no plans to remove it as some production apps use it.

However, we would strongly suggest you use

stately-isolate
and
stately-iso-collections
instead.
Collections implemented with

stately-isolate
are far more flexible and absolutely CRUSH the original
stately-collections
in performance benchmarks. See blog post.

Usage

Dependencies can be specified in the common source set, as shown above, if you have Gradle metadata enabled in

settings.gradle
.
enableFeaturePreview('GRADLE_METADATA')

License

Copyright 2020 Touchlab, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.