pvxslibs 1.5.0__cp310-cp310-manylinux2014_x86_64.whl

pvxslibs/include/pvxs/sharedpv.h

@@ -0,0 +1,121 @@
+/**
+ * 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_SHAREDPV_H
+#define PVXS_SHAREDPV_H
+
+#include <functional>
+#include <memory>
+#include <map>
+
+#include <pvxs/version.h>
+#include "srvcommon.h"
+
+namespace pvxs {
+class Value;
+
+namespace server {
+
+struct ChannelControl;
+struct Source;
+
+/** A SharedPV is a single data value which may be accessed by multiple clients through a Server.
+ *
+ * On creation a SharedPV has no associated data structure, or data type.
+ * This is set by calling open() to provide a data type, and initial data values.
+ * Subsequent calls to post() will update this data structure (and send notifications
+ * to subscribing clients).
+ *
+ * A later call to close() will force disconnect all clients, and discard the data value and type.
+ * A further call to open() sets a new data value, which may be of a different data type.
+ *
+ * The onPut() and onRPC() methods attach functors which will be called each time a Put or RPC
+ * operation is executed by a client.
+ */
+struct PVXS_API SharedPV
+{
+    //! Create a new SharedPV with a Put handler which post() s any client provided Value.
+    static SharedPV buildMailbox();
+    //! Create a new SharedPV with a Put handler which rejects any client provided Value.
+    static SharedPV buildReadonly();
+
+    ~SharedPV();
+
+    inline explicit operator bool() const { return !!impl; }
+
+    //! Attach this SharedPV with a new client channel.
+    //! Not necessary when using StaticSource.
+    //! eg. could call from Source::onCreate()
+    void attach(std::unique_ptr<ChannelControl>&& op);
+
+    //! Callback when the number of attach()d clients becomes non-zero.
+    void onFirstConnect(std::function<void(SharedPV&)>&& fn);
+    //! Callback when the number of attach()d clients becomes zero.
+    void onLastDisconnect(std::function<void(SharedPV&)>&& fn);
+    //! Callback when a client executes a new Put operation.
+    void onPut(std::function<void(SharedPV&, std::unique_ptr<ExecOp>&&, Value&&)>&& fn);
+    //! Callback when a client executes an RPC operation.
+    //! @note RPC operations are allowed even when the SharedPV is not opened (isOpen()==false)
+    void onRPC(std::function<void(SharedPV&, std::unique_ptr<ExecOp>&&, Value&&)>&& fn);
+
+    /** Provide data type and initial value.  Allows clients to begin connecting.
+     * @pre !isOpen()
+     * @param initial Defines data type, and initial value
+     */
+    void open(const Value& initial);
+    //! Test whether open() has been called w/o matching close()
+    bool isOpen() const;
+    //! Reverse the effects of open() and force disconnect any remaining clients.
+    void close();
+
+    //! Update the internal data value, and dispatch subscription updates to any clients.
+    void post(const Value& val);
+    //! query the internal data value and update the provided Value.
+    void fetch(Value& val) const;
+    //! Return a (shallow) copy of the internal data value
+    Value fetch() const;
+
+    struct Impl;
+private:
+    std::shared_ptr<Impl> impl;
+};
+
+/** Allow clients to find (through a Server) SharedPV instances by name.
+ *
+ * A single PV name may only be added once to a StaticSource.
+ * However, a single SharedPV may be added multiple times with different PV names.
+ */
+struct PVXS_API StaticSource
+{
+    static StaticSource build();
+
+    ~StaticSource();
+
+    inline explicit operator bool() const { return !!impl; }
+
+    //! Fetch the Source interface, which may be used with Server::addSource()
+    std::shared_ptr<Source> source() const;
+
+    //! call SharedPV::close() on all PVs
+    void close();
+
+    //! Add a new name through which a SharedPV may be addressed.
+    StaticSource& add(const std::string& name, const SharedPV& pv);
+    //! Remove a single name
+    StaticSource& remove(const std::string& name);
+
+    typedef std::map<std::string, SharedPV> list_t;
+    list_t list() const;
+
+    struct Impl;
+private:
+    std::shared_ptr<Impl> impl;
+};
+
+} // namespace server
+} // namespace pvxs
+
+#endif // PVXS_SHAREDPV_H

