From 9ef060a2f277dd0c4b58486d98f329db503a8925 Mon Sep 17 00:00:00 2001 From: Michael Davidsaver Date: Wed, 24 May 2017 16:31:26 -0400 Subject: [PATCH] remove deprecated monitorPlugin.h --- documentation/RELEASE_NOTES.md | 8 + documentation/TODO.md | 6 - documentation/copyandmonitor.html | 298 ------------------------------ documentation/pvDataCPP.html | 298 ------------------------------ 4 files changed, 8 insertions(+), 602 deletions(-) diff --git a/documentation/RELEASE_NOTES.md b/documentation/RELEASE_NOTES.md index 17784b7..ce6d3ef 100644 --- a/documentation/RELEASE_NOTES.md +++ b/documentation/RELEASE_NOTES.md @@ -1,3 +1,11 @@ +Release 6.0 +=========== + +* Deprecated monitorPlugin.h is removed. +* Deprecate Queue, MessageQueue, Executor, and TimeFunction. Will be removed in 7.0. +* FieldBuilder allow Structure defintion to be changed/appended +* Add createRequest() function. Simpler alternative to CreateRequest class. + Release 5.0 =========== diff --git a/documentation/TODO.md b/documentation/TODO.md index c905c52..67c9314 100644 --- a/documentation/TODO.md +++ b/documentation/TODO.md @@ -12,9 +12,3 @@ valueAlarm normativeTypes.html describes valueAlarm only for a value field that has type double. The implementation also supports all the numeric scalar types. - -monitorPlugin -------------- - -A debate is on-going about what semantics should be. - diff --git a/documentation/copyandmonitor.html b/documentation/copyandmonitor.html index 3b25eb1..33286d3 100644 --- a/documentation/copyandmonitor.html +++ b/documentation/copyandmonitor.html @@ -85,11 +85,6 @@ Monitor provides: monitor. It, together with the queue facility, provides support for monitor queues. -
monitorPlugin
-
This is support for implementing monitor plugins. - A monitor plugin can be developed that has no knowledge - of pvAccess but only pvData. -

@@ -267,8 +262,6 @@ where
monitor
Used by code that implements pvAccess monitors.
-
monitorPlugin
-
Code that provides special semantics for monitors.

monitor

@@ -383,297 +376,6 @@ It has the methods:

-

monitorPlugin

-
-class MonitorPlugin
-{
-    virtual std::string const & getName() = 0;
-    virtual bool causeMonitor(
-        PVFieldPtr const &pvField,
-        PVStructurePtr const &pvTop,
-        MonitorElementPtr const &monitorElement) = 0;
-    virtual void monitorDone(
-        MonitorElementPtr const &monitorElement);
-    virtual void startMonitoring();
-    virtual void stopMonitoring();
-    virtual void beginGroupPut();
-    virtual void endGroupPut();
-};
-
-class MonitorPluginCreator
-{
-    virtual MonitorPluginPtr create(
-        FieldConstPtr const &field,
-        StructureConstPtr const &top,
-        PVStructurePtr const &pvFieldOptions) = 0;
-     virtual std::string const & getName() = 0;
-}
-
-class MonitorPluginManager
-{
-    static MonitorPluginManagerPtr get();
-    bool addPlugin(
-         std::string const &pluginName,
-         MonitorPluginCreatorPtr const &creator);
-    MonitorPluginCreatorPtr findPlugin(std::string const &pluginName);
-    void showNames();
-};
-
-
-

MonitorPlugin

-

MonitorPlugin must be implemented by the plugin implementation. -It has methods:

-
-
getName
-
Get the name of the plugin.
-
causeMonitor
-
- Should the value of pvField cause a monitor to be raised. - pvField and pvTop are fields in the top level structure - being monitored. monitorElement has the top level structure - for the copy. - The implementation should not modify the fields in the structure - being monitored. - Called with pvTop locked. -
-
monitorDone
-
- Called just before monitorElement will be given to client. - The plugin can change the data values and bitSets in monitorElement. - Called with pvTop unlocked. -
-
startMonitoring
-
- Monitoring is starting. -
-
stopMonitoring
-
- Monitoring is being stopped. -
-
beginGroupPut
-
- A set of puts is starting. - Called with pvTop locked. -
-
endGroupPut
-
- The set of puts is complete. - Called with pvTop locked. -
-
-

MonitorPluginCreator

-

MonitorPluginCreator must also be implemented by the plugin implementation. -It is called for each field instance that has options of the from -[plugin=name...] where name is the name of the plugin. -Note that a plugin instance will belong to a single client. -It has methods:

-
-
getName
-
Get the name of the plugin.
-
create
-
- Create a new plugin instance. - If the arguments are not compatible with the plugin a NULL shared pointer is - returned.
- pvFieldOptions is - a structure with a set of PVString subfields that specify name,value - pairs. name is the subField name and value is the subField value.
- Note that a plugin will below to a single client. -
-
-

