Better multithreading options

.gitignore

@@ -5,3 +5,4 @@
 env.sh
 env.bat
 shell.nix
+.vscode

core/src/channel_group/mod.rs

@@ -16,15 +16,35 @@ const MAX_EVENT_CACHE_SIZE: u32 = 1024 * 1024;
 ///
 /// Manages multiple VoiceChannel objects at once.
 pub struct ChannelGroup {
-    thread_pool: rayon::ThreadPool,
+    thread_pool: Option<rayon::ThreadPool>,
     cached_event_count: u32,
     channel_events_cache: Box<[Vec<ChannelAudioEvent>]>,
     sample_cache_vecs: Box<[Vec<f32>]>,
     channels: Box<[VoiceChannel]>,
     audio_params: AudioStreamParams,
 }
 
+/// Options regarding which parts of the ChannelGroup should be multithreaded.
+///
+/// The following apply for all the values:
+/// - A value of `None` means no multithreading.
+/// - If the value is set to `Some(0)` then the number of threads will be
+///     determined automatically by `rayon`. Please read
+///     [this](https://docs.rs/rayon-core/1.11.0/rayon_core/struct.ThreadPoolBuilder.html#method.num_threads)
+///     for more information.
+#[derive(Clone)]
+pub struct ParallelismOptions {
+    /// Render the MIDI channels parallel in a threadpool with the specified
+    /// thread count.
+    pub channel: Option<usize>,
+
+    /// Render the individisual keys of each channel parallel in a threadpool
+    /// with the specified thread count.
+    pub key: Option<usize>,
+}
+
 /// Options for initializing a new ChannelGroup.
