cubeb-coreaudio-rs

Rust implementation of Cubeb on the MacOS platform.

Current Goals

• Rewrite the C code into Rust on a line-by-line basis
• Create some tests for later refactoring
• Defuse the OwnedCriticalSection. See proposal here.

Status

All the lines in cubeb_audiounit.cpp are translated.

By applying the patch to integrate within Cubeb, it can pass all the tests under cubeb/test.

The plain translation version from the C code is on plain-translation-from-c branch. The working draft version is on trailblazer branch. Both branches can pass all the tests on tryserver for firefox. However, we are replacing our custom mutex, which is translated from C version directly, by standard Rust mutex. The code is on ocs-disposal branch and ocs-disposal-stm branch.

The project can also be tracked on bugzilla 1530715. The instructios to integrate this project into firefox gecko can be found there. You can also find the formal patches and the reviews there. The easiest way to integrate this project into firefox gecko is to apply all the patches.

Defusing the custom mutex

Now all the custom mutexes in cubeb context is replaced. The code is on ocs-disposal branch.

The replacement for the custom mutexes in cubeb stream is still a work in process. The code is in ocs-disposal-stm branch.

Test

Please run sh run_tests.sh.

Some tests cannot be run in parallel. They may operate the same device at the same time, or indirectly fire some system events that are listened by some tests.

The tests that may affect others are marked #[ignore]. They will be run by cargo test ... -- --ignored ... after finishing normal tests. Most of the tests are executed in run_tests.sh. Only those tests commented with FIXIT are left.

Device Switching

The system default device will be changed during our tests. All the available devices will take turns being the system default device. However, after finishing the tests, the default device will be set to the original one. The sounds in the tests should be able to continue whatever the system default device is.

Device Plugging/Unplugging

We implement APIs simulating plugging or unplugging a device by adding or removing an aggregate device programmatically. It's used to verify our callbacks for minitoring the system devices work.

Manual Test

• Output devices switching
  • $ cargo test test_switch_output_device -- --ignored --nocapture
  • Enter s to switch output devices
  • Enter q to finish test
• Device change events listener
  • $ cargo test test_add_then_remove_listeners -- --ignored --nocapture
  • Plug/Unplug devices or switch input/output devices to see events log.
• Device collection change
  • cargo test test_device_collection_change -- --ignored --nocapture
  • Plug/Unplug devices to see events log.

TODO

See TO-DOs

Issues

• See discussion here
• Mutex: Find a replacement for owned_critical_section
  • A dummy mutex like Mutex<()> should work (see test_dummy_mutex_multithread) as what owned_critical_section does in C version, but it doens't has equivalent API for assert_current_thread_owns.
  • We implement a OwnedCriticalSection around pthread_mutex_t like what we do in C version for now.
  • It's hard to debug with the variables using OwnedCriticalSection. Within a test with a variable using OwnedCriticalSection, if the OwnedCriticalSection used in the test isn't be dropped in a correct order, then the test will get a crash in OwnedCriticalSection.
• Atomic:
  • We need atomic type around f32 but there is no this type in the stardard Rust
  • Using atomic-rs to do this.
• Unworkable API: dispatch_async and dispatch_sync
  • Replace dispatch_async by async_dispatch, which is based on dispatch_async_f.
  • Replace dispatch_sync by sync_dispatch, which is based on dispatch_sync_f.
• Mutex Borrowing Issues
  • We have a mutex in AudioUnitContext, and we have a reference to AudioUnitContext in AudioUnitStream. To sync what we do in C version, we need to lock the mutex in AudioUnitContext then pass a reference to AudioUnitContext to AudioUnitStream::new(...).
  • To lock the mutex in AudioUnitContext, we call AutoLock::new(&mut AudioUnitContext.mutex). That is, we will borrow a reference to AudioUnitContext as a mutable first then borrow it again. It's forbidden in Rust.
  • Some workarounds are
    1. Replace AutoLock by calling mutex.lock() and mutex.unlock() explicitly.
    2. Save the pointer to mutex first, then call AutoLock::new(unsafe { &mut (*mutex_ptr) }).
    3. Cast immutable reference to a *const then to a *mut: pthread_mutex_lock(&self.mutex as *const pthread_mutex_t as *mut pthread_mutex_t)
• No guarantee on audiounit_set_channel_layout
  • This call doesn't work all the times
  • Returned NO_ERR doesn't guarantee the layout is set to the one we want
  • The layouts on some devices won't be changed even no errors are returned, e.g., we can set stereo layout to a 4-channels aggregate device with QUAD layout (created by Audio MIDI Setup) without any error. However, the layout of this 4-channels aggregate device is still QUAD after setting it without error
  • Another weird thing is that we will get a kAudioUnitErr_InvalidPropertyValue if we set the layout to QUAD. It's the same layout as its original one but it cannot be set!

Test issues

• Complexity of creating unit tests
  • We have lots of dependent APIs, so it's hard to test one API only, specially for those APIs using mutex(OwnedCriticalSection actually)
  • It's better to split them into several APIs so it's easier to test them
• Fail to run test_create_blank_aggregate_device with test_add_device_listeners_dont_affect_other_scopes_with_* at the same time
  • audiounit_create_blank_aggregate_device will fire the callbacks in test_add_device_listeners_dont_affect_other_scopes_with_*
• Fail to run test_configure_{input, output}_with_zero_latency_frames and test_configure_{input, output} at the same time.
  • The APIs depending on audiounit_set_buffer_size cannot be called in parallel
    • kAudioDevicePropertyBufferFrameSize cannot be set when another stream using the same device with smaller buffer size is active. See here for reference.
    • The buffer frame size within same device may be overwritten (For those AudioUnits using same device ?)
• Fail to run test_ops_context_register_device_collection_changed_twice_* on my MacBook Air and Travis CI.
  • A panic in capi_register_device_collection_changed causes EXC_BAD_INSTRUCTION.
  • Works fine if replacing register_device_collection_changed: Option<unsafe extern "C" fn(..,) -> c_int> to register_device_collection_changed: unsafe extern "C" fn(..,) -> c_int
  • Test them in AudioUnitContext directly instead of calling them via OPS for now.
• TestDeviceSwitcher cannot work when there is an alive full-duplex stream
  • An aggregate device will be created for a duplex stream when its input and output devices are different.
  • TestDeviceSwitcher will cached the available devices, upon it's created, as the candidates for default device
  • Hence the created aggregate device may be cached in TestDeviceSwitcher
  • If the aggregate device is destroyed (when the destroying the duplex stream created it) but the TestDeviceSwitcher is still working, it will set a destroyed device as the default device
  • See details in device_change.rs