zbus

https://github.com/z-galaxy/zbus
Admin
zbus is a Rust API for D-Bus communication that provides a safe and simple high- and low-level...
Tokens:76,884
Snippets:466
Trust Score:8.6
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install and use zbus_xmlgen CLI

Source: https://github.com/z-galaxy/zbus/blob/main/zbus_xmlgen/README.md

Commands to install the tool and generate Rust code from various D-Bus sources including system, session, address, and local XML files.

```shell
$ cargo install zbus_xmlgen
$ zbus-xmlgen system org.freedesktop.login1 /org/freedesktop/login1
$ zbus-xmlgen session org.freedesktop.ScreenSaver /org/freedesktop/ScreenSaver
$ zbus-xmlgen address unix:abstract=/home/user/.cache/ibus/dbus-fpxKwgbJ org.freedesktop.IBus /org/freedesktop/IBus
$ zbus-xmlgen file interface.xml # Use '-' for stdin.
```

--------------------------------

### Using blocking Proxy and Connection

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/blocking.md

Demonstrates converting an asynchronous proxy setup to use the blocking API, including signal handling and object path interaction.

```rust
use zbus::{blocking::Connection, ObjectPath, proxy, Result};

#[proxy(
    default_service = "org.freedesktop.GeoClue2",
    interface = "org.freedesktop.GeoClue2.Manager",
    default_path = "/org/freedesktop/GeoClue2/Manager"
)]
trait Manager {
    #[zbus(object = "Client")]
    /// The method normally returns an `ObjectPath`.
    /// With the object attribute, we can make it return a `ClientProxy` directly.
    fn get_client(&self);
}

#[proxy(
    default_service = "org.freedesktop.GeoClue2",
    interface = "org.freedesktop.GeoClue2.Client"
)]
trait Client {
    fn start(&self) -> Result<()>;
    fn stop(&self) -> Result<()>;

    #[zbus(property)]
    fn set_desktop_id(&mut self, id: &str) -> Result<()>;

    #[zbus(signal)]
    fn location_updated(&self, old: ObjectPath<'_>, new: ObjectPath<'_>) -> Result<()>;
}

#[proxy(
    default_service = "org.freedesktop.GeoClue2",
    interface = "org.freedesktop.GeoClue2.Location"
)]
trait Location {
    #[zbus(property)]
    fn latitude(&self) -> Result<f64>;
    #[zbus(property)]
    fn longitude(&self) -> Result<f64>;
}
let conn = Connection::system().unwrap();
let manager = ManagerProxyBlocking::new(&conn).unwrap();
let mut client = manager.get_client().unwrap();
// Gotta do this, sorry!
client.set_desktop_id("org.freedesktop.zbus").unwrap();

let mut location_updated = client.receive_location_updated().unwrap();

client.start().unwrap();

// Wait for the signal.
let signal = location_updated.next().unwrap();
let args = signal.args().unwrap();

let location = LocationProxyBlocking::builder(&conn)
    .path(args.new())
    .build()
    .unwrap();
println!(
    "Latitude: {}\nLongitude: {}",
    location.latitude().unwrap(),
    location.longitude().unwrap(),
);
```

--------------------------------

### Configure object-manager feature

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/upgrading-to-6.md

Example of enabling the object-manager feature when default features are disabled.

```toml
[dependencies]
zbus = { version = "6", default-features = false, features = ["tokio", "object-manager"] }
```

--------------------------------

### Implement a complete zbus interface with properties and signals

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/service.md

This example demonstrates defining a Greeter struct with an interface, including a signal emitter, properties, and a main function to serve the object on a session bus.

```rust
use zbus::{object_server::SignalEmitter, connection::Builder, interface, fdo, Result};
use event_listener::{Event, Listener};

struct Greeter {
    name: String,
    done: Event,
}

#[interface(name = "org.zbus.MyGreeter1")]
impl Greeter {
    async fn say_hello(&self, name: &str) -> String {
        format!("Hello {}!", name)
    }

    // Rude!
    async fn go_away(
        &self,
        #[zbus(signal_emitter)]
        emitter: SignalEmitter<'_>,
    ) -> fdo::Result<()> {
        emitter.greeted_everyone().await?;
        self.done.notify(1);

        Ok(())
    }

    /// A "GreeterName" property.
    #[zbus(property)]
    async fn greeter_name(&self) -> &str {
        &self.name
    }

    /// A setter for the "GreeterName" property.
    ///
    /// Additionally, a `greeter_name_changed` method has been generated for you if you need to
    /// notify listeners that "GreeterName" was updated. It will be automatically called when
    /// using this setter.
    #[zbus(property)]
    async fn set_greeter_name(&mut self, name: String) {
        self.name = name;
    }

    /// A signal; the implementation is provided by the macro.
    #[zbus(signal)]
    async fn greeted_everyone(emitter: &SignalEmitter<'_>) -> Result<()>;
}

// Although we use `tokio` here, you can use any async runtime of choice.
#[tokio::main]
async fn main() -> Result<()> {
    let greeter = Greeter {
        name: "GreeterName".to_string(),
        done: event_listener::Event::new(),
    };
    let done_listener = greeter.done.listen();
    let connection = Builder::session()
        .name("org.zbus.MyGreeter")
        .serve_at("/org/zbus/MyGreeter", greeter)
        .build()
        .await?;

    done_listener.wait();

    // Let's emit the signal again, just for the fun of it.
    connection
        .object_server()
        .interface("/org/zbus/MyGreeter")
        .await?
        .greeted_everyone()
        .await?;

    Ok(())
}

```

