milk cacao IO conventions

Goals

Adopt clear standards for high-level applications (such as cacao TUIs/GUIs) to interface with processes and functions. The proposed standards listed in this documentation are being developed for cacao, but will ultimately be employed across milk.

The current (Apr 2019) way GUIs/TUIs read and write parameters and interact with processes is confusing and relies on multiple standards. It also makes it difficult to write GUIs/TUIs. For example, to change a parameter in a cacao process, we very frequently rely on a separate "control" process within cacao, requiring the TUI/GUI to write characters in a tmux session where the cacao instance of the "control" process is running. This is convoluted, and requires many non-standard tmux sessions.

Interacting with processes: how to read/write function parameters

Overview

The proposed new scheme will rely on the function parameter structure (fps) framework. The fps is a shared memory structure holding parameters/variables for a process. Under the new proposed standard, we will move ALL of the communication between GUIs/TUIs through the fps.

There is already a self-building TUI to interact (visually) with function parameters: fpsCTRL. The fpsCTRL TUI allows user to view and change parameters interactively by navigating through the fps entries.

fifo

Upon startup, fpsCTRL will create a fifo through which fps entries can be modified. For example:

fpsCTRL -f /milk/shm/fpsCTRL.fifo

will create the fifo file specified by the -f option. To change parameter value, user can send a string to the fifo:

echo "setval aoloop0.gain 0.2" >> /milk/shm/fpsCTRL.fifo

If/when fpsCTRL is running, it will receive and process the command.

Running multiple, separate instances of cacao

By default, if the -f option is not included, the fifo will be automatically created as:

$MILK_SHM_DIR/fpsCTRL.cmd.fifo

Where the environment variable MILK_SHM_DIR specifies the location of all shared memory and temporary files. This convention ensures that multiple instances of cacao can run on the same machine without interference, provided that they use different MILK_SHM_DIR directories. data is firewalled between the instances, allowing even incompatible versions of cacao/milk to run on the same computer.