pvxslibs/include/pvxs/source.h

@@ -0,0 +1,290 @@
+/**
+ * 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_SOURCE_H
+#define PVXS_SOURCE_H
+
+#include <string>
+#include <functional>
+
+#include <pvxs/data.h>
+#include <pvxs/server.h>
+#include "srvcommon.h"
+
+namespace pvxs {
+namespace impl {
+struct ServerConn;
+}
+namespace server {
+
+//! Handle when an operation is being setup
+struct PVXS_API ConnectOp : public OpBase, public RemoteLogger {
+protected:
+    Value _pvRequest;
+public:
+    const Value& pvRequest() const { return _pvRequest; }
+
+    //! For GET_FIELD, GET, or PUT.  Inform peer of our data-type.
+    //! @throws std::runtime_error if the client pvRequest() field mask does not select any fields of prototype.
+    virtual void connect(const Value& prototype) =0;
+    //! Indicate that this operation can not be setup
+    //! @since 1.2.3 Does not block
+    virtual void error(const std::string& msg) =0;
+
+    ConnectOp(const std::string& name,
+           const std::shared_ptr<const ClientCredentials>& cred, op_t op,
+           const Value& pvRequest)
+        :OpBase(name, cred, op)
+        ,_pvRequest(pvRequest)
+    {}
+    virtual ~ConnectOp();
+
+    //! Handler invoked when a peer executes a request for data on a GET o PUT
+    virtual void onGet(std::function<void(std::unique_ptr<ExecOp>&&)>&& fn) =0;
+    //! Handler invoked when a peer executes a send data on a PUT
+    virtual void onPut(std::function<void(std::unique_ptr<ExecOp>&&, Value&&)>&& fn) =0;
+    //! Callback when the underlying channel closes
+    virtual void onClose(std::function<void(const std::string&)>&&) =0;
+};
+
+//! Information about a running monitor
+struct MonitorStat {
+    //! Number of available elements in the output flow window.
+    size_t window=0;
+
+    //! Number of un-sent updates in the local queue.  Doesn't include updates
+    //! serialized and in the TX buffer.
+    size_t nQueue=0;
+    //! Highest value of nQueue seen
+    //! @since 1.1.0
+    size_t maxQueue=0;
+    //! Negotiated limit on nQueue
+    size_t limitQueue=0;
+    //! Number of updates squashed during post() calls
+    //! @since 1.2.0
+    size_t nSquash=0;
+
+    bool running=false;
+    bool finished=false;
+    bool pipeline=false;
+};
+
+//! Handle for active subscription
+struct PVXS_API MonitorControlOp : public OpBase, public RemoteLogger {
+    MonitorControlOp(const std::string& name,
+           const std::shared_ptr<const ClientCredentials>& cred, op_t op)
+        :OpBase(name, cred, op)
+    {}
+    virtual ~MonitorControlOp();
+
+protected:
+    virtual bool doPost(const Value& val, bool maybe, bool force) =0;
+public:
+
+    //! Add a new entry to the monitor queue.
+    //! If nFree()<=0 the output queue will be over-filled with this element.
+    //! Returns @code nFree()>0u @endcode
+    //! @warning Caller must not modify the Value
+    bool forcePost(const Value& val) {
+        return doPost(val, false, true);
+    }
+
+    //! Add a new entry to the monitor queue.
+    //! If nFree()<=0 this element will be "squashed" to the last element in the queue
+    //! Returns @code nFree()>0u @endcode
+    //! @warning Caller must not modify the Value
+    bool post(const Value& val) {
+        return doPost(val, false, false);
+    }
+
+    //! Add a new entry to the monitor queue.
+    //! If nFree()<=0 return false and take no other action
+    //! Returns @code nFree()>0u @endcode
+    //! @warning Caller must not modify the Value
+    bool tryPost(const Value& val) {
+        return doPost(val, true, false);
+    }
+
+    //! Signal to subscriber that this subscription will not yield any further events.
+    //! This is not an error.  Client should not retry.
+    void finish() {
+        doPost(Value(), false, true);
+    }
+
+    //! Poll information and statistics for this subscription.
+    //! @since 1.1.0 Added 'reset' argument.
+    virtual void stats(MonitorStat&, bool reset=false) const =0;
+
+    /** Set flow control levels.
+     *
+     *  Flow control operations against an outbound "window" size, which is the number of updates which may
+     *  be sent before a client ack. must be received.  By default both high and low levels are zero.
+     *
+     *  onLowMark callback is not currently implemented and the 'low' level is not used.
+     *  onHighMark callback will be invoked when a client ack. is received and the window size is above (>) 'high'.
+     */
+    virtual void setWatermarks(size_t low, size_t high) =0;
+
+    //! Callback when client resumes/pauses updates
+    virtual void onStart(std::function<void(bool start)>&&) =0;
+    virtual void onHighMark(std::function<void()>&&) =0;
+    virtual void onLowMark(std::function<void()>&&) =0;
+};
+
+//! Handle for subscription which is being setup
+struct PVXS_API MonitorSetupOp : public OpBase, public RemoteLogger {
+protected:
+    Value _pvRequest;
+public:
+    const Value& pvRequest() const { return _pvRequest; }
+
+    //! Inform peer of our data-type and acquire control of subscription queue.
+    //! The queue is initially stopped.
+    //! @throws std::runtime_error if the client pvRequest() field mask does not select any fields of prototype.
+    virtual std::unique_ptr<MonitorControlOp> connect(const Value& prototype) =0;
+
+    //! Indicate that this operation can not be setup
+    //! @since 1.2.3 Does not block
+    virtual void error(const std::string& msg) =0;
+
+    MonitorSetupOp(const std::string& name,
+           const std::shared_ptr<const ClientCredentials>& cred, op_t op,
+           const Value& pvRequest)
+        :OpBase(name, cred, op)
+        ,_pvRequest(pvRequest)
+    {}
+    virtual ~MonitorSetupOp();
+
+    virtual void onClose(std::function<void(const std::string&)>&&) =0;
+};
+
+/** Manipulate an active Channel, and any in-progress Operations through it.
+ *
+ */
+struct PVXS_API ChannelControl : public OpBase {
+    ChannelControl(const std::string& name,
+           const std::shared_ptr<const ClientCredentials>& cred, op_t op)
+        :OpBase(name, cred, op)
+    {}
+    virtual ~ChannelControl() =0;
+
+    //! Invoked when a new GET or PUT Operation is requested through this Channel
+    virtual void onOp(std::function<void(std::unique_ptr<ConnectOp>&&)>&& ) =0;
+    //! Invoked when the peer executes an RPC
+    virtual void onRPC(std::function<void(std::unique_ptr<ExecOp>&&, Value&&)>&& fn)=0;
+    //! Invoked when the peer create a new subscription
+    virtual void onSubscribe(std::function<void(std::unique_ptr<MonitorSetupOp>&&)>&&)=0;
+
+    //! Callback when the channel closes (eg. peer disconnect)
+    virtual void onClose(std::function<void(const std::string&)>&&) =0;
+
+    //! Force disconnection
+    //! If called from outside a handler method, blocks until in-progress Handler methods have returned.
+    //! Reference to currently attached Handler is released.
+    virtual void close() =0;
+
+    // TODO: signal Rights?
+
+#ifdef PVXS_EXPERT_API_ENABLED
+    // Store info struct which will be returned with Report::Channel
+    inline void updateInfo(const std::shared_ptr<const ReportInfo>& info)
+    { this->_updateInfo(info); }
+#endif
+private:
+    virtual void _updateInfo(const std::shared_ptr<const ReportInfo>& info) =0;
+};
+
+/** Interface through which a Server discovers Channel names and
+ *  associates with Handler instances.
+ *
+ *  User code will sub-class.
+ */
+struct PVXS_API Source {
+    virtual ~Source() =0;
+
+    /** An iterable of names (Name) being sought.
+     *
+     * @code
+     *   virtual void onSearch(Search& search) {
+     *       for(auto& op : search) {
+     *           if(strcmp(op.name(), "magic")==0)
+     *               op.claim();
+     *       }
+     *   }
+     * @endcode
+     */
+    struct Search {
+        //! A single name being searched
+        class Name {
+            const char* _name = nullptr;
+            bool _claim = false;
+            friend struct Server::Pvt;
+            friend struct impl::ServerConn;
+        public:
+            //! The Channel name
+            inline const char* name() const { return _name; }
+            //! The caller claims to be able to respond to an onCreate() for this name.
+            inline void claim() { _claim = true; }
+            // TODO claim w/ redirect
+        };
+    private:
+        typedef std::vector<Name> _names_t;
+        _names_t _names;
+        char _src[80]; // >= INET6_ADDRSTRLEN+1
+        friend struct Server::Pvt;
+        friend struct impl::ServerConn;
+    public:
+        typedef Name value_type;
+        typedef _names_t::iterator iterator;
+
+        //! Number of names
+        inline size_t size() const { return _names.size(); }
+        //! Begin iterator of Name instances
+        iterator begin() { return _names.begin(); }
+        //! End iterator of Name instances
+        iterator end() { return _names.end(); }
+        //! The Client endpoint address
+        const char* source() const { return _src; }
+    };
+    /** Called each time a client polls for the existence of some Channel names (Search::Name).
+     *
+     * A Source may only Search::Name::claim() a Channel name if it is prepared to
+     * immediately accept an onCreate() call for that Channel name.
+     * In other situations it should wait for the client to retry.
+     */
+    virtual void onSearch(Search& op) =0;
+
+    /** A Client is attempting to open a connection to a certain Channel.
+     *
+     *  This Channel name may not be one which was seen or claimed by onSearch().
+     *
+     *  Callee may:
+     *
+     *  - Do nothing, allowing some other Source with higher/later order a chance to create.
+     *  - Call ChannelControl::close() to explicitly reject the channel.
+     *  - std::move() the op and/or call ChannelControl::setHandler() to accept the new channel.
+     *  - std::move() the op and allow ChannelControl to be destroyed to implicitly reject the channel.
+     */
+    virtual void onCreate(std::unique_ptr<ChannelControl>&& op) =0;
+
+    //! List of channel names
+    struct List {
+        //! The list
+        std::shared_ptr<const std::set<std::string>> names;
+        //! True if the list may change at some future time.
+        bool dynamic;
+    };
+
+    /** A Client is requesting a list of Channel names which we may claim.
+     */
+    virtual List onList();
+
+    //! Print status information.
+    virtual void show(std::ostream& strm);
+};
+
+}} // namespace pvxs::server
+
+#endif // PVXS_SOURCE_H