MonitorPluginManager

-

MonitorPluginManager has the methods:

-
-
get
-
- MonitorPluginManager is a singleton. - The first call to get will create the single instance. - Further calls will return the single instance. -
-
addPlugin
-
- Add a new plugin. -
-
findPlugin
-
- Find a plugin. A NULL shared pointer is returned if it has not been added. -
-
showNames
-
- Show the names of all plugins that have been added. -
-
-

NOTE: -Should the method causeMonitor -have arguments pvField and pvTop -be defined so that they can not be modified. -This would be possible if the following was defined: -

-typedef std::tr1::shared_ptr<const PVField> PVFieldConstPtr;
-typedef std::tr1::shared_ptr<const PVStructure> PVStructureConstPtr;
-
-then the definition for causeMonitor could be: -
-virtual bool causeMonitor(
-        PVFieldConstPtr const &pvField,
-        PVStructureConstPtr const &pvTop,
-        MonitorElementPtr const &monitorElement) = 0;
-
-But just adding these definitions is not sufficient. -In addition all methods defined in pvDataCPP must be checked. -In particular many of the methods in Convert must have -their arguments modified. -Big job. -

-

monitorPlugin example

-

Example Plugin Overview

-

This section describes an example plugin that:

-
    -
  • Only raises monitors when a field changes value.
    - If no plugin is provided - the default is to raise a monitor when a put is issued to a field.
    • -
  • Optionally a change will not raise a monitor.
    - The change will, however, - appear if a put to another field raise a monitor.
    • -
-

As an example assume that a channel provided by pvAccess has a top level structure -that represents a power supply.

-
-structure powerSupply
-    structure alarm
-    structure timeStamp
-    structure power
-       double value
-       structure alarm
-       structure display
-    structure voltage
-       double value
-       structure alarm
-       structure display
-    structure current
-       double value
-       structure alarm
-       structure display
-
-

A pvAccess client wants to create a monitor on the powerSupply as follows: -The client wants a top level structure that looks like: -

-structure powerSupply
-    structure alarm
-    structure timeStamp
-    structure power
-       double value
-    structure voltage
-       double value
-    structure current
-       double value
-
-In addition the client wants monitors to occur only when one of the monitored -fields changes value but not just because a put occured. -Also if only the timeStamp changes value then that should not cause a monitor. -

-

The example monitor plugin implements the semantics the -client wants. It can be attached to any field via the following options: -

-[plugin=onChange,raiseMonitor=value]
-
-This plugin will trigger a monitor for the field only if the field changes -value. In addition value equals false means do not raise a monitor -for changes to this field. -But if a change to another field does cause a monitor the change to this field -will be passed to the client. -

-

-Assume that the client has already connected to the channel. -The client can then issue the commands:

-
-std::string request("field(alarm[plugin=onChange]");
-request += ",timeStamp[plugin=onChange,raiseMonitor=false]";
-request += ",power.value[plugin=onChange";
-request += ",voltage.value[plugin=onChange";
-request += ",current.value[plugin=onChange";
-
-PVStructurePtr pvRequest = createRequest->createRequest(request);
-
-MonitorPtr monitor = channel->createMonitor(monitorRequester,pvRequest);
-
-

Example Plugin Code

-

The header file to create the example has the definition:

-
-class ExampleMonitorPlugin{
-public:
-    static void create();
-};
-
-

The implementation is:

