TODO
This section describes a meta language for describing pvData. Currently there are no plans for a parser for the meta language. It is used for -documentation. Also the toString introspection and data methods described below -present data in this format.
+documentation. The toString introspection and data methods described below do +present data in a format similar to the metadata syntax. The meta language is +used to describe both introspection interfaces and data interfaces.PVData supports structured data. All data appears as a top level structure. A structure has an ordered set of fields where each field has a fieldDef defined as follows:
-type fieldName = value // comment+
type fieldName value // comment-
where = value is optional and -// indicates the the rest of the -line is a comment.
+where value is present for data +objects and // indicates the the +rest of the line is a comment.
type is one of the following:
structureName fieldName +xxx_t fieldName + // if data object then following appear fieldDef ...For structure fieldName each fieldDef must have a unique fieldName within the structure - -For structureName fieldName - the structureName must be the - fieldName of a previously - defined top level structure -
+ style="font-family: courier;">structure For "xxx_t fieldName" xxx_t must be a + previously structure definition of the form: +structure xxx_t + ...
structure[] fieldName
structureDef
...
-
- Thus a structure array is an array where each element is a structure but
- all elements have the same introspection interface. For introspection the
- structureDef appears once without any data valuies.or
+xxx_t[] fieldName+
+
Thus a structure array is an array where each element is a structure + but all elements have the same introspection interface. For introspection + the structureDef appears once without any data valuies.
+Each field can optionally have data values assigned to it. The definition of -the data values depends on the type. For scalars the data value is whatever is -valid for the type.
+The above is used to describe introspection objects. Data objects are +describe in a similar way but each scalar field and each array field has data +values. The definition of the data values depends on the type. For scalars the +data value is whatever is valid for the type.
For scalar arrays the syntax is:
@@ -592,47 +597,106 @@ scalar data value depending on the type. Thus it is a comma separated set of values enclosed in [] White space is permitted surrounding each comma. -Define the following top level structure:
-structure timeStamp +structure timeStamp_t long secondsPastEpoch int nanoSeconds-Then the following can be defined
-structure scalarDoubleExample - double value = 1.0 - timeStamp timeStamp ++ +Then the following introspection objects can be defined:
+structure scalarDoubleExample // introspection object + double value + timeStamp_t timeStamp+or +structure scalarDoubleExample // introspection object + double value + structure timeStamp + long secondsPastEpoch + int nanoSeconds-scalar arrayDoubleExample - double[] value = [1.0,2.0] - timeStamp timeStamp +The following data objects can be defined:
+structure scalarDoubleExample // data object + double value 1.0 + timeStamp_t timeStamp + long secondsPastEpoch 0 + int nanoSeconds 0+or +scalar arrayDoubleExample + double[] value [1.0,2.0] + structure timeStamp + long secondsPastEpoch 0 + int nanoSeconds 0-structure point +If the following interface is defined:
+structure point_t double x - double y + double y-structure lineExample - point begin - x 0 - y 0 - point end - x 10 - y 10 +Then the following introspection objects can be defined:
+structure lineExample + point_t begin + point_t end -structure[] structureArrayExample - structure point +structure pointArrayExample + point_t[] points ++or +structure lineExample + structure begin + double x + double y + structure end + double x + double y + +structure pointArrayExample + structure[] points + structure point + double x + double y+ +And the following data objects can be defined:
+structure lineExample + point_t begin double x 0.0 double y 0.0 - structure point - double x 10.0 - double y 10.0+ point_t end + double x 10 + double y 10 + +structure pointArrayExample + point_t[] value + structure point + double x 0.0 + double y 0.0 + structure point + double x 10.0 + double y 10.0or
+structure lineExample + structure begin + double x 0 + double y 0 + structure end + double x 10 + double y 10 + +structure pointArrayExample + structure[] value + structure point + double x 0.0 + double y 0.0 + structure point + double x 10.0 + double y 10.0
-PV - User Description
+PV - User Description
-Overview
+Overview
Directory pvDataApp/pv has header files that completely describe pvData. The implementation is provided in directory pvDataApp/factory. Test programs @@ -666,7 +730,7 @@ converting and copying data between fields.
alarm, etc. -pvType
+pvType
This provides C/C++ definitions for the pvData primitive types: boolean, byte, short, int, long, float, double, and string. Because pvData is network @@ -724,7 +788,7 @@ typedef std::string * StringBuilder;
This subsection describes pvIntrospect.h
@@ -739,7 +803,7 @@ especially important for arrays and structures so that a client can discover the type without requiring that a large data array or structure be transported over the network. -Types are defined as:
enum Type {
@@ -836,7 +900,7 @@ style="font-family: courier;">ScalarType
This section describes the reflection interfaces which provide the following:
@@ -1091,7 +1155,7 @@ methods: structure->incReferenceCount() must be called before this method. -The file standardField.h has a class description for creating or sharing Field objects for standard fields. For each type of standard object two methods @@ -1227,12 +1291,12 @@ extern StandardField * getStandardField(); the section on Properties for a description of how these are defined. -
This section defines the Java Interfaces for accessing the data within a PV record.
-PVField is the base interface for accessing data. A data structure consists of a top level PVStructure. Every field of every structure of every top level @@ -1340,7 +1404,7 @@ are:
purposes. -AuxInfo (Auxillary Information) is information about a field that is application specific. It will not be available outside the application that @@ -1377,7 +1441,7 @@ private:
class PVScalar : public PVField {
public:
virtual ~PVScalar();
@@ -1386,7 +1450,7 @@ protected:
PVScalar(PVStructure *parent,ScalarConstPtr scalar);
};
-The interfaces for primitive data types are:
template<typename T>
@@ -1425,7 +1489,7 @@ protected:
: PVScalarValue<String>(parent,scalar) {}
};
-PVArray is the base interface for all the other PV Array interfaces. It extends PVField and provides the @@ -1463,7 +1527,7 @@ protected:
The interface for each array type has get and put methods which have the same arguments except for the data type. For example PVDoubleArray is:
@@ -1600,7 +1664,7 @@ that directly access the internal data array of a PVArray. This can be required for minimizing CPU overhead. In this case it is the applications responsibility to coordinate access to the array. -The interface for a structure is:
class PVStructure : public PVField,public BitSetSerializable {
@@ -1711,7 +1775,7 @@ public:
The interface for an array of structures is:
class StructureArrayData {
@@ -1757,7 +1821,7 @@ protected:
The other methods are similar to the methods for other array types.
-PVDataCreate
+PVDataCreate
PVDataCreate is an interface that provides methods that create PVField
interfaces. A factory is provided that creates PVDataCreate.
@@ -1843,7 +1907,7 @@ extern PVDataCreate * getPVDataCreate();
before calling this method.
-A class StandardPVField has methods for creating standard data fields. Like class StandardField it has two forms of the methods which create a field, one @@ -1898,7 +1962,7 @@ public: PVStructure * powerSupply(PVStructure *parent); }; -
NOTE about copying immutable array fields. If an entire immutable array field is copied to another array that has the same elementType, both offsets @@ -2034,19 +2098,19 @@ for code that implements toString It generates a newline and inserts blanks at the beginning of the newline.
All code in project pvDataCPP appears in namespace:
namespace epics { namespace pvData {
// ...
}}
-Any class that does not want the compiler to generate default methods can privately extend the following class which is defined in file @@ -2062,12 +2126,12 @@ private: NoDefaultMethods & operator=(const NoDefaultMethods &); }; -
Introspection objects are meant to be shared. They are all made available via std::tri::shared_pointer.
-All PVData data objects must publically extend PVField, which does not allow default methods but does have a virtual destructor. It is expected that each @@ -2080,7 +2144,7 @@ After deletion all pointers to data in the record are invalid. Similarly pvAccess creates and destroys PVData objects and notifies clients before destroying PVData data objects.
-The classes in property, i.e. alarm, timeStamp, display, and control are all meant to be free copied and shared. They can be created on the stack. In most @@ -2091,10 +2155,10 @@ be extended. Thus they can only be created via "new" and must be destroyed via "delete".
Assume that code wants to print two fields from a PVStructure:
Example of creating a scalar field.
PVDataCreate *pvDataCreate = getPVDataCreate();
@@ -2152,10 +2216,10 @@ and a timeStamp and alarm. Do it the easy way.
String("timeStamp,alarm"))
Only fields named "value" have properties. A record can have multiple value fields, which can appear in the top level structure of a record or in a @@ -2195,7 +2259,7 @@ structure powerSupplySimple powerSupplyValueStructure power powerSupplyValueStructure current -
The following field names have special meaning, i.e. support properties for general purpose clients.
@@ -2263,7 +2327,7 @@ examples are: that support the PVData data model. For example a powerSupport record can have fields power, voltage, current that each support the PVData data model. -Except for enumerated, each property has two files: a property.h and a pvProperty.h . For example: timeStamp.h @@ -2292,7 +2356,7 @@ stack. For example the following is permitted:
... } -A timeStamp is represented by the following structure
structure timeStamp @@ -2319,7 +2383,7 @@ that can be attached to a time stamp pvData structure. It provides get and set methods to get/set a TimeStamp as defined by timeStamp.h -timeStamp.h
+timeStamp.h
This provides
extern int32 milliSecPerSec; @@ -2429,7 +2493,7 @@ execute. This is done as follows: endTime.getCurrent(); double time = TimeStamp::diff(endTime,startTime);-pvTimeStamp.h
+pvTimeStamp.h
class PVTimeStamp { public: PVTimeStamp(); @@ -2468,7 +2532,7 @@ public: thrown if not attached to a pvData structure.
An alarm structure is defined as follows:
structure alarm @@ -2491,7 +2555,7 @@ style="font-family: courier;">pvAlarm.h is a class that can be attached to a time stamp pvData structure. It provides get and set methods to get/set a Alarm as defined by alarm.h -alarm.h
+alarm.h
enum AlarmSeverity { noAlarm,minorAlarm,majorAlarm,invalidAlarm,undefinedAlarm }; @@ -2565,7 +2629,7 @@ public:
class PVAlarm {
public:
PVAlarm() : pvSeverity(0),pvMessage(0) {}
@@ -2605,7 +2669,7 @@ public:
if not attached to a pvData structure.
-control
+control
Control information is represented by the following structure
structure control
@@ -2623,7 +2687,7 @@ attached to a time stamp pvData structure. It provides get and set methods to
get/set a Control as defined by control.h
-control.h
+control.h
class Control {
public:
Control();
@@ -2648,7 +2712,7 @@ public:
class PVControl {
public:
PVControl();
@@ -2688,7 +2752,7 @@ public:
thrown if not attached to a pvData structure.
-display
+display
Display information is represented by the following structure
structure display
@@ -2709,7 +2773,7 @@ class that can be attached to a display pvData structure. It provides get and
set methods to get/set a Diaplay as defined by diaplay.h
-display.h
+display.h
class Display {
public:
Display();
@@ -2752,7 +2816,7 @@ public:
class PVDisplay {
public:
PVDisplay()
@@ -2792,7 +2856,7 @@ public:
thrown if not attached to a pvData structure.
-pvEnumerated
+pvEnumerated
An enumerated structure is a structure that has fields:
structure
@@ -2859,7 +2923,7 @@ public:
-PVData Factories
+PVData Factories
Directory factory has code that implements everything described by the files
@@ -2882,10 +2946,10 @@ implements getConvert.
Other files implement PVData base classes
-Miscellanous Classes
+Miscellanous Classes
-Overview
+Overview
This package provides utility code:
Note that directory testApp/misc has test code for all the classes in misc. The test code also can be used as examples.
-This is adapted from the java.util.BitSet. bitSet.h is:
class BitSet /*: public Serializable*/ {
@@ -3027,7 +3091,7 @@ private:
A ByteBuffer is used to serialize and deserialize primitive data. File byteBuffer.h is:
@@ -3067,7 +3131,7 @@ private:x
-This class provides coordinates activity between threads. One thread can wait for the event and the other signals the event.
@@ -3099,7 +3163,7 @@ private:File epicsException.h describes:
class BaseException : public std::exception {
@@ -3117,7 +3181,7 @@ private:
x
-Executor
+Executor
An Executor is a thread that can execute commands. The user can request that
a single command be executed.
@@ -3156,7 +3220,7 @@ execute.
nothing is done.
-Linked List
+Linked List
LinkedList implements a double linked list that requires a user to allocate
the nodes. It is more efficent that std::list. linkedList.h is a template that
@@ -3258,7 +3322,7 @@ public:
lock.h is:
class Mutex {
@@ -3307,9 +3371,9 @@ once. This can be implemented as follows:
// initialization
}
-class MessageNode {
public:
String getMessage() const;
@@ -3331,7 +3395,7 @@ public:
int getClearOverrun();
};
-This is for use by code that wants to handle messages without blocking higher priority threads.
@@ -3374,7 +3438,7 @@ higher priority threads.Look at miscTest/testMessageQueue.cpp for an example.
-If a class privately extends this class then the compiler can not create any of the following: default constructor, default copy constructror, or default @@ -3393,7 +3457,7 @@ assignment contructor.
NoDefaultMethods & operator=(const NoDefaultMethods &); }; -A PVField extends Requester. Requester is present so that when database errors are found there is someplace to send a message.
@@ -3423,7 +3487,7 @@ public:This is a helper class for serialization, which is required for sending and receiving pvData over the nerwork.
@@ -3494,7 +3558,7 @@ properly implemented.x
-This is a facility that allows a class to report how many objects of that @@ -3529,7 +3593,7 @@ public: static inline CDRNode* getNode(CDRNodeInstance *inst); -
Status provides a way to pass status back to client code:
class Status : public epics::pvData::Serializable {
@@ -3585,9 +3649,9 @@ static inline CDRNode* getNode(CDRNodeInstance *inst);
status optimization.
-enum ThreadPriority {
lowestPriority,
lowerPriority,
@@ -3604,7 +3668,7 @@ public:
static int getEpicsPriority(ThreadPriority threadPriority);
};
-class Runnable {
public:
virtual void run() = 0;
@@ -3651,7 +3715,7 @@ exception is thrown if run remains active when delete is called.
TimeFunction is a facility that measures the average number of seconds a function call requires. When timeCall is called, it calls function in a loop. @@ -3693,7 +3757,7 @@ long a function takes. It has the single method:
one second to call it ntimes. -This provides a general purpose timer. It allows a user callback to be called after a delay or periodically.
@@ -3768,7 +3832,7 @@ be used to schedule multiple callbacks. It has the methods:This provides a queue which has an immutable capacity. When the queue is full the user code is expected to keep using the current element until a new @@ -3850,10 +3914,10 @@ public: }
The following is also provided:
class BitSetUtil : private NoDefaultMethods {
@@ -3882,7 +3946,7 @@ currently has only one method:
entire structures if the structure offset bit is set.
-MultiChoice
+MultiChoice
MultiChoice defines an array of strings and a bit set that selects an
arbitrary set of the choices. This will be implemented if the java version is
@@ -3890,7 +3954,7 @@ accepted.
NOT DONE
-License Agreement
+License Agreement
Copyright (c) 2008 Martin R. Kraimer
Copyright (c) 2007 Control System Laboratory,