--------------------------------

### Configure proxy and service features

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/upgrading-to-6.md

Example of how to configure zbus dependencies when default features are disabled for pure client or service applications.

```toml
[dependencies]
# A pure client.
zbus = { version = "6", default-features = false, features = ["tokio", "proxy"] }
# A pure service.
zbus = { version = "6", default-features = false, features = ["tokio", "service"] }
```

--------------------------------

### FilePath conversion before upgrade

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/upgrading-to-6.md

Example of code that fails to compile in version 6 due to the change from From to TryFrom for PathBuf conversions.

```rust
use std::path::PathBuf;
use zbus::FilePath;

fn path_buf(file_path: FilePath<'_>) -> PathBuf {
    PathBuf::from(file_path)
}
```

--------------------------------

### Create a bus-less peer-to-peer connection over a UnixStream

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/connection.md

Shows how to build a client and server connection pair on a UnixStream using Builder::unix_stream().p2p() and .server(guid).p2p(). Works on Unix only; requires the zbus 'p2p' cargo feature.

```rust
# #[tokio::main]
# async fn main() -> zbus::Result<()> {
# #[cfg(unix)]
# {
use std::os::unix::net::UnixStream;
use zbus::{connection::Builder, Guid};

let guid = Guid::generate();
let (p0, p1) = UnixStream::pair().unwrap();
# #[allow(unused)]
let (client_conn, server_conn) = futures_util::try_join!(
    // Client
    Builder::unix_stream(p0).p2p().build(),
    // Server
    Builder::unix_stream(p1).server(guid).p2p().build(),
)?;
# }
#
# Ok(())
# }
```

--------------------------------

### Get location from Geoclue with zbus signals

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/client.md

A more advanced example that uses multiple proxies to interact with Geoclue's D-Bus API. It defines proxy traits for Manager, Client, and Location interfaces, then connects to the system bus, starts the client, and listens for property changes and location updates. Uses `tokio` as the async runtime and requires `futures_util` for `try_join!`.

```rust
use zbus::{ObjectPath, proxy, Connection, Result};
use futures_util::stream::StreamExt;

#[proxy(
    default_service = "org.freedesktop.GeoClue2",
    interface = "org.freedesktop.GeoClue2.Manager",
    default_path = "/org/freedesktop/GeoClue2/Manager"
)]
trait Manager {
    #[zbus(object = "Client")]
    fn get_client(&self);
}

#[proxy(
    default_service = "org.freedesktop.GeoClue2",
    interface = "org.freedesktop.GeoClue2.Client"
)]
trait Client {
    fn start(&self) -> Result<()>;
    fn stop(&self) -> Result<()>;

    #[zbus(property)]
    fn set_desktop_id(&mut self, id: &str) -> Result<()>;

    #[zbus(signal)]
    fn location_updated(&self, old: ObjectPath<'_>, new: ObjectPath<'_>) -> Result<()>;
}

#[proxy(
    default_service = "org.freedesktop.GeoClue2",
    interface = "org.freedesktop.GeoClue2.Location"
)]
trait Location {
    #[zbus(property)]
    fn latitude(&self) -> Result<f64>;
    #[zbus(property)]
    fn longitude(&self) -> Result<f64>;
}

// Although we use `tokio` here, you can use any async runtime of choice.
#[tokio::main]
async fn main() -> Result<()> {
    let conn = Connection::system().await?;
    let manager = ManagerProxy::new(&conn).await?;
    let mut client = manager.get_client().await?;
    // Gotta do this, sorry!
    client.set_desktop_id("org.freedesktop.zbus").await?;

    let props = zbus::fdo::PropertiesProxy::builder(&conn)
        .destination("org.freedesktop.GeoClue2")
        .path(client.inner().path())
        .build()
        .await?;
    let mut props_changed = props.receive_properties_changed().await?;
    let mut location_updated = client.receive_location_updated().await?;

    client.start().await?;

    futures_util::try_join!(
        async {
            while let Some(signal) = props_changed.next().await {
                let args = signal.args()?;

                for (name, value) in args.changed_properties().iter() {
                    println!("{}.{} changed to `{:?}`", args.interface_name(), name, value);
                }
            }

            Ok::<(), zbus::Error>(())
        },
        async {
            while let Some(signal) = location_updated.next().await {
                let args = signal.args()?;

                let location = LocationProxy::builder(&conn)
                    .path(args.new())
                    .build()
                    .await?;
                println!(
                    "Latitude: {}\nLongitude: {}",
                    location.latitude().await?,
                    location.longitude().await?,
                );
            }

            // No need to specify type of Result each time
            Ok(())
        }
    )?;

   Ok(())
}
```

--------------------------------

### Example D-Bus XML introspection output

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/client.md

This is an example of the XML output retrieved from the notification service, which can be saved to a file for processing.

