Remove Null host

CHANGELOG.md

@@ -30,6 +30,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `StreamInstant` creation is now `const`.
 - `SampleFormat` methods are now `const`, and take `self`.
 - Renamed the `wasm-beep` and `audioworklet-beep` examples to `webaudio` and `audioworklet`.
+- **Null**: Removed the null host.
 - **ALSA**: Update `alsa` dependency to 0.12.
 - **CoreAudio**: `DeviceDescription::interface_type()` now reports the device transport instead of only marking aggregate devices.
 - **CoreAudio**: A `None` timeout now waits indefinitely for sample rate and format changes, instead of giving up after 1 or 2 seconds.

UPGRADING.md

@@ -12,6 +12,7 @@ This guide covers breaking changes requiring code updates. See [CHANGELOG.md](CH
 - [ ] Replace `InputStreamTimestamp`/`OutputStreamTimestamp` with `StreamTimestamp`; `capture`/`playback` is now `device`.
 - [ ] Remove `ErrorKind::Xrun` match arms; read `CallbackInfo::xrun()` instead.
 - [ ] Update `SampleFormat` method calls to use `self` instead of `&self`; methods are now `const`.
+- [ ] If you relied on the `Null` host exisiting on exotic targets, `cfg()` gate `default_host()`, or impl a `Custom` host.
 
 ## 1. `DeviceTrait` and `StreamTrait` require `Send + Sync`
 
@@ -116,6 +117,28 @@ formats.retain(|f| f.is_int());
 **Why:** `SampleFormat` is a simple enum, there was no reason why it shouldn't be const-friendly, and since every method was both `inline` and it implements `Copy`, there is no performance downside to it taking `self`, but simply more legible than dereferencing.
 
 [`SampleFormat`]: https://docs.rs/cpal/latest/cpal/enum.SampleFormat.html
+
+## 6. `Null` host removed.
+
+**What changed:** The `Null` host was removed.
+
+```rust
+// Target: x86_64-unknown-illumos
+
+// Before (v0.18):
+let host = cpal::default_host();
+
+let device = host.default_output_device().unwrap();
+// Panic: No output devices
+
+// After (v0.19): no longer compiles
+let host = cpal::default_host();
+// Compilation error: No audio hosts
+```
+
+**Impact:** Compilations on targets without cpal audio backends must either gate it, or implement a `Custom` host.
+
+**Why:** `Null` served no purpose except to allow compilations to succeed, when in reality, cpal already had specific platform restrictions, and as such it is no longer required.
 ---
 
 # Upgrading from v0.17 to v0.18

src/host/mod.rs

@@ -86,22 +86,6 @@ pub(crate) mod webaudio;
 #[cfg(feature = "custom")]
 pub(crate) mod custom;
 
-#[cfg(not(any(
-    windows,
-    target_os = "linux",
-    target_os = "dragonfly",
-    target_os = "freebsd",
-    target_os = "netbsd",
-    target_vendor = "apple",
-    target_os = "android",
-    all(
-        target_arch = "wasm32",
-        any(target_os = "emscripten", target_os = "unknown"),
-        feature = "wasm-bindgen"
-    ),
-)))]
-pub(crate) mod null;
-
 #[cfg(any(
     target_vendor = "apple",
     target_os = "windows",

src/platform/mod.rs

@@ -119,7 +119,6 @@ macro_rules! impl_platform_host {
         /// - `"coreaudio"` - CoreAudio
         /// - `"custom"` - Custom host (requires `custom` feature)
         /// - `"jack"` - JACK Audio Connection Kit
-        /// - `"null"` - Null host
         /// - `"wasapi"` - Windows Audio Session API
         /// - `"webaudio"` - Web Audio API
         ///
@@ -1010,17 +1009,20 @@ mod platform_impl {
     ),
 )))]
 mod platform_impl {
-    use crate::host::null::Host as NullHost;
-
     impl_platform_host!(
-        Null => NullHost,
         #[cfg(feature = "custom")] Custom => super::CustomHost,
     );
 
     /// The default host for the current compilation target platform.
+    #[cfg(feature = "custom")]
     pub fn default_host() -> Host {
-        NullHost::new()
+        super::CustomHost::new()
             .expect("the default host should always be available")
             .into()
     }
+
+    #[cfg(not(feature = "custom"))]
+    pub fn default_host() -> Host {
+        compile_error!("The current compilation target has no audio backends, or a custom host")
+    }
 }