Struct libpd_rs::convenience::PdGlobal

pub struct PdGlobal {
    pub subscriptions: HashMap<String, ReceiverHandle>,
    pub search_paths: Vec<PathBuf>,
    /* private fields */
}

An abstraction provided for convenience to track the state of pd and execute some common functions.

Pd initializes globally.

This is one of the reasons that there are more bare functions in this crate than data structures and abstractions. This has some advantages and disadvantages. In the case of PdGlobal we can not fully trust the state we track here. To trust it we need to not mix the bare functions which PdGlobal wraps and member functions of PdGlobal together.

Example of an unwanted mix

use libpd_rs::convenience::PdGlobal;
use libpd_rs::convenience::dsp_off;

let mut pd = PdGlobal::init_and_configure(1, 2, 44100).unwrap();

// We call the member function of [`PdGlobal`] to activate audio
// which calls [`dsp_on`] internally which then sends a message
// to globally initialized pd to activate dsp.
pd.activate_audio(true).unwrap();

// So far so good.
assert_eq!(pd.audio_active(), true);

// But we can send messages to globally initialized pd many ways
// and here is one of the ways we can do it.
dsp_off().unwrap();

// But now [`PdGlobal`] is not aware of the state
// of the globally initialized pd in the background.
// The information it holds is outdated and not true anymore.
assert_eq!(pd.audio_active(), true);

To avoid this situation if you use PdGlobal check its member functions and only use them and not their bare counterparts.

There are many bare functions in this crate which is not wrapped by PdGlobal and those are safe to use while using PdGlobal related functions.

Fields

subscriptions: HashMap<String, ReceiverHandle>

A store to keep track of subscriptions which are made to senders in pd through the app lifecycle.

search_paths: Vec<PathBuf>

A store to keep track of paths which are added to pd search paths through the app lifecycle.

Implementations

impl PdGlobal

pub fn init_and_configure(
    input_channels: i32,
    output_channels: i32,
    sample_rate: i32
) -> Result<Self, Box<dyn Error>>

Initializes pd globally.

It calls init and initialize_audio with the provided arguments and returns an instance of PdGlobal where a user can keep simple state and call some convenience methods. It would be wise to call this function before anything pd related.

Please use only one instance of this struct, because of how libpd is designed the underlying initialization is scoped globally.

Examples

use libpd_rs::convenience::PdGlobal;

let mut pd = PdGlobal::init_and_configure(1, 2, 44100).unwrap();

Errors

A list of errors that can occur:

• InitializationError
  • RingBufferInitializationError
  • InitializationFailed
• AudioInitializationError
  • InitializationFailed

To match over these errors, you would need to downcast the returned error.

pub fn add_path_to_search_paths<T: AsRef<Path>>(
    &mut self,
    path: T
) -> Result<(), Box<dyn Error>>

Adds a path to the list of paths where libpd searches in.

Relative paths are relative to the current working directory. Unlike the desktop pd application, no search paths are set by default.

Errors

A list of errors that can occur:

• IoError
  • PathDoesNotExist

To match over these errors, you would need to downcast the returned error.

pub fn add_paths_to_search_paths<T: AsRef<Path>>(
    &mut self,
    paths: &[T]
) -> Result<(), Box<dyn Error>>

Adds many paths to the list of paths where libpd searches in.

Relative paths are relative to the current working directory. Unlike the desktop pd application, no search paths are set by default.

Errors

A list of errors that can occur:

• IoError
  • PathDoesNotExist

To match over these errors, you would need to downcast the returned error.

pub fn clear_all_search_paths(&mut self)

Clears all the paths where libpd searches for patches and assets.

pub fn close_patch(&mut self) -> Result<(), Box<dyn Error>>

Closes a pd patch.

Errors

A list of errors that can occur:

• PatchLifeCycleError
  • FailedToClosePatch

To match over these errors, you would need to downcast the returned error.

pub fn open_patch<T: AsRef<Path>>(
    &mut self,
    path: T
) -> Result<(), Box<dyn Error>>

Opens a pd patch.

The argument should be an absolute path to the patch file. Absolute and relative paths are supported. Relative paths and single file names are tried in executable directory and manifest directory.

Tha function first checks the executable directory and then the manifest directory.

Examples

use libpd_rs::convenience::PdGlobal;

let mut pd = PdGlobal::init_and_configure(1, 2, 44100).unwrap();
assert!(pd.open_patch("tests/patches/sine.pd").is_ok());

Errors

A list of errors that can occur:

• PatchLifeCycleError
  • FailedToClosePatch
  • FailedToOpenPatch
  • PathDoesNotExist

To match over these errors, you would need to downcast the returned error.

pub fn eval_patch<T: AsRef<str>>(
    &mut self,
    contents: T
) -> Result<(), Box<dyn Error>>

Evaluate a string as a pd patch.

This function creates a temporary file with the contents passed behind the scenes. and saves it into the PdGlobal struct holding onto it until the patch is closed or the instantiated PdGlobal is dropped.