```xml
<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
                      "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
<node>
  <!-- other interfaces omitted -->
  <interface name="org.freedesktop.Notifications">
    <method name="Notify">
      <arg type="s" name="arg_0" direction="in">
      </arg>
      <arg type="u" name="arg_1" direction="in">
      </arg>
      <arg type="s" name="arg_2" direction="in">
      </arg>
      <arg type="s" name="arg_3" direction="in">
      </arg>
      <arg type="s" name="arg_4" direction="in">
      </arg>
      <arg type="as" name="arg_5" direction="in">
      </arg>
      <arg type="a{sv}" name="arg_6" direction="in">
      </arg>
      <arg type="i" name="arg_7" direction="in">
      </arg>
      <arg type="u" name="arg_8" direction="out">
      </arg>
    </method>
    <method name="CloseNotification">
      <arg type="u" name="arg_0" direction="in">
      </arg>
    </method>
    <method name="GetCapabilities">
      <arg type="as" name="arg_0" direction="out">
      </arg>
    </method>
    <method name="GetServerInformation">
      <arg type="s" name="arg_0" direction="out">
      </arg>
      <arg type="s" name="arg_1" direction="out">
      </arg>
      <arg type="s" name="arg_2" direction="out">
      </arg>
      <arg type="s" name="arg_3" direction="out">
      </arg>
    </method>
    <signal name="NotificationClosed">
      <arg type="u" name="arg_0">
      </arg>
      <arg type="u" name="arg_1">
      </arg>
    </signal>
    <signal name="ActionInvoked">
      <arg type="u" name="arg_0">
      </arg>
      <arg type="s" name="arg_1">
      </arg>
    </signal>
  </interface>
</node>
```

--------------------------------

### Configure unixexec transport feature

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/upgrading-to-6.md

Example of enabling the unixexec transport feature when default features are disabled.

```toml
[dependencies]
zbus = { version = "6", default-features = false, features = ["tokio", "proxy", "unixexec"] }
```

--------------------------------

### Read systemd properties with zbus proxy

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/client.md

Real-world example reading two properties from systemd's main service. Uses #[proxy] with interface, default_service, and default_path. The output shows the expected result, including environment variables.

```rust
use zbus::{Connection, proxy, Result};

#[proxy(
    interface = "org.freedesktop.systemd1.Manager",
    default_service = "org.freedesktop.systemd1",
    default_path = "/org/freedesktop/systemd1"
)]
trait SystemdManager {
    #[zbus(property)]
    fn architecture(&self) -> Result<String>;
    #[zbus(property)]
    fn environment(&self) -> Result<Vec<String>>;
}

#[tokio::main]
async fn main() -> Result<()> {
    let connection = Connection::system().await?;

    let proxy = SystemdManagerProxy::new(&connection).await?;
    println!("Host architecture: {}", proxy.architecture().await?);
    println!("Environment variables:");
    for env in proxy.environment().await? {
        println!("  {}", env);
    }

    Ok(())
}
```

```none
Host architecture: x86-64
Environment variables:
  HOME=/home/zeenix
  LANG=en_US.UTF-8
  LC_ADDRESS=de_DE.UTF-8
  LC_IDENTIFICATION=de_DE.UTF-8
  LC_MEASUREMENT=de_DE.UTF-8
  LC_MONETARY=de_DE.UTF-8
  LC_NAME=de_DE.UTF-8
  LC_NUMERIC=de_DE.UTF-8
  LC_PAPER=de_DE.UTF-8
  LC_TELEPHONE=de_DE.UTF-8
  LC_TIME=de_DE.UTF-8
  ...
```

--------------------------------

### Request a well-known service name with zbus

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/service.md

This Rust example uses zbus to connect to the session bus and request the well-known name 'org.zbus.MyGreeter'. It uses the tokio async runtime, but any async runtime can be used. The service runs indefinitely with an empty loop, but does not yet handle incoming messages.

```rust
use zbus::{Connection, Result};

// Although we use `tokio` here, you can use any async runtime of choice.
#[tokio::main]
async fn main() -> Result<()> {
    let connection = Connection::session()
        .await?;
    connection
        .request_name("org.zbus.MyGreeter")
        .await?;

    loop {}
}
```

--------------------------------

### Updated zbus 6 error matching

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/upgrading-to-6.md

Example of how to match on the flattened zbus::Error variants in zbus 6.

```rust
use zbus::Error;

fn describe(error: &Error) -> String {
    match error {
        Error::IncorrectType => "a value had the wrong type".to_string(),
        Error::SignatureMismatch(signature, expected) => {
            format!("got {signature}, expected {expected}")
        }
        Error::InvalidObjectPath => "not a valid object path".to_string(),
        Error::InvalidName(reason) => (*reason).to_string(),
        Error::InvalidNameConversion { from, to } => format!("cannot convert {from} to {to}"),
        _ => error.to_string(),
    }
}
```

--------------------------------

### Example of redundant error handling in builder methods

Source: https://github.com/z-galaxy/zbus/blob/main/docs/superpowers/specs/2026-09-07-infallible-builder-setters-design.md

Demonstrates the current requirement to use the question mark operator for builder methods that take validated types like BusName or ObjectPath.

```rust
let proxy = PropertiesProxy::builder(&conn)
    .destination(proxy.destination())?   // &BusName: cannot fail
    .path(proxy.path())?                 // &ObjectPath: cannot fail
    .build()
    .await?;
```

--------------------------------

### Wire format only dependency configuration

Source: https://github.com/z-galaxy/zbus/blob/main/zbus/README.md

