pvxslibs 1.5.0__cp310-cp310-manylinux2014_x86_64.whl

pvxslibs/include/pvxs/iochooks.h

@@ -0,0 +1,170 @@
+/*
+ * 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_IOCHOOKS_H
+#define PVXS_IOCHOOKS_H
+
+#include <pvxs/version.h>
+
+#if defined(_WIN32) || defined(__CYGWIN__)
+
+#  if defined(PVXS_IOC_API_BUILDING) && defined(EPICS_BUILD_DLL)
+/* building library as dll */
+#    define PVXS_IOC_API __declspec(dllexport)
+#  elif !defined(PVXS_IOC_API_BUILDING) && defined(EPICS_CALL_DLL)
+/* calling library in dll form */
+#    define PVXS_IOC_API __declspec(dllimport)
+#  endif
+
+#elif __GNUC__ >= 4
+#  define PVXS_IOC_API __attribute__ ((visibility("default")))
+#endif
+
+#ifndef PVXS_IOC_API
+#  define PVXS_IOC_API
+#endif
+
+namespace pvxs {
+namespace server {
+class Server;
+}
+namespace ioc {
+
+/** Return the singleton Server instance which is setup
+ *  for use in an IOC process.
+ *
+ *  This Server instance is created during a registrar function,
+ *  started by the initHookAfterCaServerRunning phase of iocInit().
+ *  It is stopped and destroyed during an epicsAtExit() hook added
+ *  during an initHookAfterInitDatabase hook..
+ *
+ *  Any configuration changes via. epicsEnvSet() must be made before registrars are run
+ *  by \*_registerRecordDeviceDriver(pdbbase).
+ *
+ *  server::SharedPV and server::Source added before iocInit() will be available immediately.
+ *  Others may be added (or removed) later.
+ *
+ *  @throws std::logic_error if called before instance is created, or after instance is destroyed.
+ *
+ * @code
+ * static void myinitHook(initHookState state) {
+ *     if(state!=initHookAfterIocBuilt)
+ *         return;
+ *
+ *     server::SharedPV mypv(...);
+ *     ioc::server()
+ *           .addPV("my:pv:name", mypv);
+ * }
+ * static void myregistrar() {
+ *     initHookRegister(&myinitHook);
+ * }
+ * extern "C" {
+ *      // needs matching "registrar(myregistrar)" in .dbd
+ *     epicsExportRegistrar(myregistrar);
+ * }
+ * @endcode
+ */
+PVXS_IOC_API
+server::Server server();
+
+/**
+ * Load JSON group definition file.
+ * This function does not actually parse the given file, but adds it to the list of files to be loaded,
+ * at the appropriate time in the startup process.
+ *
+ * @param jsonFilename the json file containing the group definitions
+ * @param macros NULL, or a comma separated list of macro definitions.  eg. "KEY=VAL,OTHER=SECOND"
+ * @return 0 for success, 1 for failure
+ * @since 1.2.0
+ */
+PVXS_IOC_API
+long dbLoadGroup(const char* jsonFilename, const char* macros=nullptr);
+
+/** Call just after testdbPrepare()
+ *
+ *  Prepare QSRV for re-test.  Optional if testdbPrepare() called only once.
+ *  Required after subsequent calls.
+ *  @since 1.2.3
+ */
+PVXS_IOC_API
+void testPrepare();
+
+/** Call just before testIocShutdownOk()
+ *
+ *  Shutdown QSRV.  Only needed with Base <= 7.0.4 .
+ *  Since 7.0.4, QSRV shutdown occurs during testIocShutdownOk() .
+ *  @since 1.2.0
+ */
+PVXS_IOC_API
+void testShutdown();
+
+/** Call just after testIocShutdownOk()
+ *  @since 1.3.0
+ */
+PVXS_IOC_API
+void testAfterShutdown();
+
+/** Call just before testdbCleanup()
+ *  @since 1.3.0
+ */
+PVXS_IOC_API
+void testCleanupPrepare();
+
+#if _DOXYGEN_ || EPICS_VERSION_INT >= VERSION_INT(3, 15, 0 ,0)
+
+/** Manage Test IOC life-cycle calls.
+ *
+ *  Makes necessary calls to dbUnitTest.h API
+ *  as well as any added calls needed by PVXS components.
+ *
+ @code
+ *  MAIN(mytest) {
+ *      testPlan(0); // TODO: Set actual number of tests
+ *      pvxs::testSetup();
+ *      pvxs::logger_config_env(); // (optional)
+ *      {
+ *          TestIOC ioc; // testdbPrepare()
+ *
+ *          // mytestioc.dbd must include pvxsIoc.dbd
+ *          testdbReadDatabase("mytestioc.dbd", NULL, NULL);
+ *          mytestioc_registerRecordDeviceDriver(pdbbase);
+ *          testdbReadDatabase("sometest.db", NULL, NULL);
+ *
+ *          // tests before iocInit()
+ *
+ *          ioc.init();
+ *
+ *          // tests after iocInit()
+ *
+ *          ioc.shutdown(); // (optional) in ~TestIOC if omitted
+ *      }
+ *      {
+ *          ... repeat ...
+ *      }
+ *      epicsExitCallAtExits();
+ *      pvxs::cleanup_for_valgrind();
+ *  }
+ @endcode
+ *
+ *  @since 1.3.0
+ */
+class PVXS_IOC_API TestIOC final {
+    bool isRunning = false;
+public:
+    TestIOC();
+    ~TestIOC();
+    //! iocInit()
+    void init();
+    //! iocShutdown()
+    void shutdown();
+    //! between iocInit() and iocShutdown() ?
+    inline
+    bool running() const { return isRunning; }
+};
+
+#endif // base >= 3.15
+
+}} // namespace pvxs::ioc
+#endif // PVXS_IOCHOOKS_H

