fix usage/example of Subscription::pop()

documentation/client.rst

@@ -45,6 +45,8 @@ effected named arguments.
 .. doxygenclass:: pvxs::client::Context
     :members:
 
+.. _clientgetapi:
+
 Get/Info
 ^^^^^^^^
 
@@ -56,6 +58,8 @@ which will never have any fields marked.
 .. doxygenclass:: pvxs::client::GetBuilder
     :members:
 
+.. _clientputapi:
+
 Put
 ^^^
 
@@ -74,6 +78,8 @@ to an NTEnum.
 .. doxygenclass:: pvxs::client::PutBuilder
     :members:
 
+.. _clientrpcapi:
+
 RPC
 ^^^
 
@@ -112,6 +118,8 @@ if the operation succeeded, or an exception.
 .. doxygenclass:: pvxs::client::Result
     :members:
 
+.. _clientmonapi:
+
 Monitor
 ^^^^^^^
 
@@ -128,8 +136,13 @@ The `pvxs::client::Subscription::pop` method will remove an entry from the queue
 Data updates are returned as a valid Value.
 Events/errors are thrown as exceptions.
 
+An `pvxs::client::MonitorBuilder::event` callback is only invoked when the
+Subscription queue becomes not-empty.
+It will not be called again until `pvxs::client::Subscription::pop` has returned
+an empty/invliad Value.
+
 The special exceptions `pvxs::client::Connected`, `pvxs::client::Disconnect`, and `pvxs::client::Finished`
-have specific meaning for a Subscription.
+have specific meaning when thrown by `pvxs::client::Subscription::pop`.
 
 Connected
     Depending on `pvxs::client::MonitorBuilder::maskConnected` (default true).

documentation/index.rst

@@ -33,7 +33,7 @@ Status
 This module is considered feature complete, but is not yet making releases.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
    :caption: Contents:
 
    overview

src/pvxs/client.h

@@ -235,6 +235,7 @@ public:
      *               .exec();
      * // store op until completion
      * @endcode
+     * See <a href="#get-info">Get</a> for details.
      */
     inline
     GetBuilder get(const std::string& pvname);
@@ -262,6 +263,8 @@ public:
      *               .exec();
      * // store op until completion
      * @endcode
+     *
+     * See <a href="#get-info">Info</a> for details.
      */
     inline
     GetBuilder info(const std::string& pvname);
@@ -301,6 +304,8 @@ public:
      *               .exec();
      * // store op until completion
      * @endcode
+     *
+     * See <a href="#put">Put</a> for details.
      */
     inline
     PutBuilder put(const std::string& pvname);
@@ -334,6 +339,8 @@ public:
      *               .exec();
      * // store op until completion
      * @endcode
+     *
+     * See <a href="#rpc">RPC</a> for details.
      */
     inline
     RPCBuilder rpc(const std::string& pvname, const Value& arg);
@@ -343,17 +350,24 @@ public:
      * @code
      * auto sub = ctxt.monitor("pv:name")
      *                .event([](Subscription& sub) {
-     *                    try {
-     *                        while(Value update = sub.pop()) {
+     *                    // Subscription queue becomes not empty
+     *                    while(true) {
+     *                        try {
+     *                            Value update = sub.pop();
+     *                            if(!update)
+     *                                break; // Subscription queue becomes not empty
      *                            std::cout<<update<<"\n";
+     *                        } catch(std::exception& e) {
+     *                            // may be Connected(), Disconnect(), Finished(), or RemoteError()
+     *                            std::cerr<<"Error "<<e.what()<<"\n";
      *                        }
-     *                     } catch(std::exception& e) {
-     *                         std::cerr<<"Error "<<e.what()<<"\n";
-     *                     }
+     *                    }
      *                })
      *                .exec();
      * // store op until completion
      * @endcode
+     *
+     * See <a href="#monitor">Monitor</a> for details.
      */
     inline
     MonitorBuilder monitor(const std::string& pvname);
@@ -644,8 +658,14 @@ class MonitorBuilder : public detail::CommonBuilder<MonitorBuilder, detail::Comm
 public:
     MonitorBuilder() = default;
     MonitorBuilder(const std::shared_ptr<Context::Pvt>& ctx, const std::string& name) :CommonBuilder{ctx,name} {}
-    //! Install event callback
-    //! The functor is stored in the Subscription returned by exec().
+    /** Install FIFO not-empty event callback.
+     *
+     *  This functor will be called each time the Subscription event queue becomes
+     *  not empty.  A Subscription becomes empty when Subscription::pop() returns
+     *  an empty/invalid Value.
+     *
+     *  The functor is stored in the Subscription returned by exec().
+     */
     MonitorBuilder& event(std::function<void(Subscription&)>&& cb) { _event = std::move(cb); return *this; }
     //! Include Connected exceptions in queue (default false).
     MonitorBuilder& maskConnected(bool m = true) { _maskConn = m; return *this; }

tools/monitor.cpp

@@ -108,33 +108,39 @@ int main(int argc, char *argv[])
 
             ops.push_back(ctxt.monitor(argv[n])
                           .pvRequest(request)
+                          .maskConnected(false)
+                          .maskDisconnected(false)
                           .event([&argv, n, verbose, &remaining, &done, format, arrLimit](client::Subscription& mon)
             {
-
-                try {
-                    while(auto update = mon.pop()) {
+                while(true) {
+                    try {
+                        auto update = mon.pop();
+                        if(!update) {
+                            // event queue empty
+                            log_info_printf(app, "%s POP empty\n", argv[n]);
+                            break;
+                        }
                         log_info_printf(app, "%s POP data\n", argv[n]);
                         std::cout<<argv[n]<<"\n"<<update.format()
                                    .format(format)
                                    .arrayLimit(arrLimit);
+
+                    }catch(client::Finished& conn) {
+                        log_info_printf(app, "%s POP Finished\n", argv[n]);
+                        if(verbose)
+                            std::cerr<<argv[n]<<" Finished\n";
+                        if(remaining.fetch_sub(1)==1)
+                            done.signal();
+
+                    }catch(client::Connected& conn) {
+                        std::cerr<<argv[n]<<" Connected to "<<conn.peerName<<"\n";
+
+                    }catch(client::Disconnect& conn) {
+                        std::cerr<<argv[n]<<" Disconnected\n";
+
+                    }catch(std::exception& err) {
+                        std::cerr<<argv[n]<<" Error "<<typeid (err).name()<<" : "<<err.what()<<"\n";
                     }
-                    log_info_printf(app, "%s POP empty\n", argv[n]);
-
-                }catch(client::Finished& conn) {
-                    log_info_printf(app, "%s POP Finished\n", argv[n]);
-                    if(verbose)
-                        std::cerr<<argv[n]<<" Finished\n";
-                    if(remaining.fetch_sub(1)==1)
-                        done.signal();
-
-                }catch(client::Connected& conn) {
-                    std::cerr<<argv[n]<<" Connected to "<<conn.peerName<<"\n";
-
-                }catch(client::Disconnect& conn) {
-                    std::cerr<<argv[n]<<" Disconnected\n";
-
-                }catch(std::exception& err) {
-                    std::cerr<<argv[n]<<" Error "<<typeid (err).name()<<" : "<<err.what()<<"\n";
                 }
 
             }).exec());