`HostId` enum Refactor by cbrownsey · Pull Request #1274 · RustAudio/cpal

cbrownsey · 2026-07-15T10:48:05Z

Original Issue: #1260

This implements the change to having HostId include a variant for all possible hosts under any compilation configuration.

This also adds an implementation of TryFrom<HostId> for Host, which seemed the best way to have that. This also keeps available_hosts, host_from_id, and ALL_HOSTS, although they no longer seem relevant to keep anymore.

+ Added `host_id` sub-module, which contains the `HostId` non-exhaustive enum, and all associated implementations and definitions. + Added internal implementations in `platform::impl_platform_host`. + Added implementation of `TryFrom<HostId> for Host`. * Fixed links broken by moving `host_from_id` and `available_hosts`. * Added additional error kind to `host_from_id`. - Removed all definitions and impls of `HostId` from `platform`. - Removed `__cpal_select_host_name` internal macro. - Removed `default_host` from all `platform_impl` modules.

* Fixed hanging indentation on doc comment. - Removed import of `HostTrait` in `platform_impl` of `wasm-bindgen` target.

cbrownsey · 2026-07-15T11:02:35Z

Ack! Rookie mistake. All green now, but I'm not sure if I'm entirely keen on pushing as-is. I think the HostId enum should be pulled out of the platform module and be re-exported at the crate root. Additionally, I'm thinking that the available_hosts, host_from_id and ALL_HOSTS items should be canned. But this is what I outlined in the initial issue, so that's what I'm committing right now.

1rhino2

static pass on the HostId refactor (no runtime concerns here).

direction looks right for #1260: a single non_exhaustive HostId with every variant, plus is_supported / is_available / available_hosts(), and TryFrom for Host. that is cleaner than cfg-gated enums for cross-platform user code.

a few things to nail before merge

AvailableHostsIter::next currently returns hosts where is_supported() is true, but the docs on available_hosts / HostId::available_hosts talk about availability. supported != available (daemon down, etc). looks like the iterator should call is_available(), or the naming/docs need to match whichever filter you want.
Display writes ascii-lowercase ("wasapi") while FromStr examples/docs show mixed case like "WASAPI" / "ALSA". case-insensitive parse is fine; worth one golden test that Display round-trips through FromStr.
body notes available_hosts / host_from_id / ALL_HOSTS may be obsolete. if they stay, mark deprecated in the same PR so the migration path is obvious; if they go, UPGRADING.md needs a short note.
needs a rebase check against current master (this sat a bit).

i can help poke windows HostId::Wasapi / Asio availability after rebase if useful.

roderickvd · 2026-08-03T15:44:05Z

Valid point that supported isn’t equal to available. But to your last point, in which cases would that be different for WASAPI or ASIO?

+ Added migration path for removed items to `UPGRADING.md`. - Removed `ALL_HOSTS`, `available_hosts`, and `host_from_id`.

* `HostId::display` no longer outputs as lowercased. * `HostId::parse` now uses the mixed-case host id forms in the documentation. The error message is also slightly clarified. * `TryFrom<HostId> for Host` is now the implementation of `host_from_id`, as opposed to vice-versa.

+ Added documentation to `HostId` pointing to the `TryFrom` implementation to get a `Host`. - Removed `host_from_id`.

cbrownsey · 2026-08-06T16:11:52Z

I've made some changes. I decided to go for removing available_hosts, ALL_HOSTS, and host_from_id. I added a very short section about how to go from a HostId to a Host, which seems enough to me.

Thank you for spotting that I did use the wrong method in AvailableHostsIter, not sure what that was about. And I did remove the lowercasing in the Display method. I kept that from the previous implementation, but I never did like it as it felt like a very unnecessary allocation. I also added a test to ensure that the Display implementation round-trips, as you mentioned.

I've also updated some of the example files to have them compile with my changes, but they do still have the cfgs in them that this whole exercise is to remove, so I'll have those fixed up tomorrow. Other than that, I'm comfortable with the changes as they are.

roderickvd

Thanks for the rebase and refactor. Please find my first review attached. Happy to iterate with you to a solution that, this time, hopefully stands the test of time!

