Bump kotlinx.coroutines version to 0.26.1 (#11)

Bumped Kotlin version to `1.2.61`, as the `kotlinx.coroutines`
[GitHub page] states:

> This is a companion version for Kotlin 1.2.61 release.

[GitHub page]: https://github.com/Kotlin/kotlinx.coroutines

Author: twyatt

README.md

@@ -107,7 +107,7 @@ sealed class ConnectGattResult {
 
 <sup>1</sup> _Suspends until `STATE_CONNECTED` or non-`GATT_SUCCESS` is received._<br/>
 <sup>2</sup> _Suspends until `STATE_DISCONNECTED` or non-`GATT_SUCCESS` is received._<br/>
-<sup>3</sup> _Throws `RemoteException` if underlying `BluetoothGatt` call returns `false`._
+<sup>3</sup> _Throws [`RemoteException`] if underlying [`BluetoothGatt`] call returns `false`._
 
 ### Details
 
@@ -117,6 +117,128 @@ function. This extension function acts as a replacement for Android's
 [`BluetoothDevice.connectGatt(context: Context, autoConnect: Boolean, callback: BluetoothCallback): BluetoothGatt?`]
 method (which relies on a [`BluetoothGattCallback`]).
 
+### Prerequisites
+
+**Able** expects that Android Bluetooth Low Energy is supported
+([`BluetoothAdapter.getDefaultAdapter()`] returns non-`null`) and usage prerequisites
+(e.g. [bluetooth permissions]) are satisfied prior to use; failing to do so will result in
+[`RemoteException`] for most **Able** methods.
+
+## Structured Concurrency
+
+Kotlin Coroutines `0.26.0` introduced [structured concurrency].
+
+When establishing a connection (e.g. via
+`BluetoothDevice.connectGatt(context: Context, autoConnect: Boolean): ConnectGattResult` extension
+function), if the Coroutine is cancelled then the in-flight connection attempt will be cancelled and
+corresponding [`BluetoothGatt`] will be closed:
+
+```kotlin
+class ExampleActivity : AppCompatActivity(), CoroutineScope {
+
+    protected lateinit var job: Job
+    override val coroutineContext: CoroutineContext
+        get() = job + Dispatchers.Main
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        job = Job()
+
+        val bluetoothDevice: BluetoothDevice = TODO("Retrieve a `BluetoothDevice` from a scan.")
+
+        findViewById<Button>(R.id.connect_button).setOnClickListener {
+            launch {
+                // If Activity is destroyed during connection attempt, then `result` will contain
+                // `ConnectGattResult.Canceled`.
+                val result = bluetoothDevice.connectGatt(this@ExampleActivity, autoConnect = false)
+
+                // ...
+            }
+        }
+    }
+
+    override fun onDestroy() {
+        super.onDestroy()
+        job.cancel()
+    }
+}
+```
+
+In the above example, the connection process is tied to the Activity lifecycle. If the Activity is
+destroyed (e.g. due to device rotation or navigating away from the Activity) then the connection
+attempt will be cancelled. If it is desirable that a connection attempt proceed beyond the Activity
+lifecycle then the [`launch`] can be executed in the global scope via `GlobalScope.launch`, in which
+case the [`Job`] that [`launch`] returns can be used to manually cancel the connection process (when
+desired).
+
+Alternatively, if (for example) an app has an Activity specifically designed to handle the
+connection process, then Android Architecture Component's [`ViewModel`] can be scoped (via
+`CoroutineScope` interface) allowing connection attempts to be tied to the `ViewModel`'s lifecycle:
+
+```kotlin
+class ExampleViewModel(application: Application) : AndroidViewModel(application), CoroutineScope {
+
+    private val job = Job()
+    override val coroutineContext: CoroutineContext
+        get() = job + Dispatchers.Main
+
+    fun connect(bluetoothDevice: BluetoothDevice) {
+        launch {
+            // If ViewModel is destroyed during connection attempt, then `result` will contain
+            // `ConnectGattResult.Canceled`.
+            val result = bluetoothDevice.connectGatt(getApplication(), autoConnect = false)
+
+            // ...
+        }
+    }
+
+    override fun onCleared() {
+        job.cancel()
+    }
+}
+```
+
+Similar to the connection process, after a connection has been established, if a Coroutine is
+cancelled then any `Gatt` operation executing within the Coroutine will be cancelled.
+
+However, unlike the `connectGatt` cancellation handling, an established `Gatt` connection will
+**not** automatically disconnect or close when the Coroutine executing a `Gatt` operation is
+canceled. Special care must be taken to ensure that Bluetooth Low Energy connections are properly
+closed when no longer needed, for example:
+
+```kotlin
+val gatt: Gatt = TODO("Acquire Gatt via `BluetoothDevice.connectGatt` extension function.")
+
+launch {
+    try {
+        gatt.discoverServices()
+        // todo: Assign desired characteristic to `characteristic` variable.
+        val value = gatt.readCharacteristic(characteristic).value
+        gatt.disconnect()
+    } finally {
+        gatt.close()
+    }
+}
+```
+
+The `Gatt` interface adheres to [`Closeable`] which can simplify the above example by using [`use`]:
+
+```kotlin
+val gatt: Gatt = TODO("Acquire Gatt via `BluetoothDevice.connectGatt` extension function.")
+
+gatt.use { // Will close `gatt` if any failures or cancellation occurs.
+    gatt.discoverServices()
+    // todo: Assign desired characteristic to `characteristic` variable.
+    val value = gatt.readCharacteristic(characteristic).value
+    gatt.disconnect()
+}
+```
+
+It may be desirable to manage Bluetooth Low Energy connections entirely manually. In which case,
+Coroutine [`GlobalScope`] can be used for both the connection process and operations performed while
+connected. In which case, the returned `Gatt` object (after successful connection) can be stored and
+later used to disconnect **and** close the underlying `BluetoothGatt`.
+
 ## Example
 
 The following code snippet makes a connection to a [`BluetoothDevice`], reads a characteristic,
@@ -179,6 +301,16 @@ limitations under the License.
 [`BluetoothGattCallback`]: https://developer.android.com/reference/android/bluetooth/BluetoothGattCallback.html
 [`BluetoothDevice`]: https://developer.android.com/reference/android/bluetooth/BluetoothDevice.html
 [`BluetoothDevice.connectGatt(context: Context, autoConnect: Boolean, callback: BluetoothCallback): BluetoothGatt?`]: https://developer.android.com/reference/android/bluetooth/BluetoothDevice.html#connectGatt(android.content.Context,%20boolean,%20android.bluetooth.BluetoothGattCallback)
+[`RemoteException`]: https://developer.android.com/reference/android/os/RemoteException
 [Coroutines]: https://kotlinlang.org/docs/reference/coroutines.html
+[`Closeable`]: https://docs.oracle.com/javase/7/docs/api/java/io/Closeable.html
+[`GlobalScope`]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-global-scope/
 [suspension functions]: https://kotlinlang.org/docs/reference/coroutines.html#suspending-functions
+[structured concurrency]: https://medium.com/@elizarov/structured-concurrency-722d765aa952
+[bluetooth permissions]: https://developer.android.com/guide/topics/connectivity/bluetooth#Permissions
+[`Job`]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-job/index.html
+[`launch`]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/launch.html
+[`ViewModel`]: https://developer.android.com/topic/libraries/architecture/viewmodel
+[`use`]: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.io/use.html
+[`BluetoothAdapter.getDefaultAdapter()`]: https://developer.android.com/reference/android/bluetooth/BluetoothAdapter#getDefaultAdapter()
 [Recipes]: documentation/RECIPES.md

build.gradle

@@ -19,8 +19,8 @@ buildscript {
 
         'able': getVersionName(),
 
-        'kotlin': '1.2.51',
-        'coroutines': '0.24.0',
+        'kotlin': '1.2.61',
+        'coroutines': '0.26.1',
 
         'kotlinTestJunit': '1.2.51',
         'mockitoKotlin': '2.0.0-RC1',
@@ -53,6 +53,7 @@ allprojects {
 subprojects {
     tasks.withType(Test) {
         testLogging {
+            // For more verbosity add: "standardOut", "standardError"
             events "passed", "skipped", "failed"
             exceptionFormat "full"
             showExceptions true

core/src/main/java/messenger/Messenger.kt

@@ -11,6 +11,7 @@ import com.juul.able.experimental.messenger.Message.ReadCharacteristic
 import com.juul.able.experimental.messenger.Message.RequestMtu
 import com.juul.able.experimental.messenger.Message.WriteCharacteristic
 import com.juul.able.experimental.messenger.Message.WriteDescriptor
+import kotlinx.coroutines.experimental.GlobalScope
 import kotlinx.coroutines.experimental.channels.actor
 import kotlinx.coroutines.experimental.channels.consumeEach
 import kotlinx.coroutines.experimental.newSingleThreadContext
@@ -23,7 +24,7 @@ class Messenger internal constructor(
     internal suspend fun send(message: Message) = actor.send(message)
 
     private val context = newSingleThreadContext("Gatt")
-    private val actor = actor<Message>(context) {
+    private val actor = GlobalScope.actor<Message>(context) {
         Able.verbose { "Begin" }
         consumeEach { message ->
             Able.debug { "Waiting for Gatt" }

throw/README.md

@@ -3,14 +3,15 @@
 Adds extension functions that `throw` exceptions on failures for various BLE operations.
 
 ```kotlin
-fun connect(context: Context, device: BluetoothDevice) = launch(UI) {
+fun connect(context: Context, device: BluetoothDevice) = launch {
     device.connectGattOrThrow(context, autoConnect = false).use { gatt ->
         gatt.discoverServicesOrThrow()
 
         val characteristic = gatt
             .getService("F000AA80-0451-4000-B000-000000000000".toUuid())!!
             .getCharacteristic("F000AA83-0451-4000-B000-000000000000".toUuid())
         val value = gatt.readCharacteristicOrThrow(characteristic).value
+        println("value = $value")
 
         gatt.disconnect()
     }