-
-class OnChangePlugin : public MonitorPlugin
-{
-public:
-    virtual ~OnChangePlugin(){}
-    OnChangePlugin() {}
-    bool init(
-        FieldConstPtr const &field,
-        StructureConstPtr const &top,
-        PVStructurePtr const &pvFieldOptions)
-   {
-        pvField = getPVDataCreate()->createPVField(field);
-        raiseMonitor = true;
-        if(pvFieldOptions!=NULL) {
-            PVStringPtr pvString =
-                pvFieldOptions->getSubField<PVString>("raiseMonitor");
-                if(pvString!=NULL) {
-                    std::string value = pvString->get();
-                    if(value.compare("false")==0) raiseMonitor = false;
-                }
-        }
-        return true;
-   }
-   virtual std::string &getName(){return pluginName;}
-   virtual bool causeMonitor(
-        PVFieldPtr const &pvNew,
-        PVStructurePtr const &pvTop,
-        MonitorElementPtr const &monitorElement)
-   {
-       bool isSame = convert->equals(pvNew,pvField);
-       if(isSame) return false;
-       convert->copy(pvNew,pvField);
-       return raiseMonitor;
-   }
-private:
-   PVFieldPtr pvField;
-   bool raiseMonitor;
-};
-class OnChangePluginCreator : public MonitorPluginCreator
-{
-public:
-    virtual std::string &getName(){return pluginName;}
-    virtual MonitorPluginPtr create(
-        FieldConstPtr const &field,
-        StructureConstPtr const &top,
-        PVStructurePtr const &pvFieldOptions)
-   {
-       OnChangePluginPtr plugin(new OnChangePlugin());
-       bool result = plugin->init(field,top,pvFieldOptions);
-       if(!result) return MonitorPluginPtr();
-       return plugin;
-   }
-
-};
-
-void ExampleMonitorPlugin::create()
-{
-    static OnChangePluginCreatorPtr plugin;
-    static Mutex mutex;
-    Lock xx(mutex);
-    if(plugin==NULL) {
-        plugin = OnChangePluginCreatorPtr(new OnChangePluginCreator());
-        MonitorPluginManager::get()->addPlugin(pluginName,plugin);
-    }
-}
-
- - diff --git a/documentation/pvDataCPP.html b/documentation/pvDataCPP.html index 6e651a1..bcc3207 100644 --- a/documentation/pvDataCPP.html +++ b/documentation/pvDataCPP.html @@ -4875,11 +4875,6 @@ Monitor provides: monitor. It, together with the queue facility, provides support for monitor queues. -
monitorPlugin
-
This is support for implementing monitor plugins. - A monitor plugin can be developed that has no knowledge - of pvAccess but only pvData. -

src/copy

copy provides the ability to create a structure that has @@ -5057,8 +5052,6 @@ where

monitor
Used by code that implements pvAccess monitors.
-
monitorPlugin
-
Code that provides special semantics for monitors.

monitor

@@ -5172,297 +5165,6 @@ It has the methods:
-

monitorPlugin

-
-class MonitorPlugin
-{
-    virtual std::string const & getName() = 0;
-    virtual bool causeMonitor(
-        PVFieldPtr const &pvField,
-        PVStructurePtr const &pvTop,
-        MonitorElementPtr const &monitorElement) = 0;
-    virtual void monitorDone(
-        MonitorElementPtr const &monitorElement);
-    virtual void startMonitoring();
-    virtual void stopMonitoring();
-    virtual void beginGroupPut();
-    virtual void endGroupPut();
-};
-
-class MonitorPluginCreator
-{
-    virtual MonitorPluginPtr create(
-        FieldConstPtr const &field,
-        StructureConstPtr const &top,
-        PVStructurePtr const &pvFieldOptions) = 0;
-     virtual std::string const & getName() = 0;
-}
-
-class MonitorPluginManager
-{
-    static MonitorPluginManagerPtr get();
-    bool addPlugin(
-         std::string const &pluginName,
-         MonitorPluginCreatorPtr const &creator);
-    MonitorPluginCreatorPtr findPlugin(std::string const &pluginName);
-    void showNames();
-};
-
-
-

MonitorPlugin

-

MonitorPlugin must be implemented by the plugin implementation. -It has methods:

-
-
getName
-
Get the name of the plugin.
-
causeMonitor
-
- Should the value of pvField cause a monitor to be raised. - pvField and pvTop are fields in the top level structure - being monitored. monitorElement has the top level structure - for the copy
. - The implementation should not modify the fields in the structure - being monitored. - Called with pvTop locked. -
-
monitorDone
-
- Called just before monitorElement will be given to client. - The plugin can change the data values and bitSets in monitorElement. - Called with pvTop unlocked. -
-
startMonitoring
-
- Monitoring is starting. -
-
stopMonitoring
-
- Monitoring is being stopped. -
-
beginGroupPut
-
- A set of puts is starting. - Called with pvTop locked. -
-
endGroupPut
-
- The set of puts is complete. - Called with pvTop locked. -
-
-

MonitorPluginCreator

-

MonitorPluginCreator must also be implemented by the plugin implementation. -It is called for each field instance that has options of the from -[plugin=name...] where name is the name of the plugin. -Note that a plugin instance will belong to a single client. -It has methods:

-
-
getName
-
Get the name of the plugin.
-
create
-
- Create a new plugin instance. - If the arguments are not compatible with the plugin a NULL shared pointer is - returned.
- pvFieldOptions is - a structure with a set of PVString subfields that specify name,value - pairs. name is the subField name and value is the subField value.
- Note that a plugin will below to a single client. -
-
-

MonitorPluginManager

-

MonitorPluginManager has the methods:

-
-
get
-
- MonitorPluginManager is a singleton. - The first call to get will create the single instance. - Further calls will return the single instance. -
-
addPlugin
-
- Add a new plugin. -
-
findPlugin
-
- Find a plugin. A NULL shared pointer is returned if it has not been added. -
-
showNames
-
- Show the names of all plugins that have been added. -
-
-

NOTE: -Should the method causeMonitor -have arguments pvField and pvTop -be defined so that they can not be modified. -This would be possible if the following was defined: -

