From c9d4f6aa02e6fd61ec52d4bdf4b86aa4bb55c02d Mon Sep 17 00:00:00 2001 From: Marty Kraimer Date: Thu, 9 Oct 2014 07:46:59 -0400 Subject: [PATCH] update ntCPP.html and TODO --- documentation/TODO.html | 22 ++++++- documentation/TODO.md | 35 ++++++++++- documentation/ntCPP.html | 129 +++++++++++++++++++++------------------ 3 files changed, 124 insertions(+), 62 deletions(-) diff --git a/documentation/TODO.html b/documentation/TODO.html index c4c5863..80cfc32 100644 --- a/documentation/TODO.html +++ b/documentation/TODO.html @@ -1,2 +1,22 @@

TODO

-

lots of code is a copy paste, consider inheritance and templates

\ No newline at end of file +

NTScalarArray

+

NTScalarArrayBuilder::arrayValue

+

Should this be:

+

NTScalarArrayBuilder::value

+

This makes NTScalarArray consistent with other NTTypes.

+

NTNameValue

+

This does not have a value field like all the other NTTypes. +Perhaps instead of

+
NTNameValue
+    string[] name
+    string[] value
+
+

It should be

+
NTNameValue
+    value
+        string[] name
+        string[] value
+
+

NTTable

+

Should lables be label? +Compare with name,value from NTNameValue.

\ No newline at end of file diff --git a/documentation/TODO.md b/documentation/TODO.md index e6edb22..044b06c 100644 --- a/documentation/TODO.md +++ b/documentation/TODO.md @@ -1,4 +1,37 @@ TODO =========== -lots of code is a copy paste, consider inheritance and templates +NTScalarArray +------------ + +NTScalarArrayBuilder::arrayValue + +Should this be: + +NTScalarArrayBuilder::value + +This makes NTScalarArray consistent with other NTTypes. + + +NTNameValue +------------ + +This does not have a value field like all the other NTTypes. +Perhaps instead of + + NTNameValue + string[] name + string[] value + +It should be + + NTNameValue + value + string[] name + string[] value + +NTTable +---------- + +Should lables be label? +Compare with name,value from NTNameValue. diff --git a/documentation/ntCPP.html b/documentation/ntCPP.html index b4096b7..d214380 100644 --- a/documentation/ntCPP.html +++ b/documentation/ntCPP.html @@ -37,7 +37,7 @@

EPICS ntCPP

-

EPICS v4 Working Group, Working Draft, 01-Oct-2014

+

EPICS v4 Working Group, Working Draft, 09-Oct-2014

Latest version:
@@ -80,7 +80,7 @@ V4 control system programming environment:

Status of this Document

-

This is the 01-Oct-2014 version of the C++ implementation of pvData. +

This is the 09-Oct-2014 version of the C++ implementation of pvData.

@@ -112,9 +112,9 @@ pvDataCPP.html
NTScalarArray
This has a value field that has type scalarArray
NTNameValue
-
This has a field names that is a string array - and a field values that has type scalarArray. - Each names[i] is associated with values[i]. +
This has a field name that is a string array + and a field value that has type scalarArray. + Each name[i] is associated with value[i].
NTTable
This has a string array field named labels @@ -233,9 +233,11 @@ to report problems to the client. An alarm attached to a substructure of the top level structure is normally associated with a value field. An alarm field attached to the top level structure can be used for either: +

  1. If the top level structure has a value field then it is an alarm for that field. +
  2. To report other problems to the client.

If alarms do appear at multiple levels then an alarm is always @@ -288,9 +290,11 @@ There can be multiple timeStamp fields. A timeStamp associated with a substructure is usually associated with a value field. An timeStamp field attached to the top level structure can be used for either: +

  1. If the top level structure has a value field then it can be the timeStamp for that field. +
  2. The time when the server executed.

NTNDArray is an example that has two top level timeStamp field with different @@ -369,7 +373,7 @@ structure

NOTE: NTField, described above, has support for checking to see if a structure is an alarmLimit structure but no other support for alarmLimit.

- +

