ListenerToken's Behavior is Abnormal

[bdkjones]

Summary:

On Apple platforms, a "token" such as NSKeyValueObservation automatically releases associated resources and cancels associated activities when that token is deallocated. You do not manually call remove() on the token.

Couchbase's Swift SDK does not follow this pattern. In your SDK, you MUST call remove() before allowing the token to go out of scope, or you have a permanent leak and Couchbase activities will continue infinitely in the background.

Why This Design Should Change:

1. It does not follow platform conventions, which makes it likely that developers who are used to the mental model of: "Activity X will continue as long as I hold a strong reference to this token and X will stop when I release that reference" are set up for failure.

2. The current design makes it difficult to reliably shut down Couchbase. You store a ListenerToken as an iVar on some object such as DatabaseController. You can't just release DatabaseController, which in turn releases the ListenerToken iVars and shuts down Couchbase activities. You have to manually check for the tokens, call remove() on each, etc. You cannot do that in deinit, so you must add some kind of -closeCouchbase() method that cleans up all the tokens and remember to call that method before you nil your DatabaseController. That's fragile and complicated.

How ListenerToken Should Work:

The ListenerToken should work like other "tokens" in Swift: you keep a strong reference to the token for as long as you want the associated activity to continue. To stop/cancel the activity, you merely release the strong reference. In short, the work in remove() should be done automatically when the ListenerToken is deallocated.

Backwards Compatibility

This change is technically breaking, but only if someone is currently discarding ListenerTokens and purposefully allowing Couchbase to run infinitely without the ability to stop it. Any developer who is keeping a reference to the ListenerToken in order to call remove() at some point would be unaffected by this change.

Context

When the Replicator fails to connect to Sync Gateway, it retries at increasing intervals. I was surprised to see these retries continue even though every reference I held was nil-ed. I discovered that the ListenerToken was the culprit: you cannot simply let it go out of scope.

[pasin]

Thanks for the observation and suggestion. One of the reasons that we have implemented it that way is to have the behavior consistent across multiple platforms that Couchbase Lite is currently supported. We are more trying to be inline with the platform idioms or behaviors. For this particular case, as you have mentioned, it could be a breaking change for some users that don't ever need to remove a change listener in their app. So, generally, we cannot change this behavior until we could break the API in a major release.

I have created the internal ticket (CBL-7095) to track this issue. Mean while, you can create a class to wrap the ListenerToken and remove the token in its deinit.

[bdkjones]

Mean while, you can create a class to wrap the ListenerToken and remove the token in its deinit.

Swift 6 language mode will throw you out a window if you attempt to do that. deinit() runs on an arbitrary thread. Glad it may get improved in the next major release though.