Configure zbus to build only the wire format and names without D-Bus connection features. Disabling default features also disables tracing, which must be re-enabled explicitly to get logs.

```toml
[dependencies]
zbus = { version = "6", default-features = false }

```

--------------------------------

### Benchmarks and Fuzzing

Source: https://github.com/z-galaxy/zbus/blob/main/AGENTS.md

Commands for running benchmarks and setting up fuzz testing.

```bash
# Run benchmarks
cargo bench

# Fuzz testing (requires nightly and cargo-fuzz)
cargo install cargo-fuzz
cargo fuzz run --fuzz-dir zbus/fuzz dbus
```

--------------------------------

### Documentation Generation

Source: https://github.com/z-galaxy/zbus/blob/main/AGENTS.md

Commands for building crate documentation and the project mdbook.

```bash
# Build docs for individual crates
cargo doc --all-features -p zbus
cargo doc --no-default-features -p zbus
cargo doc --all-features -p zbus_xml

# Build the mdbook (in book/ directory)
cd book && mdbook build
```

--------------------------------

### Build and Test Commands

Source: https://github.com/z-galaxy/zbus/blob/main/AGENTS.md

Commands for running the full test suite, testing individual crates, and testing with specific feature flags.

```bash
# Full test suite (requires D-Bus session bus)
cargo test --all-features

# Test individual crates
cargo test -p zbus
cargo test -p zbus_macros
cargo test -p zbus_xml

# Test the wire-format-only build (the D-Bus API, i.e. the `comms` feature, off)
cargo test -p zbus --no-default-features

# Test with specific features
cargo test --no-default-features --features tokio
cargo test --features uuid,url,time,chrono,option-as-array,vsock,bus-impl

# Run single test
cargo test basic_connection
cargo test --test e2e specific_test_name
```

--------------------------------

### Configure service with connection::Builder

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/service.md

Uses connection::Builder to safely set up interfaces and request names, preventing potential message loss during service activation.

```rust
# use zbus::{connection, interface, Result};
#
#
# struct Greeter;
#
# #[interface(name = "org.zbus.MyGreeter1")]
# impl Greeter {
#     async fn say_hello(&self, name: &str) -> String {
#         format!("Hello {}!", name)
#     }
# }
#
# #[tokio::main]
# async fn main() -> Result<()> {
    let _connection = connection::Builder::session()
        .name("org.zbus.MyGreeter")
        .serve_at("/org/zbus/MyGreeter", Greeter)
        .build()
        .await?;
#     loop {
#         // do something else, wait forever or timeout here:
#         // handling D-Bus messages is done in the background
#         std::future::pending::<()>().await;
#     }
# }
```

--------------------------------

### Implement a D-Bus interface with MyGreeter

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/service.md

Defines a Greeter struct with a say_hello method and registers it to the session bus using the ObjectServer.

```rust
use zbus::{Connection, interface, Result};

struct Greeter;

#[interface(name = "org.zbus.MyGreeter1")]
impl Greeter {
    async fn say_hello(&self, name: &str) -> String {
        format!("Hello {}!", name)
    }
}

// Although we use `tokio` here, you can use any async runtime of choice.
#[tokio::main]
async fn main() -> Result<()> {
    let connection = Connection::session().await?;
    // setup the object server
    connection
        .object_server()
        .at("/org/zbus/MyGreeter", Greeter)
        .await?;
    // before requesting the name
    connection
        .request_name("org.zbus.MyGreeter")
        .await?;

    loop {
        // do something else, wait forever or timeout here:
        // handling D-Bus messages is done in the background
        std::future::pending::<()>().await;
    }
}
```

--------------------------------

### Builder setter error handling before 6.0

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/upgrading-to-6.md

Example of the builder pattern where setters return Result and require the ? operator after every call.

```rust
use zbus::Message;

fn make_message() -> zbus::Result<Message> {
    Message::method_call("/org/zbus/Test", "Test")?
        .destination("org.zbus.Test")?
        .build(&())
}
```

--------------------------------

### Run the full test suite

Source: https://github.com/z-galaxy/zbus/blob/main/CONTRIBUTING.md

Executes all tests, including documentation tests and compile-tests, using all available features.

```sh
cargo test --all-features
```

--------------------------------

### Duplicate From implementation error

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/upgrading-to-6.md

Example of a duplicate From implementation that causes a compiler error (E0119) in zbus 6 due to type aliasing.

```rust
# #![allow(deprecated)]
struct MyError;

impl From<zbus::Error> for MyError {
    fn from(_: zbus::Error) -> Self {
        MyError
    }
}

// This is what `impl From<zvariant::Error> for MyError` became: the same impl, twice.
impl From<zbus::zvariant::Error> for MyError {
    fn from(_: zbus::zvariant::Error) -> Self {
        MyError
    }
}
```

--------------------------------

### Builder setter error handling after 6.0

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/upgrading-to-6.md

Example of the updated builder pattern where setters return Self and errors are deferred to the build() method.

```rust
use zbus::Message;

fn make_message() -> zbus::Result<Message> {
    Message::method_call("/org/zbus/Test", "Test")
        .destination("org.zbus.Test")
        .build(&())
}
```

--------------------------------

### Builder migration table

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/upgrading-to-6.md

Summary of syntax changes for builder methods and MatchRule construction.

