source/utils/CarlaPipeUtils.hpp

   1 /*
   2  * Carla Pipe utils
   3  * Copyright (C) 2013-2024 Filipe Coelho <falktx@falktx.com>
   4  *
   5  * This program is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU General Public License as
   7  * published by the Free Software Foundation; either version 2 of
   8  * the License, or 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  * For a full copy of the GNU General Public License see the doc/GPL.txt file.
  16  */
  17
  18 #ifndef CARLA_PIPE_UTILS_HPP_INCLUDED
  19 #define CARLA_PIPE_UTILS_HPP_INCLUDED
  20
  21 #include "CarlaJuceUtils.hpp"
  22 #include "CarlaMutex.hpp"
  23
  24 #ifdef BUILDING_CARLA
  25 # include "lv2/atom.h"
  26 #else
  27 # include "lv2/atom/atom.h"
  28 #endif
  29
  30 // -----------------------------------------------------------------------
  31 // CarlaPipeCommon class
  32
  33 class CarlaPipeCommon
  34 {
  35 protected:
  36     /*!
  37      * Constructor.
  38      */
  39     CarlaPipeCommon() noexcept;
  40
  41     /*!
  42      * Destructor.
  43      */
  44     virtual ~CarlaPipeCommon() /*noexcept*/;
  45
  46     /*!
  47      * A message has been received (in the context of idlePipe()).
  48      * If extra data is required, use any of the readNextLineAs* functions.
  49      * Returning true means the message has been handled and should not propagate to subclasses.
  50      */
  51     virtual bool msgReceived(const char* msg) noexcept = 0;
  52
  53     /*!
  54      * An error has occurred during the current requested operation.
  55      * Reimplementing this method allows to catch these errors as strings.
  56      * By default the error is simply printed to stderr.
  57      */
  58     virtual void fail(const char* error) noexcept
  59     {
  60         carla_stderr2(error);
  61     }
  62
  63 public:
  64     /*!
  65      * Check if the pipe is running.
  66      */
  67     bool isPipeRunning() const noexcept;
  68
  69     /*!
  70      * Check the pipe for new messages and send them to msgReceived().
  71      */
  72     void idlePipe(bool onlyOnce = false) noexcept;
  73
  74     // -------------------------------------------------------------------
  75     // write lock
  76
  77     /*!
  78      * Lock the pipe write mutex.
  79      */
  80     void lockPipe() const noexcept;
  81
  82     /*!
  83      * Try locking the pipe write mutex.
  84      * Returns true if successful.
  85      */
  86     bool tryLockPipe() const noexcept;
  87
  88     /*!
  89      * Unlock the pipe write mutex.
  90      */
  91     void unlockPipe() const noexcept;
  92
  93     /*!
  94      * Get the pipe write lock.
  95      */
  96     CarlaMutex& getPipeLock() const noexcept;
  97
  98     // -------------------------------------------------------------------
  99     // read lines, must only be called in the context of msgReceived()
 100
 101     /*!
 102      * Read the next line as a boolean.
 103      */
 104     bool readNextLineAsBool(bool& value) const noexcept;
 105
 106     /*!
 107      * Read the next line as a byte.
 108      */
 109     bool readNextLineAsByte(uint8_t& value) const noexcept;
 110
 111     /*!
 112      * Read the next line as an integer.
 113      */
 114     bool readNextLineAsInt(int32_t& value) const noexcept;
 115
 116     /*!
 117      * Read the next line as an unsigned integer.
 118      */
 119     bool readNextLineAsUInt(uint32_t& value) const noexcept;
 120
 121     /*!
 122      * Read the next line as a long integer.
 123      */
 124     bool readNextLineAsLong(int64_t& value) const noexcept;
 125
 126     /*!
 127      * Read the next line as a long unsigned integer.
 128      */
 129     bool readNextLineAsULong(uint64_t& value) const noexcept;
 130
 131     /*!
 132      * Read the next line as a floating point number (single precision).
 133      */
 134     bool readNextLineAsFloat(float& value) const noexcept;
 135
 136     /*!
 137      * Read the next line as a floating point number (double precision).
 138      */
 139     bool readNextLineAsDouble(double& value) const noexcept;
 140
 141     /*!
 142      * Read the next line as a string.
 143      * @note: @a value must be freed if valid and allocateString is true.
 144      */
 145     bool readNextLineAsString(const char*& value, bool allocateString, uint32_t size = 0) const noexcept;
 146
 147     /*!
 148      * Read the next line as a string, returning an allocated copy that needs to be freed.
 149      */
 150     char* readNextLineAsString() const noexcept;
 151
 152     // -------------------------------------------------------------------
 153     // write messages, must be locked before calling
 154
 155     /*!
 156      * Write a valid message with unknown size.
 157      * A valid message has only one '\n' character and it's at the end.
 158      */
 159     bool writeMessage(const char* msg) const noexcept;
 160
 161     /*!
 162      * Write a valid message with known size.
 163      * A valid message has only one '\n' character and it's at the end.
 164      */
 165     bool writeMessage(const char* msg, std::size_t size) const noexcept;
 166
 167     /*!
 168      * Write and fix a message.
 169      */
 170     bool writeAndFixMessage(const char* msg) const noexcept;
 171
 172     /*!
 173      * Write an empty message, which means a single '\n'.
 174      */
 175     bool writeEmptyMessage() const noexcept;
 176
 177     /*!
 178      * Sync all messages currently in cache.
 179      * This call will forcely write any messages in cache to any relevant IO.
 180      */
 181     bool syncMessages() const noexcept;
 182
 183     // -------------------------------------------------------------------
 184     // write prepared messages, no lock or flush needed (done internally)
 185
 186     /*!
 187      * Write an "error" message.
 188      */
 189     bool writeErrorMessage(const char* error) const noexcept;
 190
 191     /*!
 192      * Write a "control" message used for parameter/control changes.
 193      */
 194     bool writeControlMessage(uint32_t index, float value, bool withWriteLock = true) const noexcept;
 195
 196     /*!
 197      * Write a "configure" message used for state changes.
 198      */
 199     bool writeConfigureMessage(const char* key, const char* value) const noexcept;
 200
 201     /*!
 202      * Write a "program" message (using index).
 203      */
 204     bool writeProgramMessage(uint32_t index) const noexcept;
 205
 206     /*!
 207      * Write a "program" message (using channel, bank and program).
 208      */
 209     bool writeProgramMessage(uint8_t channel, uint32_t bank, uint32_t program) const noexcept;
 210
 211     /*!
 212      * Write a "midiprogram" message (using bank and program).
 213      */
 214     bool writeMidiProgramMessage(uint32_t bank, uint32_t program) const noexcept;
 215
 216     /*!
 217      * Write a "reloadprograms" message.
 218      */
 219     bool writeReloadProgramsMessage(int32_t index) const noexcept;
 220
 221     /*!
 222      * Write a MIDI "note" message.
 223      */
 224     bool writeMidiNoteMessage(bool onOff, uint8_t channel, uint8_t note, uint8_t velocity) const noexcept;
 225
 226     /*!
 227      * Write an lv2 "atom" message.
 228      */
 229     bool writeLv2AtomMessage(uint32_t index, const LV2_Atom* atom) const noexcept;
 230
 231     /*!
 232      * Write an lv2 "parameter" message.
 233      */
 234     bool writeLv2ParameterMessage(const char* uri, float value, bool withWriteLock = true) const noexcept;
 235
 236     /*!
 237      * Write an lv2 "urid" message.
 238      */
 239     bool writeLv2UridMessage(uint32_t urid, const char* uri) const noexcept;
 240
 241     // -------------------------------------------------------------------
 242
 243 protected:
 244     struct PrivateData;
 245     PrivateData* const pData;
 246
 247     // -------------------------------------------------------------------
 248
 249     /*! @internal */
 250     const char* _readline(bool allocReturn, uint16_t size, bool& readSucess) const noexcept;
 251
 252     /*! @internal */
 253     const char* _readlineblock(bool allocReturn, uint16_t size = 0, uint32_t timeOutMilliseconds = 50) const noexcept;
 254
 255     /*! @internal */
 256     bool _writeMsgBuffer(const char* msg, std::size_t size) const noexcept;
 257
 258     CARLA_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR(CarlaPipeCommon)
 259 };
 260
 261 // -----------------------------------------------------------------------
 262 // CarlaPipeServer class
 263
 264 class CarlaPipeServer : public CarlaPipeCommon
 265 {
 266 public:
 267     /*!
 268      * Constructor.
 269      */
 270     CarlaPipeServer() noexcept;
 271
 272     /*!
 273      * Destructor.
 274      */
 275     ~CarlaPipeServer() /*noexcept*/ override;
 276
 277     /*!
 278      * Get the process ID of this pipe's matching client.
 279      * Will return 0 if client is not running.
 280      * @note: Unsupported on Windows
 281      */
 282     uintptr_t getPID() const noexcept;
 283
 284     /*!
 285      * Start the pipe server using @a filename with 2 arguments.
 286      * @see fail()
 287      */
 288     bool startPipeServer(const char* helperTool, const char* filename, const char* arg1, const char* arg2,
 289                          int size = -1, int timeOutMilliseconds = -1) noexcept;
 290
 291     /*!
 292      * Start the pipe server using @a filename with 2 arguments.
 293      * @see fail()
 294      */
 295     bool startPipeServer(const char* filename, const char* arg1, const char* arg2,
 296                          int size = -1, int timeOutMilliseconds = -1) noexcept;
 297
 298     /*!
 299      * Stop the pipe server.
 300      * This will send a quit message to the client, wait for it to close for @a timeOutMilliseconds, and close the pipes.
 301      */
 302     void stopPipeServer(uint32_t timeOutMilliseconds) noexcept;
 303
 304     /*!
 305      * Close the pipes without waiting for the child process to terminate.
 306      */
 307     void closePipeServer() noexcept;
 308
 309     // -------------------------------------------------------------------
 310     // write prepared messages, no lock or flush needed (done internally)
 311
 312     /*!
 313      * Write a single "show" message.
 314      */
 315     void writeShowMessage() const noexcept;
 316
 317     /*!
 318      * Write a single "focus" message.
 319      */
 320     void writeFocusMessage() const noexcept;
 321
 322     /*!
 323      * Write a single "hide" message.
 324      */
 325     void writeHideMessage() const noexcept;
 326
 327     CARLA_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR(CarlaPipeServer)
 328 };
 329
 330 // -----------------------------------------------------------------------
 331 // CarlaPipeClient class
 332
 333 class CarlaPipeClient : public CarlaPipeCommon
 334 {
 335 public:
 336     /*!
 337      * Constructor.
 338      */
 339     CarlaPipeClient() noexcept;
 340
 341     /*!
 342      * Destructor.
 343      */
 344     ~CarlaPipeClient() /*noexcept*/ override;
 345
 346     /*!
 347      * Initialize the pipes used by a server.
 348      * @a argv must match the arguments set the by server.
 349      */
 350     bool initPipeClient(const char* argv[]) noexcept;
 351
 352     /*!
 353      * Close the pipes.
 354      */
 355     void closePipeClient() noexcept;
 356
 357     // -------------------------------------------------------------------
 358     // write prepared messages, no lock or flush needed (done internally)
 359
 360     /*!
 361      * Write a single "exiting" message and wait for server to respond.
 362      */
 363     void writeExitingMessageAndWait() noexcept;
 364
 365     CARLA_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR(CarlaPipeClient)
 366 };
 367
 368 // -----------------------------------------------------------------------
 369
 370 #endif // CARLA_PIPE_UTILS_HPP_INCLUDED