-
-typedef std::tr1::shared_ptr<const PVField> PVFieldConstPtr;
-typedef std::tr1::shared_ptr<const PVStructure> PVStructureConstPtr;
-
-then the definition for causeMonitor could be: -
-virtual bool causeMonitor(
-        PVFieldConstPtr const &pvField,
-        PVStructureConstPtr const &pvTop,
-        MonitorElementPtr const &monitorElement) = 0;
-
-But just adding these definitions is not sufficient. -In addition all methods defined in pvDataCPP must be checked. -In particular many of the methods in Convert must have -their arguments modified. -Big job. -

monitorPlugin example

-

Example Plugin Overview

-

This section describes an example plugin that:

- -

As an example assume that a channel provided by pvAccess has a top level structure -that represents a power supply.

-
-structure powerSupply
-    structure alarm
-    structure timeStamp
-    structure power
-       double value
-       structure alarm
-       structure display
-    structure voltage
-       double value
-       structure alarm
-       structure display
-    structure current
-       double value
-       structure alarm
-       structure display
-
-

A pvAccess client wants to create a monitor on the powerSupply as follows: -The client wants a top level structure that looks like: -

-
-structure powerSupply
-    structure alarm
-    structure timeStamp
-    structure power
-       double value
-    structure voltage
-       double value
-    structure current
-       double value
-
-In addition the client wants monitors to occur only when one of the monitored -fields changes value but not just because a put occurred. -Also if only the timeStamp changes value then that should not cause a monitor. -

The example monitor plugin implements the semantics the -client wants. It can be attached to any field via the following options: -

-
-[plugin=onChange,raiseMonitor=value]
-
-This plugin will trigger a monitor for the field only if the field changes -value. In addition value equals false means do not raise a monitor -for changes to this field. -But if a change to another field does cause a monitor the change to this field -will be passed to the client. -

-Assume that the client has already connected to the channel. -The client can then issue the commands:

-
-std::string request("field(alarm[plugin=onChange]");
-request += ",timeStamp[plugin=onChange,raiseMonitor=false]";
-request += ",power.value[plugin=onChange";
-request += ",voltage.value[plugin=onChange";
-request += ",current.value[plugin=onChange";
-
-PVStructurePtr pvRequest = createRequest->createRequest(request);
-
-MonitorPtr monitor = channel->createMonitor(monitorRequester,pvRequest);
-
-

Example Plugin Code

-

The header file to create the example has the definition:

-
-class ExampleMonitorPlugin{
-public:
-    static void create();
-};
-
-

The implementation is:

-
-class OnChangePlugin : public MonitorPlugin
-{
-public:
-    virtual ~OnChangePlugin(){}
-    OnChangePlugin() {}
-    bool init(
-        FieldConstPtr const &field,
-        StructureConstPtr const &top,
-        PVStructurePtr const &pvFieldOptions)
-   {
-        pvField = getPVDataCreate()->createPVField(field);
-        raiseMonitor = true;
-        if(pvFieldOptions!=NULL) {
-            PVStringPtr pvString =
-                pvFieldOptions->getSubField<PVString>("raiseMonitor");
-                if(pvString!=NULL) {
-                    std::string value = pvString->get();
-                    if(value.compare("false")==0) raiseMonitor = false;
-                }
-        }
-        return true;
-   }
-   virtual std::string &getName(){return pluginName;}
-   virtual bool causeMonitor(
-        PVFieldPtr const &pvNew,
-        PVStructurePtr const &pvTop,
-        MonitorElementPtr const &monitorElement)
-   {
-       bool isSame = convert->equals(pvNew,pvField);
-       if(isSame) return false;
-       convert->copy(pvNew,pvField);
-       return raiseMonitor;
-   }
-private:
-   PVFieldPtr pvField;
-   bool raiseMonitor;
-};
-class OnChangePluginCreator : public MonitorPluginCreator
-{
-public:
-    virtual std::string &getName(){return pluginName;}
-    virtual MonitorPluginPtr create(
-        FieldConstPtr const &field,
-        StructureConstPtr const &top,
-        PVStructurePtr const &pvFieldOptions)
-   {
-       OnChangePluginPtr plugin(new OnChangePlugin());
-       bool result = plugin->init(field,top,pvFieldOptions);
-       if(!result) return MonitorPluginPtr();
-       return plugin;
-   }
-
-};
-
-void ExampleMonitorPlugin::create()
-{
-    static OnChangePluginCreatorPtr plugin;
-    static Mutex mutex;
-    Lock xx(mutex);
-    if(plugin==NULL) {
-        plugin = OnChangePluginCreatorPtr(new OnChangePluginCreator());
-        MonitorPluginManager::get()->addPlugin(pluginName,plugin);
-    }
-}
-
- -