zbus
This is the main subcrate of the zbus project, that provides the API to interact with D-Bus. It takes care of the establishment of a connection, the creation, sending and receiving of different kind of D-Bus messages (method calls, signals etc) for you.
Status: Stable.
Getting Started
The best way to get started with zbus is the book, where we start with basic D-Bus concepts and explain with code samples, how zbus makes D-Bus easy.
Example code
We'll create a simple D-Bus service and client to demonstrate the usage of zbus. Note that these
examples assume that a D-Bus broker is setup on your machine and you've a session bus running
(DBUS_SESSION_BUS_ADDRESS
environment variable must be set). This is guaranteed to be the case on
a typical Linux desktop session.
Service
A simple service that politely greets whoever calls its SayHello
method:
use ;
use ;
// Although we use `tokio` here, you can use any async runtime of choice.
async
You can use the following command to test it:
Client
Now let's write the client-side code for MyGreeter
service:
use ;
// Although we use `tokio` here, you can use any async runtime of choice.
async
Blocking API
While zbus is primarily asynchronous (since 2.0), blocking wrappers are provided for
convenience. Since zbus 5.0, blocking API can be disabled by disabling the blocking-api
cargo
feature.
Compatibility with async runtimes
zbus is runtime-agnostic and should work out of the box with different Rust async runtimes. However, in order to achieve that, zbus spawns a thread per connection to handle various internal tasks. If that is something you would like to avoid, you need to:
- Use
connection::Builder
and disable theinternal_executor
flag. - Ensure the internal executor keeps ticking continuously.
Moreover, by default zbus makes use of async-io
for all I/O, which also launches its own thread
to run its own internal executor.
Special tokio support
Since tokio
is the most popular async runtime, zbus provides an easy way to enable tight
integration with it without you having to worry about any of the above: Enabling the tokio
feature:
# Sample Cargo.toml snippet.
[]
# Also disable the default `async-io` feature to avoid unused dependencies.
= { = "3", = false, = ["tokio"] }
That's it! No threads launched behind your back by zbus (directly or indirectly) now and no need to tick any executors etc. 😼
Note: On Windows, the async-io
feature is currently required for UNIX domain socket support,
see the corresponding tokio issue on GitHub.