Tidy up and add docs to message passing primitives for worklets

Author: orottier

src/message_port.rs

@@ -5,36 +5,31 @@ use crate::node::AudioNode;
 
 use crate::events::{EventHandler, EventPayload, EventType};
 
-pub struct MessagePort<'a> {
-    inner: MessagePortFlavour<'a>,
-}
+/// One of the two ports of a message channel
+///
+/// Allowing messages to be sent from one port and listening out for them arriving at the other.
+pub struct MessagePort<'a>(&'a AudioContextRegistration);
 
 impl<'a> std::fmt::Debug for MessagePort<'a> {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         f.debug_struct("MessagePort").finish_non_exhaustive()
     }
 }
 
-enum MessagePortFlavour<'a> {
-    AudioNode(&'a AudioContextRegistration),
-    AudioProcessor,
-}
-
 impl<'a> MessagePort<'a> {
     pub(crate) fn from_node(node: &'a dyn AudioNode) -> Self {
-        let inner = MessagePortFlavour::AudioNode(node.registration());
-        Self { inner }
+        Self(node.registration())
     }
 
+    /// Send a message from the port.
     pub fn post_message<M: Any + Send + 'static>(&self, msg: M) {
-        match self.inner {
-            MessagePortFlavour::AudioNode(registration) => {
-                registration.post_message(msg);
-            }
-            _ => todo!(),
-        }
+        self.0.post_message(msg);
     }
 
+    /// Register callback to run when a message arrives on the channel.
+    ///
+    /// Only a single event handler is active at any time. Calling this method multiple times will
+    /// override the previous event handler.
     pub fn set_onmessage<F: FnMut(Box<dyn Any + Send + 'static>) + Send + 'static>(
         &self,
         mut callback: F,
@@ -44,25 +39,16 @@ impl<'a> MessagePort<'a> {
             _ => unreachable!(),
         };
 
-        match self.inner {
-            MessagePortFlavour::AudioNode(registration) => {
-                registration.context().set_event_handler(
-                    EventType::Message(registration.id()),
-                    EventHandler::Multiple(Box::new(callback)),
-                );
-            }
-            _ => todo!(),
-        }
+        self.0.context().set_event_handler(
+            EventType::Message(self.0.id()),
+            EventHandler::Multiple(Box::new(callback)),
+        );
     }
 
+    /// Unset the callback to run when a message arrives on the channel.
     pub fn clear_onmessage(&self) {
-        match self.inner {
-            MessagePortFlavour::AudioNode(registration) => {
-                registration
-                    .context()
-                    .clear_event_handler(EventType::Message(registration.id()));
-            }
-            _ => todo!(),
-        }
+        self.0
+            .context()
+            .clear_event_handler(EventType::Message(self.0.id()));
     }
 }

src/render/processor.rs

@@ -42,7 +42,7 @@ impl RenderScope {
     ///
     /// This method is just a shim of the full
     /// [`MessagePort`](https://webaudio.github.io/web-audio-api/#dom-audioworkletprocessor-port)
-    /// `onmessage` functionality of the AudioWorkletProcessor.
+    /// `postMessage` functionality of the AudioWorkletProcessor.
     pub fn post_message(&self, msg: Box<dyn Any + Send + 'static>) {
         if let Some(sender) = self.event_sender.as_ref() {
             // sending could fail if the channel is saturated or the main thread is shutting down

src/worklet.rs

@@ -1,7 +1,9 @@
 //! User-defined audio nodes and processors
 //!
-//! See `examples/worklet.rs` or `examples/worklet_bitcrusher.rs` for an example implementation of
-//! user defined nodes.
+//! See the following files for an example implementation of user defined nodes:
+//! - `examples/worklet.rs` (basics with an audio param)
+//! - `examples/worklet_message_port.rs` (basics with message port)
+//! - `examples/worklet_bitcrusher.rs` (real world example)
 
 pub use crate::render::RenderScope;
 
@@ -153,6 +155,7 @@ impl<C: Default> Default for AudioWorkletNodeOptions<C> {
 /// # Examples
 ///
 /// - `cargo run --release --example worklet`
+/// - `cargo run --release --example worklet_message_port`
 /// - `cargo run --release --example worklet_bitcrusher`
 ///
 #[derive(Debug)]
@@ -272,10 +275,19 @@ impl AudioWorkletNode {
         node
     }
 
+    /// Collection of AudioParam objects with associated names of this node
+    ///
+    /// This map is populated from a list of [`AudioParamDescriptor`]s in the
+    /// [`AudioWorkletProcessor`] class constructor at the instantiation.
     pub fn parameters(&self) -> &HashMap<String, AudioParam> {
         &self.audio_param_map
     }
 
+    /// Message port to the processor in the render thread
+    ///
+    /// Every AudioWorkletNode has an associated port which is the [`MessagePort`]. It is connected
+    /// to the port on the corresponding [`AudioWorkletProcessor`] object allowing bidirectional
+    /// communication between the AudioWorkletNode and its AudioWorkletProcessor.
     pub fn port(&self) -> MessagePort<'_> {
         MessagePort::from_node(self)
     }