+#[derive(Clone)]
 pub struct ChannelGroupConfig {
     /// Channel initialization options (same for all channels).
     /// See the `ChannelInitOptions` documentation for more information.
@@ -45,10 +65,9 @@ pub struct ChannelGroupConfig {
     /// See the `AudioStreamParams` documentation for more information.
     pub audio_params: AudioStreamParams,
 
-    /// Whether or not to use a threadpool to render individual keys' voices.
-    /// Regardless, each MIDI channel uses its own thread. This setting
-    /// adds more fine-grained threading per key rather than per channel.
-    pub use_threadpool: bool,
+    /// Options about the `ChannelGroup` instance's parallelism. See the `ParallelismOptions`
+    /// documentation for more information.
+    pub parallelism: ParallelismOptions,
 }
 
 impl ChannelGroup {
@@ -60,26 +79,38 @@ impl ChannelGroup {
         let mut sample_cache_vecs = Vec::new();
 
         // Thread pool for individual channels to split between keys
-        let pool = if config.use_threadpool {
-            Some(Arc::new(rayon::ThreadPoolBuilder::new().build().unwrap()))
-        } else {
-            None
-        };
+        let channel_pool = config.parallelism.key.map(|threads| {
+            Arc::new(
+                rayon::ThreadPoolBuilder::new()
+                    .num_threads(threads)
+                    .build()
+                    .unwrap(),
+            )
+        });
+
+        // Thread pool for splitting channels between threads
+        let group_pool = config.parallelism.channel.map(|threads| {
+            rayon::ThreadPoolBuilder::new()
+                .num_threads(threads)
+                .build()
+                .unwrap()
+        });
 
         for i in 0..config.channel_count {
             let mut init = config.channel_init_options;
             init.drums_only = config.drums_channels.clone().into_iter().any(|c| c == i);
 
-            channels.push(VoiceChannel::new(init, config.audio_params, pool.clone()));
+            channels.push(VoiceChannel::new(
+                init,
+                config.audio_params,
+                channel_pool.clone(),
+            ));
             channel_events_cache.push(Vec::new());
             sample_cache_vecs.push(Vec::new());
         }
 
-        // Thread pool for splitting channels between threads
-        let thread_pool = rayon::ThreadPoolBuilder::new().build().unwrap();
-
         Self {
-            thread_pool,
+            thread_pool: group_pool,
             cached_event_count: 0,
             channel_events_cache: channel_events_cache.into_boxed_slice(),
             channels: channels.into_boxed_slice(),
@@ -121,44 +152,75 @@ impl ChannelGroup {
             return;
         }
 
-        let thread_pool = &mut self.thread_pool;
-        let channels = &mut self.channels;
-        let channel_events_cache = &mut self.channel_events_cache;
-
-        thread_pool.install(move || {
-            channels
-                .par_iter_mut()
-                .zip(channel_events_cache.par_iter_mut())
-                .for_each(|(channel, events)| {
-                    channel.push_events_iter(events.drain(..).map(ChannelEvent::Audio));
+        match self.thread_pool.as_ref() {
+            Some(pool) => {
+                let channels = &mut self.channels;
+                let channel_events_cache = &mut self.channel_events_cache;
+
+                pool.install(move || {
+                    channels
+                        .par_iter_mut()
+                        .zip(channel_events_cache.par_iter_mut())
+                        .for_each(|(channel, events)| {
+                            channel.push_events_iter(events.drain(..).map(ChannelEvent::Audio));
+                        });
                 });
-        });
+            }
+            None => {
+                for (channel, events) in self
+                    .channels
+                    .iter_mut()
+                    .zip(self.channel_events_cache.iter_mut())
+                {
+                    channel.push_events_iter(events.drain(..).map(ChannelEvent::Audio));
+                }
+            }
+        }
 
         self.cached_event_count = 0;
     }
 
     fn render_to(&mut self, buffer: &mut [f32]) {
         self.flush_events();
-
-        let thread_pool = &mut self.thread_pool;
-        let channels = &mut self.channels;
-        let sample_cache_vecs = &mut self.sample_cache_vecs;
-
         buffer.fill(0.0);
-        thread_pool.install(move || {
-            channels
-                .par_iter_mut()
-                .zip(sample_cache_vecs.par_iter_mut())
-                .for_each(|(channel, samples)| {
-                    samples.resize(buffer.len(), 0.0);
-                    channel.read_samples(samples.as_mut_slice());
+
+        match self.thread_pool.as_ref() {
+            Some(pool) => {
+                let channels = &mut self.channels;
+                let sample_cache_vecs = &mut self.sample_cache_vecs;
+                pool.install(move || {
+                    channels
+                        .par_iter_mut()
+                        .zip(sample_cache_vecs.par_iter_mut())
+                        .for_each(|(channel, samples)| {
+                            samples.resize(buffer.len(), 0.0);
+                            channel.read_samples(samples.as_mut_slice());
+                        });
+
+                    for vec in sample_cache_vecs.iter_mut() {
+                        sum_simd(vec, buffer);
+                        vec.clear();
+                    }
                 });
+            }
+            None => {
+                let len = buffer.len();
+
+                for (channel, samples) in self
+                    .channels
+                    .iter_mut()
+                    .zip(self.sample_cache_vecs.iter_mut())
+                {
+                    samples.resize(len, 0.0);
+                    channel.read_samples(samples.as_mut_slice());
+                }
 
-            for vec in sample_cache_vecs.iter_mut() {
-                sum_simd(vec, buffer);
-                vec.clear();
+                for vec in self.sample_cache_vecs.iter_mut() {
+                    sum_simd(vec, buffer);
+                    vec.clear();
+                }
             }
-        });
+        }
     }
 
     /// Returns the active voice count of the synthesizer.

kdmapi/src/lib.rs

@@ -60,7 +60,6 @@ pub extern "C" fn GetVoiceCount() -> u64 //This entire function is custom to xsy
 pub extern "C" fn InitializeKDMAPIStream() -> i32 {
     let config = XSynthRealtimeConfig {
         render_window_ms: 5.0,
-        use_threadpool: true,
         ..Default::default()
     };
 

realtime/src/config.rs

@@ -25,12 +25,17 @@ pub struct XSynthRealtimeConfig {
     /// Default: `[9]`
     pub drums_channels: Vec<u32>,
 
-    /// Whether or not to use a threadpool to render individual keys' voices.
+    /// Controls the use a threadpool to render individual keys' voices.
+    /// When a value is set, the specified number of threads will be used
+    /// for that operation, while `None` means no per-key concurrency.
+    /// If the value is set to `Some(0)` then the number of threads will
+    /// be determined automatically by `rayon`.
+    ///
     /// Regardless, each MIDI channel uses its own thread. This setting
     /// adds more fine-grained threading per key rather than per channel.
     ///
-    /// Default: `false`
-    pub use_threadpool: bool,
+    /// Default: `None`
+    pub threadpool: Option<usize>,
 
     /// A range of velocities that will not be played.
     ///
@@ -45,7 +50,7 @@ impl Default for XSynthRealtimeConfig {
             render_window_ms: 10.0,
             channel_count: 16,
             drums_channels: vec![9],
-            use_threadpool: false,
+            threadpool: None,
             ignore_range: 0..=0,
         }
     }

realtime/src/realtime_synth.rs

@@ -137,11 +137,14 @@ impl RealtimeSynth {
         let sample_rate = stream_config.sample_rate().0;
         let stream_params = AudioStreamParams::new(sample_rate, stream_config.channels().into());
 
-        let pool = if config.use_threadpool {
-            Some(Arc::new(rayon::ThreadPoolBuilder::new().build().unwrap()))
-        } else {
-            None
-        };
+        let pool = config.threadpool.map(|threads| {
+            Arc::new(
+                rayon::ThreadPoolBuilder::new()
+                    .num_threads(threads)
+                    .build()
+                    .unwrap(),
+            )
+        });
 
         let (output_sender, output_receiver) = bounded::<Vec<f32>>(config.channel_count as usize);
 

render/src/builder.rs

@@ -23,6 +23,8 @@ use midi_toolkit::{
     },
 };
 
+pub use xsynth_core::channel_group::ParallelismOptions;
+
 /// Statistics of an XSynthRender object.
 pub struct XSynthRenderStats {
     /// The progress of the render in seconds.
@@ -64,11 +66,12 @@ pub struct XSynthRenderBuilder<'a, StatsCallback: FnMut(XSynthRenderStats)> {
 
 /// Initializes an XSynthRenderBuilder object.
 pub fn xsynth_renderer<'a>(
+    config: XSynthRenderConfig,
     midi_path: &'a str,
     out_path: &'a str,
 ) -> XSynthRenderBuilder<'a, impl FnMut(XSynthRenderStats)> {
     XSynthRenderBuilder {
-        config: XSynthRenderConfig::default(),
+        config,
         midi_path,
         soundfonts: vec![],
         layer_count: Some(4),
@@ -84,12 +87,12 @@ impl<'a, ProgressCallback: FnMut(XSynthRenderStats)> XSynthRenderBuilder<'a, Pro
     }
 
     pub fn with_channel_count(mut self, channels: u32) -> Self {
-        self.config.channel_count = channels;
+        self.config.group_options.channel_count = channels;
         self
     }
 
-    pub fn use_threadpool(mut self, use_threadpool: bool) -> Self {
-        self.config.use_threadpool = use_threadpool;
+    pub fn with_parallelism(mut self, options: ParallelismOptions) -> Self {
+        self.config.group_options.parallelism = options;
         self
     }
 
@@ -99,12 +102,12 @@ impl<'a, ProgressCallback: FnMut(XSynthRenderStats)> XSynthRenderBuilder<'a, Pro
     }
 
     pub fn with_sample_rate(mut self, sample_rate: u32) -> Self {
-        self.config.sample_rate = sample_rate;
+        self.config.group_options.audio_params.sample_rate = sample_rate;
         self
     }
 
     pub fn with_audio_channels(mut self, audio_channels: u16) -> Self {
-        self.config.audio_channels = audio_channels;
+        self.config.group_options.audio_params.channels = audio_channels.into();
         self
     }