aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2016-07-31 05:30:53 -0400
committerDavid Robillard <d@drobilla.net>2016-07-31 15:19:35 -0400
commit0bfaa3cfd32f06f1f14688ba5f4d4f15dc2e9633 (patch)
treeda1265abe4ec1f4475ff157994ee19704297805f
parent22bf425ab9d3724e8eb6961b945169c3dabd5b04 (diff)
downloadlv2-0bfaa3cfd32f06f1f14688ba5f4d4f15dc2e9633.tar.xz
Clarify worker documentation
-rw-r--r--lv2/lv2plug.in/ns/ext/worker/lv2-worker.doap.ttl9
-rw-r--r--lv2/lv2plug.in/ns/ext/worker/manifest.ttl2
-rw-r--r--lv2/lv2plug.in/ns/ext/worker/worker.ttl64
3 files changed, 34 insertions, 41 deletions
diff --git a/lv2/lv2plug.in/ns/ext/worker/lv2-worker.doap.ttl b/lv2/lv2plug.in/ns/ext/worker/lv2-worker.doap.ttl
index 18acf5f..48a7a01 100644
--- a/lv2/lv2plug.in/ns/ext/worker/lv2-worker.doap.ttl
+++ b/lv2/lv2plug.in/ns/ext/worker/lv2-worker.doap.ttl
@@ -11,6 +11,15 @@
doap:created "2012-03-22" ;
doap:developer <http://drobilla.net/drobilla#me> ;
doap:release [
+ doap:revision "1.1" ;
+ doap:created "2016-06-31" ;
+ dcs:blame <http://drobilla.net/drobilla#me> ;
+ dcs:changeset [
+ dcs:item [
+ rdfs:label "Improve documentation."
+ ]
+ ]
+ ] , [
doap:revision "1.0" ;
doap:created "2012-04-17" ;
doap:file-release <http://lv2plug.in/spec/lv2-1.0.0.tar.bz2> ;
diff --git a/lv2/lv2plug.in/ns/ext/worker/manifest.ttl b/lv2/lv2plug.in/ns/ext/worker/manifest.ttl
index 02cf27f..6e8680c 100644
--- a/lv2/lv2plug.in/ns/ext/worker/manifest.ttl
+++ b/lv2/lv2plug.in/ns/ext/worker/manifest.ttl
@@ -4,5 +4,5 @@
<http://lv2plug.in/ns/ext/worker>
a lv2:Specification ;
lv2:minorVersion 1 ;
- lv2:microVersion 0 ;
+ lv2:microVersion 1 ;
rdfs:seeAlso <worker.ttl> .
diff --git a/lv2/lv2plug.in/ns/ext/worker/worker.ttl b/lv2/lv2plug.in/ns/ext/worker/worker.ttl
index fb182a7..6b32742 100644
--- a/lv2/lv2plug.in/ns/ext/worker/worker.ttl
+++ b/lv2/lv2plug.in/ns/ext/worker/worker.ttl
@@ -10,34 +10,27 @@
rdfs:seeAlso <worker.h> ,
<lv2-worker.doap.ttl> ;
lv2:documentation """
-<p>This extension allows plugins to have a non-realtime worker method, with
-thread sychronisation and communication issues handled by the host. This
-allows plugins to perform non-realtime actions (such as loading files) using a
-simple and portable API without having to worry about the complexities of
-multi-threading.</p>
-
-<p>Because the worker thread is implemented by the host, many plugins can share
-the same thread and communication buffers, which reduces bloat and fixed
-per-plugin buffer size limitations. The host has the power to implement
-threads in a suitable way, while plugins are simpler and thus less
-error-prone.</p>
-
-<p>This interface is designed to gracefully handle single-threaded synchronous
-execution, in which case the host may simply run all work immediately. This
-makes it possible for the same plugin code to work with sample accuracy for
-offline rendering, or in real-time with non-real-time work taking place in a
-separate thread.</p>
+<p>This extension allows plugins to schedule work that must be performed in
+another thread. Plugins can use this interface to safely perform work that is
+not real-time safe, and receive the result in the run context. The details of
+threading are managed by the host, allowing plugins to be simple and portable
+while using resources more efficiently.</p>
+
+<p>This interface is designed to gracefully support single-threaded synchronous
+execution, which allows the same code to work with sample accuracy for offline
+rendering. For example, a sampler plugin may schedule a sample to be loaded
+from disk in another thread. During live execution, the host will call the
+plugin's work method from another thread, and deliver the result to the audio
+thread when it is finished. However, during offline export, the
+<q>scheduled</q> load would be executed immediately in the same thread. This
+enables reproducible offline rendering, where any changes affect the output
+immediately regardless of how long the work takes to execute.</p>
""" .
work:interface
a lv2:ExtensionData ;
lv2:documentation """
-<p>The interface provided by the plugin to implement a worker. To implement
-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>
+<p>The work interface provided by a plugin, LV2_Worker_Interface.</p>
<pre class="turtle-code">
@prefix work: &lt;http://lv2plug.in/ns/ext/worker#&gt; .
@@ -50,20 +43,11 @@ LV2_WORKER__interface.</p>
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>
-
-<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:requiredFeature work:schedule .
-</pre>
-
-<p>As usual, lv2:optionalFeature may be used instead, if the plugin is capable
-of running in a host that does not provide this feature.</p>
-""" .
+<p>The work scheduling feature provided by a host, LV2_Worker_Schedule.</p>
+
+<p>If the host passes this feature to LV2_Descriptor::instantiate, the plugin
+MAY use it to schedule work in the audio thread, and MUST NOT call it in any
+other context. Hosts MAY pass this feature to other functions as well, in
+which case the plugin MAY use it to schedule work in the calling context. The
+plugin MUST NOT assume any relationship between different schedule
+features.</p> """ .