```markdown
| Before | After |
| --- | --- |
| `.path("/org/zbus/Foo")?` | `.path("/org/zbus/Foo")` |
| `Message::method_call("/", "Ping")?` | `Message::method_call("/", "Ping")` |
| `MatchRule::builder().build()` | `MatchRule::builder().build()?` |
```

--------------------------------

### Removed zbus 5 error variants

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/upgrading-to-6.md

Example of code that fails in zbus 6 because the Variant and Names error variants no longer exist.

```rust
use zbus::Error;

fn describe(error: &Error) -> String {
    match error {
        // Neither variant exists in zbus 6.
        Error::Variant(e) => e.to_string(),
        Error::Names(e) => e.to_string(),
        _ => error.to_string(),
    }
}
```

--------------------------------

### Supply a custom runtime to a zbus connection builder

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/connection.md

Shows how to build a session connection with an arbitrary Runtime implementation using Builder::runtime(). The runtime must implement zbus::runtime::traits::Runtime.

```rust
use zbus::{Connection, Result, connection::Builder, runtime::traits::Runtime};

async fn connect(runtime: impl Runtime) -> Result<Connection> {
    Builder::session().runtime(runtime).build().await
}
```

--------------------------------

### Watch property changes with receive_log_level_changed

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/client.md

Example of using a stream to be notified of property changes. The method receive_log_level_changed() is generated from the property name. The proxy caches properties and watches for changes by default.

```rust
use zbus::{Connection, proxy, Result};
use futures_util::stream::StreamExt;
#
# #[tokio::main]
# async fn main() -> Result<()> {
    #[proxy(
        interface = "org.freedesktop.systemd1.Manager",
        default_service = "org.freedesktop.systemd1",
        default_path = "/org/freedesktop/systemd1"
    )]
    trait SystemdManager {
        #[zbus(property)]
        fn log_level(&self) -> Result<String>;
    }

    let connection = Connection::system().await?;

    let proxy = SystemdManagerProxy::new(&connection).await?;
    let mut stream = proxy.receive_log_level_changed().await;
    while let Some(v) = stream.next().await {
        println!("LogLevel changed: {:?}", v.get().await);
    }
#
#   Ok(())
# }
```

--------------------------------

### Module layout of zbus/src/runtime/

Source: https://github.com/z-galaxy/zbus/blob/main/docs/superpowers/specs/2026-09-12-external-runtime-design.md

Shows the file and module structure of the runtime directory, with comments explaining the purpose of each file.

```text
zbus/src/runtime/
├── mod.rs           # pub mod traits; pub use IoSource, Interest, AsyncDrop; private Runtime
├── traits.rs        # Runtime, PollIo, TaskHandle
├── io_source.rs     # IoSource and Interest
├── async_io.rs      # crate-private async-io implementor (feature = "async-io")
├── tokio_rt.rs      # crate-private Tokio implementor (feature = "tokio")
├── blocking_thread.rs  # default spawn_blocking hook: a std thread per call
├── unblock.rs       # spawn_blocking over the `blocking` crate's pool, for AsyncIo
├── erased.rs        # ErasedRuntime, ErasedRegistration, ErasedTask, ExternalTask
├── task.rs          # private Task: an enum over the compiled backends and erasure
├── locks.rs         # Mutex, RwLock and guards: cfg'd re-exports of async-lock or tokio::sync
├── io/              # RegisteredIo<O>, the per-family SocketOps and the connect helpers
├── timeout.rs       # Runtime::sleep and Runtime::timeout over the connection's own timer
├── async_drop.rs    # unchanged
├── test_runtime.rs  # cfg(test) runtimes the tests of the external path run on
└── process.rs       # helper processes: std spawn, registered pipes, spawn_blocking reap
```

--------------------------------

### Client: MyGreeter proxy using zbus proxy macro

Source: https://github.com/z-galaxy/zbus/blob/main/zbus/README.md

Defines a `MyGreeter` trait with the `proxy` macro, specifying the interface, default service, and default path. The main function creates a session connection, instantiates the proxy, calls `say_hello`, and prints the reply.

```rust
use zbus::{Connection, Result, proxy};

#[proxy(
    interface = "org.zbus.MyGreeter1",
    default_service = "org.zbus.MyGreeter",
    default_path = "/org/zbus/MyGreeter"
)]
trait MyGreeter {
    async fn say_hello(&self, name: &str) -> Result<String>;
}

// Although we use `tokio` here, you can use any async runtime of choice.
#[tokio::main]
async fn main() -> Result<()> {
    let connection = Connection::session().await?;

    // `proxy` macro creates `MyGreaterProxy` based on `MyGreeter` trait.
    let proxy = MyGreeterProxy::new(&connection).await?;
    let reply = proxy.say_hello("Maria").await?;
    println!("{reply}");

    Ok(())
}
```

--------------------------------

### Replace zvariant with zbus for wire-format

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/upgrading-to-6.md

Wire-format-only users should replace zvariant dependencies with zbus 6.

```toml
# Before
[dependencies]
zvariant = { version = "5", default-features = false, features = ["serde_bytes"] }

# After
[dependencies]
zbus = { version = "6", default-features = false, features = ["serde_bytes"] }
```

--------------------------------

### Using zbus 6 name types

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/upgrading-to-6.md

Shows how to use the consolidated zbus::names module for handling D-Bus interface and unique names.

