This document describes the C++ implementation of EPICS v4 pvData.
+ +For more information about the EPICS, please refer to the home page of the +Experimental Physics and Industrial +Control System.
+ +This is the 14-Dec-2011 version of the C++ implementation of pvData. It is a +complete implementation of pvData as currently defined.
TODO
This product is available via an open source license
- -This is the overview for pvDataCPP. -Doxygen documentation is available at doxygenDoc
+This product is available via an open source +license
+This is the overview for pvDataCPP. Doxygen documentation is available at doxygenDoc
pvData is one of a set of related projects:
pvData describes and implements structured data. Interspection interfaces are used to describe the data and for each type of data a data interface provides a container to hold the data.
-pvData is modeled as a structured set of fields. A field has a name are a type. The type must be one of:
@@ -250,7 +283,7 @@ type. The type must be one of: addition each type has an introspection interface: Scalar, ScalarArray, Structure, and StructureArray. -Interface PVField provides access to the common information of every data container. In addition every possible type has an interface for accessing the @@ -269,7 +302,7 @@ data:
pvData provides support, via pvData structures and associated support, for the following:
@@ -286,7 +319,7 @@ the following:pvAccess provides client/server support for transmitting pvData objects. The server must provide access to objects identified by name. Each object must have @@ -341,7 +374,7 @@ features:
Large objects automatically span network packets. -IOC means Input/Output Controller, which is an EPICS term. A pvIOC is modeled after an EPICS IOC but supports pvData instead of flat record @@ -388,7 +421,7 @@ an existing EPICS IOC.
PVData is one of a set of related projects: pvData, pvAccess, and javaIOC. @@ -488,7 +521,7 @@ pvDataApp:
This section describes a meta language for describing pvData. Currently @@ -497,7 +530,7 @@ 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 [] White space is permitted surrounding each comma.
-Define the following top level structure:
structure timeStamp_t
@@ -707,10 +740,10 @@ structure pointArrayExample
double y 10.0
Directory pvDataApp/pv has header files that completely describe pvData. The implementation is provided in directory pvDataApp/factory. Test programs @@ -744,7 +777,7 @@ converting and copying data between fields.
alarm, etc. -This provides C/C++ definitions for the pvData primitive types: boolean, byte, short, int, long, float, double, and string. Because pvData is network @@ -802,7 +835,7 @@ typedef std::string * StringBuilder;
This subsection describes pvIntrospect.h
@@ -817,7 +850,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 {
@@ -914,7 +947,7 @@ style="font-family: courier;">ScalarType
This section describes the reflection interfaces which provide the following:
@@ -1169,7 +1202,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 @@ -1305,12 +1338,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 @@ -1418,7 +1451,7 @@ are:
purposes. -AuxInfo (Auxillary Information) is information about a field that is application specific. It will not be available outside the application that @@ -1455,7 +1488,7 @@ private:
class PVScalar : public PVField {
public:
virtual ~PVScalar();
@@ -1464,7 +1497,7 @@ protected:
PVScalar(PVStructure *parent,ScalarConstPtr scalar);
};
-The interfaces for primitive data types are:
template<typename T>
@@ -1503,7 +1536,7 @@ protected:
: PVScalarValue<String>(parent,scalar) {}
};
-PVArray is the base interface for all the other PV Array interfaces. It extends PVField and provides the @@ -1541,7 +1574,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:
@@ -1678,7 +1711,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 {
@@ -1789,7 +1822,7 @@ public:
The interface for an array of structures is:
class StructureArrayData {
@@ -1835,7 +1868,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.
@@ -1921,7 +1954,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 @@ -1976,7 +2009,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 @@ -2112,19 +2145,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 @@ -2140,12 +2173,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 @@ -2158,7 +2191,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 @@ -2169,10 +2202,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();
@@ -2230,10 +2263,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 @@ -2273,7 +2306,7 @@ structure powerSupplySimple powerSupplyValueStructure power powerSupplyValueStructure current -
The following field names have special meaning, i.e. support properties for general purpose clients.
@@ -2341,7 +2374,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 @@ -2370,7 +2403,7 @@ stack. For example the following is permitted:
... } -A timeStamp is represented by the following structure
structure timeStamp @@ -2397,7 +2430,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; @@ -2507,7 +2540,7 @@ execute. This is done as follows: endTime.getCurrent(); double time = TimeStamp::diff(endTime,startTime);-pvTimeStamp.h
+pvTimeStamp.h
class PVTimeStamp { public: PVTimeStamp(); @@ -2546,7 +2579,7 @@ public: thrown if not attached to a pvData structure.
An alarm structure is defined as follows:
structure alarm @@ -2569,7 +2602,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 }; @@ -2643,7 +2676,7 @@ public:
class PVAlarm {
public:
PVAlarm() : pvSeverity(0),pvMessage(0) {}
@@ -2683,7 +2716,7 @@ public:
if not attached to a pvData structure.
-control
+control
Control information is represented by the following structure
structure control
@@ -2701,7 +2734,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();
@@ -2726,7 +2759,7 @@ public:
class PVControl {
public:
PVControl();
@@ -2766,7 +2799,7 @@ public:
thrown if not attached to a pvData structure.
-display
+display
Display information is represented by the following structure
structure display
@@ -2787,7 +2820,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();
@@ -2830,7 +2863,7 @@ public:
class PVDisplay {
public:
PVDisplay()
@@ -2870,7 +2903,7 @@ public:
thrown if not attached to a pvData structure.
-pvEnumerated
+pvEnumerated
An enumerated structure is a structure that has fields:
structure
@@ -2937,7 +2970,7 @@ public:
-PVData Factories
+PVData Factories
Directory factory has code that implements everything described by the files
@@ -2960,10 +2993,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*/ {
@@ -3105,7 +3138,7 @@ private:
A ByteBuffer is used to serialize and deserialize primitive data. File byteBuffer.h is:
@@ -3145,7 +3178,7 @@ private:x
-This class provides coordinates activity between threads. One thread can wait for the event and the other signals the event.
@@ -3177,7 +3210,7 @@ private:File epicsException.h describes:
class BaseException : public std::exception {
@@ -3195,7 +3228,7 @@ private:
x
-Executor
+Executor
An Executor is a thread that can execute commands. The user can request that
a single command be executed.
@@ -3234,7 +3267,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
@@ -3336,7 +3369,7 @@ public:
lock.h is:
class Mutex {
@@ -3385,9 +3418,9 @@ once. This can be implemented as follows:
// initialization
}
-class MessageNode {
public:
String getMessage() const;
@@ -3409,7 +3442,7 @@ public:
int getClearOverrun();
};
-This is for use by code that wants to handle messages without blocking higher priority threads.
@@ -3452,7 +3485,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 @@ -3471,7 +3504,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.
@@ -3501,7 +3534,7 @@ public:This is a helper class for serialization, which is required for sending and receiving pvData over the nerwork.
@@ -3572,7 +3605,7 @@ properly implemented.x
-This is a facility that allows a class to report how many objects of that @@ -3607,7 +3640,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 {
@@ -3663,9 +3696,9 @@ static inline CDRNode* getNode(CDRNodeInstance *inst);
status optimization.
-enum ThreadPriority {
lowestPriority,
lowerPriority,
@@ -3682,7 +3715,7 @@ public:
static int getEpicsPriority(ThreadPriority threadPriority);
};
-class Runnable {
public:
virtual void run() = 0;
@@ -3729,7 +3762,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. @@ -3771,7 +3804,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.
@@ -3846,7 +3879,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 @@ -3928,10 +3961,10 @@ public: }
The following is also provided:
class BitSetUtil : private NoDefaultMethods {
@@ -3960,7 +3993,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