Streams for D-Bus signals

[swsnr]

As briefly discussed in #1820 I'd like to add means to receive signals as streams, which is a lot more convenient to use than callbacks.

Closes #1820

[swsnr]

@sdroege This PR doesn't actually do what it's said to do yet 😬 but I'd like to have some early feedback on the current commit which replaces the SignalSubscriptionId with a droppable object to which the lifetime of the signal subscription is attached.

This change is a bit of a prerequisite for actually receiving a signal as stream, because making a signal subscription droppable makes it a lot easier to manage the subscription in the context of streams and futures.

I've left comments on the diff with specific questions. If this first part is settled, I'll push another commit with the actual stream implementation.

[swsnr]

@sdroege This is incompatible, obviously. Is this okay? Or would you rather have me mark signal_subscribe and signal_unsubscribe as deprecated, and add a new separate method. If so, can you suggest a new for this new method?

[sdroege]

Breaking the API is OK but we obviously can't backport this then and it will have to wait until the next breaking release next summer.

[bilelmoussaoui]

Do it in two steps: one that deprecate the current methods & add new ones & a new commit dropping the deprecated methods & rename the new ones. This way we can backport only the first commit

[swsnr]

Two steps, but in MR? That I can do. Suggestions for a new name? I'd go for subscribe_signal, which is arguably the nicer name anyway. Slightly confusing if we have signal_subscribe and subscribe_signal but if the former is clearly deprecated it's perhaps fine?

[swsnr]

I've added this as a separate subscribe_to_signal method, and marked signal_subscribe and signal_unsubscribe as deprecated. I'm open for a better name for the new method.

I didn't remove signal_subscribe and signal_unsubscribe, because the new method is actually implemented on top of these, which sort of nicely separates the FFI binding boilerplate from the Rust-level interface, and signal_subscribe at least also offers valuable documentation which I couldn't copy to the new method due to the licensing situation.

In the next breaking release you could then either just remove the pub, or completely inline both, or even indefinitely retain them as deprecated methods, if only for documentation.

[swsnr]

PS: I'm not really following the CI errors; are these mine?

[sdroege]

PS: I'm not really following the CI errors; are these mine?

No, you can ignore them. Things changed on the github side and now stuff is failing.

[swsnr]

@sdroege @bilelmoussaoui I've addressed your answers to my questions, and while I was at it I also pushed a second commit which replaces the lengthy callback signature with four anonymous &strs with a struct, so as to properly name things. I believe that this makes it much easier to understand the signature, and it probably also plays a lot better with editor support, e.g auto-completion.

I don't cling to this tho, so if you dislike that I can back out that commit.

If you agree with the proposed API I'd continue with implementing the Stream support for signals, either in this PR with new commits or in a separate one after merging this one, whatever you prefer.

[swsnr]

@sdroege @bilelmoussaoui I went ahead and added receive_signal which creates a stream mapping signal emissions with a custom function, and receive_signal_parameters which directly decodes the signal parameters, as I believe that's the most frequent use of this.

[sdroege]

Looks good to me otherwise