source/includes/lv2/worker.h

   1 /*
   2   Copyright 2012-2016 David Robillard <http://drobilla.net>
   3
   4   Permission to use, copy, modify, and/or distribute this software for any
   5   purpose with or without fee is hereby granted, provided that the above
   6   copyright notice and this permission notice appear in all copies.
   7
   8   THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
   9   WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  10   MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  11   ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  12   WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  13   ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  14   OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  15 */
  16
  17 /**
  18    @defgroup worker Worker
  19
  20    Support for non-realtime plugin operations, see
  21    <http://lv2plug.in/ns/ext/worker> for details.
  22
  23    @{
  24 */
  25
  26 #ifndef LV2_WORKER_H
  27 #define LV2_WORKER_H
  28
  29 #include <stdint.h>
  30
  31 #include "lv2.h"
  32
  33 #define LV2_WORKER_URI    "http://lv2plug.in/ns/ext/worker"  ///< http://lv2plug.in/ns/ext/worker
  34 #define LV2_WORKER_PREFIX LV2_WORKER_URI "#"                 ///< http://lv2plug.in/ns/ext/worker#
  35
  36 #define LV2_WORKER__interface LV2_WORKER_PREFIX "interface"  ///< http://lv2plug.in/ns/ext/worker#interface
  37 #define LV2_WORKER__schedule  LV2_WORKER_PREFIX "schedule"   ///< http://lv2plug.in/ns/ext/worker#schedule
  38
  39 #ifdef __cplusplus
  40 extern "C" {
  41 #endif
  42
  43 /**
  44    Status code for worker functions.
  45 */
  46 typedef enum {
  47         LV2_WORKER_SUCCESS       = 0,  /**< Completed successfully. */
  48         LV2_WORKER_ERR_UNKNOWN   = 1,  /**< Unknown error. */
  49         LV2_WORKER_ERR_NO_SPACE  = 2   /**< Failed due to lack of space. */
  50 } LV2_Worker_Status;
  51
  52 /** Opaque handle for LV2_Worker_Interface::work(). */
  53 typedef void* LV2_Worker_Respond_Handle;
  54
  55 /**
  56    A function to respond to run() from the worker method.
  57
  58    The `data` MUST be safe for the host to copy and later pass to
  59    work_response(), and the host MUST guarantee that it will be eventually
  60    passed to work_response() if this function returns LV2_WORKER_SUCCESS.
  61 */
  62 typedef LV2_Worker_Status (*LV2_Worker_Respond_Function)(
  63         LV2_Worker_Respond_Handle handle,
  64         uint32_t                  size,
  65         const void*               data);
  66
  67 /**
  68    Plugin Worker Interface.
  69
  70    This is the interface provided by the plugin to implement a worker method.
  71    The plugin's extension_data() method should return an LV2_Worker_Interface
  72    when called with LV2_WORKER__interface as its argument.
  73 */
  74 typedef struct _LV2_Worker_Interface {
  75         /**
  76            The worker method.  This is called by the host in a non-realtime context
  77            as requested, possibly with an arbitrary message to handle.
  78
  79            A response can be sent to run() using `respond`.  The plugin MUST NOT
  80            make any assumptions about which thread calls this method, except that
  81            there are no real-time requirements and only one call may be executed at
  82            a time.  That is, the host MAY call this method from any non-real-time
  83            thread, but MUST NOT make concurrent calls to this method from several
  84            threads.
  85
  86            @param instance The LV2 instance this is a method on.
  87            @param respond  A function for sending a response to run().
  88            @param handle   Must be passed to `respond` if it is called.
  89            @param size     The size of `data`.
  90            @param data     Data from run(), or NULL.
  91         */
  92         LV2_Worker_Status (*work)(LV2_Handle                  instance,
  93                                   LV2_Worker_Respond_Function respond,
  94                                   LV2_Worker_Respond_Handle   handle,
  95                                   uint32_t                    size,
  96                                   const void*                 data);
  97
  98         /**
  99            Handle a response from the worker.  This is called by the host in the
 100            run() context when a response from the worker is ready.
 101
 102            @param instance The LV2 instance this is a method on.
 103            @param size     The size of `body`.
 104            @param body     Message body, or NULL.
 105         */
 106         LV2_Worker_Status (*work_response)(LV2_Handle  instance,
 107                                            uint32_t    size,
 108                                            const void* body);
 109
 110         /**
 111            Called when all responses for this cycle have been delivered.
 112
 113            Since work_response() may be called after run() finished, this provides
 114            a hook for code that must run after the cycle is completed.
 115
 116            This field may be NULL if the plugin has no use for it.  Otherwise, the
 117            host MUST call it after every run(), regardless of whether or not any
 118            responses were sent that cycle.
 119         */
 120         LV2_Worker_Status (*end_run)(LV2_Handle instance);
 121 } LV2_Worker_Interface;
 122
 123 /** Opaque handle for LV2_Worker_Schedule. */
 124 typedef void* LV2_Worker_Schedule_Handle;
 125
 126 /**
 127    Schedule Worker Host Feature.
 128
 129    The host passes this feature to provide a schedule_work() function, which
 130    the plugin can use to schedule a worker call from run().
 131 */
 132 typedef struct _LV2_Worker_Schedule {
 133         /**
 134            Opaque host data.
 135         */
 136         LV2_Worker_Schedule_Handle handle;
 137
 138         /**
 139            Request from run() that the host call the worker.
 140
 141            This function is in the audio threading class.  It should be called from
 142            run() to request that the host call the work() method in a non-realtime
 143            context with the given arguments.
 144
 145            This function is always safe to call from run(), but it is not
 146            guaranteed that the worker is actually called from a different thread.
 147            In particular, when free-wheeling (e.g. for offline rendering), the
 148            worker may be executed immediately.  This allows single-threaded
 149            processing with sample accuracy and avoids timing problems when run() is
 150            executing much faster or slower than real-time.
 151
 152            Plugins SHOULD be written in such a way that if the worker runs
 153            immediately, and responses from the worker are delivered immediately,
 154            the effect of the work takes place immediately with sample accuracy.
 155
 156            The `data` MUST be safe for the host to copy and later pass to work(),
 157            and the host MUST guarantee that it will be eventually passed to work()
 158            if this function returns LV2_WORKER_SUCCESS.
 159
 160            @param handle The handle field of this struct.
 161            @param size   The size of `data`.
 162            @param data   Message to pass to work(), or NULL.
 163         */
 164         LV2_Worker_Status (*schedule_work)(LV2_Worker_Schedule_Handle handle,
 165                                            uint32_t                   size,
 166                                            const void*                data);
 167 } LV2_Worker_Schedule;
 168
 169 #ifdef __cplusplus
 170 }  /* extern "C" */
 171 #endif
 172
 173 #endif  /* LV2_WORKER_H */
 174
 175 /**
 176    @}
 177 */