Cancellation support

[philips77]

This PR adds support for cancellation of selected requests.

Important

Bluetooth LE requests, which extend SimpleRequest cannot be cancelled. In Android API, each BluetoothGatt method triggers corresponding call in BluetoothGattCallback.

Changes

ble

• New cancel() method added to TimetoutableRequest.
• RequestQueue now extends TimeoutableRequest making it and ReliableWriteRequest both cancellable and timetable. Mind, that SimpleRequests added to those queues won't be cancelled, but the queue itself can be.
• SleepRequest now extends TimeoutableRequest and the timeout is used as waking up mechanism (eacbad45f98c5299b5e805f8ab8b186635a25832).
• A request that has completed or was cancelled cannot be enqueued again (each request can be enqueued just once).
• Logging improvement - logs related to awaiting requests have been added (e40cbd49fd316396637b676e6e44b745d80d069a).
• Kinda breaking: A request enqueued in initialize() (during connecting) and cancelled does not cancel the ConnectRequest itself.

ble-ktx

• Cancelling a coroutine suspended on a TimeoutableRequest will trigger the request to be cancelled.

[corentin-c]

@philips77 thank you for this feature, I needed it !

Just a question, shouldn't SimpleRequests that uses split be also cancelled when the queue they are in is cancelled ?

Possible use case

For example, let's say I want to write a big file using a splitter, without using a ReliableWriteRequest, but while being able to cancel the remaining split request that were not sent when I call the cancel on the queue.

Possible solution 1

We could make the spliter used in the WriteRequest return null when we want to cancel the remaining write, but that seems like a dirty fix for me.

class BleDataSplitter : DataSplitter {

    private var isCanceled = false

    override fun chunk(
        message: ByteArray,
        @IntRange(from = 0) index: Int,
        @IntRange(from = 20) maxLength: Int
    ): ByteArray? {
        if(isCanceled) return null
        ...
        return data
    }

    fun cancel() {
        isCanceled = true
    }
}

Possible solution 2

I have tested on my side, adding this line to cancelCurrent in BleManagerHandler seems to resolve my issue :

@Override
final void cancelCurrent() {
     final BluetoothDevice device = bluetoothDevice;
     if (device == null)
    return;

     log(Log.WARN, () -> "Request cancelled");
     request.finished = true;  // ------------------------->  LINE ADDED HERE
     if (request instanceof TimeoutableRequest) {
    request.notifyFail(device, FailCallback.REASON_CANCELLED);
     }
     if (awaitingRequest != null) {
    awaitingRequest.notifyFail(device, FailCallback.REASON_CANCELLED);
    awaitingRequest = null;
     }
     if (requestQueue instanceof ReliableWriteRequest) {
    // Cancelling a Reliable Write request requires sending Abort command.
    // Instead of notifying failure, we will remove all enqueued tasks and
    // let the nextRequest to sent Abort command.
    requestQueue.cancelQueue();
     } else if (requestQueue != null) {
    requestQueue.notifyFail(device, FailCallback.REASON_CANCELLED);
    requestQueue = null;
}
nextRequest(request == null || request.finished);
}

Could this interaction with split SimpleRequests be a wanted feature ? Is there a solution I'm not seeing ?

Thanks

[philips77]

Just a question, shouldn't SimpleRequests that uses split be also cancelled when the queue they are in is cancelled ?

You're right. I did not think about that...

[philips77]

Thank you for bringing this up. You're right, there should be an way to cancel it. However, it also implies cancellation of receiving a huge packet using notifications, indications, write request (for server case) using DataMerger, which seems to be a bit tricky. I have to sleep with this in mind.