Note: The patch opened after this evaluation could be closed safely with close_patch.

Examples

use libpd_rs::convenience::PdGlobal;

let mut pd = PdGlobal::init_and_configure(1, 2, 44100).unwrap();
     
assert!(pd.eval_patch(
r#"
#N canvas 577 549 158 168 12;
#X obj 23 116 dac~;
#X obj 23 17 osc~ 440;
#X obj 23 66 *~ 0.1;
#X obj 81 67 *~ 0.1;
#X connect 1 0 2 0;
#X connect 1 0 3 0;
#X connect 2 0 0 0;
#X connect 3 0 0 1;
"#
,).is_ok());

Errors

A list of errors that can occur:

• PatchLifeCycleError
  • FailedToEvaluateAsPatch
  • FailedToClosePatch
  • FailedToOpenPatch
  • PathDoesNotExist

To match over these errors, you would need to downcast the returned error.

pub fn subscribe_to<T: AsRef<str>>(
    &mut self,
    source: T
) -> Result<(), Box<dyn Error>>

Starts listening messages from a source.

If the source is already being listened to, this function will early return not doing anything without an error.

Examples

use libpd_rs::convenience::PdGlobal;

let mut pd = PdGlobal::init_and_configure(1, 2, 44100).unwrap();
pd.open_patch("tests/patches/sine.pd").unwrap();
pd.subscribe_to("sender").unwrap();

Errors

A list of errors that can occur:

• SubscriptionError
  • FailedToSubscribeToSender

To match over these errors, you would need to downcast the returned error.

pub fn subscribe_to_many<T: AsRef<str>>(
    &mut self,
    sources: &[T]
) -> Result<(), Box<dyn Error>>

Starts listening messages from many source.

If the any source is already being listened to, this function will will ignore them.

Examples

use libpd_rs::convenience::PdGlobal;

let mut pd = PdGlobal::init_and_configure(1, 2, 44100).unwrap();
pd.open_patch("tests/patches/sine.pd").unwrap();
pd.subscribe_to_many(&["sender", "other_sender"]).unwrap();

Errors

A list of errors that can occur:

• SubscriptionError
  • FailedToSubscribeToSender

To match over these errors, you would need to downcast the returned error.

pub fn unsubscribe_from<T: AsRef<str>>(&mut self, source: T)

Stops listening messages from a source.

Examples

use libpd_rs::convenience::PdGlobal;

let mut pd = PdGlobal::init_and_configure(1, 2, 44100).unwrap();
pd.open_patch("tests/patches/sine.pd").unwrap();
pd.subscribe_to("sender").unwrap();
pd.unsubscribe_from("sender");

pub fn unsubscribe_from_many<T: AsRef<str>>(&mut self, sources: &[T])

Stops listening messages from many sources.

Examples

use libpd_rs::convenience::PdGlobal;

let mut pd = PdGlobal::init_and_configure(1, 2, 44100).unwrap();
pd.open_patch("tests/patches/sine.pd").unwrap();
pd.subscribe_to_many(&["sender", "other_sender"]).unwrap();

pd.unsubscribe_from_many(&["sender", "other_sender"]);

pub fn unsubscribe_from_all(&mut self)

Stops listening from all sources.

Examples

use libpd_rs::convenience::PdGlobal;

let mut pd = PdGlobal::init_and_configure(1, 2, 44100).unwrap();
pd.open_patch("tests/patches/sine.pd").unwrap();
pd.subscribe_to_many(&["sender", "other_sender"]).unwrap();

pd.unsubscribe_from_all();

pub fn dollar_zero(&self) -> Result<i32, Box<dyn Error>>

Gets the $0 of the running patch.

$0 id in pd could be thought as a auto generated unique identifier for the patch.

Errors

A list of errors that can occur:

• PatchLifeCycleError
  • PatchIsNotOpen

To match over these errors, you would need to downcast the returned error.

pub const fn audio_active(&self) -> bool

Checks if the audio is active.

The state is tracked by PdGlobal.

If messages sent to pd previously to activate or de-activate audio not using methods provided in this struct. This state might be false.

pub fn activate_audio(&mut self, on: bool) -> Result<(), Box<dyn Error>>

Activates or deactivates audio in pd.

Errors

A list of errors that can occur:

• SendError
  • MissingDestination
• SizeError
  • TooLarge

To match over these errors, you would need to downcast the returned error.

pub const fn sample_rate(&self) -> i32

Gets the sample rate which pd is configured with.

The state is tracked by PdGlobal.

If anything else changes the internal state of pd it will not be reflected in this struct.

pub const fn input_channels(&self) -> i32

Gets the number of input channels which pd is configured with.

The state is tracked by PdGlobal.

If anything else changes the internal state of pd it will not be reflected in this struct.

pub const fn output_channels(&self) -> i32

Gets the number of output channels which pd is configured with.

The state is tracked by PdGlobal.

If anything else changes the internal state of pd it will not be reflected in this struct.