From 0bfaa3cfd32f06f1f14688ba5f4d4f15dc2e9633 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Sun, 31 Jul 2016 05:30:53 -0400 Subject: Clarify worker documentation --- lv2/lv2plug.in/ns/ext/worker/lv2-worker.doap.ttl | 9 ++++ lv2/lv2plug.in/ns/ext/worker/manifest.ttl | 2 +- lv2/lv2plug.in/ns/ext/worker/worker.ttl | 64 +++++++++--------------- 3 files changed, 34 insertions(+), 41 deletions(-) (limited to 'lv2/lv2plug.in/ns/ext/worker') 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 ; doap:release [ + doap:revision "1.1" ; + doap:created "2016-06-31" ; + dcs:blame ; + dcs:changeset [ + dcs:item [ + rdfs:label "Improve documentation." + ] + ] + ] , [ doap:revision "1.0" ; doap:created "2012-04-17" ; doap:file-release ; 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 @@ a lv2:Specification ; lv2:minorVersion 1 ; - lv2:microVersion 0 ; + lv2:microVersion 1 ; rdfs:seeAlso . 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 , ; lv2:documentation """ -

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.

- -

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.

- -

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.

+

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.

+ +

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 +scheduled 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.

""" . work:interface a lv2:ExtensionData ; lv2:documentation """ -

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.

- -

The plugin data file should describe this like so:

+

The work interface provided by a plugin, LV2_Worker_Interface.

 @prefix work: <http://lv2plug.in/ns/ext/worker#> .
 
@@ -50,20 +43,11 @@ LV2_WORKER__interface.

 work:schedule
 	a lv2:Feature ;
 	lv2:documentation """
-
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.

-
-
The plugin data file should describe this like so:

-
-@prefix work: <http://lv2plug.in/ns/ext/worker#> .
-
-<plugin>
-    a lv2:Plugin ;
-    lv2:requiredFeature work:schedule .
-

-
-
As usual, lv2:optionalFeature may be used instead, if the plugin is capable
-of running in a host that does not provide this feature.

-""" .
+
The work scheduling feature provided by a host, LV2_Worker_Schedule.

+
+
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.
 """ .
-- 
cgit v1.2.1