roderickvd · 2026-08-15T09:48:48Z

    let host = if opt.jack {
        jack_host_id
-            .and_then(cpal::host_from_id)
+            .and_then(TryFrom::try_from)


I like using TryFrom. How about keeping host_from_id around for one more release cycle and tagging it as deprecated?

roderickvd · 2026-08-15T09:51:04Z

-            if let Ok(host) = PipeWireHost::new() {
-                return host.into();
-            }
+    pub(crate) fn default_host_id() -> HostId {


This is silently removing the fallback paths checking whether PipeWire and PulseAudio aren't just supported but actually available. If they aren't, rather than falling back to ALSA, it will now panic.

roderickvd · 2026-08-15T09:54:04Z

+
+impl std::fmt::Display for HostId {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(self.name())


Though you did say you don't like the allocation, I'm not clear why you want to drop the convenience contract and consistency of using .to_ascii_lowercase().

If we do change then it needs to be mentioned in the changelog, because it will break existing string-compares and hash keys. But I'd first like to settle changing at all.

roderickvd · 2026-08-15T09:58:29Z

-        );
-        WebAudioHost::new().unwrap().into()
+    pub(crate) fn default_host_id() -> HostId {
+        HostId::WebAudio


What's your rationale for dropping the assertion that was there?

roderickvd · 2026-08-15T10:18:04Z

+/// If you have a `HostId` that you would like to turn into an instance of a [`Host`],
+/// you can use the `TryFrom<HostId>` implementation of [`Host`].
+///
+/// ```ignore


We used to have a more exhaustive and compiled doctest here.

roderickvd · 2026-08-15T10:21:44Z

+///
+/// [`Host`]: crate::Host
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+#[non_exhaustive]


We should ensure that the changelog contains entries for all breaking items. Beyond the changelog, this warrants an entry in the upgrading guide as well.

Further, we should ensure all examples and docs compile, and that docs are consistent with the new implementation and practices.

roderickvd · 2026-08-15T10:23:42Z

@@ -63,13 +67,35 @@ pub use crate::host::custom::{Device as CustomDevice, Host as CustomHost, Stream
 macro_rules! impl_platform_host {
    ($($(#[cfg($feat: meta)])? $HostVariant:ident $($HostName:literal)? => $Host:ty),* $(,)?) => {


Is $HostName dead now?

roderickvd · 2026-08-15T10:25:10Z

+    }
+}
+
+pub struct AvailableHostsIter(std::slice::Iter<'static, HostId>);


I think it'd be consistent with Devices and Supported*Configs to re-export this and derive Debug + Clone on it.

roderickvd · 2026-08-16T16:54:08Z

+
+        match_str_case_insensitive! {
+            s => {
+                "AAudio" => Ok(HostId::AAudio),


Mirroring FromStr and Display is normal in Rust, I know, but just to point out that the previous macro did that automatically. Not a blocker for me but worth considering to re-add.

roderickvd · 2026-08-16T16:55:21Z

+    pub const SUPPORTED_HOSTS: &[HostId] = {
+        // This is a hack to prevent rustdoc from referencing the
+        // implementation const in its output.
+        let _ = 1 + 2;


What happens without this?

roderickvd · 2026-08-16T19:41:56Z

I've promoted develop to master, so please rebase on master where we'll continue the 0.19.0 work.

cbrownsey added 2 commits July 15, 2026 22:35

fix(hostid): Fixed docs and extraneous import.

af4a010

* Fixed hanging indentation on doc comment. - Removed import of `HostTrait` in `platform_impl` of `wasm-bindgen` target.

1rhino2 reviewed Aug 2, 2026

View reviewed changes

This was referenced Aug 2, 2026

v0.19 design goals #1220

Open

Looking for maintainers #981

Open

cbrownsey added 5 commits August 7, 2026 01:56

fix(examples): No longer referencing to-be removed items.

8e2d1ce

refactor: Removed ALL_HOSTS, available_hosts, and host_from_id.

7c1da68

+ Added migration path for removed items to `UPGRADING.md`. - Removed `ALL_HOSTS`, `available_hosts`, and `host_from_id`.

fix: Actually remove host_from_id.

64d35ed

+ Added documentation to `HostId` pointing to the `TryFrom` implementation to get a `Host`. - Removed `host_from_id`.

test: HostId roundtrips through Display and FromStr.

833fd71

roderickvd requested changes Aug 16, 2026

View reviewed changes

roderickvd added the enhancement label Aug 16, 2026

		@@ -63,13 +67,35 @@ pub use crate::host::custom::{Device as CustomDevice, Host as CustomHost, Stream
		macro_rules! impl_platform_host {
		($($(#[cfg($feat: meta)])? $HostVariant:ident $($HostName:literal)? => $Host:ty),* $(,)?) => {

Uh oh!

Conversation

cbrownsey commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cbrownsey commented Jul 15, 2026

Uh oh!

1rhino2 left a comment

Choose a reason for hiding this comment

Uh oh!

roderickvd commented Aug 3, 2026

Uh oh!

cbrownsey commented Aug 6, 2026

Uh oh!

roderickvd left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

roderickvd commented Aug 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

cbrownsey commented Jul 15, 2026 •

edited

Loading