pvxslibs/include/pvxs/log.h

@@ -0,0 +1,148 @@
+/**
+ * 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_LOG_H
+#define PVXS_LOG_H
+
+#include <atomic>
+
+#include <cstddef>
+#include <stdarg.h>
+
+#include <compilerDependencies.h>
+#include <errlog.h>
+
+#include <pvxs/version.h>
+
+// MSVC specific function parameter annotation for printf() spec. validation.
+#ifndef _MSC_VER
+#  define _Printf_format_string_
+#elif defined(PVXS_API_BUILDING)
+// Internally, treat some printf() related warnings as errors.
+#  pragma warning(error:6302; error:6303; error:6306)
+#endif
+
+namespace pvxs {
+
+//! Importance of message
+enum struct Level {
+    Debug = 50,
+    Info  = 40,
+    Warn  = 30,
+    Err   = 20,
+    Crit  = 10,
+};
+
+//! A logger
+struct logger {
+    //! global name of this logger.  Need not be unique
+    const char * const name;
+    //! Current logging level.  See logger_level_set().
+    std::atomic<Level> lvl;
+    constexpr logger(const char *name) :name(name), lvl{Level(-1)} {}
+
+private:
+    PVXS_API Level init();
+public:
+
+    //! @returns true if the logger currently allows a message at level LVL.
+    inline bool test(Level lvl) {
+        Level cur = this->lvl.load(std::memory_order_relaxed);
+        if(cur==Level(-1)) cur = init();
+        return cur>=lvl;
+    }
+};
+
+namespace detail {
+
+PVXS_API
+const char *log_prep(logger& log, unsigned lvl);
+
+PVXS_API
+void _log_printf(unsigned rawlvl, _Printf_format_string_ const char *fmt, ...) EPICS_PRINTF_STYLE(2,3);
+
+PVXS_API
+void _log_printf_hex(unsigned rawlvl, _Printf_format_string_ const void *buf, size_t buflen, const char *fmt, ...) EPICS_PRINTF_STYLE(4,5);
+
+} // namespace detail
+
+//! Define a new logger global.
+//! @param VAR The (static) variable name passed to log_printf() and friends.
+//! @param NAME A name string in "A.B.C" form.
+#define DEFINE_LOGGER(VAR, NAME) static ::pvxs::logger VAR{NAME}
+
+PVXS_API
+void xerrlogHexPrintf(const void *buf, size_t buflen);
+
+/** Try to log a message at the defined level.
+ *
+ * Due to portability issues with MSVC, log formats must have at least one argument.
+ *
+ *  @code
+ *      DEFINE_LOGGER(blah, "myapp.blah");
+ *      void blahfn(int x) {
+ *          log_info_printf(blah, "blah happened with %d\n", x);
+ *  @endcode
+ */
+#define log_printf(LOGGER, LVL, FMT, ...) do{ \
+    if(auto _log_prefix = ::pvxs::detail::log_prep(LOGGER, unsigned(LVL))) \
+        ::pvxs::detail:: _log_printf(unsigned(LVL), "%s " FMT, _log_prefix, __VA_ARGS__); \
+}while(0)
+
+/* A note about MSVC (legacy) pre-processor weirdness.
+ * Care needs to be taken when expanding nested macros w/ __VA_ARGS__.
+ * Expansion of __VA_ARGS__ for the outer macro seems to result in
+ * all of the contents, including commas, being treated as a single
+ * token.  Which won't be split during expansion of the inner macro!
+ *
+ *   #define inner(FMT, ...) printf("%s " FMT, "prefix", __VA_ARGS__)
+ *   #define outer(...) inner(__VA_ARGS__)
+ *   outer("%d", 42);
+ * expands to
+ *   printf("%s " "%d", 42, "prefix");
+ *
+ * The prefix string has jumped to the end because FMT has expanded
+ * with all of the arguments of outer(...).  Surprise!
+ *
+ * Thus FMT is explicitly matched in the following "outer" macros.
+ */
+
+#define log_exc_printf(LOGGER, FMT, ...)  log_printf(LOGGER, unsigned(::pvxs::Level::Crit)|0x1000, FMT, __VA_ARGS__)
+#define log_crit_printf(LOGGER, FMT, ...)  log_printf(LOGGER, ::pvxs::Level::Crit, FMT, __VA_ARGS__)
+#define log_err_printf(LOGGER, FMT, ...)   log_printf(LOGGER, ::pvxs::Level::Err, FMT, __VA_ARGS__)
+#define log_warn_printf(LOGGER, FMT, ...)  log_printf(LOGGER, ::pvxs::Level::Warn, FMT, __VA_ARGS__)
+#define log_info_printf(LOGGER, FMT, ...)  log_printf(LOGGER, ::pvxs::Level::Info, FMT, __VA_ARGS__)
+#define log_debug_printf(LOGGER, FMT, ...) log_printf(LOGGER, ::pvxs::Level::Debug, FMT, __VA_ARGS__)
+
+#define log_hex_printf(LOGGER, LVL, BUF, BUFLEN, FMT, ...) do{ \
+    if(auto _log_prefix = ::pvxs::detail::log_prep(LOGGER, unsigned(LVL))) \
+        ::pvxs::detail:: _log_printf_hex(unsigned(LVL), BUF, BUFLEN, "%s " FMT, _log_prefix, __VA_ARGS__);\
+    }while(0)
+
+//! Set level for a specific logger
+PVXS_API void logger_level_set(const char *name, int lvl);
+inline void logger_level_set(const char *name, Level lvl) {
+    logger_level_set(name, int(lvl));
+}
+//! Remove any previously logger configurations.
+//! Does _not_ change any logger::lvl
+//! Use prior to re-applying new configuration.
+PVXS_API void logger_level_clear();
+
+/** Configure logging from environment variable **$PVXS_LOG**
+ *
+ * Value of the form "key=VAL,..."
+ *
+ * Keys may be literal logger names, or may include '*' wildcards
+ * to match multiple loggers.  eg. "pvxs.*=DEBUG" will enable
+ * all internal log messages.
+ *
+ * VAL may be one of "CRIT", "ERR", "WARN", "INFO", or "DEBUG"
+ */
+PVXS_API void logger_config_env();
+
+} // namespace pvxs
+
+#endif // PVXS_LOG_H

