Improve exception message when attempting to connect a cancelled pe…

…ripheral (#808)

README.md

@@ -140,6 +140,9 @@ peripheral.launch {
 > ```kotlin
 > peripheral.cancel()
 > ```
+>
+> Once a [`Peripheral`] is cancelled (via `cancel`) it can no longer be used (e.g. calling `connect` will throw
+> `IllegalStateException`).
 
 > [!TIP]
 > `launch`ed coroutines from a `Peripheral` object are permitted to run until `Peripheral.cancel()` is called

kable-core/src/androidMain/kotlin/BluetoothDeviceAndroidPeripheral.kt

@@ -145,7 +145,7 @@ internal class BluetoothDeviceAndroidPeripheral(
     }
 
     override suspend fun connect(): CoroutineScope =
-        connectAction.await()
+        connectAction.awaitConnect()
 
     override suspend fun disconnect() {
         connectAction.cancelAndJoin(

kable-core/src/appleMain/kotlin/CBPeripheralCoreBluetoothPeripheral.kt

@@ -136,7 +136,7 @@ internal class CBPeripheralCoreBluetoothPeripheral(
     }
 
     override suspend fun connect(): CoroutineScope =
-        connectAction.await()
+        connectAction.awaitConnect()
 
     override suspend fun disconnect() {
         connectAction.cancelAndJoin(

kable-core/src/commonMain/kotlin/SharedRepeatableAction.awaitConnect.kt

@@ -0,0 +1,10 @@
+package com.juul.kable
+
+import kotlinx.coroutines.CoroutineScope
+
+internal suspend fun SharedRepeatableAction<CoroutineScope>.awaitConnect(): CoroutineScope =
+    try {
+        await()
+    } catch (e: IllegalStateException) {
+        throw IllegalStateException("Cannot connect peripheral that has been cancelled", e)
+    }

kable-core/src/commonMain/kotlin/SharedRepeatableAction.kt

@@ -86,6 +86,7 @@ internal class SharedRepeatableAction<T>(
 
     private suspend fun stateOrNull(): State<T>? = guard.withLock { state }
 
+    /** @throws IllegalStateException if parent [scope] is not active. */
     suspend fun await() = getOrCreate().action.await()
 
     /**

kable-core/src/jsMain/kotlin/BluetoothDeviceWebBluetoothPeripheral.kt

@@ -106,7 +106,7 @@ internal class BluetoothDeviceWebBluetoothPeripheral(
     }
 
     override suspend fun connect(): CoroutineScope =
-        connectAction.await()
+        connectAction.awaitConnect()
 
     override suspend fun disconnect() {
         connectAction.cancelAndJoin(