diff options
| -rw-r--r-- | include/raul/Array.hpp | 9 | ||||
| -rw-r--r-- | include/raul/Deletable.hpp | 9 | ||||
| -rw-r--r-- | include/raul/DoubleBuffer.hpp | 22 | ||||
| -rw-r--r-- | include/raul/Exception.hpp | 6 | ||||
| -rw-r--r-- | include/raul/Maid.hpp | 64 | ||||
| -rw-r--r-- | include/raul/Noncopyable.hpp | 9 | ||||
| -rw-r--r-- | include/raul/Path.hpp | 94 | ||||
| -rw-r--r-- | include/raul/Process.hpp | 20 | ||||
| -rw-r--r-- | include/raul/RingBuffer.hpp | 31 | ||||
| -rw-r--r-- | include/raul/Semaphore.hpp | 12 | ||||
| -rw-r--r-- | include/raul/Socket.hpp | 63 | ||||
| -rw-r--r-- | include/raul/Symbol.hpp | 64 |
12 files changed, 216 insertions, 187 deletions
diff --git a/include/raul/Array.hpp b/include/raul/Array.hpp index 10f352d..911fca9 100644 --- a/include/raul/Array.hpp +++ b/include/raul/Array.hpp @@ -25,10 +25,11 @@ namespace raul { -/** A disposable array with size. - * - * \ingroup raul - */ +/** + A disposable array with a size. + + @ingroup raul +*/ template<class T> class Array : public Maid::Disposable { diff --git a/include/raul/Deletable.hpp b/include/raul/Deletable.hpp index e8f33bc..704d89c 100644 --- a/include/raul/Deletable.hpp +++ b/include/raul/Deletable.hpp @@ -18,10 +18,11 @@ namespace raul { -/** Something with a virtual destructor. - * - * \ingroup raul - */ +/** + Something with a virtual destructor. + + @ingroup raul +*/ class Deletable { public: diff --git a/include/raul/DoubleBuffer.hpp b/include/raul/DoubleBuffer.hpp index 1693f25..ac5256d 100644 --- a/include/raul/DoubleBuffer.hpp +++ b/include/raul/DoubleBuffer.hpp @@ -21,16 +21,18 @@ namespace raul { -/** Double buffer. - * - * Can be thought of as a wrapper class to make a non-atomic type atomically - * settable (with no locking). - * - * Read/Write realtime safe, many writers safe - but set calls may fail. - * - * Space: 2*sizeof(T) + sizeof(int) + sizeof(void*) - * \ingroup raul - */ +/** + Double buffer. + + Can be thought of as a wrapper class to make a non-atomic type atomically + settable (with no locking). + + Read/Write realtime safe, many writers safe - but set calls may fail. + + Space: 2*sizeof(T) + sizeof(int) + sizeof(void*) + + @ingroup raul +*/ template<typename T> class DoubleBuffer { diff --git a/include/raul/Exception.hpp b/include/raul/Exception.hpp index 595800f..13dea19 100644 --- a/include/raul/Exception.hpp +++ b/include/raul/Exception.hpp @@ -22,7 +22,11 @@ namespace raul { -/** An exception (unexpected error). */ +/** + An exception (unexpected error). + + @ingroup raul +*/ class Exception : public std::exception { public: diff --git a/include/raul/Maid.hpp b/include/raul/Maid.hpp index bc0ac4f..5c02b7f 100644 --- a/include/raul/Maid.hpp +++ b/include/raul/Maid.hpp @@ -25,20 +25,21 @@ namespace raul { -/** Explicit garbage-collector. - * - * This allows objects to be disposed of in a real-time thread, but actually - * deleted later by another thread which calls cleanup(). Disposable objects - * may be explicitly disposed by calling dispose(), or automatically managed - * with a managed_ptr which can safely be dropped in any thread, including - * real-time threads. - * - * \ingroup raul - */ +/** + Explicit garbage collector. + + This allows objects to be disposed of in a real-time thread, but actually + deleted later by another thread which calls cleanup(). Disposable objects + may be explicitly disposed by calling dispose(), or automatically managed + with a managed_ptr which can safely be dropped in any thread, including + real-time threads. + + @ingroup raul +*/ class Maid : public Noncopyable { public: - /** An object that can be disposed via Maid::dispose(). */ + /// An object that can be disposed via Maid::dispose() class Disposable : public Deletable { public: @@ -57,7 +58,7 @@ public: Disposable* _maid_next{}; }; - /** Disposable wrapper for any type. */ + /// Disposable wrapper for any type template<typename T> class Managed : public raul::Maid::Disposable @@ -70,7 +71,7 @@ public: {} }; - /** Deleter for Disposable objects. */ + /// Deleter for Disposable objects template<typename T> class Disposer { @@ -92,11 +93,12 @@ public: Maid* _maid{nullptr}; }; - /** A managed pointer that automatically disposes of its contents. - * - * This is a unique_ptr so that it is possible to statically verify that - * code is real-time safe. - */ + /** + A managed pointer that automatically disposes of its contents. + + This is a unique_ptr so that it is possible to statically verify that + code is real-time safe. + */ template<typename T> using managed_ptr = std::unique_ptr<T, Disposer<T>>; @@ -112,17 +114,18 @@ public: inline ~Maid() { cleanup(); } - /** Return false iff there is currently no garbage. */ + /// Return false iff there is currently no garbage inline bool empty() const { return !_disposed.load(std::memory_order_relaxed); } - /** Enqueue an object for deletion when cleanup() is called next. - * - * This is thread-safe, and real-time safe assuming reasonably low - * contention. - */ + /** + Enqueue an object for deletion when cleanup() is called next. + + This is thread-safe, and real-time safe assuming reasonably low + contention. + */ inline void dispose(Disposable* obj) { if (obj) { @@ -136,11 +139,12 @@ public: } } - /** Delete all disposed objects immediately. - * - * Obviously not real-time safe, but may be called while other threads are - * calling dispose(). - */ + /** + Delete all disposed objects immediately. + + Obviously not real-time safe, but may be called while other threads are + calling dispose(). + */ inline void cleanup() { // Atomically get the head of the disposed list @@ -155,7 +159,7 @@ public: } } - /** Make a unique_ptr that will dispose its object when dropped. */ + /// Make a unique_ptr that will dispose its object when dropped template<class T, class... Args> managed_ptr<T> make_managed(Args&&... args) { diff --git a/include/raul/Noncopyable.hpp b/include/raul/Noncopyable.hpp index 189bd22..76e1f6d 100644 --- a/include/raul/Noncopyable.hpp +++ b/include/raul/Noncopyable.hpp @@ -18,10 +18,11 @@ namespace raul { -/** Convenience base for non-copyable and non-movable classes. - * - * \ingroup raul - */ +/** + Convenience base for non-copyable and non-movable classes. + + @ingroup raul +*/ class Noncopyable { public: diff --git a/include/raul/Path.hpp b/include/raul/Path.hpp index e5ca5c9..1ddfb24 100644 --- a/include/raul/Path.hpp +++ b/include/raul/Path.hpp @@ -25,17 +25,18 @@ namespace raul { -/** A restricted path of Symbols separated by, and beginning with, "/". - * - * A Path never ends with a "/", except for the root Path "/", which is the - * only valid single-character Path. - * - * @ingroup raul - */ +/** + A restricted path of Symbols separated by, and beginning with, "/". + + A Path never ends with a "/", except for the root Path "/", which is the + only valid single-character Path. + + @ingroup raul +*/ class Path : public std::basic_string<char> { public: - /** Attempt to construct an invalid Path. */ + /// Attempt to construct an invalid Path class BadPath : public Exception { public: @@ -44,16 +45,17 @@ public: {} }; - /** Construct an uninitialzed path, because the STL is annoying. */ + /// Construct the root path `/` Path() : std::basic_string<char>("/") {} - /** Construct a Path from a C++ string. - * - * This will throw an exception if `path` is invalid. To avoid this, use - * is_valid() first to check. - */ + /** + Construct a Path from a C++ string. + + This will throw an exception if `path` is invalid. To avoid this, use + is_valid() first to check. + */ explicit Path(const std::basic_string<char>& path) : std::basic_string<char>(path) { @@ -62,11 +64,12 @@ public: } } - /** Construct a Path from a C string. - * - * This will throw an exception if `path` is invalid. To avoid this, use - * is_valid() first to check. - */ + /** + Construct a Path from a C string. + + This will throw an exception if `path` is invalid. To avoid this, use + is_valid() first to check. + */ explicit Path(const char* path) : std::basic_string<char>(path) { @@ -83,13 +86,13 @@ public: ~Path() = default; - /** Return true iff `c` is a valid Path character. */ + /// Return true iff `c` is a valid Path character static inline bool is_valid_char(char c) { return c == '/' || Symbol::is_valid_char(c); } - /** Return true iff `str` is a valid Path. */ + /// Return true iff `str` is a valid Path static inline bool is_valid(const std::basic_string<char>& str) { if (str.empty() || (str[0] != '/')) { @@ -119,28 +122,29 @@ public: return true; } - /** Return true iff this path is the root path ("/"). */ + /// Return true iff this path is the root path ("/") inline bool is_root() const { return *this == "/"; } - /** Return true iff this path is a child of `parent` at any depth. */ + /// Return true iff this path is a child of `parent` at any depth inline bool is_child_of(const Path& parent) const { const std::string parent_base = parent.base(); return substr(0, parent_base.length()) == parent_base; } - /** Return true iff this path is a parent of `child` at any depth. */ + /// Return true iff this path is a parent of `child` at any depth inline bool is_parent_of(const Path& child) const { return child.is_child_of(*this); } - /** Return the symbol of this path (everything after the last '/'). - * - * This is what is called the "basename" for file paths, the "method name" - * for OSC paths, and so on. Since the root path does not have a symbol, - * this does not return a raul::Symbol but may return the empty string. - */ + /** + Return the symbol of this path (everything after the last '/'). + + This is what is called the "basename" for file paths, the "method name" + for OSC paths, and so on. Since the root path does not have a symbol, + this does not return a raul::Symbol but may return the empty string. + */ inline const char* symbol() const { if (!is_root()) { @@ -152,11 +156,12 @@ public: return ""; } - /** Return the parent's path. - * - * Calling this on the path "/" will return "/". - * This is the (deepest) "container path" for OSC paths. - */ + /** + Return the parent's path. + + Calling this on the path "/" will return "/". + This is the (deepest) "container path" for OSC paths. + */ inline Path parent() const { if (is_root()) { @@ -168,23 +173,24 @@ public: return (first_sep == last_sep) ? Path("/") : Path(substr(0, last_sep)); } - /** Return a child Path of this path. */ + /// Return a child Path of this path inline Path child(const Path& p) const { return p.is_root() ? *this : Path(base() + p.substr(1)); } - /** Return a direct child Path of this Path with the given Symbol. */ + /// Return a direct child Path of this Path with the given Symbol inline Path child(const raul::Symbol& symbol) const { return Path(base() + symbol.c_str()); } - /** Return path with a trailing "/". - * - * The returned string is such that appending a valid Symbol to it is - * guaranteed to form a valid path. - */ + /** + Return path with a trailing "/". + + The returned string is such that appending a valid Symbol to it is + guaranteed to form a valid path. + */ inline std::string base() const { if (is_root()) { @@ -194,7 +200,7 @@ public: return *this + '/'; } - /** Return the lowest common ancestor of a and b. */ + /// Return the lowest common ancestor of a and b static inline Path lca(const Path& a, const Path& b) { const size_t len = std::min(a.length(), b.length()); @@ -215,7 +221,7 @@ public: return Path(a.substr(0, last_sep)); } - /** Return true iff `child` is equal to, or a descendant of `parent`. */ + /// Return true iff `child` is equal to, or a descendant of `parent` static inline bool descendant_comparator(const Path& parent, const Path& child) { diff --git a/include/raul/Process.hpp b/include/raul/Process.hpp index b05b038..085ed8b 100644 --- a/include/raul/Process.hpp +++ b/include/raul/Process.hpp @@ -23,18 +23,20 @@ namespace raul { -/** A child process. - * - * \ingroup raul - */ +/** + A child process. + + @ingroup raul +*/ class Process : Noncopyable { public: - /** Launch a sub process. - * - * @param argv List of arguments, where argv[0] is the command name. - * @return True on success. - */ + /** + Launch a sub process. + + @param argv List of arguments, where argv[0] is the command name. + @return True on success. + */ static bool launch(const char* const argv[]) { // Use the same double fork() trick as JACK to prevent zombie children diff --git a/include/raul/RingBuffer.hpp b/include/raul/RingBuffer.hpp index d194ca4..9c49d1b 100644 --- a/include/raul/RingBuffer.hpp +++ b/include/raul/RingBuffer.hpp @@ -39,8 +39,9 @@ class RingBuffer : public Noncopyable public: /** Create a new RingBuffer. + @param size Size in bytes (note this may be rounded up). - */ + */ explicit RingBuffer(uint32_t size) : _write_head(0) , _read_head(0) @@ -72,38 +73,28 @@ public: _read_head = 0; } - /** - Return the number of bytes of space available for reading. - */ + /// Return the number of bytes of space available for reading inline uint32_t read_space() const { return read_space_internal(_read_head, _write_head); } - /** - Return the number of bytes of space available for writing. - */ + /// Return the number of bytes of space available for writing inline uint32_t write_space() const { return write_space_internal(_read_head, _write_head); } - /** - Return the capacity (i.e. total write space when empty). - */ + /// Return the capacity (i.e. total write space when empty) inline uint32_t capacity() const { return _size - 1; } - /** - Read from the RingBuffer without advancing the read head. - */ + /// Read from the RingBuffer without advancing the read head inline uint32_t peek(uint32_t size, void* dst) { return peek_internal(_read_head, _write_head, size, dst); } - /** - Read from the RingBuffer and advance the read head. - */ + /// Read from the RingBuffer and advance the read head inline uint32_t read(uint32_t size, void* dst) { const uint32_t r = _read_head; @@ -118,9 +109,7 @@ public: return 0; } - /** - Skip data in the RingBuffer (advance read head without reading). - */ + /// Skip data in the RingBuffer (advance read head without reading) inline uint32_t skip(uint32_t size) { const uint32_t r = _read_head; @@ -134,9 +123,7 @@ public: return size; } - /** - Write data to the RingBuffer. - */ + /// Write data to the RingBuffer inline uint32_t write(uint32_t size, const void* src) { const uint32_t r = _read_head; diff --git a/include/raul/Semaphore.hpp b/include/raul/Semaphore.hpp index 9e8dbb1..f4dc447 100644 --- a/include/raul/Semaphore.hpp +++ b/include/raul/Semaphore.hpp @@ -43,6 +43,8 @@ namespace raul { At least on Lignux, the main advantage of this is that it is fast and the only safe way to reliably signal from a real-time audio thread. The counting semantics also complement ringbuffers of events nicely. + + @ingroup raul */ class Semaphore { @@ -68,23 +70,23 @@ public: inline ~Semaphore() { destroy(); } - /** Destroy and reset to a new initial value. */ + /// Destroy and reset to a new initial value inline void reset(unsigned initial) { destroy(); init(initial); } - /** Post/Increment/Signal */ + /// Post/Increment/Signal inline void post(); - /** Wait/Decrement. Return false on error. */ + /// Wait/Decrement, return false on error inline bool wait(); - /** Attempt Wait/Decrement. Return true iff decremented. */ + /// Attempt Wait/Decrement, return true iff decremented inline bool try_wait(); - /** Wait for at most `ms` milliseconds. Return true iff decremented. */ + /// Wait for at most `ms` milliseconds, return true iff decremented template<class Rep, class Period> inline bool timed_wait(const std::chrono::duration<Rep, Period>& wait); diff --git a/include/raul/Socket.hpp b/include/raul/Socket.hpp index 55d2f70..6a2883c 100644 --- a/include/raul/Socket.hpp +++ b/include/raul/Socket.hpp @@ -31,16 +31,20 @@ namespace raul { -/** A safe and simple interface for UNIX or TCP sockets. */ +/** + A safe and simple interface for UNIX or TCP sockets. + + @ingroup raul +*/ class Socket : public raul::Noncopyable { public: enum class Type { UNIX, TCP }; - /** Create a new unbound/unconnected socket of a given type. */ + /// Create a new unbound/unconnected socket of a given type explicit Socket(Type t); - /** Wrap an existing open socket. */ + /// Wrap an existing open socket Socket(Type t, std::string uri, struct sockaddr* addr, @@ -55,41 +59,52 @@ public: ~Socket(); - /** Bind a server socket to an address. - * @param uri Address URI, e.g. unix:///tmp/foo, or tcp://hostname:1234. - * Use "*" as hostname to listen on all interfaces. - * @return True on success. - */ + /** + Bind a server socket to an address. + + @param uri Address URI, e.g. unix:///tmp/foo, or tcp://hostname:1234. + Use "*" as hostname to listen on all interfaces. + + @return True on success. + */ bool bind(const std::string& uri); - /** Connect a client socket to a server address. - * @param uri Address URI, e.g. unix:///tmp/foo or tcp://somehost:1234 - * @return True on success. - */ + /** + Connect a client socket to a server address. + + @param uri Address URI, e.g. unix:///tmp/foo or tcp://somehost:1234 + @return True on success. + */ bool connect(const std::string& uri); - /** Mark server socket as passive to listen for incoming connections. - * @return True on success. - */ + /** + Mark server socket as passive to listen for incoming connections. + + @return True on success. + */ bool listen(); - /** Accept a connection. - * @return An new open socket for the connection. - */ + /** + Accept a connection. + + @return An new open socket for the connection. + */ std::shared_ptr<Socket> accept(); - /** Return the file descriptor for the socket. */ + /// Return the file descriptor for the socket int fd() const { return _sock; } const std::string& uri() const { return _uri; } - /** Close the socket. */ + /// Close the socket void close(); - /** Shut down the socket. - * This terminates any connections associated with the sockets, and will - * (unlike close()) cause a poll on the socket to return. - */ + /** + Shut down the socket. + + This terminates any connections associated with the socket, and will + (unlike close()) cause a poll on the socket to return. + */ void shutdown(); private: diff --git a/include/raul/Symbol.hpp b/include/raul/Symbol.hpp index 10446d0..a4ac6bd 100644 --- a/include/raul/Symbol.hpp +++ b/include/raul/Symbol.hpp @@ -24,21 +24,22 @@ namespace raul { -/** A restricted string which is a valid C identifier and Path component. - * - * A Symbol is a very restricted string suitable for use as an identifier. - * It is a valid LV2 symbol, URI fragment, filename, OSC path fragment, - * and identifier for virtually all programming languages. - * - * Valid characters are _, a-z, A-Z, 0-9, except the first character which - * must not be 0-9. - * - * @ingroup raul - */ +/** + A restricted string which is a valid C identifier and Path component. + + A Symbol is a very restricted string suitable for use as an identifier. + It is a valid LV2 symbol, URI fragment, filename, OSC path fragment, + and identifier for virtually all programming languages. + + Valid characters are _, a-z, A-Z, 0-9, except the first character which + must not be 0-9. + + @ingroup raul +*/ class Symbol : public std::basic_string<char> { public: - /** Attempt to construct an invalid Symbol. */ + /// Attempt to construct an invalid Symbol class BadSymbol : public Exception { public: @@ -47,11 +48,12 @@ public: {} }; - /** Construct a Symbol from a C++ string. - * - * This will throw an exception if `symbol` is invalid. To avoid this, - * use is_valid() first to check. - */ + /** + Construct a Symbol from a C++ string. + + This will throw an exception if `symbol` is invalid. To avoid this, + use is_valid() first to check. + */ explicit Symbol(const std::basic_string<char>& symbol) : std::basic_string<char>(symbol) { @@ -60,11 +62,12 @@ public: } } - /** Construct a Symbol from a C string. - * - * This will throw an exception if `symbol` is invalid. To avoid this, - * use is_valid() first to check. - */ + /** + Construct a Symbol from a C string. + + This will throw an exception if `symbol` is invalid. To avoid this, + use is_valid() first to check. + */ explicit Symbol(const char* symbol) : std::basic_string<char>(symbol) { @@ -81,19 +84,19 @@ public: ~Symbol() = default; - /** Return true iff `c` is a valid Symbol start character. */ + /// Return true iff `c` is a valid Symbol start character static inline bool is_valid_start_char(char c) { return (c == '_') || (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z'); } - /** Return true iff `c` is a valid Symbol character. */ + /// Return true iff `c` is a valid Symbol character static inline bool is_valid_char(char c) { return is_valid_start_char(c) || (c >= '0' && c <= '9'); } - /** Return true iff `str` is a valid Symbol. */ + /// Return true iff `str` is a valid Symbol static inline bool is_valid(const std::basic_string<char>& str) { if (str.empty() || (str[0] >= '0' && str[0] <= '9')) { @@ -103,11 +106,12 @@ public: return std::all_of(str.begin(), str.end(), is_valid_char); } - /** Convert a string to a valid symbol. - * - * This will make a best effort at turning `str` into a complete, valid - * Symbol, and will always return one. - */ + /** + Convert a string to a valid symbol. + + This will make a best effort at turning `str` into a complete, valid + Symbol, and will always return one. + */ static inline Symbol symbolify(const std::basic_string<char>& in) { if (in.empty()) { |