You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This release includes major internal re-workings of Kable, as well as some externally facing API changes. Most notably, the scanning and connection handling internals have been refactored to better leverage structured concurrency and provide a more predictable connection shutdown procedure.
The exception hierarchy has been significantly simplified, making error handling more consistent and possible in common code.
In general, you should now only ever need to catch IOException when calling Kable functions, all other exceptions should be considered programming error (could've been prevented either by pre-checking conditions). Pre-conditions that could change between a check and call are thrown as IOExceptions.
Deprecate Peripheral creation via CoroutineScope extension function
Creating a Peripheral via CoroutineScope extension function has been deprecated.
A Peripheral's connection needs to be explicitly managed, having its lifecycle be implicitly governed by a parent CroutineScope provided a footgun.
It is clearer / easier to reason about if a Peripheral shall be disposed of manually when it is no longer needed: the Peripheral.cancel function provides an explicit means of disposing of a Peripheral.
Old
New
val scope:CoroutineScopeval peripheral = scope.peripheral(advertisement) {
// Configure peripheral.
}
val peripheral =Peripheral(advertisement) {
// Configure peripheral.
}
val peripheral:Peripheral=..
peripheral.disconnect()
scope.cancel() // Dispose of `Peripheral`.
val peripheral:Peripheral=..
peripheral.disconnect()
peripheral.cancel() // Dispose of `Peripheral`.
Peripheral is now a CoroutineScope
Every Peripheral is now itself a CoroutineScope. You can launch jobs from peripherals that you wish to run until the Peripheral is disposed (via Peripheral.cancel).
val peripheral:Peripheral=..
peripheral.launch {
// Long running task that will be shutdown when `Peripheral` is disposed via `cancel`.
}
Every connection is now a CoroutineScope
Whenever a connection is established (Peripheral.connect) the function call returns a CoroutineScope that can be used to launch jobs that should run until the connection is terminated (either via Peripheral.disconnect or connection drop).
val peripheral:Peripheral=..val scope = peripheral.connect()
scope.launch {
// Long running task that will be shutdown when connection terminates.
}
Deprecate Bluetooth.availability
Having a consistent means of providing realtime bluetooth availability (Bluetooth.availability flow) proved impossible — mostly due to Core Bluetooth limitations. As such, it is expected that library consumers will roll their own mechanism of determining bluetooth availability, and Bluetooth.availability will be removed in a future version. See #737 for more details.
Dropped kable-exceptions Maven artifact
The kable-exceptions Maven artifact has been dropped in favor of having exceptions provided by kable-core artifact. If you were previously pulling in com.juul.kable:kable-exceptions dependency, you should remove it and you only need to pull in com.juul.kable:kable-core.
Release candidate
This release is considered a "release candidate" as it has not had thorough testing to be considered ready for wider use. The API surface changed significantly as well, and may warrant additional feedback to drive its final form. Please try this version and report any issues.
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
-
🚀 Changes
This release includes major internal re-workings of Kable, as well as some externally facing API changes. Most notably, the scanning and connection handling internals have been refactored to better leverage structured concurrency and provide a more predictable connection shutdown procedure.
The exception hierarchy has been significantly simplified, making error handling more consistent and possible in common code.
In general, you should now only ever need to catch
IOExceptionwhen calling Kable functions, all other exceptions should be considered programming error (could've been prevented either by pre-checking conditions). Pre-conditions that could change between a check and call are thrown asIOExceptions.Deprecate
Peripheralcreation viaCoroutineScopeextension functionCreating a
PeripheralviaCoroutineScopeextension function has been deprecated.A
Peripheral's connection needs to be explicitly managed, having its lifecycle be implicitly governed by a parentCroutineScopeprovided a footgun.It is clearer / easier to reason about if a
Peripheralshall be disposed of manually when it is no longer needed: thePeripheral.cancelfunction provides an explicit means of disposing of aPeripheral.Peripheralis now aCoroutineScopeEvery
Peripheralis now itself aCoroutineScope. You canlaunchjobs from peripherals that you wish to run until thePeripheralis disposed (viaPeripheral.cancel).Every connection is now a
CoroutineScopeWhenever a connection is established (
Peripheral.connect) the function call returns aCoroutineScopethat can be used tolaunchjobs that should run until the connection is terminated (either viaPeripheral.disconnector connection drop).Deprecate
Bluetooth.availabilityHaving a consistent means of providing realtime bluetooth availability (
Bluetooth.availabilityflow) proved impossible — mostly due to Core Bluetooth limitations. As such, it is expected that library consumers will roll their own mechanism of determining bluetooth availability, andBluetooth.availabilitywill be removed in a future version. See #737 for more details.Dropped
kable-exceptionsMaven artifactThe
kable-exceptionsMaven artifact has been dropped in favor of having exceptions provided bykable-coreartifact. If you were previously pulling incom.juul.kable:kable-exceptionsdependency, you should remove it and you only need to pull incom.juul.kable:kable-core.Release candidate
This release is considered a "release candidate" as it has not had thorough testing to be considered ready for wider use. The API surface changed significantly as well, and may warrant additional feedback to drive its final form. Please try this version and report any issues.
Common
kable-exceptionsmodule and remove unused exceptions (Dropkable-exceptionsmodule and remove unused exceptions #769)Bluetooth.availability(DeprecateBluetooth.availability#772)CBCentralManager(Prevent bluetooth permission dialog when spinning upCBCentralManager#739)Bluetooth.isSupported()function (AddBluetooth.isSupported()function #738)IOExceptionprovided by kotlinx-io (UseIOExceptionprovided by kotlinx-io #728)ConnectionRejectedException(DropConnectionRejectedException#771)allowDuplicateKeysdefault totrue(HaveallowDuplicateKeysdefault totrue#760)isSupportedalwaystrueon Apple (MakeisSupportedalwaystrueon Apple #752)jsofrom kotlin-wrappers library (Usejsofrom kotlin-wrappers library #726)🧰 Maintenance
Optionsbuilder example in README (Fix closing parenthesis inOptionsbuilder example in README #727), special thanks to @khebrati!This discussion was created from the release 0.35.0-rc.
Beta Was this translation helpful? Give feedback.
All reactions