```rust
use zbus::names::{InterfaceName, UniqueName};

let interface = InterfaceName::try_from("org.freedesktop.DBus").unwrap();
assert_eq!(interface, "org.freedesktop.DBus");

// A unique name has to start with a colon.
UniqueName::try_from("not.unique").unwrap_err();
```

--------------------------------

### Define a property getter with #[zbus(property)]

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/client.md

Annotate a trait method with #[zbus(property)] to generate a property getter. The method state() translates to a "State" property Get call. To set the property, prefix the method name with set_.

```rust
use zbus::{proxy, Result};

#[proxy]
trait MyInterface {
    #[zbus(property)]
    fn state(&self) -> Result<String>;
}
```

--------------------------------

### busctl test call for SayHello

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/service.md

Verifies the manual handler works by invoking it with busctl and expecting the greeting response.

```bash
$ busctl --user call org.zbus.MyGreeter /org/zbus/MyGreeter org.zbus.MyGreeter1 SayHello s "zbus"
s "Hello zbus!"
```

--------------------------------

### Compile-fail: zbus::zvariant::DynamicTuple constructor through alias

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/upgrading-to-6.md

This example triggers E0423 because a type alias names a type, not its constructor function. The correct spelling is zbus::DynamicTuple((1u32, "a")). The #![allow(deprecated)] attribute suppresses deprecation warnings for the alias.

```rust
# #![allow(deprecated)]
let _ = zbus::zvariant::DynamicTuple((1u32, "a"));
```

--------------------------------

### Trait-derived proxy call with #[proxy] attribute

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/client.md

Define a trait with the #[proxy] attribute to generate a NotificationsProxy and NotificationsProxyBlocking. The trait method wraps the D-Bus call, providing type safety and convenience. The example creates a proxy and calls the notify method, then prints the reply.

```rust
use std::collections::HashMap;
use std::error::Error;

use zbus::{Value, proxy, Connection};

#[proxy(
    default_service = "org.freedesktop.Notifications",
    default_path = "/org/freedesktop/Notifications"
)]
trait Notifications {
    /// Call the org.freedesktop.Notifications.Notify D-Bus method
    fn notify(&self,
              app_name: &str,
              replaces_id: u32,
              app_icon: &str,
              summary: &str,
              body: &str,
              actions: &[&str],
              hints: HashMap<&str, &Value<'_>>,
              expire_timeout: i32) -> zbus::Result<u32>;
}

// Although we use `tokio` here, you can use any async runtime of choice.
#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let connection = Connection::session().await?;

    let proxy = NotificationsProxy::new(&connection).await?;
    let reply = proxy.notify(
        "my-app",
        0,
        "dialog-information",
        "A summary", "Some body",
        &[],
        HashMap::new(),
        5000,
    ).await?;
    dbg!(reply);

    Ok(())
}

```

--------------------------------

### Code Quality and Cross-Platform Checks

Source: https://github.com/z-galaxy/zbus/blob/main/AGENTS.md

Commands for formatting code, running clippy lints, and verifying cross-platform compatibility.

```bash
# Format code (requires nightly)
cargo +nightly fmt --all

# Lint with clippy
cargo clippy -- -D warnings

# Check cross-platform compatibility
cargo check --target x86_64-pc-windows-gnu
cargo check --target x86_64-apple-darwin
cargo check --target x86_64-unknown-freebsd
```

--------------------------------

### Low-level D-Bus call with zbus::Connection::call_method

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/client.md

Use Connection::call_method to invoke a D-Bus method directly. This approach is flexible but error-prone because arguments are passed as a tuple and type mismatches can occur. The example calls the Notify method on org.freedesktop.Notifications and deserializes the reply as u32.

```rust
use std::collections::HashMap;
use std::error::Error;

use zbus::{Value, Connection};

// Although we use `tokio` here, you can use any async runtime of choice.
#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let connection = Connection::session().await?;

    let m = connection.call_method(
        Some("org.freedesktop.Notifications"),
        "/org/freedesktop/Notifications",
        Some("org.freedesktop.Notifications"),
        "Notify",
        &("my-app", 0u32, "dialog-information", "A summary", "Some body",
          vec![""; 0], HashMap::<&str, &Value>::new(), 5000),
    ).await?;
    let reply: u32 = m.body().deserialize().unwrap();
    dbg!(reply);
    Ok(())
}

```

--------------------------------

### Implement a blocking Greeter interface

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/blocking.md

Defines a Greeter struct with an interface containing both synchronous and asynchronous methods, and demonstrates how to serve it using a blocking connection builder.

