cpal/src/host/wasapi/com.rs
Tatsuyuki Ishi 03947afefb wasapi: Allow both threading models and switch the default to STA
COM can prevent undefined behavior in either concurrency model by
performing marshaling when necessary. As a result, CoInitializeEx can be
called with either concurrency model, and in this case STA provides better
compatibility with other code requiring STA, e.g. ASIO backend or winit
drag-and-drop.

To dive into the detail, the entry point of WASAPI, MMDeviceEnumerator, is
registered with "both" threading model, which means that COM objects are
created with whatever the thread's concurrency model is set to. This raises
the concern that when STA is used, marshaling might make audio buffer
operations block on the main thread, breaking continuous audio processing.
However, the implementation actually uses free-threaded marshaller for
interfaces dealing with buffer operations, which effectively bypasses COM's
compatibility marshaling behavior and perform any API calls on the caller's
thread instead. Therefore, the interfaces would operate just fine on either
concurrency model.

For more details on COM's threading model, see [1].

[1] https://thrysoee.dk/InsideCOM+/ch04d.htm

Co-Authored-By: Henrik Rydgård <hrydgard@gmail.com>

Close #59
Close #348
Close #504
Close #530
Close #538
Close #572
2021-08-08 12:03:18 +09:00

56 lines
1.9 KiB
Rust

//! Handles COM initialization and cleanup.
use super::IoError;
use std::marker::PhantomData;
use std::ptr;
use super::winapi::shared::winerror::{HRESULT, RPC_E_CHANGED_MODE, SUCCEEDED};
use super::winapi::um::combaseapi::{CoInitializeEx, CoUninitialize};
use super::winapi::um::objbase::COINIT_APARTMENTTHREADED;
thread_local!(static COM_INITIALIZED: ComInitialized = {
unsafe {
// Try to initialize COM with STA by default to avoid compatibility issues with the ASIO
// backend (where CoInitialize() is called by the ASIO SDK) or winit (where drag and drop
// requires STA).
// This call can fail with RPC_E_CHANGED_MODE if another library initialized COM with MTA.
// That's OK though since COM ensures thread-safety/compatibility through marshalling when
// necessary.
let result = CoInitializeEx(ptr::null_mut(), COINIT_APARTMENTTHREADED);
if SUCCEEDED(result) || result == RPC_E_CHANGED_MODE {
ComInitialized {
result,
_ptr: PhantomData,
}
} else {
// COM initialization failed in another way, something is really wrong.
panic!("Failed to initialize COM: {}", IoError::from_raw_os_error(result));
}
}
});
/// RAII object that guards the fact that COM is initialized.
///
// We store a raw pointer because it's the only way at the moment to remove `Send`/`Sync` from the
// object.
struct ComInitialized {
result: HRESULT,
_ptr: PhantomData<*mut ()>,
}
impl Drop for ComInitialized {
#[inline]
fn drop(&mut self) {
// Need to avoid calling CoUninitialize() if CoInitializeEx failed since it may have
// returned RPC_E_MODE_CHANGED - which is OK, see above.
if SUCCEEDED(self.result) {
unsafe { CoUninitialize() };
}
}
}
/// Ensures that COM is initialized in this thread.
#[inline]
pub fn com_initialized() {
COM_INITIALIZED.with(|_| {});
}