aboutsummaryrefslogtreecommitdiffstats
path: root/lv2/lv2plug.in/ns/ext/worker
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2012-03-23 01:26:47 +0000
committerDavid Robillard <d@drobilla.net>2012-03-23 01:26:47 +0000
commit5ef77d9bd9b102c76dbef24fbcd006c4534e9fc1 (patch)
tree37c43c211e7ba050535f2c6e4130685fdbff2bc2 /lv2/lv2plug.in/ns/ext/worker
parentf161f400ce62326142f7ea5f613032f230d0d795 (diff)
downloadlv2-5ef77d9bd9b102c76dbef24fbcd006c4534e9fc1.tar.xz
Add worker extension to remove thread stuff from plugins.
Diffstat (limited to 'lv2/lv2plug.in/ns/ext/worker')
l---------lv2/lv2plug.in/ns/ext/worker/ext.pc.in1
-rw-r--r--lv2/lv2plug.in/ns/ext/worker/manifest.ttl8
l---------lv2/lv2plug.in/ns/ext/worker/waf1
-rw-r--r--lv2/lv2plug.in/ns/ext/worker/worker.h138
-rw-r--r--lv2/lv2plug.in/ns/ext/worker/worker.ttl58
l---------lv2/lv2plug.in/ns/ext/worker/wscript1
6 files changed, 207 insertions, 0 deletions
diff --git a/lv2/lv2plug.in/ns/ext/worker/ext.pc.in b/lv2/lv2plug.in/ns/ext/worker/ext.pc.in
new file mode 120000
index 0000000..03dd044
--- /dev/null
+++ b/lv2/lv2plug.in/ns/ext/worker/ext.pc.in
@@ -0,0 +1 @@
+../../../../../ext.pc.in \ No newline at end of file
diff --git a/lv2/lv2plug.in/ns/ext/worker/manifest.ttl b/lv2/lv2plug.in/ns/ext/worker/manifest.ttl
new file mode 100644
index 0000000..af46f01
--- /dev/null
+++ b/lv2/lv2plug.in/ns/ext/worker/manifest.ttl
@@ -0,0 +1,8 @@
+@prefix lv2: <http://lv2plug.in/ns/lv2core#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+
+<http://lv2plug.in/ns/ext/worker>
+ a lv2:Specification ;
+ lv2:minorVersion 0 ;
+ lv2:microVersion 1 ;
+ rdfs:seeAlso <worker.ttl> .
diff --git a/lv2/lv2plug.in/ns/ext/worker/waf b/lv2/lv2plug.in/ns/ext/worker/waf
new file mode 120000
index 0000000..5235032
--- /dev/null
+++ b/lv2/lv2plug.in/ns/ext/worker/waf
@@ -0,0 +1 @@
+../../../../../waf \ No newline at end of file
diff --git a/lv2/lv2plug.in/ns/ext/worker/worker.h b/lv2/lv2plug.in/ns/ext/worker/worker.h
new file mode 100644
index 0000000..612a24c
--- /dev/null
+++ b/lv2/lv2plug.in/ns/ext/worker/worker.h
@@ -0,0 +1,138 @@
+/*
+ Copyright 2012 David Robillard <http://drobilla.net>
+
+ Permission to use, copy, modify, and/or distribute this software for any
+ purpose with or without fee is hereby granted, provided that the above
+ copyright notice and this permission notice appear in all copies.
+
+ THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+*/
+
+/**
+ @file worker.h C header for the LV2 Worker extension
+ <http://lv2plug.in/ns/ext/worker>.
+*/
+
+#ifndef LV2_WORKER_H
+#define LV2_WORKER_H
+
+#include <stdint.h>
+
+#include "lv2/lv2plug.in/ns/lv2core/lv2.h"
+
+#define LV2_WORKER_URI "http://lv2plug.in/ns/ext/worker"
+#define LV2_WORKER_PREFIX LV2_WORKER_URI "#"
+
+#define LV2_WORKER__Interface LV2_WORKER_PREFIX "Interface"
+#define LV2_WORKER__schedule LV2_WORKER_PREFIX "schedule"
+
+/**
+ A status code for worker functions.
+*/
+typedef enum {
+ LV2_WORKER_SUCCESS = 0, /**< Completed successfully. */
+ LV2_WORKER_ERR_UNKNOWN = 1, /**< Unknown error. */
+ LV2_WORKER_ERR_NO_SPACE = 2 /**< Failed due to lack of space. */
+} LV2_Worker_Status;
+
+typedef void* LV2_Worker_Respond_Handle;
+
+/**
+ A function to respond to run() from the worker method.
+
+ The @p data MUST be safe for the host to copy and later pass to
+ work_response(), and the host MUST guarantee that it will be eventually
+ passed to work_response() if this function returns LV2_WORKER_SUCCESS.
+*/
+typedef LV2_Worker_Status (*LV2_Worker_Respond_Function)(
+ LV2_Worker_Respond_Handle handle,
+ uint32_t size,
+ const void* data);
+
+/**
+ LV2 Plugin Worker Interface.
+
+ This is the interface provided by the plugin to implement a worker method.
+ The plugin's extension_data() method should return an LV2_Worker_Interface
+ when called with LV2_WORKER__Interface as its argument.
+*/
+typedef struct _LV2_Worker_Interface {
+ /**
+ The worker method. This is called by the host in a non-realtime context
+ as requested, possibly with an arbitrary message to handle.
+
+ A response can be sent to run() using @p respond. The plugin MUST NOT
+ make any assumptions about which thread calls this method, other than
+ the fact that there are no real-time requirements.
+
+ @param instance The LV2 instance this is a method on.
+ @param respond A function for sending a response to run().
+ @param handle Must be passed to @p respond if it is called.
+ @param size The size of @p data.
+ @param data Data from run(), or NULL.
+ */
+ LV2_Worker_Status (*work)(LV2_Handle instance,
+ LV2_Worker_Respond_Function respond,
+ LV2_Worker_Respond_Handle handle,
+ uint32_t size,
+ const void* data);
+
+ /**
+ Handle a response from the worker. This is called by the host in the
+ run() context when a response from the worker is ready.
+
+ @param instance The LV2 instance this is a method on.
+ @param size The size of @p body.
+ @param body Message body, or NULL.
+ */
+ LV2_Worker_Status (*work_response)(LV2_Handle instance,
+ uint32_t size,
+ const void* body);
+} LV2_Worker_Interface;
+
+typedef void* LV2_Worker_Schedule_Handle;
+
+typedef struct _LV2_Worker_Schedule {
+ /**
+ Opaque host data.
+ */
+ LV2_Worker_Schedule_Handle handle;
+
+ /**
+ Request from run() that the host call the worker.
+
+ This function is in the audio threading class. It should be called from
+ run() to request that the host call the work() method in a non-realtime
+ context with the given arguments.
+
+ This function is always safe to call from run(), but it is not
+ guaranteed that the worker is actually called from a different thread.
+ In particular, when free-wheeling (e.g. for offline rendering), the
+ worker may be executed immediately. This allows single-threaded
+ processing with sample accuracy and avoids timing problems when run() is
+ executing much faster or slower than real-time.
+
+ Plugins SHOULD be written in such a way that if the worker runs
+ immediately, and responses from the worker are delivered immediately,
+ the effect of the work takes place immediately with sample accuracy.
+
+ The @p data MUST be safe for the host to copy and later pass to work(),
+ and the host MUST guarantee that it will be eventually passed to work()
+ if this function returns LV2_WORKER_SUCCESS.
+
+ @param handle The handle field of this struct.
+ @param size The size of @p body.
+ @param data Message to pass to work(), or NULL.
+ */
+ LV2_Worker_Status (*schedule_work)(LV2_Worker_Schedule_Handle handle,
+ uint32_t size,
+ const void* data);
+} LV2_Worker_Schedule;
+
+#endif /* LV2_WORKER_H */
diff --git a/lv2/lv2plug.in/ns/ext/worker/worker.ttl b/lv2/lv2plug.in/ns/ext/worker/worker.ttl
new file mode 100644
index 0000000..ea49056
--- /dev/null
+++ b/lv2/lv2plug.in/ns/ext/worker/worker.ttl
@@ -0,0 +1,58 @@
+# LV2 Worker Extension
+# Copyright 2012 David Robillard <d@drobilla.net>
+#
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+@prefix work: <http://lv2plug.in/ns/ext/worker#> .
+@prefix lv2: <http://lv2plug.in/ns/lv2core#> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+@prefix doap: <http://usefulinc.com/ns/doap#> .
+@prefix foaf: <http://xmlns.com/foaf/0.1/> .
+
+<http://lv2plug.in/ns/ext/worker>
+ a lv2:Specification ,
+ lv2:Feature ;
+ doap:name "LV2 Worker" ;
+ doap:shortdesc "Support for a non-realtime plugin worker method." ;
+ lv2:documentation """
+""" .
+
+work:Interface
+ a rdfs:Class ;
+ rdfs:subClassOf lv2:ExtensionData ;
+ lv2:documentation """
+<p>A structure (LV2_Worker_Interface) which contains the worker method to be
+called by the host. In order to support this extension, the plugin must return
+a valid LV2_Worker_Interface from LV2_Descriptor::extension_data() when it is
+called with URI LV2_WORKER__Interface.</p>
+
+<p>The plugin data file should describe this like so:</p>
+<pre class="turtle-code">
+@prefix work: &lt;http://lv2plug.in/ns/ext/worker#&gt; .
+
+&lt;plugin&gt;
+ a lv2:Plugin ;
+ lv2:extensionData work:Interface .
+</pre>
+""" .
+
+work:schedule
+ a lv2:Feature ;
+ lv2:documentation """
+<p>A feature which provides functions for use by the plugin to implement a
+worker method. To support this feature, the host must pass an LV2_Feature to
+LV2_Descriptor::instantiate() with URI LV2_WORKER__schedule and data pointed to
+an instance of LV2_Worker_Schedule.</p>
+""" .
diff --git a/lv2/lv2plug.in/ns/ext/worker/wscript b/lv2/lv2plug.in/ns/ext/worker/wscript
new file mode 120000
index 0000000..7e2c01b
--- /dev/null
+++ b/lv2/lv2plug.in/ns/ext/worker/wscript
@@ -0,0 +1 @@
+../../../../../ext.wscript \ No newline at end of file