pvxslibs/include/pvxs/netcommon.h

@@ -0,0 +1,82 @@
+/**
+ * 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_NETCOMMON_H
+#define PVXS_NETCOMMON_H
+
+#if !defined(PVXS_CLIENT_H) && !defined(PVXS_SERVER_H)
+#  error Include <pvxs/client.h> or <pvxs/server.h>  Do not include netcommon.h directly
+#endif
+
+#include <string>
+#include <list>
+#include <memory>
+
+#include <pvxs/version.h>
+
+namespace pvxs {
+namespace impl {
+struct Report;
+struct ReportInfo;
+}
+namespace server {
+struct ClientCredentials;
+using impl::Report;
+using impl::ReportInfo;
+}
+namespace client {
+using impl::Report;
+using impl::ReportInfo;
+}
+namespace impl {
+
+#ifdef PVXS_EXPERT_API_ENABLED
+
+/** Snapshot of information about a client/server
+ *
+ * cf. pvxs::server::Server::report() and pvxs::client::Context::report()
+ *
+ * @since 0.2.0
+ */
+struct Report {
+    //! Info for a single channel (to a particular PV name on a particular server)
+    struct Channel {
+        //! Channel name.  aka. PV name
+        std::string name;
+        //! transmit and receive counters in bytes
+        size_t tx{}, rx{};
+        //! Contextual information (maybe) supplied by the Source
+        std::shared_ptr<const ReportInfo> info;
+    };
+
+    //! Info for a single connection to remote peer
+    struct Connection {
+        //! peer endpoint (eg. IPv4 address and port)
+        std::string peer;
+        //! Credentials presented by peer.  Only from Server::report()
+        std::shared_ptr<const server::ClientCredentials> credentials;
+        //! transmit and receive counters in bytes
+        size_t tx{}, rx{};
+        //! Channels currently connected through this socket
+        std::list<Channel> channels;
+    };
+
+    //! Currently open sockets
+    std::list<Connection> connections;
+};
+
+struct PVXS_API ReportInfo {
+    ReportInfo() = default;
+    ReportInfo(const ReportInfo&) = delete;
+    ReportInfo& operator=(const ReportInfo&) = delete;
+    virtual ~ReportInfo();
+};
+
+#endif
+
+} // namespace impl
+} // namespace pvxs
+
+#endif // PVXS_NETCOMMON_H