```rust
use zbus::{blocking::connection, interface, fdo, object_server::SignalEmitter};
use event_listener::{Event, Listener};

struct Greeter {
    name: String,
    done: Event,
}

#[interface(name = "org.zbus.MyGreeter1")]
impl Greeter {
    fn say_hello(&self, name: &str) -> String {
        format!("Hello {}!", name)
    }

    // Rude!
    async fn go_away(
        &self,
        #[zbus(signal_emitter)]
        emitter: SignalEmitter<'_>,
    ) -> fdo::Result<()> {
        emitter.greeted_everyone().await?;
        self.done.notify(1);

        Ok(())
    }

    /// A "GreeterName" property.
    #[zbus(property)]
    fn greeter_name(&self) -> &str {
        &self.name
    }

    /// A setter for the "GreeterName" property.
    ///
    /// Additionally, a `greeter_name_changed` method has been generated for you if you need to
    /// notify listeners that "GreeterName" was updated. It will be automatically called when
    /// using this setter.
    #[zbus(property)]
    fn set_greeter_name(&mut self, name: String) {
        self.name = name;
    }

    /// A signal; the implementation is provided by the macro.
    #[zbus(signal)]
    async fn greeted_everyone(emitter: &SignalEmitter<'_>) -> zbus::Result<()>;
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let greeter = Greeter {
        name: "GreeterName".to_string(),
        done: event_listener::Event::new(),
    };
    let done_listener = greeter.done.listen();
    let _handle = connection::Builder::session()
        .name("org.zbus.MyGreeter")
        .serve_at("/org/zbus/MyGreeter", greeter)
        .build()?;

    done_listener.wait();

    Ok(())
}
```

--------------------------------

### Implement a D-Bus Client with zbus

Source: https://github.com/z-galaxy/zbus/blob/main/README.md

Uses the proxy macro to interact with the MyGreeter service defined previously.

```rust
use zbus::{Connection, Result, proxy};

#[proxy(
    interface = "org.zbus.MyGreeter1",
    default_service = "org.zbus.MyGreeter",
    default_path = "/org/zbus/MyGreeter"
)]
trait MyGreeter {
    async fn say_hello(&self, name: &str) -> Result<String>;
}

// Although we use `tokio` here, you can use any async runtime of choice.
#[tokio::main]
async fn main() -> Result<()> {
    let connection = Connection::session().await?;

    // `proxy` macro creates `MyGreeterProxy` based on `Notifications` trait.
    let proxy = MyGreeterProxy::new(&connection).await?;
    let reply = proxy.say_hello("Maria").await?;
    println!("{reply}");

    Ok(())
```

--------------------------------

### Enable git hooks

Source: https://github.com/z-galaxy/zbus/blob/main/CONTRIBUTING.md

Copies the repository's git hook scripts into the local .git/hooks directory to automate development tasks.

```sh
cp .githooks/* .git/hooks/
```

--------------------------------

### Test D-Bus Service with busctl

Source: https://github.com/z-galaxy/zbus/blob/main/README.md

Command to invoke the SayHello method on the registered D-Bus service.

```bash
$ busctl --user call org.zbus.MyGreeter /org/zbus/MyGreeter org.zbus.MyGreeter1 SayHello s "Maria"
s "Hello Maria! I have been called 1 times."
```

--------------------------------

### Implement a D-Bus Service with zbus

Source: https://github.com/z-galaxy/zbus/blob/main/README.md

Defines a Greeter struct with an interface to handle D-Bus method calls. Requires a running D-Bus session bus.

```rust
use std::{error::Error, future::pending};
use zbus::{connection, interface};

struct Greeter {
    count: u64
}

#[interface(name = "org.zbus.MyGreeter1")]
impl Greeter {
    // Can be `async` as well.
    fn say_hello(&mut self, name: &str) -> String {
        self.count += 1;
        format!("Hello {}! I have been called {} times.", name, self.count)
    }
}

// Although we use `tokio` here, you can use any async runtime of choice.
#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let greeter = Greeter { count: 0 };
    let _conn = connection::Builder::session()
        .name("org.zbus.MyGreeter")
        .serve_at("/org/zbus/MyGreeter", greeter)
        .build()
        .await?;

    // Do other things or go to wait forever
    pending::<()>().await;

    Ok(())
}
```

--------------------------------

### FilePath conversion after upgrade

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/upgrading-to-6.md

Updated code using TryFrom to handle potential conversion errors.

```rust
use std::path::PathBuf;
use zbus::FilePath;

fn path_buf(file_path: FilePath<'_>) -> zbus::Result<PathBuf> {
    PathBuf::try_from(file_path)
}
```

--------------------------------

### Using the zbus 6 wire API

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/upgrading-to-6.md

Demonstrates the updated wire API for serialization and deserialization using zbus 6, including the use of zbus::wire::serialized::Context and zbus::wire::to_bytes.

```rust
use serde::{Deserialize, Serialize};
use zbus::{Type, wire::{serialized::Context, to_bytes, LE}};

#[derive(Deserialize, Serialize, Type, PartialEq, Debug)]
struct Struct<'s> {
    field1: u16,
    field2: i64,
    field3: &'s str,
}

assert_eq!(Struct::SIGNATURE, "(qxs)");

let ctxt = Context::new(LE, 0);
let s = Struct { field1: 42, field2: i64::MAX, field3: "hello" };
let encoded = to_bytes(ctxt, &s).unwrap();
let decoded: Struct<'_> = encoded.deserialize().unwrap().0;
assert_eq!(decoded, s);
```

--------------------------------

### Connect Functionality

Source: https://github.com/z-galaxy/zbus/blob/main/docs/superpowers/plans/2026-09-13-runtime-abstraction.md

Asynchronous connection logic for socket sources.

```rust
// io/connect.rs
pub(crate) async fn connect(runtime: &Runtime, domain: socket2::Domain, ty: socket2::Type,
                            addr: &socket2::SockAddr) -> io::Result<IoSource>
```

--------------------------------

### Connect helper function

Source: https://github.com/z-galaxy/zbus/blob/main/docs/superpowers/specs/2026-09-12-external-runtime-design.md