PVData has support named valueAlarm instead of alarmLimit (alarmLimit is identical to valueAlarm for type double). For numeric types the field names are the same but the type @@ -394,11 +398,12 @@ PVData can be used to generate a valueAlarm field as an extra field.

The introspection instance for the data structure associated with the type.
PVStructure
The data instance for the data structure associated with the type.
-
NTXXX
+
NTType
The instance for the NT type. + For example NTScalar
-

Each builder also has a number of additional methods for optional fields +

Each bulder also has a number of additional methods for optional fields and a method to add extra fields.

Normative Type Class

@@ -494,13 +499,13 @@ where a unique name that is not the name of any mandatory or possible optional field.

An NTScalaBuilder can be used to create multiple PVStructure and/or NTScalar instances. -Each time createPVScalar is called it clears all interval data after the PVStructure +Each time createPVScalar is called it clears all internal data after the PVStructure is created.

NTScalarBuilder Examples

An example of creating an NTScalar instance is:

 NTScalarBuilderPtr builder = NTScalar::createBuilder();
-NTScalarPtr ntScalar = builder->
+NTScalarPtr ntScalar = builder->
     value(pvInt)->
     addDescriptor()->
     addAlarm()->
@@ -525,7 +530,7 @@ NTScalarPtr ntScalar = builder->create();
 
ntscalar.h defines the following:

 
 class NTScalar;
-typedef std::tr1::shared_ptr NTScalarPtr;
+typedef std::tr1::shared_ptr<NTScalar> NTScalarPtr;
 
 class NTScalar
 {
@@ -549,7 +554,7 @@ public:
     PVStructurePtr getControl() const;
     PVFieldPtr getValue() const;
     template<typename PVT>
-    std::tr1::shared_ptr<PV> getValue() const
+    std::tr1::shared_ptr<PVT> getValue() const
 private:
 }
 

@@ -557,12 +562,13 @@ where
 

    
wrap

      
Given a pvStructure this creates an NTScalar that warps it.
-       It calls isCompatible returns a null PVScalar if isCompatible returns false.
-       

+       It calls isCompatible.
+       It returns a null PVScalar if isCompatible returns false.
+       

 The primary use of wrap is by pvAccess client code.
 The server creates a pvStructure that is valid for an NTScalar
 and passes it to the client.
-The client can call wrap to create an NTScalar for it;s own use.
+The client can call wrap to create an NTScalar for it's own use.
 An example is:
 
 void myCallback(PVStructurePtr const & pvStructure)
@@ -574,7 +580,7 @@ void myCallback(PVStructurePtr const & pvStructure)
      ...
 }
 

-     

+     

    
wrapUnsafe

      
Given a pvStructure this creates an NTScalar that warps it.
       It does not check that the introspection interface is compatible.
@@ -596,11 +602,11 @@ An example is:
 PVTimeStamp pvTimeStamp;
 TimeStamp timeStamp;
 
-ntscalar-&attachTimeStamp(pvTimeStamp);
+ntscalar->attachTimeStamp(pvTimeStamp);
 pvTimeStamp.get(timeStamp);
 TimeStamp current;
 current.getCurrent();
-double diff = TimeStamp::diff(timeStamp,current); // timeStamp = current
+double diff = TimeStamp::diff(timeStamp,current); // timeStamp - current
attachAlarm
@@ -613,7 +619,7 @@ An example is: PVAlarm pvAlarm; Alarm alarm; -ntscalar-&attachAlarm(pvAlarm); +ntscalar->attachAlarm(pvAlarm); pvAlarm.get(alarm); int severity = alarm.getSeverity(); int status = alarm.getStatus(); @@ -656,7 +662,7 @@ string message = alarm.getMessage();
Returns the value field.

Normative Type NTScalarArray

-

This class is similar to NTScalarArray except that the value +

This class is similar to NTScalar except that the value field is a scalar array field instead of just a scalar.

This has the following fields:

@@ -711,7 +717,7 @@ private:
where
-
value
+
arrayValue
This determines the element type for the value field. This must be specified or createStructure will throw an exception.
addDescriptor
@@ -738,7 +744,7 @@ where

ntscalarArray.h defines the following:

 class NTScalarArray;