pvxslibs/include/pvxs/nt.h

@@ -0,0 +1,208 @@
+/**
+ * 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_NT_H
+#define PVXS_NT_H
+
+#include <memory>
+
+#include <pvxs/version.h>
+#include <pvxs/data.h>
+
+struct epicsTimeStamp; // epicsTime.h
+
+namespace pvxs {
+namespace nt {
+
+/** The time_t struct
+ *
+ * @code
+ * // equivalent
+ * struct time_t {
+ *     int64_t secondsPastEpoch;
+ *     int32_t nanoseconds;
+ *     int32_t userTag;
+ * };
+ * @endcode
+ * @since 0.1.4
+ */
+struct TimeStamp {
+    PVXS_API
+    TypeDef build();
+};
+
+/** The alarm_t struct
+ *
+ * @code
+ * // equivalent
+ * struct alarm_t {
+ *     int32_t severity;
+ *     int32_t status;
+ *     string message;
+ * };
+ * @endcode
+ * @since 0.1.4
+ */
+struct Alarm {
+    PVXS_API
+    TypeDef build();
+};
+
+/** A scalar, or array of scalars, and meta-data
+ *
+ * @code
+ * auto def = pvxs::nt::NTScalar{TypeCode::Float64}.build();
+ * def += {
+ *      Member(TypeCode::String, "myspecial"),
+ * };
+ * auto value = def.create(); // instantiate a Value
+ * @endcode
+ */
+struct NTScalar {
+    //! Type of the ".value" field.
+    TypeCode value;
+    //! Include display (range) meta-data
+    bool display;
+    //! Include control (range) meta-data
+    bool control;
+    //! Include alarm (range) meta-data
+    bool valueAlarm;
+    /** Include 'display.form' and 'display.precision' when 'value' is a numeric type
+     *  @pre requires display=true
+     *  @since 1.2.0
+     */
+    bool form;
+
+    constexpr
+    NTScalar(TypeCode value = TypeCode::Float64,
+             bool display = false,
+             bool control = false,
+             bool valueAlarm = false,
+             bool form = false)
+        :value(value), display(display), control(control), valueAlarm(valueAlarm), form(form)
+    {}
+
+    //! A TypeDef which can be appended
+    PVXS_API
+    TypeDef build() const;
+    //! Instantiate
+    inline Value create() const {
+        return build().create();
+    }
+};
+
+/** An enumerated value (choice from a list of strings)
+ *
+ * @since 0.1.5
+ */
+struct NTEnum {
+    //! A TypeDef which can be appended
+    PVXS_API
+    TypeDef build() const;
+    //! Instantiate
+    inline Value create() const {
+        return build().create();
+    }
+};
+
+/** Columnar data.
+ *
+ *  Unlike other NT* builders.  This create() method returns a Value
+ *  with the labels field set, and marked.  While suitable for an
+ *  initial value, repeated create() could result in re-sending
+ *  the same labels array with every update.  Users should
+ *  create() once, and then Value::cloneEmpty() or Value::unmark() for
+ *  subsequent updates.
+ *
+ *  @since 1.2.3
+ */
+struct PVXS_API NTTable final {
+
+    NTTable();
+    ~NTTable();
+
+    /** Append a column
+     *
+     *  @param code Value type of column
+     *  @param name Field name of column
+     *  @param label Display label of column.  (defaults to field name)
+     *         Only used in create().
+     *  @returns this
+     */
+    NTTable& add_column(TypeCode code,
+                        const char *name,
+                        const char *label=nullptr);
+
+    //! A TypeDef which can be appended
+    TypeDef build() const;
+    //! Instantiate.  Also populates labels list.
+    Value create() const;
+
+    struct Pvt;
+private:
+    std::shared_ptr<Pvt> pvt;
+};
+
+/** The areaDetector inspired N-dimension array/image container.
+ *
+ * @code
+ * auto def = pvxs::nt::NTNDArray{}.build();
+ * auto value = def.create(); // instantiate a Value
+ * @endcode
+ */
+struct NTNDArray {
+    //! A TypeDef which can be appended
+    PVXS_API
+    TypeDef build() const;
+    //! Instantiate
+    inline Value create() const {
+        return build().create();
+    }
+};
+
+class PVXS_API NTURI {
+    TypeDef _def;
+public:
+    NTURI(std::initializer_list<Member> mem);
+
+    //! A TypeDef which can be appended
+    inline
+    TypeDef build() const { return _def; }
+
+    //! Instantiate
+    inline Value create() const {
+        return build().create();
+    }
+
+private:
+    template<typename Iter, typename T, typename ...Args>
+    static
+    void _assign(Iter& cur, const Iter& end, const T& v, Args... args)
+    {
+        if(cur==end)
+            throw std::logic_error("Too many arguments");
+        (*cur).template from<T>(v);
+        ++cur;
+        _assign(cur, end, args...);
+    }
+    template<typename Iter>
+    static
+    void _assign(Iter& cur, const Iter& end)
+    {}
+public:
+
+    template<typename ...Args>
+    Value call(Args... args) const {
+        auto val(create());
+        auto iterable = val["query"].ichildren();
+        auto it = iterable.begin();
+        _assign(it, iterable.end(), args...);
+        return val;
+    }
+};
+
+}} // namespace pvxs::nt
+
+#endif // PVXS_NT_H