`HostId` enum Refactor

[cbrownsey]

The HostId enum currently depends very heavily on the features cpal is compiled with, as each variant is only available if the corresponding backend is supported in the current build. This means that writing code which can switch between different backends, or which even just wants to be aware of which backend is currently being used must convert it into a string, and work with that. This is error prone and laborious.

I propose changing the HostId to be #[non_exhaustive], and to include every backend which is supported by cpal under any possible combination of features. The SUPPORTED_HOSTS associated constant, and is_supported method will surface the same information as the ALL_HOSTS constant currently does before these changes, with is_supported being equivalent to being included in SUPPORTED_HOSTS. The available_hosts iterator method and is_available method will surface the same information that the available_hosts function currently exposes, without the mandatory Vec allocation.

The items HostId, ALL_HOSTS, available_hosts, default_host, and host_from_id will also be pulled out from behind any feature gates to improve the documentation UX, as they aren't feature-dependent. This does add another failure mode to host_from_id, that being passing the HostId of an unsupported backend, in which case it will return ErrorKind::UnsupportedOperation.

HostId is also given a Default implementation, which is equivalent to the id of the host returned by default_host. This is primarily for the sake of the implementation, as opposed to being something users are inspecting, but it may also be useful for that purpose.

I'm not necessarily proposing deprecating ALL_HOSTS and available_hosts, although they would be made redundant should this be implemented, so they could be deprecated.

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
enum HostId {
    AAudio,
    Alsa,
    Asio,
    AudioWorklet,
    CoreAudio,
    Custom,
    Jack,
    Null,
    Wasapi,
    WebAudio,
}

impl HostId {
    /// Every `HostId` supported by the current configuration of cpal.
    const SUPPORTED_HOSTS: &[Self];
    
    /// Returns `true` if the given host is supported by the current configuration of cpal.
    const fn is_supported(&self) -> bool;
    
    /// Returns `true` if the given host is currently available on this platform.
    fn is_available(&self) -> bool;
    
    /// Returns an iterator over the hosts which are currently available on this platform.
    const fn available_hosts() -> AvailableHostsIter;
}

struct AvailableHostsIter { .. }

impl Iterator for AvailableHostsIter {
    type Item = HostId;
    
    ...
}

impl Default for HostId { ... }

[cbrownsey]

@roderickvd previously mentioned that the HostId::is_available method conflates the concept of a Host versus a HostId, which is probably true. My reasoning for including it is that it is information which is available without needing a host to be instantiated, but which is currently stuck behind a cfg attribute for each host. In my opinion, it also doesn't conflate them any more than the currently existing available_hosts function.

[roderickvd]

This seems to be a good idea. A single HostId with every variant present regardless of platform, #[non_exhaustive], looks right. @xephyris what do you think? I remember we discussed it when you introduced stable device IDs with #1014. I have to read back to what we considered then.

With regards to Default for HostId: I'd push this further than "for the implementation's sake." default_host() on Linux manually implements a runtime PipeWire -> PulseAudio -> ALSA fallback. If HostId::default() can do that, then that'd be a real simplification.

Have you already tried working on the impl_platform_host! macro? Today that only expands over variants that exist on the current platform/feature set. Making every variant always present means is_supported/is_available need to answer for hosts that aren't compiled in without referencing their (absent) types.

[BillyDM]

Yes, I think this is a good change.

[xephyris]

This seems like a pretty good idea to me.

It is somewhat similar to the original implementation of DeviceId, however in this case it seems to be more dedicated for Host only.

When we were initially discussing the stable device IDs, the DeviceId enum had branches for each possible Host like what the planned HostId is, but we eventually settled for simplifying it to become (HostId, String) in #1046 , and instead had a list of all the possible hosts placed in the documentation.

I also am curious about what the plan is to resolve the issue with the modules and types not being present when compiling as mentioned above.

[cbrownsey]

Have you already tried working on the impl_platform_host! macro? Today that only expands over variants that exist on the current platform/feature set. Making every variant always present means is_supported/is_available need to answer for hosts that aren't compiled in without referencing their (absent) types.

I had a bit of a fiddle around with it. I'm in the middle of moving house so don't have access to my main PC right at the moment, but it seems to me that the cleanest implementation is to add two crate-internal functions host_id_is_available and host_id_is_supported inside impl_platform_host!, defined something like:

pub(crate) const fn host_id_is_supported(id: HostId) -> bool {
    match id {
        $(
            $(#[cfg($feat)])?
            HostId::$HostVariant => true,
        )*

        _ => false
    }
}

pub(crate) fn host_id_is_available(id: HostId) -> bool {
    match id {
        $(
            $(#[cfg($feat)])?
            HostId::$HostVariant => <$Host as crate::traits::HostTrait>::is_available(),
        )*

        _ => false
    }
}

HostId::is_available/is_supported can then just be a wrapper around those functions. The same thing should work for HostId::SUPPORTED_HOSTS, but the function that Default for HostId wraps won't go in the macro, and can just live next to default_host().

I'll probably also pull the actual HostId enum into its own sub-module, and have it re-exported under platform.