From 9718e10c7f4151cea895f515c785c14e0021d967 Mon Sep 17 00:00:00 2001 From: cbdev Date: Wed, 18 Mar 2020 22:36:35 +0100 Subject: Implement default channel handlers for Lua/Python --- backends/lua.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) (limited to 'backends/lua.md') diff --git a/backends/lua.md b/backends/lua.md index db4cf39..96e53c8 100644 --- a/backends/lua.md +++ b/backends/lua.md @@ -6,7 +6,8 @@ and manipulate events using the Lua scripting language. Every instance has its own interpreter state which can be loaded with custom handler scripts. To process incoming channel events, the MIDIMonster calls corresponding Lua functions (if they exist) -with the value (as a Lua `number` type) as parameter. +with the value (as a Lua `number` type) as parameter. Alternatively, a designated default channel handler +may be supplied in the configuration. The following functions are provided within the Lua interpreter for interaction with the MIDIMonster @@ -42,9 +43,10 @@ The `lua` backend does not take any global configuration. #### Instance configuration -| Option | Example value | Default value | Description | -|---------------|-----------------------|-----------------------|-----------------------| -| `script` | `script.lua` | none | Lua source file (relative to configuration file)| +| Option | Example value | Default value | Description | +|-----------------------|-----------------------|-----------------------|-----------------------| +| `script` | `script.lua` | none | Lua source file (relative to configuration file) | +| `default-handler` | `handler` | none | Name of a function to be called as handler for all incoming channels (instead of the per-channel handlers) | A single instance may have multiple `script` options specified, which will all be read cumulatively. -- cgit v1.2.3 From 2d66d5cee9bf3ed5779f65d8a99b40ee5181bf30 Mon Sep 17 00:00:00 2001 From: cbdev Date: Fri, 20 Mar 2020 21:50:33 +0100 Subject: Implement Lua threading --- backends/lua.md | 30 ++++++++++++++++++++++++------ 1 file changed, 24 insertions(+), 6 deletions(-) (limited to 'backends/lua.md') diff --git a/backends/lua.md b/backends/lua.md index 96e53c8..05509b6 100644 --- a/backends/lua.md +++ b/backends/lua.md @@ -19,24 +19,41 @@ The following functions are provided within the Lua interpreter for interaction | `output_value(string)` | `output_value("bar")` | Get the last output value on a channel | | `input_channel()` | `print(input_channel())` | Returns the name of the input channel whose handler function is currently running or `nil` if in an `interval`'ed function (or the initial parse step) | | `timestamp()` | `print(timestamp())` | Returns the core timestamp for this iteration with millisecond resolution. This is not a performance timer, but intended for timeouting, etc | +| `thread(function)` | `thread(run_show)` | Run a function as a Lua thread (see below) | +| `sleep(number)` | `sleep(100)` | Suspend current thread for time specified in milliseconds | Example script: -``` +```lua function bar(value) - output("foo", value / 2) + output("foo", value / 2); end step = 0 function toggle() - output("bar", step * 1.0) + output("bar", step * 1.0); step = (step + 1) % 2; end +function run_show() + while(true) do + sleep(1000); + output("narf", 0); + sleep(1000); + output("narf", 1.0); + end +end + interval(toggle, 1000) +thread(run_show) ``` Input values range between 0.0 and 1.0, output values are clamped to the same range. +Threads are implemented as Lua coroutines, not operating system threads. This means that +cooperative multithreading is required, which can be achieved by calling the `sleep(number)` +function from within a running thread. Calling that function from any other context is +not supported. + #### Global configuration The `lua` backend does not take any global configuration. @@ -61,9 +78,10 @@ lua1.foo > lua2.bar #### Known bugs / problems -Using any of the interface functions (`output`, `interval`, `input_value`, `output_value`, `input_channel`, -`timestamp`) as an input channel name to a Lua instance will not call any handler functions. -Using these names as arguments to the output and value interface functions works as intended. +Using any of the interface functions (`output`, `interval`, etc.) as an input channel name to a +Lua instance will not call any handler functions. Using these names as arguments to the output and +value interface functions works as intended. When using a default handler, the default handler will +be called. Output values will not trigger corresponding input event handlers unless the channel is mapped back in the MIDIMonster configuration. This is intentional. -- cgit v1.2.3 From 2a079f72483aa853d68430883b2281f436512c6b Mon Sep 17 00:00:00 2001 From: cbdev Date: Thu, 26 Mar 2020 22:42:38 +0100 Subject: Implement lua cleanup handlers --- backends/lua.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) (limited to 'backends/lua.md') diff --git a/backends/lua.md b/backends/lua.md index 05509b6..30d7580 100644 --- a/backends/lua.md +++ b/backends/lua.md @@ -13,14 +13,15 @@ The following functions are provided within the Lua interpreter for interaction | Function | Usage example | Description | |-------------------------------|-------------------------------|---------------------------------------| -| `output(string, number)` | `output("foo", 0.75)` | Output a value event to a channel | +| `output(string, number)` | `output("foo", 0.75)` | Output a value event to a channel on this instance | | `interval(function, number)` | `interval(update, 100)` | Register a function to be called periodically. Intervals are milliseconds (rounded to the nearest 10 ms). Calling `interval` on a Lua function multiple times updates the interval. Specifying `0` as interval stops periodic calls to the function | -| `input_value(string)` | `input_value("foo")` | Get the last input value on a channel | -| `output_value(string)` | `output_value("bar")` | Get the last output value on a channel | +| `input_value(string)` | `input_value("foo")` | Get the last input value on a channel on this instance | +| `output_value(string)` | `output_value("bar")` | Get the last output value on a channel on this instance | | `input_channel()` | `print(input_channel())` | Returns the name of the input channel whose handler function is currently running or `nil` if in an `interval`'ed function (or the initial parse step) | | `timestamp()` | `print(timestamp())` | Returns the core timestamp for this iteration with millisecond resolution. This is not a performance timer, but intended for timeouting, etc | | `thread(function)` | `thread(run_show)` | Run a function as a Lua thread (see below) | | `sleep(number)` | `sleep(100)` | Suspend current thread for time specified in milliseconds | +| `cleanup_handler(function)` | | Register a function to be called when the instance is destroyed (on MIDIMonster shutdown). One cleanup handler can be registered per instance. Calling this function when the instance already has a cleanup handler registered replaces the handler, returning the old one. | Example script: ```lua @@ -43,8 +44,12 @@ function run_show() end end +function save_values() +end + interval(toggle, 1000) thread(run_show) +cleanup_handler(save_values) ``` Input values range between 0.0 and 1.0, output values are clamped to the same range. @@ -86,6 +91,9 @@ be called. Output values will not trigger corresponding input event handlers unless the channel is mapped back in the MIDIMonster configuration. This is intentional. +Output events generated from cleanup handlers called during shutdown will not be routed, as the core +routing facility has already shut down at this point. There are no plans to change this behaviour. + To build (and run) the `lua` backend on Windows, a compiled version of the Lua 5.3 library is required. For various reasons (legal, separations of concern, not wanting to ship binary data in the repository), the MIDIMonster project can not provide this file within this repository. -- cgit v1.2.3 From 253125ea28925e5207c375987ac36468327bed66 Mon Sep 17 00:00:00 2001 From: cbdev Date: Fri, 27 Mar 2020 21:40:45 +0100 Subject: Implement python cleanup handlers --- backends/lua.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'backends/lua.md') diff --git a/backends/lua.md b/backends/lua.md index 30d7580..e59e513 100644 --- a/backends/lua.md +++ b/backends/lua.md @@ -15,13 +15,13 @@ The following functions are provided within the Lua interpreter for interaction |-------------------------------|-------------------------------|---------------------------------------| | `output(string, number)` | `output("foo", 0.75)` | Output a value event to a channel on this instance | | `interval(function, number)` | `interval(update, 100)` | Register a function to be called periodically. Intervals are milliseconds (rounded to the nearest 10 ms). Calling `interval` on a Lua function multiple times updates the interval. Specifying `0` as interval stops periodic calls to the function | +| `cleanup_handler(function)` | `cleanup_handler(shutdown)` | Register a function to be called when the instance is destroyed (on MIDIMonster shutdown). One cleanup handler can be registered per instance. Calling this function when the instance already has a cleanup handler registered replaces the handler, returning the old one. | | `input_value(string)` | `input_value("foo")` | Get the last input value on a channel on this instance | | `output_value(string)` | `output_value("bar")` | Get the last output value on a channel on this instance | | `input_channel()` | `print(input_channel())` | Returns the name of the input channel whose handler function is currently running or `nil` if in an `interval`'ed function (or the initial parse step) | | `timestamp()` | `print(timestamp())` | Returns the core timestamp for this iteration with millisecond resolution. This is not a performance timer, but intended for timeouting, etc | | `thread(function)` | `thread(run_show)` | Run a function as a Lua thread (see below) | | `sleep(number)` | `sleep(100)` | Suspend current thread for time specified in milliseconds | -| `cleanup_handler(function)` | | Register a function to be called when the instance is destroyed (on MIDIMonster shutdown). One cleanup handler can be registered per instance. Calling this function when the instance already has a cleanup handler registered replaces the handler, returning the old one. | Example script: ```lua @@ -45,6 +45,7 @@ function run_show() end function save_values() + -- Store state to a file, for example end interval(toggle, 1000) -- cgit v1.2.3 From bc275e10defe27e6d288ccf9125fe9b915168240 Mon Sep 17 00:00:00 2001 From: cbdev Date: Tue, 21 Apr 2020 00:20:23 +0200 Subject: Do not load lua backend automatically on Windows --- backends/lua.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'backends/lua.md') diff --git a/backends/lua.md b/backends/lua.md index e59e513..0a31dce 100644 --- a/backends/lua.md +++ b/backends/lua.md @@ -101,7 +101,6 @@ the MIDIMonster project can not provide this file within this repository. You will need to acquire a copy of `lua53.dll`, for example by downloading it from the [luabinaries project](http://luabinaries.sourceforge.net/download.html). -To build the `lua` backend for Windows, place `lua53.dll` in a subdirectory `libs/` in the project root -and run `make lua.dll` inside the `backends/` directory. - +Place this file in the project root directory and run `make lua.dll` inside the `backends/` directory +to build the backend. At runtime, Windows searches for the file in the same directory as `midimonster.exe`. -- cgit v1.2.3 From ff785c5c5a300d01b404c48335de7f68ad8711a9 Mon Sep 17 00:00:00 2001 From: cbdev Date: Fri, 24 Apr 2020 00:18:36 +0200 Subject: Update lua documentation, keep last value for handler --- backends/lua.md | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) (limited to 'backends/lua.md') diff --git a/backends/lua.md b/backends/lua.md index 0a31dce..4e58ded 100644 --- a/backends/lua.md +++ b/backends/lua.md @@ -3,18 +3,21 @@ The `lua` backend provides a flexible programming environment, allowing users to route, generate and manipulate events using the Lua scripting language. -Every instance has its own interpreter state which can be loaded with custom handler scripts. +Every instance has its own interpreter state which can be loaded with custom scripts. To process incoming channel events, the MIDIMonster calls corresponding Lua functions (if they exist) with the value (as a Lua `number` type) as parameter. Alternatively, a designated default channel handler -may be supplied in the configuration. +which will receive events for all incoming channels may be supplied in the configuration. + +The backend can also call Lua functions repeatedly using a timer, allowing users to implement time-based +functionality (such as evaluating a fixed mathematical function or outputting periodic updates). The following functions are provided within the Lua interpreter for interaction with the MIDIMonster | Function | Usage example | Description | |-------------------------------|-------------------------------|---------------------------------------| | `output(string, number)` | `output("foo", 0.75)` | Output a value event to a channel on this instance | -| `interval(function, number)` | `interval(update, 100)` | Register a function to be called periodically. Intervals are milliseconds (rounded to the nearest 10 ms). Calling `interval` on a Lua function multiple times updates the interval. Specifying `0` as interval stops periodic calls to the function | +| `interval(function, number)` | `interval(update, 100)` | Register a function to be called periodically. Intervals are milliseconds (rounded to the nearest 10 ms). Calling `interval` on a Lua function multiple times updates the interval. Specifying `0` as interval stops periodic calls to the function. Do not call this function from within a Lua thread. | | `cleanup_handler(function)` | `cleanup_handler(shutdown)` | Register a function to be called when the instance is destroyed (on MIDIMonster shutdown). One cleanup handler can be registered per instance. Calling this function when the instance already has a cleanup handler registered replaces the handler, returning the old one. | | `input_value(string)` | `input_value("foo")` | Get the last input value on a channel on this instance | | `output_value(string)` | `output_value("bar")` | Get the last output value on a channel on this instance | @@ -23,18 +26,27 @@ The following functions are provided within the Lua interpreter for interaction | `thread(function)` | `thread(run_show)` | Run a function as a Lua thread (see below) | | `sleep(number)` | `sleep(100)` | Suspend current thread for time specified in milliseconds | +While a channel handler executes, calling `input_value` for that channel returns the previous value. Once +the handler returns, the internal buffer is updated. + Example script: ```lua +-- This function is called when there are incoming events on input channel `bar` +-- It outputs half the input value on the channel `foo` function bar(value) output("foo", value / 2); end +-- This function is registered below to execute every second +-- It toggles output channel `bar` every time it is called by storing the next state in the variable `step` step = 0 function toggle() output("bar", step * 1.0); step = (step + 1) % 2; end +-- This function is registered below to run as a Lua thread +-- It loops infinitely and toggles the output channel `narf` every second function run_show() while(true) do sleep(1000); @@ -44,10 +56,12 @@ function run_show() end end +-- This function is registered below to be called when the MIDIMonster shuts down function save_values() -- Store state to a file, for example end +-- Register the functions interval(toggle, 1000) thread(run_show) cleanup_handler(save_values) -- cgit v1.2.3 From f692715444c6ddeb47bf87b53acf46798785290a Mon Sep 17 00:00:00 2001 From: cbdev Date: Mon, 27 Apr 2020 20:54:02 +0200 Subject: Allow access to previous value in python handlers --- backends/lua.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'backends/lua.md') diff --git a/backends/lua.md b/backends/lua.md index 4e58ded..b2f40e0 100644 --- a/backends/lua.md +++ b/backends/lua.md @@ -26,8 +26,8 @@ The following functions are provided within the Lua interpreter for interaction | `thread(function)` | `thread(run_show)` | Run a function as a Lua thread (see below) | | `sleep(number)` | `sleep(100)` | Suspend current thread for time specified in milliseconds | -While a channel handler executes, calling `input_value` for that channel returns the previous value. Once -the handler returns, the internal buffer is updated. +While a channel handler executes, calling `input_value` for that channel returns the previous value. +The stored value is updated once the handler returns. Example script: ```lua -- cgit v1.2.3