pvxslibs 1.5.0__cp310-cp310-manylinux2014_x86_64.whl

pvxslibs/include/pvxs/unittest.h

@@ -0,0 +1,327 @@
+/**
+ * Copyright - See the COPYRIGHT that is included with this distribution.
+ * pvxs is distributed subject to a Software License Agreement found
+ * in file LICENSE that is included with this distribution.
+ */
+
+#ifndef PVXS_UNITTEST_H
+#define PVXS_UNITTEST_H
+
+/** @file pvxs/unittest.h
+ *
+ * C++ helpers for use with epicsUnitTest.h
+ */
+
+#include <sstream>
+#include <vector>
+#include <functional>
+#include <type_traits>
+
+#include <pvxs/version.h>
+#include <pvxs/util.h>
+
+namespace pvxs {
+
+/** Prepare for testing.  Call after testPlan()
+ * @since 1.2.0 If linked with pvxsIoc library, PVA server started
+ *              by ``iocInit()`` will use "isolated" configuration.
+ */
+PVXS_API
+void testSetup();
+
+/** Free some internal global allocations to avoid false positives in
+ *  valgrind (or similar) tools looking for memory leaks.
+ *
+ *  Calls libevent_global_shutdown() when available (libevent >=2.1).
+ *
+ * @warning This function is optional.
+ *          If you don't understand the intended use case, then do not call it!
+ *
+ * @pre Caller must release all resources explicitly allocated through PVXS (on all threads).
+ * @post Invalidates internal state.
+ *       Use of __any__ API functions afterwards is undefined!
+ */
+PVXS_API
+void cleanup_for_valgrind();
+
+/** A single test case (or diagnostic line).
+ *
+ * Acts as an output string to accumulate test comment.
+ * Multi-line output results in one test line, and subsequent diagnostic lines.
+ *
+ * Test line is printed when an active (non-moved) testCase is destroyed.
+ */
+class PVXS_API testCase
+{
+    enum {
+        Nothing, // after move()'d
+        Diag,    // no test, just print
+        Pass,
+        Fail,
+    } result;
+    std::ostringstream msg;
+public:
+    //! new diag message
+    testCase();
+    //! new test case
+    explicit testCase(bool result);
+    testCase(const testCase&) = delete;
+    testCase& operator=(const testCase&) = delete;
+    testCase(testCase&&) noexcept;
+    testCase& operator=(testCase&&) noexcept;
+    ~testCase();
+
+    //! true when passing
+    explicit operator bool() const { return result==Pass; }
+
+    //! Override current pass/fail result
+    testCase& setPass(bool v) {
+        result = v ? Pass : Fail;
+        return *this;
+    }
+
+    //! Override current pass/fail result if input matches a regular expression
+    //! @since 0.2.1 Expression syntax is POSIX extended.
+    //! @since 0.1.1 Added
+    testCase& setPassMatch(const std::string& expr, const std::string& inp);
+
+    //! Append to message
+    template<typename T>
+    inline testCase& operator<<(const T& v) {
+        msg<<v;
+        return *this;
+    }
+
+    /** Access to underlying std::ostream used to accumulate notes.
+     *  When our operator<< isn't enough.
+     *  @since 1.1.4
+     */
+    inline
+    std::ostream& stream() { return msg; }
+};
+
+namespace detail {
+
+// control how testEq() and testNotEq() print things
+template<typename T, typename Enable=void>
+struct test_print {
+    template<class C>
+    static inline void op(C& strm, const T& v) {
+        strm<<v;
+    }
+};
+template <>
+struct test_print<std::string> {
+    template<class C>
+    static inline void op(C& strm, const std::string& v) {
+        strm<<'"'<<escape(v)<<'"';
+    }
+};
+template <>
+struct test_print<const char*> {
+    template<class C>
+    static inline void op(C& strm, const char* v) {
+        strm<<'"'<<escape(v)<<'"';
+    }
+};
+template<typename E>
+struct test_print<std::vector<E>, typename std::enable_if<sizeof(E)==1>::type> {
+    template<class C>
+    static inline void op(C& strm, const std::vector<E>& v) {
+        strm<<'"'<<escape((const char*)v.data(), v.size())<<'"';
+    }
+};
+template <typename E>
+struct test_print<E, typename std::enable_if<std::is_same<E, char>::value||std::is_same<E, signed char>::value||std::is_same<E, unsigned char>::value>::type> {
+    template<class C>
+    static inline void op(C& strm, char v) {
+        strm<<int(v);
+    }
+};
+
+template<typename LHS, typename RHS>
+testCase testEq(const char *sLHS, const LHS& lhs, const char *sRHS, const RHS& rhs)
+{
+    testCase ret(lhs==rhs);
+    ret<<sLHS<<" (";
+    test_print<LHS>::op(ret, lhs);
+    ret<<") == "<<sRHS<<" (";
+    test_print<RHS>::op(ret, rhs);
+    ret<<") ";
+    return ret;
+}
+
+template<typename LHS, typename RHS>
+testCase testNotEq(const char *sLHS, const LHS& lhs, const char *sRHS, const RHS& rhs)
+{
+    testCase ret(lhs!=rhs);
+    ret<<sLHS<<" (";
+    test_print<LHS>::op(ret, lhs);
+    ret<<") != "<<sRHS<<" (";
+    test_print<RHS>::op(ret, rhs);
+    ret<<") ";
+    return ret;
+}
+
+template<typename T>
+struct as_str {
+    static const char* op(const T& v) { return v; }
+};
+template<> struct as_str<std::string> {
+    static const char* op(const std::string& v) { return v.c_str(); }
+};
+template<> struct as_str<const std::string> {
+    static const char* op(const std::string& v) { return v.c_str(); }
+};
+
+template<typename T>
+const char* asStr(const T& v) { return as_str<T>::op(v); }
+
+PVXS_API
+testCase _testStrTest(unsigned op, const char *sLHS, const char* lhs, const char *sRHS, const char* rhs);
+
+PVXS_API
+testCase _testStrMatch(const char *spat, const std::string& pat, const char *sstr, const std::string& str);
+
+template<typename LHS, typename RHS>
+testCase testArrEq(const char *sLHS, const LHS& lhs, const char *sRHS, const RHS& rhs)
+{
+    bool eq = lhs.size()==rhs.size();
+    testCase ret;
+    ret<<sLHS<<" (";
+    test_print<LHS>::op(ret, lhs);
+    ret<<") == "<<sRHS<<" (";
+    test_print<RHS>::op(ret, rhs);
+    ret<<")\n";
+    for(size_t i=0; i<lhs.size() && i<rhs.size(); i++) {
+        if(lhs[i]!=rhs[i]) {
+            eq = false;
+            ret<<" ["<<i<<"] -> ";
+            test_print<typename std::decay<decltype (lhs[i])>::type>::op(ret, lhs[i]);
+            ret<<" != ";
+            test_print<typename std::decay<decltype (rhs[i])>::type>::op(ret, rhs[i]);
+            ret<<"\n";
+        }
+    }
+    ret.setPass(eq);
+    return ret;
+}
+
+} // namespace detail
+
+/** Assert that an exception is thrown.
+ *
+ * @tparam Exception The exception type which should be thrown
+ * @param fn A callable
+ *
+ * @returns A testCase which passes if an Exception instance was caught,
+ *          and false otherwise (wrong type, or no exception).
+ *
+ * @code
+ * testThrows<std::runtime_error>([]() {
+ *      testShow()<<"Now you see me";
+ *      throw std::runtime_error("I happened");
+ *      testShow()<<"Now you don't";
+ * })<<"some message";
+ * @endcode
+ */
+template<class Exception, typename FN>
+testCase testThrows(FN fn)
+{
+    testCase ret(false);
+    try {
+        fn();
+        ret<<"Unexpected success - ";
+    }catch(Exception& e){
+        ret.setPass(true)<<"Expected exception \""<<e.what()<<"\" - ";
+    }catch(std::exception& e){
+        ret<<"Unexpected exception "<<typeid(e).name()<<" \""<<e.what()<<"\" - ";
+    }
+    return ret;
+}
+
+/** Assert that an exception is throw with a certain message.
+ *
+ * @tparam Exception The exception type which should be thrown
+ * @param expr A regular expression
+ * @param fn A callable
+ *
+ * @returns A testCase which passes if an Exception instance was caught
+ *          and std::exception::what() matched the provided regular expression.
+ *
+ * @code
+ * testThrowsMatch<std::runtime_error>("happened", []() {
+ *      testShow()<<"Now you see me";
+ *      throw std::runtime_error("I happened");
+ *      testShow()<<"Now you don't";
+ * })<<"some message";
+ * @endcode
+ *
+ * @since 0.1.1
+ */
+template<class Exception, typename FN>
+testCase testThrowsMatch(const std::string& expr, FN fn)
+{
+    testCase ret(false);
+    try {
+        fn();
+        ret<<"Unexpected success - ";
+    }catch(Exception& e){
+        ret.setPassMatch(expr, e.what())<<"Expected matching (\""<<expr<<"\") exception \""<<e.what()<<"\" - ";
+    }catch(std::exception& e){
+        ret<<"Unexpected exception "<<typeid(e).name()<<" \""<<e.what()<<"\" - ";
+    }
+    return ret;
+}
+
+} // namespace pvxs
+
+//! Macro which assert that an expression evaluate to 'true'.
+//! Evaluates to a pvxs::testCase
+#define testTrue(EXPR) ::pvxs::testCase(EXPR)<<(" " #EXPR)
+
+//! Macro which assert that an expression evaluate to 'true'.
+//! Evaluates to a pvxs::testCase
+#define testFalse(EXPR) ::pvxs::testCase(!(EXPR))<<(" !" #EXPR)
+
+//! Macro which asserts equality between LHS and RHS.
+//! Evaluates to a pvxs::testCase
+//! Roughly equivalent to @code testOk((LHS)==(RHS), "..."); @endcode
+#define testEq(LHS, RHS) ::pvxs::detail::testEq(#LHS, LHS, #RHS, RHS)
+
+//! Macro which asserts in-equality between LHS and RHS.
+//! Evaluates to a pvxs::testCase
+//! Roughly equivalent to @code testOk((LHS)!=(RHS), "..."); @endcode
+#define testNotEq(LHS, RHS) ::pvxs::detail::testNotEq(#LHS, LHS, #RHS, RHS)
+
+//! Macro which asserts equality between LHS and RHS.
+//! Evaluates to a pvxs::testCase
+//! Functionally equivalent to testEq() with two std::string instances.
+//! Prints diff-like output which is friendlier to multi-line strings.
+#define testStrEq(LHS, RHS) ::pvxs::detail::_testStrTest(1, #LHS, ::pvxs::detail::asStr(LHS), #RHS, ::pvxs::detail::asStr(RHS))
+
+//! Macro which asserts inequality between LHS and RHS.
+//! Evaluates to a pvxs::testCase
+//! Functionally equivalent to testNotEq() with two std::string instances.
+//! Prints diff-like output which is friendlier to multi-line strings.
+//! @since 0.2.0
+#define testStrNotEq(LHS, RHS) ::pvxs::detail::_testStrTest(0, #LHS, ::pvxs::detail::asStr(LHS), #RHS, ::pvxs::detail::asStr(RHS))
+
+//! Macro which asserts that STR matches the regular expression EXPR
+//! Evaluates to a pvxs::testCase
+//! @since 0.2.1 Expression syntax is POSIX extended.
+//! @since 0.1.1
+#define testStrMatch(EXPR, STR) ::pvxs::detail::_testStrMatch(#EXPR, EXPR, #STR, STR)
+
+//! Macro which asserts equality between LHS and RHS.
+//! Evaluates to a pvxs::testCase
+//! Functionally equivalent to testEq() for objects with .size() and operator[].
+//! Prints element by element differences
+#define testArrEq(LHS, RHS) ::pvxs::detail::testArrEq(#LHS, LHS, #RHS, RHS)
+
+//! Macro which prints diagnostic (non-test) lines.
+//! Evaluates to a pvxs::testCase
+//! Roughly equivalent to @code testDiag("..."); @endcode
+#define testShow() ::pvxs::testCase()
+
+#endif // PVXS_UNITTEST_H

