update docs for threading & createStore functions

Author: patjackson52

Diff for: website/docs/README.md

@@ -25,6 +25,8 @@
 - [Glossary](Glossary.md)
 - [API Reference](api/README.md)
   - [createStore](api/createStore.md)
+  - [createThreadSafeStore](api/createThreadSafeStore.md)
+  - [createSameThreadEnforcedStore](api/createSameThreadEnforcedStore.md)
   - [Store](api/Store.md)
   - [applyMiddleware](api/applyMiddleware.md)
   - [compose](api/compose.md)

Diff for: website/docs/api/createSameThreadEnforcedStore.md

@@ -0,0 +1,17 @@
+---
+id: createSameThreadEnforcedstore
+title: createSameThreadEnforcedStore
+sidebar_label: createSameThreadEnforcedStore
+hide_title: true
+---
+
+# `createSameThreadEnforcedStore(reducer, preloadedState, enhancer)
+
+Creates a Redux [store](Store.md) that can only be accessed from the same thread.  
+Any call to the store's functions called from a thread other than thread from which  
+ it was created will throw an IllegalStateException.
+
+ *Strongly* recommended that [`createThreadSafeStore()`](./createThreadSafeStore.md) is used unless there is
+ good reason to do otherwise.
+
+ see [`createStore()`](./createStore.md) for usage.

Diff for: website/docs/api/createStore.md

@@ -10,6 +10,13 @@ hide_title: true
 Creates a Redux [store](Store.md) that holds the complete state tree of your app.  
 There should only be a single store in your app.
 
+If using `createStore` directly, it will not be threadsafe.
+
+It is ***STRONGLY*** recommended that [`createThreadSafeStore()`](./createThreadSafeStore.md) is used unless there is
+ good reason to do otherwise.
+
+The rest of this doc applies to all `createStore` functions.
+
 #### Arguments
 
 1. `reducer` _(Reducer)_: A [reducing function](../Glossary.md#reducer) that returns the next 

Diff for: website/docs/api/createThreadSafeStore.md

@@ -0,0 +1,23 @@
+---
+id: createThreadSafeStore
+title: createThreadSafeStore
+sidebar_label: createThreadSafeStore
+hide_title: true
+---
+
+# `createThreadSafeStore(reducer, preloadedState, enhancer)
+
+Creates a Redux [store](Store.md) that is may be accessed from any thread.
+
+***This is the recommended way to create a store.***
+
+There is some performance overhead in using `createThreadSafeStore()` due to
+synchronization, however it is small and mostly likely not impact UI.
+
+Some quick benchmarks on an Android app have shown that:
+
+1. calling `getState` was always < 1ms with or without synchronization
+2. `dispatch` calls to 1-3ms longer with synchronization
+3. During a cold launch of app differences were more dramatic.  Some calls to `dispatch` took +100ms more than an store that was not synchronized.
+
+see [`createStore()`](./createStore.md) for usage.

Diff for: website/docs/introduction/Threading.md

@@ -7,24 +7,71 @@ hide_title: true
 
 # Redux on Multi-threaded Platforms
 
+TLDR; use [createThreadSafeStore()](../api/createThreadSafeStore.md), unless your Javascript only
+
 Redux in multi-threaded environments brings additional concerns that are not present in redux
 for Javascript.  Javascript is single threaded, so Redux.js did not have to address the issue.
 Android, iOS, and native do have threading, and as such attention must be paid to which threads interact with the store.
 
-As of ReduxKotlin 0.3.0 there is `same thread enforcement` for the [getState](../api/store#getstate-_or_-state-property), [dispatch](../api/store#dispatchaction-any-any), [replaceReducer](../api/store#replacereducernextreducer-reducer-state-unit),
-and [subscribe](../api/store#subscribelistener-storesubscriber) functions on the store.  This means these methods must be called from the same thread where
+In a multi-threaded system invalid states and race conditions can happen.
+For example if `getState` was called at the same time as a dispatch, the state could represent a past
+state.  Or 2 actions dispatched concurrently could cause an invalid state.
+
+**So you there are 3 options:**
+
+    1) Synchronize access to the store  - [createThreadSafeStore()](../api/createThreadSafeStore.md)
+    2) Only access the store from the same thread - [createSameThreadEnforcedStore()](../api/createSameThreadEnforcedStore.md)
+    3) Live in the wild west and access store anytime, any thread and live with consequences - NOT RECOMMENDED - [createStore()](../api/createStore.md)
+
+ReduxKotlin allows all these, but most cases will fall into #1.
+
+Starting with ReduxKotlin 0.5.0 there is a threadsafe store which uses synchronization (AtomicFu library)
+to allow safe access to all the functions on the store.  This is the recommended usage for 90% of use cases.
+
+```kotlin
+    val store = createThreadSafeStore(...)
+```
+
+Who is the other 10%? If you are only targeting Javascript thread safety is not an issue, so
+`createStore` is the way to go.  Other possible reasons could be applications that need optimal
+performance, however it is unlikely that the extra overhead from synchronization will be an issue.
+
+## Same thread enforcement
+
+Another option is `same thread enforcement`. This means these methods must be called from the same thread where
 the store was created.  An `IllegalStateException` will be thrown if one of these are called from a 
 different thread.
 
-If this `same thread enforcement` was not in place invalid states and race conditions could happen.  
-For example if `getState` was called at the same time as a dispatch, the state would represent a past
-state.  Or 2 actions dispatched concurrently could cause an invalid state.
+
+`Same thread enforcement` was the default behavior for ReduxKotlin 0.3.0 - 0.4.0.
 
 Note that this is __SAME__ thread enforcement - not __MAIN__ thread enforcement.  ReduxKotlin does not
 force you to use the main thread, although you can if you'd like.  Most mobile applications do redux on the main
 thread, however it could be moved to a background thread.  Using a background thread could be desirable 
 if the reducers & middleware processing produce UI effects such as dropped frames.
 
-
 Currently `same thread enforcement` is implemented for JVM, iOS, & macOS.  The other platforms
 have do not have the enforcement in place yet.
+
+To use `same thread enforcement`:
+```kotlin
+    val store = createSameThreadEnforcedStore(...)
+```
+
+
+***IF*** you are using vanilla `createStore()`, then you may use an different artifact,  
+and avoid pulling in AtomicFu dependency:
+
+```groovy
+kotlin {
+    sourceSets {
+        commonMain {
+            dependencies {
+                implementation "org.reduxkotlin:redux-kotlin:0.5.0"
+            }
+        }
+    }
+}
+```
+**ONLY USE THE ABOVE IF YOU DO NOT WANT THREAD SAFETY**
+