source/utils/CarlaRunner.hpp

   1 /*
   2  * Carla Runner
   3  * Copyright (C) 2022-2023 Filipe Coelho <falktx@falktx.com>
   4  *
   5  * Permission to use, copy, modify, and/or distribute this software for any purpose with
   6  * or without fee is hereby granted, provided that the above copyright notice and this
   7  * permission notice appear in all copies.
   8  *
   9  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD
  10  * TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN
  11  * NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
  12  * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER
  13  * IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
  14  * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  15  */
  16
  17 #ifndef CARLA_RUNNER_HPP_INCLUDED
  18 #define CARLA_RUNNER_HPP_INCLUDED
  19
  20 #include "CarlaUtils.hpp"
  21
  22 #ifndef CARLA_OS_WASM
  23 # include "CarlaThread.hpp"
  24 #else
  25 # include "CarlaString.hpp"
  26 # include <emscripten/html5.h>
  27 #endif
  28
  29 // -------------------------------------------------------------------------------------------------------------------
  30 // CarlaRunner class
  31
  32 /**
  33    This is a handy class that handles "idle" time in either background or main thread,
  34    whichever is more suitable to the target platform.
  35    Typically background threads on desktop platforms, main thread on web.
  36
  37    A single function is expected to be implemented by subclasses,
  38    which directly allows it to stop the runner by returning false.
  39
  40    You can use it for quick operations that do not need to be handled in the main thread if possible.
  41    The target is to spread out execution over many runs, instead of spending a lot of time on a single task.
  42  */
  43 class CarlaRunner
  44 {
  45 protected:
  46     /*
  47      * Constructor.
  48      */
  49     CarlaRunner(const char* const runnerName = nullptr) noexcept
  50        #ifndef CARLA_OS_WASM
  51         : fRunnerThread(this, runnerName),
  52           fTimeInterval(0)
  53        #else
  54         : fRunnerName(runnerName),
  55           fIntervalId(0)
  56        #endif
  57     {
  58     }
  59
  60     /*
  61      * Destructor.
  62      */
  63     virtual ~CarlaRunner() /*noexcept*/
  64     {
  65         CARLA_SAFE_ASSERT(! isRunnerActive());
  66
  67         stopRunner();
  68     }
  69
  70     /*
  71      * Virtual function to be implemented by the subclass.
  72      * Return true to keep running, false to stop execution.
  73      */
  74     virtual bool run() = 0;
  75
  76     /*
  77      * Check if the runner should stop.
  78      * To be called from inside the runner to know if a stop request has been made.
  79      */
  80     bool shouldRunnerStop() const noexcept
  81     {
  82        #ifndef CARLA_OS_WASM
  83         return fRunnerThread.shouldThreadExit();
  84        #else
  85         return fIntervalId == 0;
  86        #endif
  87     }
  88
  89     // ---------------------------------------------------------------------------------------------------------------
  90
  91 public:
  92     /*
  93      * Check if the runner is active.
  94      */
  95     bool isRunnerActive() noexcept
  96     {
  97        #ifndef CARLA_OS_WASM
  98         return fRunnerThread.isThreadRunning();
  99        #else
 100         return fIntervalId != 0;
 101        #endif
 102     }
 103
 104     /*
 105      * Start the thread.
 106      */
 107     bool startRunner(const uint timeIntervalMilliseconds = 0) noexcept
 108     {
 109        #ifndef CARLA_OS_WASM
 110         CARLA_SAFE_ASSERT_RETURN(!fRunnerThread.isThreadRunning(), false);
 111         fTimeInterval = timeIntervalMilliseconds;
 112         return fRunnerThread.startThread();
 113        #else
 114         CARLA_SAFE_ASSERT_RETURN(fIntervalId == 0, false);
 115         fIntervalId = emscripten_set_interval(_entryPoint, timeIntervalMilliseconds, this);
 116         return true;
 117        #endif
 118     }
 119
 120     /*
 121      * Stop the runner.
 122      * This will signal the runner to stop if active, and wait until it finishes.
 123      */
 124     bool stopRunner() noexcept
 125     {
 126        #ifndef CARLA_OS_WASM
 127         return fRunnerThread.stopThread(-1);
 128        #else
 129         signalRunnerShouldStop();
 130         return true;
 131        #endif
 132     }
 133
 134     /*
 135      * Tell the runner to stop as soon as possible.
 136      */
 137     void signalRunnerShouldStop() noexcept
 138     {
 139        #ifndef CARLA_OS_WASM
 140         fRunnerThread.signalThreadShouldExit();
 141        #else
 142         if (fIntervalId != 0)
 143         {
 144             emscripten_clear_interval(fIntervalId);
 145             fIntervalId = 0;
 146         }
 147        #endif
 148     }
 149
 150     // ---------------------------------------------------------------------------------------------------------------
 151
 152     /*
 153      * Returns the name of the runner.
 154      * This is the name that gets set in the constructor.
 155      */
 156     const CarlaString& getRunnerName() const noexcept
 157     {
 158        #ifndef CARLA_OS_WASM
 159         return fRunnerThread.getThreadName();
 160        #else
 161         return fRunnerName;
 162        #endif
 163     }
 164
 165     // ---------------------------------------------------------------------------------------------------------------
 166
 167 private:
 168 #ifndef CARLA_OS_WASM
 169     class RunnerThread : public CarlaThread
 170     {
 171         CarlaRunner* const runner;
 172
 173     public:
 174         RunnerThread(CarlaRunner* const r, const char* const rn)
 175             : CarlaThread(rn),
 176               runner(r) {}
 177
 178     protected:
 179         void run() override
 180         {
 181             const uint timeInterval = runner->fTimeInterval;
 182
 183             while (!shouldThreadExit())
 184             {
 185                 bool stillRunning = false;
 186
 187                 try {
 188                     stillRunning = runner->run();
 189                 } catch(...) {}
 190
 191                 if (stillRunning && !shouldThreadExit())
 192                 {
 193                     if (timeInterval != 0)
 194                         carla_msleep(timeInterval);
 195
 196                     // FIXME
 197                     // pthread_yield();
 198                     continue;
 199                 }
 200
 201                 break;
 202             }
 203         }
 204
 205         CARLA_DECLARE_NON_COPYABLE(RunnerThread)
 206     } fRunnerThread;
 207
 208     uint fTimeInterval;
 209 #else
 210     const CarlaString fRunnerName;
 211     long fIntervalId;
 212
 213     void _runEntryPoint() noexcept
 214     {
 215         bool stillRunning = false;
 216
 217         try {
 218             stillRunning = run();
 219         } catch(...) {}
 220
 221         if (fIntervalId != 0 && !stillRunning)
 222         {
 223             emscripten_clear_interval(fIntervalId);
 224             fIntervalId = 0;
 225         }
 226     }
 227
 228     static void _entryPoint(void* const userData) noexcept
 229     {
 230         static_cast<CarlaRunner*>(userData)->_runEntryPoint();
 231     }
 232 #endif
 233
 234     CARLA_DECLARE_NON_COPYABLE(CarlaRunner)
 235 };
 236
 237 // -------------------------------------------------------------------------------------------------------------------
 238
 239 #endif // CARLA_RUNNER_HPP_INCLUDED