README.md 2.36 KB
Newer Older
jhammen's avatar
jhammen committed
1
2
# bipscript

jhammen's avatar
jhammen committed
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
## User Docs

Examples, Demos and API docs at http://bipscript.org

## Developer Docs

### Threads

There are two main threads, the usual audio process thread and a separate script interpreter thread, in which you can safely do things like memory allocation and file I/O.

Much of the API involves scheduling events on different nodes (plugins, outputs), when you do this an event object is created in the script thread and sent via lockfree queues
to the process thread. Events that arrive in time are dropped into audio or MIDI buffers with frame accuracy. OSC events similar but an OSC output has it's own process thread
that receives scheduled events from the script thread and sends them at the "right" time (timing here less precise than audio, and maybe should use some compensation)

Many LV2 plugins also request worker threads that handle things like loading large sample sets in the background. Also squirrel has its own threads for users, they should work
in theory.

Because API schedule methods do not block the main script should complete quickly. At that point any defined event handlers will run in that same script thread, triggered by
events created in process threads.

### Script Object Lifecycles

Script objects are controlled by the squirrel VM, it gives a callback "release hook" for what happens when an object goes out of scope in the script and is no longer needed.

If a script is reloaded in-process (via IDE, signal etc) all script objects will go out of scope and factories will be notified.

Each script object in the API just wraps a pointer to an underlying C++ object. There are a few different strategies for the C++ objects:

 * Cached - created via factory and cached, the same C++ pointer is given each time the script is reloaded. Release hook does nothing. This is for "heavy" objects that take time
    to instantiate like plugins. Also useful for e.g. system ports so they do not flicker in and out of existence between script runs.

 * Refcounted - created via ctor and given a reference count, the count is incremented for each C++ usage (e.g. adding to a container). Release hook deletes the object if the refcount
    drops to zero. Refcounted objects are mostly (all?) immutable.

 * Transient - created via ctor and returned directly to the script with no other C++ usage. Release hook deletes the underlying object when its script wrapper is deleted.