libs/ardour/ardour/worker.h

   1 /*
   2   Copyright (C) 2012-2016 Paul Davis
   3   Author: David Robillard
   4
   5   This program is free software; you can redistribute it and/or modify
   6   it under the terms of the GNU General Public License as published by
   7   the Free Software Foundation; either version 2 of the License, or
   8   (at your option) any later version.
   9
  10   This program is distributed in the hope that it will be useful,
  11   but WITHOUT ANY WARRANTY; without even the implied warranty of
  12   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13   GNU General Public License for more details.
  14
  15   You should have received a copy of the GNU General Public License
  16   along with this program; if not, write to the Free Software
  17   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  18 */
  19
  20 #ifndef __ardour_worker_h__
  21 #define __ardour_worker_h__
  22
  23 #include <stdint.h>
  24
  25 #include <glibmm/threads.h>
  26
  27 #include "pbd/ringbuffer.h"
  28 #include "pbd/semutils.h"
  29
  30 #include "ardour/libardour_visibility.h"
  31
  32 namespace ARDOUR {
  33
  34 class Worker;
  35
  36 /**
  37    An object that needs to schedule non-RT work in the audio thread.
  38 */
  39 class LIBARDOUR_API Workee {
  40 public:
  41         virtual ~Workee() {}
  42
  43         /**
  44            Do some work in the worker thread.
  45         */
  46         virtual int work(Worker& worker, uint32_t size, const void* data) = 0;
  47
  48         /**
  49            Handle a response from the worker thread in the audio thread.
  50         */
  51         virtual int work_response(uint32_t size, const void* data) = 0;
  52 };
  53
  54 /**
  55    A worker for non-realtime tasks scheduled from another thread.
  56
  57    A worker may be a separate thread that runs to execute scheduled work
  58    asynchronously, or unthreaded, in which case work is executed immediately
  59    upon scheduling by the calling thread.
  60 */
  61 class LIBARDOUR_API Worker
  62 {
  63 public:
  64         Worker(Workee* workee, uint32_t ring_size, bool threaded=true);
  65         ~Worker();
  66
  67         /**
  68            Schedule work (audio thread).
  69            @return false on error.
  70         */
  71         bool schedule(uint32_t size, const void* data);
  72
  73         /**
  74            Respond from work (worker thread).
  75            @return false on error.
  76         */
  77         bool respond(uint32_t size, const void* data);
  78
  79         /**
  80            Emit any pending responses (audio thread).
  81         */
  82         void emit_responses();
  83
  84         /**
  85            Enable or disable synchronous execution.
  86
  87            If enabled, all work is performed immediately in schedule() regardless
  88            of whether or not the worker is threaded.  This is used for exporting,
  89            where we want to temporarily execute all work synchronously but the
  90            worker is typically used threaded for live rolling.
  91         */
  92         void set_synchronous(bool synchronous) { _synchronous = synchronous; }
  93
  94 private:
  95         void run();
  96         /**
  97            Peek in RB, get size and check if a block of 'size' is available.
  98
  99            Handle the unlikley edge-case, if we're called in between the
 100            responder writing 'size' and 'data'.
 101
 102            @param rb the ringbuffer to check
 103            @return true if the message is complete, false otherwise
 104         */
 105         bool verify_message_completeness(RingBuffer<uint8_t>* rb);
 106
 107         Workee*                _workee;
 108         RingBuffer<uint8_t>*   _requests;
 109         RingBuffer<uint8_t>*   _responses;
 110         uint8_t*               _response;
 111         PBD::Semaphore         _sem;
 112         Glib::Threads::Thread* _thread;
 113         bool                   _exit;
 114         bool                   _synchronous;
 115 };
 116
 117 } // namespace ARDOUR
 118
 119 #endif  /* __ardour_worker_h__ */