pvxslibs/include/pvxs/srvcommon.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_SRVCOMMON_H
+#define PVXS_SRVCOMMON_H
+
+#if !defined(PVXS_SHAREDPV_H) && !defined(PVXS_SOURCE_H)
+#  error Include <pvxs/sharedpv.h> or <pvxs/source.h>  Do not include srvcommon.h directly
+#endif
+
+#include <iosfwd>
+#include <string>
+#include <set>
+#include <functional>
+
+#include <pvxs/version.h>
+#include <pvxs/util.h>
+#include <pvxs/data.h>
+
+namespace pvxs {
+enum struct Level;
+namespace server {
+
+/** Credentials presented by a client.
+ *
+ * Primarily a way of presenting peer address and a remote user account name.
+ * The method gives the authentication sub-protocol used and is presently one of:
+ *
+ * - "ca" - Client provided account name.
+ * - "anonymous" - Client provided no credentials.  account will also be "anonymous".
+ *
+ * @since 0.2.0
+ */
+struct PVXS_API ClientCredentials {
+    //! Peer address (eg. numeric IPv4)
+    std::string peer;
+    //! The local interface address (eg. numeric IPv4) through which this client is connected.
+    //! May be a wildcard address (eg. 0.0.0.0) if the receiving socket is so bound.
+    std::string iface;
+    //! Authentication "method"
+    std::string method;
+    //! Remote user account name.  Meaning depends upon method.
+    std::string account;
+    //! (Copy of) Credentials blob as presented by the client.
+    Value raw;
+    /** Lookup (locally) roles associated with the account.
+     *
+     * On *nix targets this is the list of primary and secondary groups
+     * in with the account is a member.
+     * On Windows targets this returns the list of local groups for the account.
+     * On other targets, an empty list is returned.
+     */
+    std::set<std::string> roles() const;
+};
+
+PVXS_API
+std::ostream& operator<<(std::ostream&, const ClientCredentials&);
+
+//! Base for all operation classes
+struct PVXS_API OpBase {
+    enum op_t {
+        None, //!< invalid
+        Info, //!< A GET_FIELD operation
+        Get,  //!< A GET operation
+        Put,  //!< A PUT operation
+        RPC,  //!< A RPC operation
+    };
+protected:
+    const std::string _name;
+    const std::shared_ptr<const ClientCredentials> _cred;
+    const op_t _op;
+public:
+    //! The Client endpoint address in "X.X.X.X:Y" format.
+    const std::string& peerName() const { return _cred->peer; }
+    //! The Channel name
+    const std::string& name() const { return _name; }
+    //! Client credentials.  Never NULL.
+    //! @since 0.2.0
+    const std::shared_ptr<const ClientCredentials>& credentials() const { return _cred; }
+    //! Operation type
+    op_t op() const { return _op; }
+
+    OpBase(const std::string& name,
+           const std::shared_ptr<const ClientCredentials>& cred, op_t op)
+        :_name(name)
+        ,_cred(cred)
+        ,_op(op)
+    {}
+    OpBase(const OpBase&) = delete;
+    OpBase& operator=(const OpBase&) = delete;
+    virtual ~OpBase() =0;
+};
+//! Log to remote peer
+//! @since 1.4.0
+struct PVXS_API RemoteLogger {
+    virtual ~RemoteLogger() =0;
+
+    //! Request log message to peer
+    //! @since 1.4.0
+    virtual void logRemote(Level lvl, const std::string& msg) =0;
+};
+
+//! Handle when an operation is being executed
+struct PVXS_API ExecOp : public OpBase, public RemoteLogger {
+    //! Issue a reply without data.  (eg. to complete a PUT)
+    virtual void reply() =0;
+    //! Issue a reply with data.  For a GET or RPC  (or PUT/Get)
+    virtual void reply(const Value& val) =0;
+    //! Indicate the request has resulted in an error.
+    //! @since 1.2.3 Does not block
+    virtual void error(const std::string& msg) =0;
+
+    //! Callback invoked if the peer cancels the operation before reply() or error() is called.
+    virtual void onCancel(std::function<void()>&&) =0;
+
+protected:
+    const Value _pvRequest;
+public:
+    //! Access to pvRequest blob
+    //! @since 0.2.0
+    const Value& pvRequest() const { return _pvRequest; }
+
+    ExecOp(const std::string& name,
+           const std::shared_ptr<const ClientCredentials>& cred, op_t op,
+           const Value& pvRequest)
+        :OpBase(name, cred, op)
+        ,_pvRequest(pvRequest)
+    {}
+    ExecOp(const ExecOp&) = delete;
+    ExecOp& operator=(const ExecOp&) = delete;
+    virtual ~ExecOp();
+
+#ifdef PVXS_EXPERT_API_ENABLED
+    //! Create/start timer.  cb runs on worker associated with Channel of this Operation.
+    //! @since 0.2.0
+    Timer timerOneShot(double delay, std::function<void()>&& cb) {
+        return _timerOneShot(delay, std::move(cb));
+    }
+#endif // PVXS_EXPERT_API_ENABLED
+private:
+    virtual Timer _timerOneShot(double delay, std::function<void()>&& cb) =0;
+};
+
+}} // namespace pvxs::server
+
+#endif // PVXS_SRVCOMMON_H