-typedef std::tr1::shared_ptr NTScalarArrayPtr;
+typedef std::tr1::shared_ptr<NTScalarArray> NTScalarArrayPtr;
 
 class NTScalarArray
 {
@@ -771,7 +777,7 @@ where
    
wrap

      
Given a pvStructure this creates an NTScalarArray that warps it.
        It calls isCompatible returns a null PVScalarArray if isCompatible returns false.
-     

+     

    
wrapUnsafe

      
Given a pvStructure this creates an NTScalarArray that warps it.
       It does not check that the introspection interface is compatible.
@@ -833,8 +839,8 @@ where
 
Normative Type NTNameValue

 
 ev4:nt/NTNameValue:1.0
-    string[] names                 // mandatory
-    double[] values                // mandatory, can be any type, must be same length as names
+    string[] name                 // mandatory
+    double[] value                // madatory, can be any type, must be same length as name
     string descriptor              // optional
     alarm_t alarm                  // optional
         int severity
@@ -896,7 +902,7 @@ where
 
NTNameValue

 
 class NTNameValue;
-typedef std::tr1::shared_ptr NTNameValuePtr;
+typedef std::tr1::shared_ptr<NTNameValue> NTNameValuePtr;
 
 class NTNameValue
 {
@@ -911,11 +917,12 @@ public:
 
     bool attachTimeStamp(PVTimeStamp &pvTimeStamp) const;
     bool attachAlarm(PVAlarm &pvAlarm) const;
+    PVStringPtr getDescriptor() const;
     PVStructurePtr getPVStructure() const;
     PVStructurePtr getTimeStamp() const;
     PVStructurePtr getAlarm() const;
-    PVStringArrayPtr getNames() const;
-    PVFieldPtr getValues() const;
+    PVStringArrayPtr getName() const;
+    PVFieldPtr getValue() const;
     template<typename PVT>
     std::tr1::shared_ptr<PV> getValue() const
 private:
@@ -926,7 +933,7 @@ where
    
wrap

      
Given a pvStructure this creates an NTNameValue that warps it.
        It calls isCompatible returns a null NTNameValue if isCompatible returns false.
-     

+     

    
wrapUnsafe

      
Given a pvStructure this creates an NTNameValue that warps it.
       It does not check that the introspection interface is compatible.
@@ -963,10 +970,10 @@ where
        If the alarm was not selected as an optional field
        a null pvStructure is returned.
        

-   
getNames

-       
Returns field names.

-   
getValues

-       
Returns field values.

+   
getName

+       
Returns field name.

+   
getValue

+       
Returns field value.

Normative Type NTTable

@@ -1035,7 +1042,7 @@ where

NTTable

 class NTTable;
-typedef std::tr1::shared_ptr NTTablePtr;
+typedef std::tr1::shared_ptr<NTTable> NTTablePtr;
 
 class NTTable
 {
@@ -1066,7 +1073,7 @@ where
    
wrap

      
Given a pvStructure this creates an NTTable that warps it.
        It calls isCompatible returns a null NTTable if isCompatible returns false.
-     

+     

    
wrapUnsafe

      
Given a pvStructure this creates an NTTable that warps it.
       It does not check that the introspection interface is compatible.
@@ -1189,7 +1196,7 @@ where
 
NTMultiChannel

 
 class NTMultiChannel;
-typedef std::tr1::shared_ptr NTMultiChannelPtr;
+typedef std::tr1::shared_ptr<NTMultiChannel> NTMultiChannelPtr;
 
 class NTMultiChannel
 {
@@ -1204,6 +1211,7 @@ public:
 
     bool attachTimeStamp(PVTimeStamp &pvTimeStamp) const;
     bool attachAlarm(PVAlarm &pvAlarm) const;
+    PVStringPtr getDescriptor() const;
     PVStructurePtr getPVStructure() const;
     PVStructurePtr getTimeStamp() const;
     PVStructurePtr getAlarm() const;
@@ -1216,9 +1224,6 @@ public:
     PVLongArrayPtr getSecondsPastEpoch() const;
     PVIntArrayPtr getNanoseconds() const;
     PVIntArrayPtr getUserTag() const;
-    PVStringPtr getDescriptor() const;
-    template<typename PVT>
-    std::tr1::shared_ptr<PV> getValue() const
 private:
 }
 

@@ -1227,7 +1232,7 @@ where
    
wrap

      
Given a pvStructure this creates an NTMultiChannel that warps it.
        It calls isCompatible returns a null NTMultiChannel if isCompatible returns false.
-     

+     

    
wrapUnsafe

      
Given a pvStructure this creates an NTMultiChannel that warps it.
       It does not check that the introspection interface is compatible.
@@ -1288,11 +1293,11 @@ where
 
 ev4:nt/NTNDArray:1.0 
     union value                                 //mandatory
-    long compressedSize                         //mandatory
-    long uncompressedSize                       //mandatory
     codec_t codec                               //mandatory
         string name 
         any parameters
+    long compressedSize                         //mandatory
+    long uncompressedSize                       //mandatory
     dimension_t[] dimension                     //mandatory
         dimension_t[]
             dimension_t
@@ -1377,7 +1382,7 @@ where
 
NTNDArray

 
 class NTNDArray;
-typedef std::tr1::shared_ptr NTNDArrayPtr;
+typedef std::tr1::shared_ptr<NTNDArray> NTNDArrayPtr;
 
 class NTNDArray
 {
@@ -1390,20 +1395,21 @@ public:
     static bool isComparible(PVStructurePtr const &pvStructure);
     static NTNDArrayBuilderPtr createBuilder();
 
+    PVStringPtr getDescriptor() const;
     bool attachTimeStamp(PVTimeStamp &pvTimeStamp) const;
     bool attachDataTimeStamp(PVTimeStamp &pvTimeStamp) const;
     bool attachAlarm(PVAlarm &pvAlarm) const;
     PVStructurePtr getPVStructure() const;
     PVUnionPtr getValue() const;
+    PVStructurePtr getCodec() const;
     PVLongPtr getCompressedDataSize() const;
     PVLongPtr getUncompressedDataSize() const;
-    PVStructurePtr getCodec() const;
     PVStructureArrayPtr getAttribute() const;
     PVStructureArrayPtr getDimension() const;
     PVIntPtr getUniqueId() const;
-    PVStructurePtr getTimeStamp() const;
     PVStructurePtr getDataTimeStamp() const;
     PVStringPtr getDescriptor() const;
+    PVStructurePtr getTimeStamp() const;
     PVStructurePtr getAlarm() const;
     PVStructurePtr getDisplay() const;
 private:
@@ -1414,7 +1420,7 @@ where
    
wrap

      
Given a pvStructure this creates an NTNDArray that warps it.
        It calls isCompatible returns a null NTNDArray if isCompatible returns false.
-     

+     

    
wrapUnsafe

      
Given a pvStructure this creates an NTNDArray that warps it.
       It does not check that the introspection interface is compatible.
@@ -1442,6 +1448,23 @@ where
       

    
getPVStructure

        
Returns the pvStructure that NTNDArray wraps.

+   
getValue

+       
Returns the value field.

+   
getCodec

+       
Returns the severity of each channel.

+   
getCompressedDataSize

+       
Returns the name of each channel.

+   
getUncompressedDataSize

+       
Returns connection state of each channel.

+   
getAttribute

+       
Returns the status of each channel.

+   
getDimension

+       
Returns the message of each channel.

+   
getUniqueId

+       
Returns the secondsPastEpoch of each channel.

+   
getDataTimeStamp

+       
Returns the data timeStamp.
+       

     
getDescriptor

        
Get the descriptor.

    
getTimeStamp

@@ -1459,20 +1482,6 @@ where
        If the display was not selected as an optional field
        a null pvStructure is returned.
        

-   
getValue

-       
Returns the value field.

-   
getCompressedDataSize

-       
Returns the name of each channel.

-   
getUncompressedDataSize

-       
Returns connection state of each channel.

-   
getCodec

-       
Returns the severity of each channel.

-   
getAttribute

-       
Returns the status of each channel.

-   
getDimension

-       
Returns the message of each channel.

-   
getUniqueId

-       
Returns the secondsPastEpoch of each channel.