The connect function establishes a non-blocking socket connection using the provided runtime, domain, type, and address.

```rust
pub(crate) async fn connect(
    runtime: &Runtime,
    domain: socket2::Domain,
    ty: socket2::Type,
    address: &socket2::SockAddr,
) -> io::Result<IoSource>;
```

--------------------------------

### Generate client-side proxy with interface macro

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/service.md

Use the proxy attribute within the interface macro to generate a client-side proxy. Attributes like gen_blocking, default_path, and default_service are forwarded to the proxy macro.

```rust
use zbus::interface;

struct Greeter {
    name: String
}

#[interface(
    name = "org.zbus.MyGreeter.WithProxy",
    // Specifying the `proxy` attribute instructs `interface` to generate the
    // client-side proxy. You can specify proxy-specific attributes
    // (e.g `gen_blocking) here. All the attributes that are common between
    // `proxy` and `interface` macros (e.g `name`) are automtically forwarded to
    // the `proxy` macro.
    proxy(
        gen_blocking = false,
        default_path = "/org/zbus/MyGreeter/WithProxy",
        default_service = "org.zbus.MyGreeter.WithProxy",
    ),
)]
impl Greeter {
    #[zbus(property)]
    async fn greeter_name(&self) -> String {
        self.name.clone()
    }

    #[zbus(proxy(no_reply))]
    async fn whatever(&self) {
        println!("Whatever!");
    }
}

# #[tokio::main]
# async fn main() -> zbus::Result<()> {

let greeter = Greeter { name: "GreeterName".to_string() };
let connection = zbus::connection::Builder::session()
        .name("org.zbus.MyGreeter.WithProxy")
        .serve_at("/org/zbus/MyGreeter/WithProxy", greeter)
        .build()
        .await?;
let proxy = GreeterProxy::new(&connection).await?;
assert_eq!(proxy.greeter_name().await?, "GreeterName");
proxy.whatever().await?;

# Ok(())
# }
```

--------------------------------

### Builder Usage with String Arguments Before and After

Source: https://github.com/z-galaxy/zbus/blob/main/docs/superpowers/specs/2026-09-07-infallible-builder-setters-design.md

Comparison of builder usage with string arguments, showing the removal of the ? operator from individual setter calls.

```rust
let proxy = PropertiesProxy::builder(&conn)
    .destination("org.zbus.Foo")?
    .path("/org/zbus/Foo")?
    .build()
    .await?;
```

```rust
let proxy = PropertiesProxy::builder(&conn)
    .destination("org.zbus.Foo")
    .path("/org/zbus/Foo")
    .build()
    .await?;
```

--------------------------------

### Call Notify method with busctl

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/client.md

Sends a method call to the org.freedesktop.Notifications service on the user bus, triggering a desktop notification. The signature 'susssasa{sv}i' indicates 8 arguments of various types. Requires a desktop that supports the notification service.

```bash
busctl --user call \
  org.freedesktop.Notifications \
  /org/freedesktop/Notifications \
  org.freedesktop.Notifications \
  Notify \
  susssasa\{sv\}i \
  "my-app" 0 "dialog-information" "A summary" "Some body" 0 0 5000
```

--------------------------------

### Update zbus_xml lifetime parameters

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/upgrading-to-6.md

Demonstrates how to update function signatures to handle the new lifetime parameters in zbus_xml types and how to use into_owned() to persist a tree.

```rust
use zbus_xml::{Arg, Node};

// Was: fn describe(arg: &Arg) -> Option<&str>
fn describe<'a>(arg: &'a Arg<'_>) -> Option<&'a str> {
    arg.name()
}

// Keep the tree past the document it was parsed from.
fn parse(xml: &str) -> zbus_xml::Result<Node<'static>> {
    Ok(Node::try_from(xml)?.into_owned())
}
```

--------------------------------

### Builder Usage with Typed Arguments Before and After

Source: https://github.com/z-galaxy/zbus/blob/main/docs/superpowers/specs/2026-09-07-infallible-builder-setters-design.md

Comparison of builder usage with already-typed arguments, demonstrating that the ? operator is no longer required for setters even when inputs are guaranteed to be valid.

```rust
let proxy = PropertiesProxy::builder(&conn)
    .destination(proxy.destination())?   // &BusName: cannot fail
    .path(proxy.path())?                 // &ObjectPath: cannot fail
    .build()
    .await?;
```

```rust
let proxy = PropertiesProxy::builder(&conn)
    .destination(proxy.destination())   // &BusName: still cannot fail
    .path(proxy.path())                 // &ObjectPath: still cannot fail
    .build()
    .await?;
```

--------------------------------

### Verify service name with busctl

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/service.md

This bash command lists bus names and filters for 'zbus' to confirm that the service is running and associated with the requested name. The output shows the service name 'org.zbus.MyGreeter' and its process details.

```bash
$ busctl --user list | grep zbus
org.zbus.MyGreeter                             412452 service           elmarco :1.396        user@1000.service -       -
```

--------------------------------

### Configure zbus dependency for wire format only

Source: https://github.com/z-galaxy/zbus/blob/main/book/src/introduction.md

Use this configuration in your Cargo.toml to use the zbus wire format serialization without the full D-Bus connection features.

```toml
[dependencies]
zbus = { version = "6", default-features = false }
```
Tokens:
Raw