pvxslibs/include/pvxs/util.h

@@ -0,0 +1,354 @@
+/**
+ * Copyright - See the COPYRIGHT that is included with this distribution.
+ * pvxs is distributed subject to a Software License Agreement found
+ * in file LICENSE that is included with this distribution.
+ */
+
+#ifndef PVXS_UTIL_H
+#define PVXS_UTIL_H
+
+#include <map>
+#include <array>
+#include <deque>
+#include <functional>
+#include <iosfwd>
+#include <type_traits>
+#include <stdexcept>
+#include <memory>
+
+#include <osiSock.h>
+#include <epicsEvent.h>
+#include <epicsMutex.h>
+#include <epicsGuard.h>
+
+#include <pvxs/version.h>
+
+namespace pvxs {
+
+namespace detail {
+// ref. wrapper to mark string for escaping
+class Escaper
+{
+    const char* val;
+    size_t count;
+    friend
+    PVXS_API
+    std::ostream& operator<<(std::ostream& strm, const Escaper& esc);
+public:
+    PVXS_API explicit Escaper(const char* v);
+    constexpr explicit Escaper(const char* v, size_t l) :val(v),count(l) {}
+};
+
+PVXS_API
+std::ostream& operator<<(std::ostream& strm, const Escaper& esc);
+
+} // namespace detail
+
+//! Print string to output stream with non-printable characters escaped.
+//!
+//! Outputs (almost) C-style escapes.
+//! Prefers short escapes for newline, tab, quote, etc ("\\n").
+//! Falls back to hex escape (eg. "\xab").
+//!
+//! Unlike C, hex escapes are always 2 chars.  eg. the output "\xabcase"
+//! would need to be manually changed to "\xab""case" to be used as C source.
+//!
+//! @code
+//!   std::string blah("this \"is a test\"");
+//!   std::cout<<pvxs::escape(blah);
+//! @endcode
+inline detail::Escaper escape(const std::string& s) {
+    return detail::Escaper(s.c_str(), s.size());
+}
+//! Print nil terminated char array to output stream with non-printable characters escaped.
+//! @code
+//!   std::cout<<pvxs::escape("this \"is a test\"");
+//! @endcode
+inline detail::Escaper escape(const char* s) {
+    return detail::Escaper(s);
+}
+//! Print fixed length char array to output stream with non-printable characters escaped.
+//! @code
+//!   std::cout<<pvxs::escape("this \"is a test\"", 6);
+//!   // prints 'this \"'
+//! @endcode
+inline detail::Escaper escape(const char* s,size_t n) {
+    return detail::Escaper(s,n);
+}
+
+struct ServerGUID : public std::array<uint8_t, 12> {};
+
+PVXS_API
+std::ostream& operator<<(std::ostream&, const ServerGUID&);
+
+#if !defined(__rtems__) && !defined(vxWorks)
+
+/** Portable process signal handling in CLI tools.
+ *
+ * @code
+ *     epicsEvent evt;
+ *     SigInt handle([&evt]() {
+ *          evt.trigger();
+ *     });
+ *     ... setup network operations
+ *     evt.wait();
+ *     // completion, or SIGINT
+ * @endcode
+ *
+ * Saves existing handler, which are restored by dtor.
+ *
+ * @since 1.1.0 "handler" action runs in thread context.
+ *              Safe to take locks etc.
+ *              Previously handler action ran in signal handler context.
+ */
+class PVXS_API SigInt {
+public:
+    //! Install signal handler.
+    SigInt(const std::function<void()>&& handler);
+    SigInt(const SigInt&) = delete;
+    ~SigInt();
+    struct Pvt;
+private:
+    std::shared_ptr<Pvt> pvt;
+};
+
+#else // !defined(__rtems__) && !defined(vxWorks)
+
+class SigInt {
+    const std::function<void()> handler;
+public:
+    SigInt(std::function<void()>&& handler) :handler(std::move(handler)) {}
+};
+
+#endif // !defined(__rtems__) && !defined(vxWorks)
+
+//! return a snapshot of internal instance counters
+PVXS_API
+std::map<std::string, size_t> instanceSnapshot();
+
+//! See Indented
+struct indent {};
+
+PVXS_API
+std::ostream& operator<<(std::ostream& strm, const indent&);
+
+//! Scoped indentation for std::ostream
+struct PVXS_API Indented {
+    explicit Indented(std::ostream& strm, int depth=1);
+    Indented(const Indented&) = delete;
+    Indented(Indented&& o) noexcept
+        :strm(o.strm)
+        ,depth(o.depth)
+    {
+        o.strm = nullptr;
+        o.depth = 0;
+    }
+    ~Indented();
+private:
+    std::ostream *strm;
+    int depth;
+};
+
+struct PVXS_API Detailed {
+    explicit Detailed(std::ostream& strm, int lvl=1);
+    Detailed(const Detailed&) = delete;
+    Detailed(Detailed&& o) noexcept
+        :strm(o.strm)
+        ,lvl(o.lvl)
+    {
+        o.strm = nullptr;
+        o.lvl = 0;
+    }
+    ~Detailed();
+    static
+    int level(std::ostream& strm);
+private:
+    std::ostream *strm;
+    int lvl;
+};
+
+/** Describe build and runtime configuration of current system.
+ *
+ * Print information which may be using for when troubleshooting,
+ * or creating a bug report.
+ *
+ * Printed by CLI "pvxinfo -D" and iocsh "pvxs_target_information".
+ *
+ * @returns The same ostream passed as argument.
+ */
+PVXS_API
+std::ostream& target_information(std::ostream&);
+
+/** Print version information for PVXS library and dependencies
+ *
+ * As shown by eg. ``pvxget -V``
+ *
+ * @returns The same ostream passed as argument.
+ *
+ * @since 1.2.3
+ */
+PVXS_API
+std::ostream& version_information(std::ostream&);
+
+/** Thread-safe, bounded, multi-producer, multi-consumer FIFO queue.
+ *
+ * Queue value_type must be movable.  If T is also copy constructable,
+ * then push(const T&) may be used.
+ *
+ * As an exception, the destructor is not re-entrant.  Concurrent calls
+ * to methods during destruction will result in undefined behavior.
+ *
+ * @code
+ * MPMCFIFO<std::function<void()>> Q;
+ * ...
+ * while(auto work = Q.pop()) { // Q.push(nullptr) to break loop
+ *     work();
+ * }
+ * @endcode
+ *
+ * @since 0.2.0
+ */
+template<typename T>
+class MPMCFIFO {
+    mutable epicsMutex lock;
+    epicsEvent notifyW, notifyR;
+    std::deque<T> Q;
+    const size_t nlimit;
+    unsigned nwriters=0u, nreaders=0u;
+
+    typedef epicsGuard<epicsMutex> Guard;
+    typedef epicsGuardRelease<epicsMutex> UnGuard;
+public:
+    //! Template parameter
+    typedef T value_type;
+
+    //! Construct a new queue
+    //! @param limit If non-zero, then emplace()/push() will block while while
+    //!              queue size is greater than or equal to this limit.
+    explicit MPMCFIFO(size_t limit=0u)
+        :nlimit(limit)
+    {}
+    //! Destructor is not re-entrant
+    ~MPMCFIFO() {}
+
+    //! Poll number of elements in the work queue at this moment.
+    size_t size() const {
+        Guard G(lock);
+        return Q.size();
+    }
+    size_t max_size() const {
+        return nlimit ? nlimit : Q.max_size();
+    }
+
+    /** Construct a new element into the queue.
+     *
+     * Will block while full.
+     */
+    template<typename ...Args>
+    void emplace(Args&&... args) {
+        bool wakeupR, wakeupW;
+        {
+            Guard G(lock);
+            // while full, wait for reader to consume an entry
+            while(nlimit && Q.size()>=nlimit) {
+                nwriters++;
+                {
+                    UnGuard U(G);
+                    notifyW.wait();
+                }
+                nwriters--;
+            }
+            // notify reader when queue becomes not empty
+            wakeupR = Q.empty() && nreaders;
+            Q.emplace_back(std::forward<Args>(args)...);
+            // wakeup next writer if there is still space
+            wakeupW = nwriters && Q.size()<nlimit;
+        }
+        if(wakeupR)
+            notifyR.signal();
+        if(wakeupW)
+            notifyW.signal();
+    }
+
+    //! Move a new element to the queue
+    void push(T&& ent) {
+        // delegate to T::T(T&&)
+        emplace(std::move(ent));
+    }
+
+    //! Copy a new element to the queue
+    void push(const T& ent) {
+        // delegate to T::T(const T&)
+        emplace(ent);
+    }
+
+    /** Remove an element from the queue.
+     *
+     * Blocks while queue is empty.
+     */
+    T pop() {
+        bool wakeupW, wakeupR;
+        T ret;
+        {
+            Guard G(lock);
+            // wait for queue to become not empty
+            while(Q.empty()) {
+                nreaders++;
+                {
+                    UnGuard U(G);
+                    notifyR.wait();
+                }
+                nreaders--;
+            }
+            // wakeup a writer since the queue will have an empty entry
+            wakeupW = nwriters;
+            ret = std::move(Q.front());
+            Q.pop_front();
+            // wakeup next reader if entries remain
+            wakeupR = !Q.empty() && nreaders;
+        }
+        if(wakeupR)
+            notifyR.signal();
+        if(wakeupW)
+            notifyW.signal();
+        return ret;
+    }
+};
+
+struct Timer;
+
+#ifdef PVXS_EXPERT_API_ENABLED
+
+//! Timer associated with a client::Context or server::Server
+//! @since 0.2.0
+struct PVXS_API Timer {
+    struct Pvt;
+
+    //! dtor implicitly cancel()s
+    ~Timer();
+    //! Explicit cancel.
+    //! @returns true if the timer was running, and now is not.
+    bool cancel();
+
+    explicit operator bool() const { return pvt.operator bool(); }
+
+private:
+    std::shared_ptr<Pvt> pvt;
+    friend struct Pvt;
+};
+
+//! Allocate a pair of connected stream sockets
+//! \since 1.1.4
+PVXS_API
+void compat_socketpair(SOCKET sock[2]);
+
+//! Setup socket for non-blocking I/O
+//! \since 1.1.4
+PVXS_API
+void compat_make_socket_nonblocking(SOCKET sock);
+
+#endif // PVXS_EXPERT_API_ENABLED
+
+} // namespace pvxs
+
+#endif // PVXS_UTIL_H