The main changes since release 3.0.2 are:
Currently if a subField of any of these is changed postMonitor is not called for the field itself.
David asked if this could be changed so that it is called. Marty thinks this may not be a good idea.
-normativeTypes.html defines time_t, display_t, control_t, and alarmlimit_t. -The definitions are not compatible with how property defined timeStamp, display, control, and valueAlarm. -The definition of alarm_t does match the definition of property alarm.
+normativeTypes.html describes valueAlarm only for a value field that has type +double. +The implementation also supports all the numeric scalar types.
A debate is on-going about what semantics should be.
\ No newline at end of file diff --git a/documentation/TODO.md b/documentation/TODO.md index 63e097c..1a135d2 100644 --- a/documentation/TODO.md +++ b/documentation/TODO.md @@ -23,12 +23,13 @@ Currently if a subField of any of these is changed postMonitor is not called for David asked if this could be changed so that it is called. Marty thinks this may not be a good idea. -timeStamp, display, control, and valueAlarm ----------- -normativeTypes.html defines time_t, display_t, control_t, and alarmlimit_t. -The definitions are not compatible with how property defined timeStamp, display, control, and valueAlarm. -The definition of alarm_t does match the definition of property alarm. +valueAlarm +--------- + +normativeTypes.html describes valueAlarm only for a value field that has type +double. +The implementation also supports all the numeric scalar types. monitorPlugin ------------- diff --git a/documentation/pvDataCPP.html b/documentation/pvDataCPP.html index 6416981..8caf403 100644 --- a/documentation/pvDataCPP.html +++ b/documentation/pvDataCPP.html @@ -46,11 +46,11 @@For now this is a working copy so it is not the same as "This version" shown above.
-This is the 23-July-2014 version of the C++ implementation of pvData.
diff --git a/documentation/pvDataCPP_20140723.html b/documentation/pvDataCPP_20140723.html new file mode 100644 index 0000000..8caf403 --- /dev/null +++ b/documentation/pvDataCPP_20140723.html @@ -0,0 +1,5392 @@ + + + + + +This product is made available subject to acceptance of the EPICS open source +license.
+EPICS Version 4 provides efficient
+storage, access, and communication, of memory resident structured data.
+pvData is the storage compoment.
+pvDataCPP is the C++ implementation of pvData.
+It is one part of the set of related products in the EPICS
+V4 control system programming environment:
+relatedDocumentsV4.html
+
This is the 23-July-2014 version of the C++ implementation of pvData. +
+ +RELEASE_NOTES.md provides changes since the last release. +TODO.md describes things to do before the next release. +
+ + + +pvData is one of a set of related projects. It describes and implements +data that the other projects support. Thus it is not useful by itself but +understanding pvData is required in order to understand the other projects. The +reader should also become familar with project pvAccess, which is +located via the same sourceforge site as this project.
+ +The Java and C++ implementation of pvData implement the same data model but +differ in implementation because of the differences between Java and C++.
+ +It is a good idea to read all of pvDataJava.html but read at least the +first two chapters:
+The material in these two chapters is NOT repeated in this documentation.
+ +Doxygen documentation is available at doxygenDoc
+The next section provides some examples of creating and accessing data. +
+This document discusses the following:
+This section provides some examples of creating and accessing both introspection and +data interfaces. The first time reader may not understand them but hopefully will get an +idea of how pvData works. After reading the rest of this document the examples will +be much easier to understand. +
+The documentation directory for this project has a file examples.zip. +It has the code for the examples. +After it is unzipped: ++cd examples/configure +cp ExampleRELEASE.local RELEASE.local +#edit RELEASE.local +cd .. +make +bin/linux-x86_64/introspectMain +bin/linux-x86_64/dataMain ++ +
The examples assume that the following statements have been issued:
++using std::cout; +using std::endl; +FieldCreatePtr fieldCreate = getFieldCreate(); +PVDataCreatePtr pvDataCreate = getPVDataCreate(); +StandardFieldPtr standardField = getStandardField(); +StandardPVFieldPtr standardPVField = getStandardPVField(); ++
These provide access to most of pvData:
+The examples all produce a top level structure. +The reason is that top level structures are what pvAccess passes between client and server +and what pvDatabaseCPP supports.
+The following is the hardest way to create structure that has a double value field and a time stamp field: +It uses only createField. +
+
+ size_t n = 3;
+ StringArray names;
+ names.reserve(n);
+ FieldConstPtrArray fields;
+ fields.reserve(n);
+ names.push_back("secondsPastEpoch");
+ fields.push_back(fieldCreate->createScalar(pvLong));
+ names.push_back("nanoseconds");
+ fields.push_back(fieldCreate->createScalar(pvInt));
+ names.push_back("userTag");
+ fields.push_back(fieldCreate->createScalar(pvInt));
+ StructureConstPtr timeStamp = fieldCreate->createStructure(names,fields);
+ size_t ntop = 2;
+ StringArray topnames;
+ topnames.reserve(ntop);
+ FieldConstPtrArray topfields;
+ topfields.reserve(ntop);
+ topnames.push_back("value");
+ topfields.push_back(fieldCreate->createScalar(pvDouble));
+ topnames.push_back("timeStamp");
+ topfields.push_back(timeStamp);
+ StructureConstPtr doubleScalar =
+ fieldCreate->createStructure(topnames,topfields);
+ cout << doubleScalar->dump(cout) << endl;
+
+Using FieldBuilder the same can be done via:
+
+ StructureConstPtr doubleScalarHard =
+ getFieldCreate()->createFieldBuilder()->
+ add("value",pvDouble) ->
+ addNestedStructure("timeStamp")->
+ setId("time_t")->
+ add("secondsPastEpoch", pvLong)->
+ add("nanoseconds", pvInt)->
+ add("userTag", pvInt)->
+ endNested()->
+ createStructure();
+ cout << doubleScalarHard->dump(cout) << endl;
+
+The easiest way to produce the structure is:
++ StructureConstPtr stringArrayEasy = + getStandardField()->scalarArray(pvString,"alarm,timeStamp"); + cout << stringArrayEasy->dump(cout) << "\n\n"; ++These three ways produce: +
+hardest way +structure + double value + structure timeStamp + long secsPastEpoch + int nanoseconds + int userTag + +hardway +structure + double value + time_t timeStamp + long secsPastEpoch + int nanoseconds + int userTag + +easy way +uri:ev4:nt/2012/pwd:NTScalarArray + string[] value + alarm_t alarm + int severity + int status + string message + time_t timeStamp + long secondsPastEpoch + int nanoseconds + int userTag ++
An easy way to create a structure with a string array value field and an alarm and time stamp is +via standardField:
++ StructureConstPtr stringArrayEasy = + standardField->scalarArray(pvString,"alarm,timeStamp"); + cout <<stringArrayEasy->dump(cout) << endl; ++It produces : +
+uri:ev4:nt/2012/pwd:NTScalarArray + string[] value + alarm_t alarm + int severity + int status + string message + time_t timeStamp + long secondsPastEpoch + int nanoseconds + int userTag +0x607188 ++
An enumerated structure is a structure with two sub-fields: +index, which is an int, and choices, which is an array of string. +The following examples create a structure which has a field names value, which +is an enumerated structure and additional fields. +A hard way to create an structure with an enumerated value field and a time stamp is:
+
+ StructureConstPtr enum_t =
+ fieldCreate->createFieldBuilder()->
+ setId("enum_t")->
+ add("index", pvInt)->
+ addArray("choices", pvString)->
+ createStructure();
+
+ StructureConstPtr ntEnumHard =
+ fieldCreate->createFieldBuilder()->
+ setId("uri:ev4:nt/2012/pwd/NTEnum")->
+ add("value", enum_t)->
+ addNestedStructure("timeStamp")->
+ setId("time_t")->
+ add("secondsPastEpoch", pvLong)->
+ add("nanoseconds", pvInt)->
+ add("userTag", pvInt)->
+ endNested()->
+ createStructure();
+ cout <<ntEnumHard->dump(cout) << endl;
+
+It produces:
++uri:ev4:nt/2012/pwd/NTEnum + enum_t value + int index + string[] choices + time_t timeStamp + long secondsPastEpoch + int nanoseconds + int userTag ++
The following is an easy way. Note that it has two additional +fields: alarm and timeStamp:
+
+ StructureConstPtr ntEnumEasy = getStandardField()->enumerated("alarm,timeStamp");
+ cout <<ntEnumEsay->dump(cout) << endl;
+
+It produces:
++uri:ev4:nt/2012/pwd:NTEnum + enum_t value + int index + string[] choices + alarm_t alarm + int severity + int status + string message + time_t timeStamp + long secondsPastEpoch + int nanoseconds + int userTag ++ +
The following creates a union and a structure with a union value field:
+ +
+ UnionConstPtr ntunion =
+ fieldCreate->createFieldBuilder()->
+ add("doubleValue", pvDouble)->
+ add("intValue", pvInt)->
+ add("timeStamp",standardField->timeStamp())->
+ createUnion();
+ cout <<ntunion->dump(cout) << endl;
+
+ StructureConstPtr unionValue = standardField->regUnion(punion,"alarm,timeStamp");
+ cout <<unionValue->dump(cout) << endl;
+
+It produces:
++union + double doubleValue + int intValue + time_t timeStamp + long secondsPastEpoch + int nanoseconds + int userTag + +structure with value field being a union +uri:ev4:nt/2012/pwd:NTUnion + union value + double doubleValue + int intValue + time_t timeStamp + long secondsPastEpoch + int nanoseconds + int userTag + alarm_t alarm + int severity + int status + string message + time_t timeStamp + long secondsPastEpoch + int nanoseconds + int userTag ++ +
The following:
++ UnionArrayConstPtr unionArray = fieldCreate->createUnionArray( + fieldCreate->createVariantUnion()); + cout << unionArray->dump(cout) << "\n\n"; ++
Produces
++any[] +any +0x607188 ++
The following creates a more complex structure:
+
+ StructureConstPtr powerSupply =
+ fieldCreate->createFieldBuilder()->
+ add("alarm",standardField->alarm()) ->
+ add("timestamp",standardField->timeStamp()) ->
+ addNestedStructure("power") ->
+ add("value",pvDouble) ->
+ add("alarm",standardField->alarm()) ->
+ endNested()->
+ addNestedStructure("voltage") ->
+ add("value",pvDouble) ->
+ add("alarm",standardField->alarm()) ->
+ endNested()->
+ addNestedStructure("current") ->
+ add("value",pvDouble) ->
+ add("alarm",standardField->alarm()) ->
+ endNested()->
+ createStructure();
+ std::cout << powerSupply->dumpValue(cout) <<std::endl;
+
+It produces:
++structure + alarm_t alarm + int severity + int status + string message + time_t timestamp + long secondsPastEpoch + int nanoseconds + int userTag + structure power + double value + alarm_t alarm + int severity + int status + string message + structure voltage + double value + alarm_t alarm + int severity + int status + string message + structure current + double value + alarm_t alarm + int severity + int status + string message ++
The examples all produce a top level structure.
+
+ PVStructurePtr doubleValue = getPVDataCreate()->createPVStructure(
+ getStandardField()->scalar(pvDouble,"alarm,timeStamp"));
+ PVDoublePtr pvdouble =
+ doubleValue->getSubField<PVDouble>("value");
+ pvdouble->put(1e5);
+ cout << doubleValue->dumpValue(cout) << endl;
+ double value = doubleValue->getSubField<PVDouble>("value")->get();
+ cout << "from get " << value << "\n\n";
+
+This produces:
++uri:ev4:nt/2012/pwd:NTScalar + double value 100000 + alarm_t alarm + int severity 0 + int status 0 + string message + time_t timeStamp + long secondsPastEpoch 0 + int nanoseconds 0 + int userTag 0 +0x607268 +from get 100000 ++
+ PVStructurePtr doubleArrayValue = pvDataCreate->createPVStructure(
+ standardField->scalarArray(pvDouble,"alarm,timeStamp"));
+ PVDoubleArrayPtr pvDoubleArray =
+ doubleArrayValue->getSubField<PVDoubleArray>("value");
+ size_t len = 10;
+ shared_vector<double> xxx(len);
+ for(size_t i=0; i< len; ++i) xxx[i] = i;
+ shared_vector<const double> data(freeze(xxx));
+ pvDoubleArray->replace(data);
+ cout << doubleArrayValue->dumpValue(cout) << endl;
+
+ shared_vector<const double> getData = pvDoubleArray->view();
+ cout << "via getData";
+ for (size_t i=0; i< len; ++i) cout << " " << getData[i];
+ cout << endl;
+
+This produces:
++uri:ev4:nt/2012/pwd:NTScalarArray + double[] value [0,1,2,3,4,5,6,7,8,9] + alarm_t alarm + int severity 0 + int status 0 + string message + time_t timeStamp + long secondsPastEpoch 0 + int nanoseconds 0 + int userTag 0 +0x607268 +via getData 0 1 2 3 4 5 6 7 8 9 ++
+ PVStructurePtr pvntenum = pvDataCreate->createPVStructure(
+ standardField->enumerated("alarm,timeStamp"));
+ cout << pvntenum->dumpValue(cout) << "\n\n";
+
+This produces:
++uri:ev4:nt/2012/pwd:NTEnum + enum_t value + int index 0 + string[] choices [] + alarm_t alarm + int severity 0 + int status 0 + string message + time_t timeStamp + long secondsPastEpoch 0 + int nanoseconds 0 + int userTag 0 +0x607268 ++
+ StructureConstPtr powerSupply =
+ fieldCreate->createFieldBuilder()->
+ add("alarm",alarm) ->
+ add("timestamp",timeStamp) ->
+ addNestedStructure("power") ->
+ add("value",pvDouble) ->
+ add("alarm",alarm) ->
+ endNested()->
+ addNestedStructure("voltage") ->
+ add("value",pvDouble) ->
+ add("alarm",alarm) ->
+ endNested()->
+ addNestedStructure("current") ->
+ add("value",pvDouble) ->
+ add("alarm",alarm) ->
+ endNested()->
+ createStructure();
+ PVStructurePtr pvpowerSupply = pvDataCreate->createPVStructure(powerSupply);
+ cout << pvpowerSupply->dumpValue(cout) << endl;
+
+This produces:
++structure + alarm_t alarm_t + int severity 0 + int status 0 + string message + time_t timestamp_t + long secondsPastEpoch 0 + int nanoseconds 0 + int userTag 0 + structure power + double value 0 + alarm_t alarm + int severity 0 + int status 0 + string message + structure voltage + double value 0 + alarm_t alarm + int severity 0 + int status 0 + string message + structure current + double value 0 + alarm_t alarm + int severity 0 + int status 0 + string message +0x607268 ++
+ PVStructurePtr pvStructure = pvDataCreate->createPVStructure(
+ standardField->regUnion(
+ fieldCreate->createFieldBuilder()->
+ add("doubleValue", pvDouble)->
+ add("intValue", pvInt)->
+ add("timeStamp",standardField->timeStamp())->
+ createUnion(),
+ "alarm,timeStamp"));
+ PVStructurePtr pvTimeStamp =
+ pvStructure->getSubField<PVUnion>("value")->select<PVStructure>(2);
+ pvTimeStamp->getSubField<PVLong>("secondsPastEpoch")->put(1000);
+ cout << pvStructure->dumpValue(cout) << "\n";
+ pvStructure->getSubField<PVUnion>("value")->select<PVDouble>(0)->put(1e5);
+ cout << pvStructure->dumpValue(cout) << "\n\n";
+
+This produces:
++uri:ev4:nt/2012/pwd:NTUnion + union value + time_t + long secondsPastEpoch 1000 + int nanoseconds 0 + int userTag 0 + alarm_t alarm + int severity 0 + int status 0 + string message + time_t timeStamp + long secondsPastEpoch 0 + int nanoseconds 0 + int userTag 0 +0x60a2c8 +uri:ev4:nt/2012/pwd:NTUnion + union value + double 100000 + alarm_t alarm + int severity 0 + int status 0 + string message + time_t timeStamp + long secondsPastEpoch 0 + int nanoseconds 0 + int userTag 0 +0x60a2c8 ++ +
+ PVStructurePtr pvStructure = pvDataCreate->createPVStructure(
+ standardField->variantUnion("alarm,timeStamp"));
+ PVStructurePtr pvTimeStamp =
+ pvDataCreate->createPVStructure(standardField->timeStamp());
+ pvStructure->getSubField<PVUnion>("value")->set(pvTimeStamp);
+ pvTimeStamp->getSubField<PVLong>("secondsPastEpoch")->put(1000);
+ cout << pvStructure->dumpValue(cout) << "\n";
+ pvStructure->getSubField<PVUnion>("value")->set(
+ pvDataCreate->createPVScalar(pvDouble));
+ PVDoublePtr pvValue = static_pointer_cast<PVDouble>(
+ pvStructure->getSubField<PVUnion>("value")->get());
+ pvValue->put(1e5);
+ cout << pvStructure->dumpValue(cout) << "\n\n";
+
+This produces:
++uri:ev4:nt/2012/pwd:NTUnion + any value + time_t + long secondsPastEpoch 1000 + int nanoseconds 0 + int userTag 0 + alarm_t alarm + int severity 0 + int status 0 + string message + time_t timeStamp + long secondsPastEpoch 0 + int nanoseconds 0 + int userTag 0 +0x60a2c8 +uri:ev4:nt/2012/pwd:NTUnion + any value + double 100000 + alarm_t alarm + int severity 0 + int status 0 + string message + time_t timeStamp + long secondsPastEpoch 0 + int nanoseconds 0 + int userTag 0 +0x60a2c8 ++ +
+ PVStructurePtr pvStructure = pvDataCreate->createPVStructure(
+ standardField->regUnion(
+ fieldCreate->createFieldBuilder()->
+ add("doubleValue", pvDouble)->
+ addArray("doubleArrayValue",pvDouble)->
+ addNestedUnion("unionValue") ->
+ add("doubleValue", pvDouble)->
+ add("alarm",standardField->alarm()) ->
+ endNested() ->
+ addNestedStructure("structValue") ->
+ add("doubleValue", pvDouble)->
+ addArray("doubleArrayValue",pvDouble)->
+ endNested() ->
+ addNestedUnionArray("unionArrayValue") ->
+ add("doubleValue", pvDouble)->
+ add("alarm",standardField->alarm()) ->
+ endNested() ->
+ addNestedStructureArray("structArrayValue") ->
+ add("doubleValue", pvDouble)->
+ addArray("doubleArrayValue",pvDouble)->
+ endNested() ->
+ createUnion(),
+ "alarm,timeStamp"));
+ cout << "introspection\n";
+ cout <<pvStructure->getStructure()->dump(cout) << endl;
+ cout << "data\n";
+ cout << pvStructure->dumpValue(cout) << "\n";
+ PVUnionPtr pvUnion = pvStructure->getSubField<PVUnion>("value");;
+ pvUnion->select("doubleValue");
+ PVDoublePtr pvDouble = pvUnion->get<PVDouble>();
+ pvDouble->put(1.55);
+ cout << "select valueDouble\n";
+ cout << pvStructure->dumpValue(cout) << "\n";
+ cout << "value = " << pvDouble->get() << "\n";
+ pvUnion->select("structValue");
+ pvDouble = pvUnion->get<PVStructure>()->getSubField<PVDouble>("doubleValue");
+ pvDouble->put(1.65);
+ cout << "select structValue\n";
+ cout << pvStructure->dumpValue(cout) << "\n";
+ cout << "value = " << pvDouble->get() << "\n";
+
+This produces:
++introspection +uri:ev4:nt/2012/pwd:NTUnion + union value + double doubleValue + double[] doubleArrayValue + union unionValue + double doubleValue + alarm_t alarm + int severity + int status + string message + structure structValue + double doubleValue + double[] doubleArrayValue + union[] unionArrayValue + union[] + union + double doubleValue + alarm_t alarm + int severity + int status + string message + structure[] structArrayValue + structure[] + structure + double doubleValue + double[] doubleArrayValue + alarm_t alarm + int severity + int status + string message + time_t timeStamp + long secondsPastEpoch + int nanoseconds + int userTag +0x60a2c8 +data +uri:ev4:nt/2012/pwd:NTUnion + union value + (none) + alarm_t alarm + int severity 0 + int status 0 + string message + time_t timeStamp + long secondsPastEpoch 0 + int nanoseconds 0 + int userTag 0 +0x60a2c8 +select valueDouble +uri:ev4:nt/2012/pwd:NTUnion + union value + double 1.55 + alarm_t alarm + int severity 0 + int status 0 + string message + time_t timeStamp + long secondsPastEpoch 0 + int nanoseconds 0 + int userTag 0 +0x60a2c8 +value = 1.55 +select structValue +uri:ev4:nt/2012/pwd:NTUnion + union value + structure + double doubleValue 1.65 + double[] doubleArrayValue [] + alarm_t alarm + int severity 0 + int status 0 + string message + time_t timeStamp + long secondsPastEpoch 0 + int nanoseconds 0 + int userTag 0 +0x60a2c8 +value = 1.65 ++ +
All code in project pvDataCPP appears in namespace:
+namespace epics { namespace pvData {
+ // ...
+}}
+
+Many pvDataCPP introspection and data objects are designed to be shared. They are +made availiable via std::tr1::shared_ptr. +The following naming convention is used +in typedefs:
+For example:
++typedef PVScalarValue<boolean> PVBoolean; +typedef std::tr1::shared_ptr<PVBoolean> PVBooleanPtr; ++ +
Directory pvDataApp/pv has header files that completely describe pvData. +The implementation is provided in directory pvDataApp/factory. +Test programs appears in testApp/pv.
+ +NOTES:
+A PVStructure is a field that contains an array of subfields. Each field has +code for accessing the field. The interface for each field is an interface that +extends PVField. Each field also has an introspection interface, which an +extension of Field. The next few sections describes the complete set of C++ +introspection and data interfaces for pvData.
+ +Class FieldCreate creates introspection objects. Class PVDataCreate creates +data objects. Class Convert provides a rich set of methods for converting and +copying data between fields.
+ +Directory pvDataApp/pv has the following header files:
+This provides C/C++ definitions for the pvData primitive types: boolean, +byte, short, int, long, ubyte,ushort, uint,u long,float, double, and string. +Because pvData is network data, the C++ implementation must implement the +proper semantics for the primitive types.
+ +pvType.h provides the proper semantics.
+ +It includes the definitions:
++typedef /*lots of stuff*/ boolean + +typedef int8_t int8; +typedef int16_t int16; +typedef int32_t int32; +typedef int64_t int64; +typedef uint8_t uint8; +typedef uint16_t uint16; +typedef uint32_t uint32; +typedef uint64_t uint64; +// float and double are types + +typedef std::vector<std::string> StringArray; +typedef std::tr1::shared_ptr<StringArray> StringArrayPtr; +inline std::string * get(StringArray &value); +inline std::string const * get(StringArray const &value); +inline std::string * get(StringArrayPtr &value); +inline std::string const * get(StringArrayPtr const &value); +} +inline StringArray & getVector(StringArrayPtr &value); +inline StringArray const & getVector(StringArrayPtr const &value); +typedef std::vector<std::string>::iterator StringArray_iterator; +typedef std::vector<std::string>::const_iterator StringArray_const_iterator; ++ +
where
+TBD +
+typedef uint8_t boolean; ++
This subsection describes pvIntrospect.h This file is quite big so rather +than showing the entire file, it will be described in parts.
+ +The primary purpose for pvData is to support network access to structured data. +pvAccess transports top level pvStructures. In addition a pvAccess server holds +a set of pvnames, where each name is a unique name in the local network. +This is also refered to as the channel name. +
+ +Given a pvname , it is possible to introspect the types of the associated data +access to data. The reflection and data interfaces are separate because the +data may not be available. For example when a pvAccess client connects to a pvname, +the client library can obtain the reflection information without obtaining any +data. Only when a client issues an I/O request will data be available. This +separation is 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 {
+ scalar,
+ scalarArray,
+ structure,
+ structureArray,
+ union_,
+ unionArray
+};
+
+class TypeFunc {
+public:
+ epicsShareExtern const char* name(Type type);
+};
+
+enum ScalarType {
+ pvBoolean,
+ pvByte, pvShort, pvInt, pvLong,
+ pvUByte, pvUShort, pvUInt, pvULong,
+ pvFloat,pvDouble,
+ pvString;
+};
+
+namespace ScalarTypeFunc {
+public:
+ bool isInteger(ScalarType type);
+ bool isUInteger(ScalarType type);
+ bool isNumeric(ScalarType type);
+ bool isPrimitive(ScalarType type);
+ ScalarType getScalarType(std::string const &value);
+ const char* name(ScalarType);
+ size_t elementSize(ScalarType id);
+};
+std::ostream& operator<<(std::ostream& o, const ScalarType& scalarType);
+
+
+Type is one of the following:
+ScalarType is one of the following:
+TypeFunction is a set of convenience methods for Type
+ScalarTypeFunction is a set of convenience methods for ScalarType
+This section describes the reflection interfaces which provide the +following:
+class Field;
+class Scalar;
+class ScalarArray;
+class Structure;
+class StructureArray;
+class Union;
+class UnionArray;
+
+typedef std::tr1::shared_ptr<const Field> FieldConstPtr;
+typedef std::vector<FieldConstPtr> FieldConstPtrArray;
+typedef std::tr1::shared_ptr<const Scalar> ScalarConstPtr;
+typedef std::tr1::shared_ptr<const ScalarArray> ScalarArrayConstPtr;
+typedef std::tr1::shared_ptr<const Structure> StructureConstPtr;
+typedef std::tr1::shared_ptr<const StructureArray> StructureArrayConstPtr;
+typedef std::tr1::shared_ptr<const Union> UnionConstPtr;
+typedef std::tr1::shared_ptr<const UnionArray> UnionArrayConstPtr;
+
+
+class Field :
+ virtual public Serializable,
+ public std::tr1::enable_shared_from_this<Field>
+{
+public:
+ POINTER_DEFINITIONS(Field);
+ virtual ~Field();
+ Type getType() const{return m_type;}
+ virtual std::string getID() const = 0;
+ virtual std::ostream& dump(std::ostream& o) const = 0;
+ ...
+};
+std::ostream& operator<<(std::ostream& o, const Field& field);
+
+class Scalar : public Field{
+public:
+ POINTER_DEFINITIONS(Scalar);
+ virtual ~Scalar();
+ typedef Scalar& reference;
+ typedef const Scalar& const_reference;
+
+ ScalarType getScalarType() const {return scalarType;}
+ virtual std::string getID() const;
+ virtual std::ostream& dump(std::ostream& o) const;
+ virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
+ virtual void deserialize(ByteBuffer *buffer, DeserializableContol *control);
+ ...
+};
+
+class epicsShareClass Array : public Field{
+public:
+ POINTER_DEFINITIONS(Array);
+ virtual ~Array();
+ typedef Array& reference;
+ typedef const Array& const_reference;
+ ...
+};
+
+
+class ScalarArray : public Field{
+public:
+ POINTER_DEFINITIONS(ScalarArray);
+ typedef ScalarArray& reference;
+ typedef const ScalarArray& const_reference;
+
+ ScalarArray(ScalarType scalarType);
+ ScalarType getElementType() const {return elementType;}
+ virtual std::string getID() const;
+ virtual std::ostream& dump(std::ostream& o) const;
+ virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
+ virtual void deserialize(ByteBuffer *buffer, DeserializableControl *control);
+ ...
+};
+
+class StructureArray : public Field{
+public:
+ POINTER_DEFINITIONS(StructureArray);
+ typedef StructureArray& reference;
+ typedef const StructureArray& const_reference;
+
+ StructureConstPtr getStructure() const {return pstructure;}
+ virtual std::string getID() const;
+ virtual std::ostream& dump(std::ostream& o) const;
+ virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
+ virtual void deserialize(ByteBuffer *buffer, DeserializableControl *control);
+ ...
+};
+
+class epicsShareClass UnionArray : public Field{
+public:
+ POINTER_DEFINITIONS(UnionArray);
+ typedef UnionArray& reference;
+ typedef const UnionArray& const_reference;
+ UnionConstPtr getUnion() const {return punion;}
+ virtual std::string getID() const;
+ virtual std::ostream& dump(std::ostream& o) const;
+ virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
+ virtual void deserialize(ByteBuffer *buffer, DeserializableControl *control);
+};
+
+class Structure : public Field {
+public:
+ POINTER_DEFINITIONS(Structure);
+ typedef Structure& reference;
+ typedef const Structure& const_reference;
+
+ std::size_t getNumberFields() const {return numberFields;}
+ FieldConstPtr getField(std::string const & fieldName) const;
+ FieldConstPtr getField(std::size_t index) const;
+ std::size_t getFieldIndex(std::string const &fieldName) const;
+ FieldConstPtrArray const & getFields() const {return fields;}
+ StringArray const & getFieldNames() const;
+ std::string getFieldName(std::size_t fieldIndex) const;
+ virtual std::string getID() const;
+ virtual std::ostream& dump(std::ostream& o) const;
+ virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
+ virtual void deserialize(ByteBuffer *buffer, DeserializableControl *control);
+ ...
+};
+
+class epicsShareClass Union : public Field {
+public:
+ POINTER_DEFINITIONS(Union);
+ static std::string DEFAULT_ID;
+ static std::string ANY_ID;
+ virtual ~Union();
+ typedef Union& reference;
+ typedef const Union& const_reference;
+
+ std::size_t getNumberFields() const;
+ FieldConstPtr getField(std::string const &fieldName) const;
+ FieldConstPtr getField(std::size_t index);
+ std::size_t getFieldIndex(std::string const &fieldName) const;
+ FieldConstPtrArray const & getFields() const;
+ StringArray const & getFieldNames() const;
+ std::string getFieldName(std::size_t fieldIndex) const;
+ bool isVariant() const;
+ virtual std::string getID() const;
+ virtual std::ostream& dump(std::ostream& o) const;
+ virtual void serialize(
+ ByteBuffer *buffer, SerializableControl *control) const;
+ virtual void deserialize(
+ ByteBuffer *buffer, DeserializableControl *control);
+
+};
+
+
+class epicsShareClass FieldBuilder :
+ public std::tr1::enable_shared_from_this<FieldBuilder>
+{
+public:
+ FieldBuilderPtr setId(std::string const & id);
+ FieldBuilderPtr add(std::string const & name, ScalarType scalarType);
+ FieldBuilderPtr add(std::string const & name, FieldConstPtr const & field);
+ FieldBuilderPtr addArray(std::string const & name, ScalarType scalarType);
+ FieldBuilderPtr addArray(std::string const & name, FieldConstPtr const & element);
+ StructureConstPtr createStructure();
+ UnionConstPtr createUnion();
+ FieldBuilderPtr addNestedStructure(std::string const & name);
+ FieldBuilderPtr addNestedUnion(std::string const & name);
+ FieldBuilderPtr addNestedStructureArray(std::string const & name);
+ FieldBuilderPtr addNestedUnionArray(std::string const & name);
+ FieldBuilderPtr endNested();
+};
+
+class epicsShareClass FieldCreate {
+public:
+ static FieldCreatePtr getFieldCreate();
+ FieldBuilderPtr createFieldBuilder() const;
+ ScalarConstPtr createScalar(ScalarType scalarType) const;
+ ScalarArrayConstPtr createScalarArray(ScalarType elementType) const;
+ StructureArrayConstPtr createStructureArray(StructureConstPtr const & structure) const;
+ StructureConstPtr createStructure () const;
+ StructureConstPtr createStructure (
+ StringArray const & fieldNames,
+ FieldConstPtrArray const & fields) const;
+ StructureConstPtr createStructure (
+ std::string const & id,
+ StringArray const & fieldNames,
+ FieldConstPtrArray const & fields) const;
+ UnionConstPtr createUnion (
+ StringArray const & fieldNames,
+ FieldConstPtrArray const & fields) const;
+ UnionConstPtr createUnion (
+ std::string const & id,
+ StringArray const & fieldNames,
+ FieldConstPtrArray const & fields) const;
+ UnionConstPtr createVariantUnion() const;
+ UnionArrayConstPtr createVariantUnionArray() const;
+ UnionArrayConstPtr createUnionArray(UnionConstPtr const & punion) const;
+ StructureConstPtr appendField(
+ StructureConstPtr const & structure,
+ std::string const & fieldName, FieldConstPtr const & field) const;
+ StructureConstPtr appendFields(
+ StructureConstPtr const & structure,
+ StringArray const & fieldNames,
+ FieldConstPtrArray const & fields) const;
+ FieldConstPtr deserialize(ByteBuffer* buffer, DeserializableControl* control) const;
+
+};
+
+epicsShareExtern FieldCreatePtr getFieldCreate();
+
+
+This is a class that makes it easier to create introspection interfaces. +It is meant to be used via stream input syntax. See the examples that follow the +description of the methods. +
+Examples of using fieldBuilder were given earlier in this manual.
+The file standardField.h has a class description for creating or sharing +Field objects for standard fields. For each type of field a method is provided. +Each creates a structure that has a field named "value" and a set of properyt +fields, The property field is a comma separated string of property names of the +following: alarm, timeStamp, display, control, and valueAlarm. An example is +"alarm,timeStamp,valueAlarm". The method with properties creates a structure +with fields named value and each of the property names. Each property field is +a structure defining the property. The details about each property is given in +the section named "Property". For example the call:
++StructureConstPtr example = standardField->scalar( + pvDouble, + "value,alarm,timeStamp" + ); ++ +
Will result in a Field definition that has the form:
+structure example + double value + alarm_t alarm + int severity + int status + string message + timeStamp_t timeStamp + long secondsPastEpoch + int nanoseconds + int userTag+ +
In addition there are methods that create each of the property structures, +i.e. the methods named: alarm, .... enumeratedAlarm."
+ +standardField.h contains:
+class StandardField;
+typedef std::tr1::shared_ptr<StandardField> StandardFieldPtr;
+
+class StandardField {
+public:
+ static StandardFieldPtr getStandardField();
+ ~StandardField();
+ StructureConstPtr scalar(ScalarType type,std::string const &properties);
+ StructureConstPtr regUnion(
+ UnionConstPtr const & punion,
+ std::string const & properties);
+ StructureConstPtr variantUnion(std::string const & properties);
+ StructureConstPtr scalarArray(
+ ScalarType elementType, std::string const &properties);
+ StructureConstPtr structureArray(
+ StructureConstPtr const & structure,std::string const &properties);
+ StructureConstPtr unionArray(UnionConstPtr const & punion,std::string const & properties);
+ StructureConstPtr enumerated();
+ StructureConstPtr enumerated(std::string const &properties);
+ StructureConstPtr alarm();
+ StructureConstPtr timeStamp();
+ StructureConstPtr display();
+ StructureConstPtr control();
+ StructureConstPtr booleanAlarm();
+ StructureConstPtr byteAlarm();
+ StructureConstPtr ubyteAlarm();
+ StructureConstPtr shortAlarm();
+ StructureConstPtr ushortAlarm();
+ StructureConstPtr intAlarm();
+ StructureConstPtr uintAlarm();
+ StructureConstPtr longAlarm();
+ StructureConstPtr ulongAlarm();
+ StructureConstPtr floatAlarm();
+ StructureConstPtr doubleAlarm();
+ StructureConstPtr enumeratedAlarm();
+ ...
+};
+This section describes pvData.h This file is quite big so rather than +showing the entire file, it will be described in parts.
+ +These are typedefs for Array and Ptr for the various pvData class +definitions, i.e. typdefs for "std::vector" and "std::tr1::shared_ptr".
++class PVField; +class PVScalar; +class PVScalarArray; +class PVStructure; +class PVStructureArray; +class PVUnion; +class PVUnionArray; + +typedef std::tr1::shared_ptr<PostHandler> PostHandlerPtr; + +typedef std::tr1::shared_ptr<PVField> PVFieldPtr; +typedef std::vector<PVFieldPtr> PVFieldPtrArray; +typedef std::vector<PVFieldPtr>::iterator PVFieldPtrArray_iterator; +typedef std::vector<PVFieldPtr>::const_iterator PVFieldPtrArray_const__iterator; + +typedef std::tr1::shared_ptr<PVScalar> PVScalarPtr; +typedef std::tr1::shared_ptr<PVScalarArray> PVScalarArrayPtr; + +typedef std::tr1::shared_ptr<PVStructure> PVStructurePtr; +typedef std::vector<PVStructurePtr> PVStructurePtrArray; +typedef std::vector<PVStructurePtr>::iterator PVStructurePtrArray_iterator; +typedef std::vector<PVStructurePtr>::const_iterator PVStructurePtrArray_const__iterator; + +typedef PVValueArray<PVStructurePtr> PVStructureArray; +typedef std::tr1::shared_ptr<PVStructureArray> PVStructureArrayPtr; +typedef std::vector<PVStructureArrayPtr> PVStructureArrayPtrArray; +typedef std::tr1::shared_ptr<PVStructureArrayPtrArray> PVStructureArrayPtrArrayPtr; + +typedef std::tr1::shared_ptr<PVUnion> PVUnionPtr; +typedef std::vector<PVUnionPtr> PVUnionPtrArray; +typedef std::vector<PVUnionPtr>::iterator PVUnionPtrArray_iterator; +typedef std::vector<PVUnionPtr>::const_iterator PVUnionPtrArray_const__iterator; + +typedef PVValueArray<PVUnionPtr> PVUnionArray; +typedef std::tr1::shared_ptr<PVUnionArray> PVUnionArrayPtr; +typedef std::vector<PVUnionArrayPtr> PVUnionArrayPtrArray; +typedef std::tr1::shared_ptr<PVUnionArrayPtrArray> PVUnionArrayPtrArrayPtr; + +class PVDataCreate; +typedef std::tr1::shared_ptr<PVDataCreate> PVDataCreatePtr; + + +/** + * typedefs for the various possible scalar types. + */ +typedef PVScalarValue<boolean> PVBoolean; +typedef PVScalarValue<int8> PVByte; +typedef PVScalarValue<int16> PVShort; +typedef PVScalarValue<int32> PVInt; +typedef PVScalarValue<int64> PVLong; +typedef PVScalarValue<uint8> PVUByte; +typedef PVScalarValue<uint16> PVUShort; +typedef PVScalarValue<uint32> PVUInt; +typedef PVScalarValue<uint64> PVULong; +typedef PVScalarValue<float> PVFloat; +typedef PVScalarValue<double> PVDouble; +class PVString; +typedef std::tr1::shared_ptr<PVBoolean> PVBooleanPtr; +typedef std::tr1::shared_ptr<PVByte> PVBytePtr; +typedef std::tr1::shared_ptr<PVShort> PVShortPtr; +typedef std::tr1::shared_ptr<PVInt> PVIntPtr; +typedef std::tr1::shared_ptr<PVLong> PVLongPtr; +typedef std::tr1::shared_ptr<PVUByte> PVUBytePtr; +typedef std::tr1::shared_ptr<PVUShort> PVUShortPtr; +typedef std::tr1::shared_ptr<PVUInt> PVUIntPtr; +typedef std::tr1::shared_ptr<PVULong> PVULongPtr; +typedef std::tr1::shared_ptr<PVFloat> PVFloatPtr; +typedef std::tr1::shared_ptr<PVDouble> PVDoublePtr; +typedef std::tr1::shared_ptr<PVString> PVStringPtr; + +/** + * Definitions for the various scalarArray types. + */ +typedef PVValueArray<boolean> PVBooleanArray; +typedef PVValueArray<int8> PVByteArray; +typedef PVValueArray<int16> PVShortArray; +typedef PVValueArray<int32> PVIntArray; +typedef PVValueArray<int64> PVLongArray; +typedef PVValueArray<uint8> PVUByteArray; +typedef PVValueArray<uint16> PVUShortArray; +typedef PVValueArray<uint32> PVUIntArray; +typedef PVValueArray<uint64> PVULongArray; +typedef PVValueArray<float> PVFloatArray; +typedef PVValueArray<double> PVDoubleArray; +typedef PVValueArray<std::string> PVStringArray; + +typedef std::tr1::shared_ptr<PVBooleanArray> PVBooleanArrayPtr; +typedef std::tr1::shared_ptr<PVByteArray> PVByteArrayPtr; +typedef std::tr1::shared_ptr<PVShortArray> PVShortArrayPtr; +typedef std::tr1::shared_ptr<PVIntArray> PVIntArrayPtr; +typedef std::tr1::shared_ptr<PVLongArray> PVLongArrayPtr; +typedef std::tr1::shared_ptr<PVUByteArray> PVUByteArrayPtr; +typedef std::tr1::shared_ptr<PVUShortArray> PVUShortArrayPtr; +typedef std::tr1::shared_ptr<PVUIntArray> PVUIntArrayPtr; +typedef std::tr1::shared_ptr<PVULongArray> PVULongArrayPtr; +typedef std::tr1::shared_ptr<PVFloatArray> PVFloatArrayPtr; +typedef std::tr1::shared_ptr<PVDoubleArray> PVDoubleArrayPtr; +typedef std::tr1::shared_ptr<PVStringArray> PVStringArrayPtr; ++ +
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 +structure has a PVField associated with it.
+
+class PostHandler
+{
+public:
+ POINTER_DEFINITIONS(PostHandler);
+ virtual ~PostHandler(){}
+ virtual void postPut() = 0;
+};
+
+class PVField
+: virtual public Serializable,
+ public std::tr1::enable_shared_from_this<PVField>
+{
+public:
+ POINTER_DEFINITIONS(PVField);
+ virtual ~PVField();
+ std::string getFieldName() const ;
+ std::string getFullName() const;
+ std::size_t getFieldOffset() const;
+ std::size_t getNextFieldOffset() const;
+ std::size_t getNumberFields() const;
+ bool isImmutable() const;
+ virtual void setImmutable();
+ const FieldConstPtr & getField() const ;
+ PVStructure * getParent() const
+ void postPut();
+ void setPostHandler(PostHandlerPtr const &postHandler);
+ virtual bool equals(PVField &pv);
+ std::ostream& dumpValue(std::ostream& o) const;
+ ...
+}
+std::ostream& operator<<(std::ostream& o, const PVField& f);
+
+
+The public methods for PVField are:
+This is the base class for all scalar data.
+class PVScalar : public PVField {
+public:
+ POINTER_DEFINITIONS(PVScalar);
+ virtual ~PVScalar();
+ typedef PVScalar &reference;
+ typedef const PVScalar& const_reference;
+ const ScalarConstPtr getScalar() const ;
+ template<typename T>
+ T getAs() const;
+ ...
+}
+
+where
++uint32 val = pv->getAs+(); +
The interfaces for primitive data types are:
+template<typename T>
+class PVScalarValue : public PVScalar {
+public:
+ POINTER_DEFINITIONS(PVScalarValue);
+ typedef T value_type;
+ typedef T* pointer;
+ typedef const T* const_pointer;
+ static const ScalarType typeCode;
+
+ virtual ~PVScalarValue() {}
+ virtual T get() const = 0;
+ virtual void put(T value) = 0;
+ std::ostream& dumpValue(std::ostream& o) const;
+ void operator>>=(T& value) const;
+ void operator<<=(T value);
+ template<typename T1>
+ T1 getAs() const;
+ template<typename T1>
+ void putFrom(T1 val);
+ ...
+}
+
+typedef PVScalarValue<boolean> PVBoolean;
+typedef PVScalarValue<int8> PVByte;
+typedef PVScalarValue<int16> PVShort;
+typedef PVScalarValue<int32> PVInt;
+typedef PVScalarValue<int64> PVLong;
+typedef PVScalarValue<uint8> PVUByte;
+typedef PVScalarValue<uint16> PVUShort;
+typedef PVScalarValue<uint32> PVUInt;
+typedef PVScalarValue<uint64> PVULong;
+typedef PVScalarValue<float> PVFloat;
+typedef PVScalarValue<double> PVDouble;
+typedef std::tr1::shared_ptr<PVBoolean> PVBooleanPtr;
+typedef std::tr1::shared_ptr<PVByte> PVBytePtr;
+typedef std::tr1::shared_ptr<PVShort> PVShortPtr;
+typedef std::tr1::shared_ptr<PVInt> PVIntPtr;
+typedef std::tr1::shared_ptr<PVLong> PVLongPtr;
+typedef std::tr1::shared_ptr<PVUByte> PVUBytePtr;
+typedef std::tr1::shared_ptr<PVUShort> PVUShortPtr;
+typedef std::tr1::shared_ptr<PVUInt> PVUIntPtr;
+typedef std::tr1::shared_ptr<PVULong> PVULongPtr;
+typedef std::tr1::shared_ptr<PVFloat> PVFloatPtr;
+typedef std::tr1::shared_ptr<PVDouble> PVDoublePtr;
+
+
+// PVString is special case, since it implements SerializableArray
+class PVString : public PVScalarValue<std::string>, SerializableArray {
+public:
+ virtual ~PVString() {}
+ ...
+};
+
+
+
+
+where
++double value; +PVDoublePtr pvDouble; +... +pvDouble>>=value; ++
+double value; +PVDoublePtr pvDouble; +... +pvDouble<<=value; ++
+int32 val = pv->getAs<pvInt>>(); ++
+int32 val; +pv->putFrom<pvInt>(val); ++ +
A PVUnion has a single subfield. +The Union introspection interface determines the possible +field types for the subfield. +If it is a varient union then any type is allowed and the +subfield name is normally any. +If it is not a varient union that the Union interface determines +the possible field types and names.
+
+class PVUnion : public PVField
+{
+public:
+ POINTER_DEFINITIONS(PVUnion);
+ virtual ~PVUnion();
+ typedef PVUnion & reference;
+ typedef const PVUnion & const_reference;
+
+ UnionConstPtr getUnion() const;
+ PVFieldPtr get() const;
+
+ template<typename PVT>
+ std::tr1::shared_ptr<PVT> get() const;
+
+ PVFieldPtr select(int32 index);
+
+ template<typename PVT>
+ std::tr1::shared_ptr<PVT> select(int32 index);
+
+ PVFieldPtr select(std::string const & fieldName);
+
+ template<typename PVT>
+ std::tr1::shared_ptr<PVT> select(std::string const & fieldName);
+
+ int32 getSelectedIndex() const;
+ std::string getSelectedFieldName() const;
+ void set(PVFieldPtr const & value);
+ void set(int32 index, PVFieldPtr const & value);
+ void set(std::string const & fieldName, PVFieldPtr const & value);
+ virtual void serialize(
+ ByteBuffer *pbuffer,SerializableControl *pflusher) const ;
+ PVUnion(UnionConstPtr const & punion);
+};
+
+PVArray is the base interface for all the other PV Array interfaces. It +extends PVField and provides the additional methods:
+
+class PVArray : public PVField, public SerializableArray {
+public:
+ POINTER_DEFINITIONS(PVArray);
+ virtual ~PVArray();
+ virtual ArrayConstPtr getArray() const = 0;
+ virtual void setImmutable();
+ std::size_t getLength() const;
+ virtual void setLength(std::size_t length);
+ std::size_t getCapacity() const;
+ bool isCapacityMutable() const;
+ void setCapacityMutable(bool isMutable);
+ virtual void setCapacity(std::size_t capacity) = 0;
+ virtual std::ostream& dumpValue(std::ostream& o, std::size_t index) const;
+ ...
+};
+PVScalarArray is the base class for scalar array data. PVValueArray is a +templete for the various scalar array data classes. There is a class for each +possible scalar type, i. e. PVBooleanArray, ..., PVStringArray.
+
+class PVScalarArray : public PVArray {
+public:
+ POINTER_DEFINITIONS(PVScalarArray);
+ virtual ~PVScalarArray();
+ typedef PVScalarArray &reference;
+ typedef const PVScalarArray& const_reference;
+
+ const ScalarArrayConstPtr getScalarArray() const ;
+
+ template<typename T>
+ void getAs(shared_vector<const T>& out) const
+
+ template<typename T>
+ void putFrom(const shared_vector<const T>& inp)
+
+ void assign(PVScalarArray& pv);
+ ...
+}
+
+
+where
+The interface for a structure is:
+class PVStructure : public PVField,public BitSetSerializable {
+public:
+ POINTER_DEFINITIONS(PVStructure);
+ virtual ~PVStructure();
+ typedef PVStructure & reference;
+ typedef const PVStructure & const_reference;
+
+ virtual void setImmutable();
+ StructureConstPtr getStructure() const;
+ const PVFieldPtrArray & getPVFields() const;
+ PVFieldPtr getSubField(std::string const &fieldName) const;
+
+ template<typename PVT>
+ std::tr1::shared_ptr<PVT> getSubField(std::string const &fieldName) const
+
+ PVFieldPtr getSubField(std::size_t fieldOffset) const;
+
+ template<typename PVT>
+ std::tr1::shared_ptr<PVT> getSubField(std::size_t fieldOffset) const
+
+ virtual void serialize(
+ ByteBuffer *pbuffer,SerializableControl *pflusher) const ;
+ virtual void deserialize(
+ ByteBuffer *pbuffer,DeserializableControl *pflusher);
+ virtual void serialize(ByteBuffer *pbuffer,
+ SerializableControl *pflusher,BitSet *pbitSet) const;
+ virtual void deserialize(ByteBuffer *pbuffer,
+ DeserializableControl*pflusher,BitSet *pbitSet);
+ PVStructure(StructureConstPtr const & structure);
+ PVStructure(StructureConstPtr const & structure,PVFieldPtrArray const & pvFields);
+ virtual std::ostream& dumpValue(std::ostream& o) const;
+};
+
+where
+This is a template class plus instances for PVBooleanArray, ..., +PVStringArray.
+template<typename T>
+class PVValueArray : public detail::PVVectorStorage<T,PVScalarArray>
+{
+public:
+ POINTER_DEFINITIONS(PVValueArray);
+ typedef T value_type;
+ typedef T* pointer;
+ typedef const T* const_pointer;
+ typedef ::epics::pvData::shared_vector<T> svector;
+ typedef ::epics::pvData::shared_vector<const T> const_svector;
+ static const ScalarType typeCode;
+
+ virtual ~PVValueArray() {}
+ std::ostream& dumpValue(std::ostream& o) const;
+ std::ostream& dumpValue(std::ostream& o, size_t index) const;
+ // inherited from PVVectorStorage
+ const_svector view();
+ void swap(const_svector& other);
+ void replace(const const_svector& next);
+ svector reuse();
+ ...
+};
+
+
+where
+TBD +
The interface for an array of structures is:
+
+template<>
+class PVValueArray<PVStructurePtr> : public detail::PVVectorStorage<PVStructurePtr,PVArray>
+{
+public:
+ POINTER_DEFINITIONS(PVStructureArray);
+ typedef PVStructurePtr value_type;
+ typedef PVStructurePtr* pointer;
+ typedef const PVStructurePtr* const_pointer;
+ typedef PVStructureArray &reference;
+ typedef const PVStructureArray& const_reference;
+ typedef ::epics::pvData::shared_vector<PVStructurePtr> svector;
+ typedef ::epics::pvData::shared_vector<const PVStructurePtr> const_svector;
+
+ virtual ~PVStructureArray() {}
+ virtual ArrayConstPtr getArray() const;
+ virtual size_t getLength();
+ virtual size_t getCapacity();
+ virtual void setCapacity(size_t capacity);
+ virtual void setLength(std::size_t length);
+ virtual StructureArrayConstPtr getStructureArray() const ;
+ virtual std::size_t append(std::size_t number);
+ virtual bool remove(std::size_t offset,std::size_t number);
+ virtual void compress();
+ virtual const_svector view() const;
+ virtual void swap(const_svector &other);
+ virtual void replace(const const_svector &other);
+ virtual void serialize(ByteBuffer *pbuffer,
+ SerializableControl *pflusher) const;
+ virtual void serialize(ByteBuffer *pbuffer,
+ SerializableControl *pflusher, std::size_t offset, std::size_t count) const ;
+ virtual void deserialize(ByteBuffer *buffer,
+ DeserializableControl *pflusher);
+ virtual std::ostream& dumpValue(std::ostream& o) const;
+ virtual std::ostream& dumpValue(std::ostream& o, std::size_t index) const;
+ // inherited from PVVectorStorage
+ const_svector view();
+ void swap(const_svector& other);
+ void replace(const const_svector& next);
+ svector reuse();
+ ...
+}
+where
+The other methods are similar to the methods for other array types. + See PVArray above for details.
+ +The interface for an array of unions is:
+
+template&ly;>
+class epicsShareClass PVValueArray&ly;PVUnionPtr> : public detail::PVVectorStorage&ly;PVUnionPtr,PVArray>
+{
+ typedef detail::PVVectorStorage&ly;PVUnionPtr,PVArray> base_t;
+public:
+ POINTER_DEFINITIONS(PVUnionArray);
+ typedef PVUnionPtr value_type;
+ typedef PVUnionPtr* pointer;
+ typedef const PVUnionPtr* const_pointer;
+ typedef PVUnionArray &reference;
+ typedef const PVUnionArray& const_reference;
+
+ //TODO: full namespace can be removed along with local typedef 'shared_vector'
+ typedef ::epics::pvData::shared_vector&ly;PVUnionPtr> svector;
+ typedef ::epics::pvData::shared_vector&ly;const PVUnionPtr> const_svector;
+
+ virtual ~PVValueArray() {}
+ virtual ArrayConstPtr getArray() const;
+ virtual size_t getLength() const;
+ virtual size_t getCapacity() const;
+ virtual void setCapacity(size_t capacity);
+ virtual void setLength(std::size_t length);
+ UnionArrayConstPtr getUnionArray() const;
+ virtual std::size_t append(std::size_t number);
+ virtual bool remove(std::size_t offset,std::size_t number);
+ virtual void compress();
+ virtual const_svector view() const;
+ virtual void swap(const_svector &other);
+ virtual void replace(const const_svector &other);
+ virtual void serialize(ByteBuffer *pbuffer,
+ SerializableControl *pflusher) const;
+ virtual void deserialize(ByteBuffer *buffer,
+ DeserializableControl *pflusher);
+ virtual void serialize(ByteBuffer *pbuffer,
+ SerializableControl *pflusher, std::size_t offset, std::size_t count) const ;
+ virtual std::ostream& dumpValue(std::ostream& o) const;
+ virtual std::ostream& dumpValue(std::ostream& o, std::size_t index) const;
+};
+
+where
+The other methods are similar to the methods for other array types. + See PVArray above for details.
+ +PVDataCreate is an interface that provides methods that create PVField +interfaces. A factory is provided that creates PVDataCreate.
+class PVDataCreate {
+public:
+ static PVDataCreatePtr getPVDataCreate();
+
+ PVFieldPtr createPVField(FieldConstPtr const & field);
+ PVFieldPtr createPVField(PVFieldPtr const & fieldToClone);
+
+ PVScalarPtr createPVScalar(ScalarConstPtr const & scalar);
+ PVScalarPtr createPVScalar(ScalarType scalarType);
+ PVScalarPtr createPVScalar(PVScalarPtr const & scalarToClone);
+ template<typename PVT>
+ std::tr1::shared_ptr<PVT> createPVScalar();
+
+ PVStructurePtr createPVStructure(
+ StringArray const & fieldNames,PVFieldPtrArray const & pvFields);
+ PVStructurePtr createPVStructure(PVStructurePtr const & structToClone);
+ PVStructurePtr createPVStructure(StructureConstPtr const & structure);
+
+ PVUnionPtr createPVUnion(UnionConstPtr const & punion);
+ PVUnionPtr createPVUnion(PVUnionPtr const & unionToClone);
+ PVUnionPtr createPVVariantUnion();
+
+ PVScalarArrayPtr createPVScalarArray(ScalarArrayConstPtr const & scalarArray);
+ PVScalarArrayPtr createPVScalarArray(ScalarType elementType);
+ PVScalarArrayPtr createPVScalarArray(PVScalarArrayPtr const & scalarArrayToClone);
+ template<typename PVAT>
+ std::tr1::shared_ptr<PVAT> createPVScalarArray();
+
+ PVStructureArrayPtr createPVStructureArray(StructureArrayConstPtr const & structureArray);
+ PVStructureArrayPtr createPVStructureArray(StructureConstPtr const ∓ structure);
+
+ PVUnionArrayPtr createPVUnionArray(UnionArrayConstPtr const & unionArray);
+ PVUnionArrayPtr createPVUnionArray(UnionConstPtr const & punion);
+ PVUnionArrayPtr createPVVariantUnionArray();
+ ...
+};
+
+extern PVDataCreatePtr getPVDataCreate();
+
+where
++PVDoublePtr pvDouble = getPVDataCreate()->createPVScalar<PVDouble>(); ++
+PVDoubleArrayPtr pvDoubleArray = getPVDataCreate()->createPVScalarArray<PVDoubleArray>(); ++
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 +without properties and one with properties. Again the properties is some +combination of alarm, timeStamp, control, display, and valueAlarm. And just +like StandardField there are methods to create the standard properties. The +methods are:
+class StandardPVField;
+typedef std::tr1::shared_ptr<StandardPVField> StandardPVFieldPtr;
+
+class StandardPVField : private NoDefaultMethods {
+public:
+ static StandardPVFieldPtr getStandardPVField();
+ ~StandardPVField();
+ PVStructurePtr scalar(ScalarType type,std::string const &properties);
+ PVStructurePtr scalarArray(ScalarType elementType, std::string const &properties);
+ PVStructurePtr structureArray(StructureConstPtr const &structure,std::string const &properties);
+ PVStructurePtr unionArray(UnionConstPtr const &punion,std::string const &properties);
+ PVStructurePtr enumerated(StringArray const &choices);
+ PVStructurePtr enumerated(StringArray const &choices, std::string const &properties);
+ ...
+}
+
+extern StandardPVFieldPtr getStandardPVField();
+
+
+There are two facilities for converting between two different PVData +objects:
+NOTE about copying immutable array fields. If an entire immutable array +field is copied to another array that has the same elementType, both offsets +are 0, and the length is the length of the source array, then the shareData +method of the target array is called and the target array is set immutable. +Thus the source and target share the same primitive array.
+ +This section describes the supported conversions between data types.
+
+bool operator==(PVField&, PVField&);
+
+static bool operator!=(PVField& a, PVField& b);
+
+bool operator==(const Field&, const Field&);
+bool operator==(const Scalar&, const Scalar&);
+bool operator==(const ScalarArray&, const ScalarArray&);
+bool operator==(const Structure&, const Structure&);
+bool operator==(const StructureArray&, const StructureArray&);
+bool operator==(const Union&, const Union&);
+bool operator==(const UnionArray&, const UnionArray&);
+
+static inline bool operator!=(const Field& a, const Field& b);
+static inline bool operator!=(const Scalar& a, const Scalar& b);
+static inline bool operator!=(const ScalarArray& a, const ScalarArray& b);
+static inline bool operator!=(const Structure& a, const Structure& b);
+static inline bool operator!=(const StructureArray& a, const StructureArray& b);
+static inline bool operator!=(const Union& a, const Union& b);
+static inline bool operator!=(const UnionArray& a, const UnionArray& b);
+
+class Convert;
+typedef std::tr1::shared_ptr<Convert> ConvertPtr;
+
+class Convert {
+public:
+ static ConvertPtr getConvert();
+ ~Convert();
+ void getFullName(std::string * buf,PVFieldPtr const & pvField);
+ bool equals(PVFieldPtr const &a,PVFieldPtr const &b);
+ bool equals(PVField &a,PVField &b);
+ void getString(std::string * buf,PVFieldPtr const & pvField,int indentLevel);
+ void getString(std::string * buf,PVFieldPtr const & pvField);
+ void getString(std::string * buf,PVField const * pvField,int indentLevel);
+ void getString(std::string * buf,PVField const * pvField);
+ std::size_t fromString(
+ PVStructurePtr const &pv,
+ StringArray const & from,
+ std::size_t fromStartIndex = 0);
+ void fromString(PVScalarPtr const & pv, std::string const & from);
+ std::size_t fromString(PVScalarArrayPtr const & pv, std::string const &from);
+ std::size_t fromStringArray(
+ PVScalarArrayPtr const & pv,
+ std::size_t offset, std::size_t length,
+ StringArray const & from,
+ std::size_t fromOffset);
+ std::size_t toStringArray(PVScalarArrayPtr const & pv,
+ std::size_t offset,
+ std::size_t length,
+ StringArray & to,
+ std::size_t toOffset);
+ bool isCopyCompatible(FieldConstPtr const & from, FieldConstPtr const & to);
+ void copy(PVFieldPtr const & from, PVFieldPtr const & to);
+ bool isCopyScalarCompatible(
+ ScalarConstPtr const & from,
+ ScalarConstPtr const & to);
+ void copyScalar(PVScalarPtr const & from, PVScalarPtr const & to);
+ bool isCopyScalarArrayCompatible(
+ ScalarArrayConstPtr const & from,
+ ScalarArrayConstPtr const & to);
+ bool isCopyStructureCompatible(
+ StructureConstPtr const & from, StructureConstPtr const & to);
+ void copyStructure(PVStructurePtr const & from, PVStructurePtr const & to);
+ bool isCopyStructureArrayCompatible(
+ StructureArrayConstPtr const & from, StructureArrayConstPtr const & to);
+ void copyStructureArray(
+ PVStructureArrayPtr const & from, PVStructureArrayPtr const & to);
+ bool isCopyUnionCompatible(
+ UnionConstPtr const & from, UnionConstPtr const & to);
+ void copyUnion(
+ PVUnionPtr const & from, PVUnionPtr const & to);
+ bool isCopyUnionArrayCompatible(
+ UnionArrayConstPtr const & from, UnionArrayConstPtr const & to);
+ void copyUnionArray(
+ PVUnionArrayPtr const & from, PVUnionArrayPtr const & to);
+ int8 toByte(PVScalarPtr const & pv);
+ int16 toShort(PVScalarPtr const & pv);
+ int32 toInt(PVScalarPtr const & pv);
+ int64 toLong(PVScalarPtr const & pv);
+ uint8 toUByte(PVScalarPtr const & pv);
+ uint16 toUShort(PVScalarPtr const & pv);
+ uint32 toUInt(PVScalarPtr const & pv);
+ uint64 toULong(PVScalarPtr const & pv);
+ float toFloat(PVScalarPtr const & pv);
+ double toDouble(PVScalarPtr const & pv);
+ std::string toString(PVScalarPtr const & pv);
+ void fromByte(PVScalarPtr const & pv,int8 from);
+ void fromShort(PVScalarPtr const & pv,int16 from);
+ void fromInt(PVScalarPtr const & pv, int32 from);
+ void fromLong(PVScalarPtr const & pv, int64 from);
+ void fromUByte(PVScalarPtr const & pv,uint8 from);
+ void fromUShort(PVScalarPtr const & pv,uint16 from);
+ void fromUInt(PVScalarPtr const & pv, uint32 from);
+ void fromULong(PVScalarPtr const & pv, uint64 from);
+ void fromFloat(PVScalarPtr const & pv, float from);
+ void fromDouble(PVScalarPtr const & pv, double from);
+ void newLine(std::string * buf, int indentLevel);
+ ...
+}
+
+extern ConvertPtr getConvert();
+
+newLine is a convenience method for code that implements toString It +generates a newline and inserts blanks at the beginning of the newline.
+ ++template<typename T> +void copy( + PVValueArray<T> & pvFrom, + size_t fromOffset, + size_t fromStride, + PVValueArray<T> & pvTo, + size_t toOffset, + size_t toStride, + size_t count); + +void copy( + PVScalarArray & from, + size_t fromOffset, + size_t fromStride, + PVScalarArray & to, + size_t toOffset, + size_t toStride, + size_t count); + +void copy( + PVStructureArray & from, + size_t fromOffset, + size_t fromStride, + PVStructureArray & to, + size_t toOffset, + size_t toStride, + size_t count); + +void copy( + PVArray & from, + size_t fromOffset, + size_t fromStride, + PVArray & to, + size_t toOffset, + size_t toStride, + size_t count); ++
The last copy is the only one most client need to call. +It either throws an error of the element types do not match or calls the +other copy functions. The arguments are:
+An exception is thrown if:
+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 +substructure. All other fields in the structure containing a value field are +considered properties of the value field. The fieldname is also the property +name. The value field can have any type, i.e. scalar, scalarArray, or +structure. Typical property fields are timeStamp, alarm, display, control, and +history. The timeStamp is a special case. If it appears anywhere in the +structure hieraracy above a value field it is a property of the value field.
+ +For example the following top level structure has a single value field. The +value field has properties alarm, timeStamp, and display.
+structure counterOutput + double value + alarm_t + int severity 0 + int status 0 + string message + timeStamp_t + long secondsPastEpoch + int nanoseconds + int userTag + display_t + double limitLow 0.0 + double limitHigh 10.0 + string description "Sample Description" + string format "%f" + string units volts+ +
The following example has three value fields each with properties alarm and +timeStamp. Voltage, Current, and Power each have a different alarms but all +share the timeStamp.
+structure powerSupplyValue + double value + alarm_t + int severity 0 + int status 0 + string message + +structure powerSupplySimple + alarm_t + int severity 0 + int status 0 + string message + timeStamp_t + long secondsPastEpoch + int nanoseconds + int userTag + powerSupplyValue_t voltage + double value + alarm_t + int severity 0 + int status 0 + string message + powerSupplyValue_t power + double value + alarm_t + int severity 0 + int status 0 + string message + powerSupplyValue_t current + double value + alarm_t + int severity 0 + int status 0 + string message+ +
The following field names have special meaning, i.e. support properties for +general purpose clients.
+In addition a structure can have additional fields that support the value +field but are not recognized by most general purpose client tools. Typical +examples are:
+The model allows for device records. A device record has structure fields +that 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 and pvTimeStamp.h In each case the +property.h file defined methods for manipulating the property data and the +pvProperty.h provides methods to transfer the property data to/from a pvData +structure.
+ +All methods copy data via copy by value semantics, i.e. not by pointer or by +reference. No property class calls new or delete and all allow the compiler to +generate default methods. All allow a class instance to be generated on the +stack. For example the following is permitted:
+void example(PVFieldPtr const &pvField) {
+ Alarm alarm;
+ PVAlarm pvAlarm;
+ bool result;
+ result = pvAlarm.attach(pvField);
+ assert(result);
+ Alarm al;
+ al.setMessage(std::string("testMessage"));
+ al.setSeverity(majorAlarm);
+ result = pvAlarm.set(al);
+ assert(result);
+ alarm = pvAlarm.get();
+ ...
+}
+
+A timeStamp is represented by the following structure
+structure timeStamp + long secondsPastEpoch + int nanoseconds + int userTag+ +
The Epoch is the posix epoch, i.e. Jan 1, 1970 00:00:00 UTC. Both the +seconds and nanoseconds are signed integers and thus can be negative. Since the +seconds is kept as a 64 bit integer, it allows for a time much greater than the +present age of the universe. Since the nanoseconds portion is kept as a 32 bit +integer it is subject to overflow if a value that corresponds to a value that +is greater than a little more than 2 seconds of less that about -2 seconds. The +support code always adjust seconds so that the nanoSecconds part is normlized, +i. e. it has is 0<=nanoseconds<nanoSecPerSec..
+ +Two header files are provided for manipulating time stamps:
+This provides
+extern int32 milliSecPerSec;
+extern int32 microSecPerSec;
+extern int32 nanoSecPerSec;
+extern int64 posixEpochAtEpicsEpoch;
+
+class TimeStamp {
+public:
+ TimeStamp()
+ :secondsPastEpoch(0), nanoseconds(0), userTag(0) {}
+ TimeStamp(int64 secondsPastEpoch,int32 nanoseconds = 0,int32 userTag = 0);
+ //default constructors and destructor are OK
+ //This class should not be extended
+ void normalize();
+ void fromTime_t(const time_t &);
+ void toTime_t(time_t &) const;
+ int64 getSecondsPastEpoch() const {return secondsPastEpoch;}
+ int64 getEpicsSecondsPastEpoch() const {
+ return secondsPastEpoch - posixEpochAtEpicsEpoch;
+ }
+ int32 getNanoseconds() const {return nanoseconds;}
+ int32 getUserTag() const {return userTag;}
+ void setUserTag(int userTag) {this->userTag = userTag;}
+ void put(int64 secondsPastEpoch,int32 nanoseconds = 0) {
+ this->secondsPastEpoch = secondsPastEpoch;
+ this->nanoseconds = nanoseconds;
+ normalize();
+ }
+ void put(int64 milliseconds);
+ void getCurrent();
+ double toSeconds() const ;
+ bool operator==(TimeStamp const &) const;
+ bool operator!=(TimeStamp const &) const;
+ bool operator<=(TimeStamp const &) const;
+ bool operator< (TimeStamp const &) const;
+ bool operator>=(TimeStamp const &) const;
+ bool operator> (TimeStamp const &) const;
+ static double diff(TimeStamp const & a,TimeStamp const & b);
+ TimeStamp & operator+=(int64 seconds);
+ TimeStamp & operator-=(int64 seconds);
+ TimeStamp & operator+=(double seconds);
+ TimeStamp & operator-=(double seconds);
+ int64 getMilliseconds(); // milliseconds since epoch
+ ...
+}
+
+where
+The TimeStamp class provides arithmetic operations on time stamps. The +result is always kept in normalized form, which means that the nano second +portion is 0≤=nano<nanoSecPerSec. Note that it is OK to have timeStamps +for times previous to the epoch.
+ +TimeStamp acts like a primitive. It can be allocated on the stack and the +compiler is free to generate default methods, i.e. copy constructor, assignment +constructor, and destructor.
+ +One use for TimeStamp is to time how long a section of code takes to +execute. This is done as follows:
+TimeStamp startTime; + TimeStamp endTime; + ... + startTime.getCurrent(); + // code to be measured for elapsed time + endTime.getCurrent(); + double time = TimeStamp::diff(endTime,startTime);+ +
class PVTimeStamp {
+public:
+ PVTimeStamp();
+ //default constructors and destructor are OK
+ //This class should not be extended
+ //returns (false,true) if pvField(isNot, is valid timeStamp structure
+ bool attach(PVFieldPtr const &pvField);
+ void detach();
+ bool isAttached();
+ // following throw logic_error if not attached to PVField
+ // a set returns false if field is immutable
+ void get(TimeStamp &) const;
+ bool set(TimeStamp const & timeStamp);
+};
+
+where
+An alarm structure is defined as follows:
+structure alarm + int severity + int status + string message+ +
Note that neither severity or status is defined as an enumerated structure. +The reason is performance, i. e. prevent passing the array of choice strings +everywhere. The file alarm.h provides the choice strings. Thus all code that +needs to know about alarms share the exact same choice strings.
+ +Two header files are provided for manipulating alarms:
+enum AlarmSeverity {
+ noAlarm,minorAlarm,majorAlarm,invalidAlarm,undefinedAlarm
+};
+
+enum AlarmStatus {
+ noStatus,deviceStatus,driverStatus,recordStatus,
+ dbStatus,confStatus,undefinedStatus,clientStatus
+};
+
+
+class AlarmSeverityFunc {
+public:
+ static AlarmSeverity getSeverity(int value);
+ static StringArrayPtr getSeverityNames();
+};
+
+class AlarmStatusFunc {
+public:
+ static AlarmStatus getStatus(int value);
+ static StringArrayPtr getStatusNames();
+};
+
+class Alarm {
+public:
+ Alarm();
+ //default constructors and destructor are OK
+ std::string getMessage();
+ void setMessage(std::string const &value);
+ AlarmSeverity getSeverity() const;
+ void setSeverity(AlarmSeverity value);
+ AlarmStatus getStatus() const;
+ void setStatus(AlarmStatus value);
+};
+
+Alarm Severity defines the possible alarm severities:
+Alarm Status defines the possible choices for alarm status:
+Alarm has the methods:
+class PVAlarm {
+public:
+ PVAlarm() : pvSeverity(0),pvMessage(0) {}
+ //default constructors and destructor are OK
+ //returns (false,true) if pvField(isNot, is valid enumerated structure
+ //An automatic detach is issued if already attached.
+ bool attach(PVFieldPtr const &pvField);
+ void detach();
+ bool isAttached();
+ // each of the following throws logic_error is not attached to PVField
+ // set returns false if field is immutable
+ void get(Alarm & alarm) const;
+ bool set(Alarm const & alarm);
+};
+
+where
+Control information is represented by the following structure
+structure control + double limitLow + double limitHigh + double minStep+ +
Two header files are provided for manipulating control:
+class Control {
+public:
+ Control();
+ //default constructors and destructor are OK
+ double getLow() const;
+ double getHigh() const;
+ double getMinStep() const;
+ void setLow(double value);
+ void setHigh(double value);
+ void setMinStep(double value);
+};
+
+where
+class PVControl {
+public:
+ PVControl();
+ //default constructors and destructor are OK
+ //returns (false,true) if pvField(isNot, is valid enumerated structure
+ //An automatic detach is issued if already attached.
+ bool attach(PVFieldPtr const &pvField);
+ void detach();
+ bool isAttached();
+ // each of the following throws logic_error is not attached to PVField
+ // set returns false if field is immutable
+ void get(Control &) const;
+ bool set(Control const & control);
+};
+
+where
+Display information is represented by the following structure
+structure display + double limitLow + double limitHigh + string description + string format + string units+ +
Two header files are provided for manipulating display:
+class Display {
+public:
+ Display();
+ //default constructors and destructor are OK
+ double getLow() const;
+ double getHigh() const;
+ void setLow(double value);
+ void setHigh(double value);
+ std::string getDescription() const;
+ void setDescription(std::string const &value);
+ std::string getFormat() const;
+ void setFormat(std::string const &value);
+ std::string getUnits() const;
+ void setUnits(std::string const &value);
+};
+
+where
+class PVDisplay {
+public:
+ PVDisplay()
+ : pvDescription(0),pvFormat(),pvUnits(),pvLow(),pvHigh() {}
+ //default constructors and destructor are OK
+ //An automatic detach is issued if already attached.
+ bool attach(PVFieldPtr const&pvField);
+ void detach();
+ bool isAttached();
+ // each of the following throws logic_error is not attached to PVField
+ // a set returns false if field is immutable
+ void get(Display &) const;
+ bool set(Display const & display);
+};
+
+where
+An enumerated structure is a structure that has fields:
+structure + int index + string[] choices+ +
For enumerated structures a single header file pvEnumerted.h is available
+class PVEnumerated {
+public:
+ PVEnumerated();
+ //default constructors and destructor are OK
+ //This class should not be extended
+ //returns (false,true) if pvField(isNot, is valid enumerated structure
+ //An automatic detach is issued if already attached.
+ bool attach(PVFieldPtr const &pvField);
+ void detach();
+ bool isAttached();
+ // each of the following throws logic_error is not attached to PVField
+ // a set returns false if field is immutable
+ bool setIndex(int32 index);
+ int32 getIndex();
+ std::string getChoice();
+ bool choicesMutable();
+ StringArrayPtr const & getChoices();
+ int32 getNumberChoices();
+ bool setChoices(StringArray &choices,int32 numberChoices);
+};
+
+where
+Directory factory has code that implements everything described by the files +in directory pv
+ +TypeFunc.cpp implements the functions for the enums defined in +pvIntrospecct.h
+ +FieldCreateFactory.cpp automatically creates a single instance of +FieldCreate and implements getFieldCreate.
+ +PVDataCreateFactory.cpp automatically creates a single instance of +PVDataCreate and implements getPVDataCreate.
+ + +Convert.cpp automatically creates a single instance of Convert and +implements getConvert.
+ +Other files implement PVData base classes
+ +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;
+typedef std::tr1::shared_ptr<BitSet> BitSetPtr;
+
+class BitSet : public Serializable {
+public:
+ static BitSetPtr create(uint32 nbits);
+ BitSet();
+ BitSet(uint32 nbits);
+ virtual ~BitSet();
+ void flip(uint32 bitIndex);
+ void set(uint32 bitIndex);
+ void clear(uint32 bitIndex);
+ void set(uint32 bitIndex, bool value);
+ bool get(uint32 bitIndex) const;
+ void clear();
+ int32 nextSetBit(uint32 fromIndex) const;
+ int32 nextClearBit(uint32 fromIndex) const;
+ bool isEmpty() const;
+ uint32 cardinality() const;
+ uint32 size() const;
+ BitSet& operator&=(const BitSet& set);
+ BitSet& operator|=(const BitSet& set);
+ BitSet& operator^=(const BitSet& set);
+ BitSet& operator-=(const BitSet& set);
+ BitSet& operator=(const BitSet &set);
+ void or_and(const BitSet& set1, const BitSet& set2);
+ bool operator==(const BitSet &set) const;
+ bool operator!=(const BitSet &set) const;
+ virtual void serialize(
+ ByteBuffer *buffer,SerializableControl *flusher) const;
+ virtual void deserialize(
+ ByteBuffer *buffer,DeserializableControl *flusher);
+private:
+};
+
+std::ostream& operator<<(std::ostream& o, const BitSet& b);
+
+
+where
+Clears all of the bits in this bitSet whose corresponding bit is set + in the specified bitSet.
+A ByteBuffer is used to serialize and deserialize primitive data. File +byteBuffer.h is:
+class ByteBuffer {
+public:
+ ByteBuffer(std::size_t size, int byteOrder = EPICS_BYTE_ORDER)
+ ~ByteBuffer();
+ void setEndianess(int byteOrder);
+ const char* getBuffer();
+ void clear();
+ void flip();
+ void rewind();
+ std::size_t getPosition();
+ void setPosition(std::size_t pos);
+ std::size_t getLimit();
+ void setLimit(std::size_t limit);
+ std::size_t getRemaining();
+ std::size_t getSize();
+ template<typename T>
+ void put(T value)
+ template<typename T>
+ void put(std::size_t index, T value);
+ template<typename T>
+ T get()
+ template<typename T>
+ T get(std::size_t index)
+ void put(const char* src, std::size_t src_offset, std::size_t count);
+ void get(char* dest, std::size_t dest_offset, std::size_t count);
+ template<typename T>
+ inline void putArray(T* values, std::size_t count)
+ template<typename T>
+ inline void getArray(T* values, std::size_t count)
+ template<typename T>
+ inline bool reverse();
+ inline void align(std::size_t size)
+ void putBoolean( bool value);
+ void putByte ( int8 value);
+ void putShort ( int16 value);
+ void putInt ( int32 value);
+ void putLong ( int64 value);
+ void putFloat ( float value);
+ void putDouble (double value);
+ void putBoolean(std::size_t index, bool value);
+ void putByte (std::size_t index, int8 value);
+ void putShort (std::size_t index, int16 value);
+ void putInt (std::size_t index, int32 value);
+ void putFloat (std::size_t index, float value);
+ void putDouble (std::size_t index, double value);
+ bool getBoolean();
+ int8 getByte ();
+ int16 getShort ();
+ int32 getInt ();
+ int64 getLong ();
+ float getFloat ();
+ double getDouble ();
+ bool getBoolean(std::size_t index);
+ int8 getByte (std::size_t index);
+ int16 getShort (std::size_t index);
+ int32 getInt (std::size_t index);
+ int64 getLong (std::size_t index);
+ float getFloat (std::size_t index);
+ double getDouble (std::size_t index);
+ const char* getArray();
+ ...
+};
+
+class Destroyable {
+public:
+ POINTER_DEFINITIONS(Destroyable);
+ virtual void destroy() = 0;
+ virtual ~Destroyable() {};
+};
+
+/*
+ * Throwing exceptions w/ file+line# and, when possibly, a stack trace
+ *
+ * THROW_EXCEPTION1( std::bad_alloc );
+ *
+ * THROW_EXCEPTION2( std::logic_error, "my message" );
+ *
+ * THROW_EXCEPTION( mySpecialException("my message", 42, "hello", ...) );
+ *
+ * Catching exceptions
+ *
+ * catch(std::logic_error& e) {
+ * fprintf(stderr, "%s happened\n", e.what());
+ * PRINT_EXCEPTION2(e, stderr);
+ * cout<<SHOW_EXCEPTION(e);
+ * }
+ *
+ * If the exception was not thrown with the above THROW_EXCEPTION*
+ * the nothing will be printed.
+ */
+
+This class provides coordinates activity between threads. One thread can +wait for the event and the other signals the event.
+class Event;
+typedef std::tr1::shared_ptr<Event> EventPtr;
+
+class Event {
+public:
+ POINTER_DEFINITIONS(Event);
+ explicit Event(bool = false);
+ ~Event();
+ void signal();
+ bool wait (); /* blocks until full */
+ bool wait ( double timeOut ); /* false if empty at time out */
+ bool tryWait (); /* false if empty */
+...
+};
+
+where
+An Executor is a thread that can execute commands. The user can request that +a single command be executed.
+
+class Command;
+class Executor;
+typedef std::tr1::shared_ptr<Command> CommandPtr;
+typedef std::tr1::shared_ptr<Executor> ExecutorPtr;
+
+class Command {
+public:
+ POINTER_DEFINITIONS(Command);
+ virtual ~Command(){}
+ virtual void command() = 0;
+private:
+ CommandPtr next;
+ friend class Executor;
+};
+
+class Executor : public Runnable{
+public:
+ POINTER_DEFINITIONS(Executor);
+ Executor(std::string threadName,ThreadPriority priority);
+ ~Executor();
+ void execute(CommandPtr const &node);
+ virtual void run();
+ ...
+};
+
+Command is a class that must be implemented by the code that calls execute. +It contains the single virtual method command, which is the command to +execute.
+ +Executor has the methods:
+
+extern epics::pvData::Mutex& getLocalStaticInitMutex();
+
+static class MutexInitializer {
+ public:
+ MutexInitializer ();
+ ~MutexInitializer ();
+} localStaticMutexInitializer; // Note object here in the header.
+
+TBD Matej will explain.
+ +
+typedef epicsMutex Mutex;
+
+class Lock : private NoDefaultMethods {
+public:
+ explicit Lock(Mutex &pm);
+ ~Lock();
+ void lock();
+ void unlock();
+ bool tryLock();
+ bool ownsLock() ;
+ ...
+};
+
+Lock is as easy to use as Java synchronize. To protect some object just +create a Mutex for the object and then in any method to be synchronized just +have code like:
+class SomeClass {
+private
+ Mutex mutex;
+ ...
+public
+ SomeClass() : mutex(Mutex()) {}
+ ...
+ void method()
+ {
+ Lock xx(mutex);
+ ...
+ }
+
+
+The method will take the lock when xx is created and release the lock when +the current code block completes.
+ +Another example of Lock is initialization code that must initialize only +once. This can be implemented as follows:
+ static void init(void) {
+ static Mutex mutex;
+ Lock guard(mutex);
+ if(alreadyInitialized) return;
+ // initialization
+ }
++
Lock has a private variable: +
+bool locked; ++and improves efficency by checking the local variable before calling the +mutex methods. This is not thread safe if any methods are called by a thread other than +the thread that created the Lock. + +
It is thread safe if used as follows:
+
+{
+ Lock guard(mutex);
+ ...
+ /* the following can optionally be called
+ guard.unlock();
+ guard.lock();
+ */
+}
+
+It is not thread safe if used as follows:
+
+class SomeClass
+{
+private:
+ Mutex mutex;
+ Lock lock;
+public:
+ SomeClass: lock(mutex) {}
+ ...
+ void someMethod() {
+ lock.unlock();
+ ...
+ }
+ ...
+};
+
+It is only safe if all methods of Lock, including ~Lock(), +are called by the same thread. +
+ +A messageQueue is for use by code that wants to handle messages without +blocking higher priority threads.
+class MessageNode;
+class MessageQueue;
+typedef std::tr1::shared_ptr<MessageNode> MessageNodePtr;
+typedef std::vector<MessageNodePtr> MessageNodePtrArray;
+typedef std::tr1::shared_ptr<MessageQueue> MessageQueuePtr;
+
+class MessageNode {
+public:
+ std::string getMessage() const;
+ MessageType getMessageType() const;
+ void setMessageNull();
+};
+
+class MessageQueue : public Queue<MessageNode> {
+public:
+ POINTER_DEFINITIONS(MessageQueue);
+ static MessageQueuePtr create(int size);
+ MessageQueue(MessageNodePtrArray &nodeArray);
+ virtual ~MessageQueue();
+ MessageNodePtr &get();
+ // must call release before next get
+ void release();
+ // return (false,true) if message (was not, was) put into queue
+ bool put(std::string message,MessageType messageType,bool replaceLast);
+ bool isEmpty() ;
+ bool isFull() ;
+ int getClearOverrun();
+ ...
+};
+
+A messageNode is a class with two public data members:
+A messageQueue is an interface with public methods:
+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 +assignment contructor.
+/* This is based on Item 6 of
+ * Effective C++, Third Edition, Scott Meyers
+ */
+ class NoDefaultMethods {
+ protected:
+ // allow by derived objects
+ NoDefaultMethods(){};
+ ~NoDefaultMethods(){}
+ private:
+ // do not implment
+ NoDefaultMethods(const NoDefaultMethods&);
+ NoDefaultMethods & operator=(const NoDefaultMethods &);
+ };
+
+This provides a bounded queue. When the queue is +full the user code is expected to keep using the current element until a new +free element becomes avalable.
+
+template <typename T>
+class Queue
+{
+public:
+ POINTER_DEFINITIONS(Queue);
+ typedef std::tr1::shared_ptr<T> queueElementPtr;
+ typedef std::vector<queueElementPtr> queueElementPtrArray;
+ Queue(queueElementPtrArray &);
+ virtual ~Queue();
+ void clear();
+ int capacity();
+ int getNumberFree();
+ int getNumberUsed();
+ queueElementPtr & getFree();
+ void setUsed(queueElementPtr const &element);
+ queueElementPtr & getUsed();
+ void releaseUsed(queueElementPtr const &element);
+ ...
+};
+
+testApp/misc/testQueue.cpp provides an example of how to define a queue.
+ +The queue methods are:
+A queue is created as follows:
+ class MyClass;
+ typedef MyQueueElement<MyClass> MyElement;
+ typedef MyQueue<MyClass> MyQueue;
+ int numElement = 5;
+ ...
+ MyClass *array[numElements];
+ for(int i=0; i<numElements; i++) {
+ array[i] = new MyClass();
+ }
+ MyQueue *queue = new MyQueue(array,numElements);
+
+A producer calls getFree and setUsed via code like the following:
+ MyClass *getFree() {
+ MyElement *element = queue->getFree();
+ if(element==0) return 0;
+ return element->getObject();
+ }
+
+A consumer calls getUsed and releaseUsed via code like the following:
+ while(true) {
+ MyElement *element = queue->getUsed();
+ if(element==0) break;
+ MyClass *myClass = element->getObject();
+ // do something with myClass
+ queue->releaseUsed(element);
+ }
+
+Requester is present so that when +errors are found there is someplace to send a message. +At one time PVField extended Requester but it no longer does. +Requester is, however, used by pvAccess. +
+
+class Requester;
+typedef std::tr1::shared_ptr<Requester> RequesterPtr;
+
+enum MessageType {
+ infoMessage,warningMessage,errorMessage,fatalErrorMessage
+};
+
+extern std::string getMessageTypeName(MessageType messageType);
+extern const size_t messageTypeCount;
+class Requester {
+public:
+ POINTER_DEFINITIONS(Requester);
+ virtual ~Requester(){}
+ virtual std::string getRequesterName() = 0;
+ virtual void message(std::string const & message,MessageType messageType) = 0;
+};
+
+where
+
+ class SerializableControl;
+ class DeserializableControl;
+ class Serializable;
+ class BitSetSerializable;
+ class SerializableArray;
+ class BitSet;
+ class Field;
+
+ class SerializableControl {
+ public:
+ virtual ~SerializableControl(){}
+ virtual void flushSerializeBuffer() =0;
+ virtual void ensureBuffer(std::size_t size) =0;
+ virtual void alignBuffer(std::size_t alignment) =0;
+ virtual void cachedSerialize(
+ std::tr1::shared_ptr<const Field> const & field,
+ ByteBuffer* buffer) = 0;
+ };
+
+ class DeserializableControl {
+ public:
+ virtual ~DeserializableControl(){}
+ virtual void ensureData(std::size_t size) =0;
+ virtual void alignData(std::size_t alignment) =0;
+ virtual std::tr1::shared_ptr<const Field> cachedDeserialize(
+ ByteBuffer* buffer) = 0;
+ };
+
+ class Serializable {
+ public:
+ virtual ~Serializable(){}
+ virtual void serialize(ByteBuffer *buffer,
+ SerializableControl *flusher) const = 0;
+ virtual void deserialize(ByteBuffer *buffer,
+ DeserializableControl *flusher) = 0;
+ };
+
+ class BitSetSerializable {
+ public:
+ virtual ~BitSetSerializable(){}
+ virtual void serialize(ByteBuffer *buffer,
+ SerializableControl *flusher,BitSet *bitSet) const = 0;
+ virtual void deserialize(ByteBuffer *buffer,
+ DeserializableControl *flusher,BitSet *bitSet) = 0;
+ };
+
+
+ class SerializableArray : virtual public Serializable {
+ public:
+ virtual ~SerializableArray(){}
+ virtual void serialize(ByteBuffer *buffer,
+ SerializableControl *flusher, std::size_t offset,
+ std::size_t count) const = 0;
+ };
+
+This is a helper class for serialization, which is required for sending and +receiving pvData over the nerwork.
+class SerializeHelper : public NoDefaultMethods {
+public:
+ static void writeSize(int s, ByteBuffer* buffer,
+ SerializableControl* flusher);
+ static int readSize(ByteBuffer* buffer,
+ DeserializableControl* control);
+ static void serializeString(const std::string& value,
+ ByteBuffer* buffer,SerializableControl* flusher);
+ static void serializeSubstring(const std::string& value, int offset,
+ int count, ByteBuffer* buffer,
+ SerializableControl* flusher);
+ static std::string deserializeString(ByteBuffer* buffer,
+ DeserializableControl* control);
+ ...
+};
+
+where
++#define POINTER_DEFINITIONS(clazz) \ + typedef std::tr1::shared_ptr<clazz> shared_pointer; \ + typedef std::tr1::shared_ptr<const clazz> const_shared_pointer; \ + typedef std::tr1::weak_ptr<clazz> weak_pointer; \ + typedef std::tr1::weak_ptr<const clazz> const_weak_pointer;+ +
+shared_vector is a holder for a contigious piece of memory. +Data is shared, but offset and length are not. +This allows one vector to have access to only a subset of a piece of memory. +
++shared_vector differs from std::vector as follows:
+
+template<typename E, class Enable = void& class shared_vector;
+
+template<typename E, class Enable&
+class shared_vector : public detail::shared_vector_base<E&
+{
+ typedef detail::shared_vector_base<E& base_t;
+ typedef typename detail::call_with<E&::type param_type;
+ typedef typename meta::strip_const<E&::type _E_non_const;
+public:
+ typedef E value_type;
+ typedef E& reference;
+ typedef typename meta::decorate_const<E&::type& const_reference;
+ typedef E* pointer;
+ typedef typename meta::decorate_const<E&::type* const_pointer;
+ typedef E* iterator;
+ typedef std::reverse_iterator<iterator& reverse_iterator;
+ typedef typename meta::decorate_const<E&::type* const_iterator;
+ typedef std::reverse_iterator<const_iterator& const_reverse_iterator;
+ typedef ptrdiff_t difference_type;
+ typedef size_t size_type;
+
+ typedef E element_type;
+ typedef std::tr1::shared_ptr<E& shared_pointer_type;
+
+ // allow specialization for all E to be friends
+ template<typename E1, class Enable1& friend class shared_vector;
+
+ shared_vector() :base_t();
+ explicit shared_vector(size_t c)
+ :base_t(new _E_non_const[c], 0, c);
+ shared_vector(size_t c, param_type e);
+ template<typename A&
+ shared_vector(A v, size_t o, size_t c) :base_t(v,o,c);
+ template<typename E1&
+ shared_vector(const std::tr1::shared_ptr<E1&& d, size_t o, size_t c);
+ template<typename A, typename B&
+ shared_vector(A d, B b, size_t o, size_t c);
+ shared_vector(const shared_vector& o) :base_t(o);
+
+ size_t max_size() const;
+ size_t capacity() const;
+ void reserve(size_t i);
+ void resize(size_t i);
+ void resize(size_t i, param_type v);
+ void make_unique();
+
+ iterator begin() const;
+ iterator end() const;
+ reverse_iterator rbegin() const;
+ reverse_iterator rend() const;
+ reference front() const;
+ reference back() const;
+
+ void push_back(param_type v);
+ void pop_back();
+ pointer data() const;
+ reference operator[](size_t i) const;
+ reference at(size_t i) const;
+ // inherited from detail
+ shared_vector_base& operator=(const shared_vector_base& o);
+ void swap(shared_vector_base& o);
+ void clear();
+ bool unique() const;
+ size_t size() const;
+ bool empty() const;
+ void slice(size_t offset, size_t length=(size_t)-1);
+ const std::tr1::shared_ptr<E&& dataPtr();
+ size_t dataOffset() const;
+ size_t dataCount() const;
+ size_t dataTotal() const;
+
+where
++shared_vector(size_t c); ++ This creates a shared_vector of the specified size/ +
TBD +Michael should decide if this is the correct set of methods to describe. +Also he should check for correct descriptions. +
+ + +Status provides a way to pass status back to client code:
+class Status : public epics::pvData::Serializable {
+ public:
+ enum StatusType {
+ /** Operation completed successfully. */
+ STATUSTYPE_OK,
+ /** Operation completed successfully, but there is a warning message. */
+ STATUSTYPE_WARNING,
+ /** Operation failed due to an error. */
+ STATUSTYPE_ERROR,
+ /** Operation failed due to an unexpected error. */
+ STATUSTYPE_FATAL
+ };
+ static const char* StatusTypeName[];
+ static Status Ok;
+ Status();
+ Status(StatusType type, std::string const & message);
+ Status(StatusType type, std::string const & message, std::string stackDump);
+ ~Status()
+ StatusType getType() const;
+ std::string getMessage() const;
+ std::string getStackDump() const;
+ bool isOK() const;
+ bool isSuccess() const;
+ void serialize(ByteBuffer *buffer, SerializableControl *flusher) const;
+ void deserialize(ByteBuffer *buffer, DeserializableControl *flusher);
+ void dump(std::ostream& o) const;
+};
+
+The Status methods are:
+The StatusCreate methods are:
+TBD Michael will explain.
+ +enum ThreadPriority {
+ lowestPriority,
+ lowerPriority,
+ lowPriority,
+ middlePriority,
+ highPriority,
+ higherPriority,
+ highestPriority
+};
+
+
+class Thread;
+typedef std::tr1::shared_ptr<Thread> ThreadPtr;
+typedef std::tr1::shared_ptr<epicsThread> EpicsThreadPtr;
+
+class Runnable {
+public:
+ virtual void run() = 0;
+};
+
+class Thread;
+
+class Thread : public epicsThread, private NoDefaultMethods {
+public:
+ Thread(
+ std::string name,
+ ThreadPriority priority,
+ Runnable *runnableReady,
+ epicsThreadStackSizeClass stkcls=epicsThreadStackSmall);
+ ~Thread();
+ ...
+};
+
+Runnable must be implement by code that wants to be run via a thread. It has +one virtual method: run. Run is the code that is run as a thread. When run +compeletes it can not be restarted. If code wants to delete a thread then it +MUST arrange that the run returns before the thread can be deleted. An +exception is thrown if run remains active when delete is called.
+ +Thread has the methods:
+delete pthread;+
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. +It starts with a loop of one iteration. If the total elapsed time is less then +.1 seconds it increases the number of iterrations by a factor of 10. It keeps +repeating until the elapsed time is greater than .1 seconds. It returns the +average number of seconds per call.
+class TimeFunctionRequester;
+class TimeFunction;
+typedef std::tr1::shared_ptr<TimeFunctionRequester> TimeFunctionRequesterPtr;
+typedef std::tr1::shared_ptr<TimeFunction> TimeFunctionPtr;
+
+class TimeFunctionRequester {
+public:
+ POINTER_DEFINITIONS(TimeFunctionRequester);
+ virtual ~TimeFunctionRequester(){}
+ virtual void function() = 0;
+};
+
+
+class TimeFunction {
+public:
+ POINTER_DEFINITIONS(TimeFunction);
+ TimeFunction(TimeFunctionRequesterPtr const & requester);
+ ~TimeFunction();
+ double timeCall();
+ ...
+};
+
+TimeFunctionRequester must be implemented by code that wants to time how +long a function takes. It has the single method:
+TimeFunction has the methods:
+This provides a general purpose timer. It allows a user callback to be +called after a delay or periodically.
+class TimerCallback;
+class Timer;
+typedef std::tr1::shared_ptr<TimerCallback> TimerCallbackPtr;
+typedef std::tr1::shared_ptr<Timer> TimerPtr;
+
+
+class TimerCallback {
+public:
+ POINTER_DEFINITIONS(TimerCallback);
+ TimerCallback();
+ virtual ~TimerCallback(){}
+ virtual void callback() = 0;
+ virtual void timerStopped() = 0;
+};
+
+class Timer : private Runnable {
+public:
+ POINTER_DEFINITIONS(Timer);
+ Timer(std::string threadName, ThreadPriority priority);
+ virtual ~Timer();
+ virtual void run();
+ void scheduleAfterDelay(
+ TimerCallbackPtr const &timerCallback,
+ double delay);
+ void schedulePeriodic(
+ TimerCallbackPtr const &timerCallback,
+ double delay,
+ double period));
+ void cancel(TimerCallbackPtr const &timerCallback);
+ bool isScheduled(TimerCallbackPtr const &timerCallback);
+ void dump(std::ostream& o);
+ ...
+};
+
+TimerCallback must be implemented by the user. It has the following methods: +
+In order to schedule a callback client code must allocate a TimerNode It can +be used to schedule multiple callbacks. It has the methods:
+delete timerNode;+
Timer has the methods:
+TBD Michael will explain.
+ +The following is also provided:
+class BitSetUtil : private NoDefaultMethods {
+public:
+ static bool compress(BitSet const &bitSet,PVStructure const &pvStructure);
+};
+
+This provides functions that operate on a BitSet for a PVStructure. It +currently has only one method:
+copy and monitor are not used in this project. +They are intended for use by pvAccess and by pvAccess servers. +They are provided with this project because the code depends only on +pvData itself. +
+This document describes C++ specific code. + +pvRequest.html +provides a language independent overview of copy and monitor. +
++NOTE:pvRequest.html must be updated since it is based on an earlier version of pvCopy that +had knowlege of PVRecord. The C++ version was implemented in pvDatabaseCPP +and the Java version on pvIOCJava. +At present only the C++ version of the new API for pvCopy is implemented. +
+Copy provides: +
copy provides the ability to create a structure that has +a copy of an arbitrary subset of the fields in an existing top level +structure. In addition it allows global options and field specific options. +It has two main components: createRequest and pvCopy. +Given a string createRequest creates a pvRequest, which is a PVStructure +that has the format expected by pvCopy. +
+ +This is mainly used by pvAccess clients. Given a request string it creates +a pvRequest structure that can be passed to the pvAccess create methods. +In turn pvAccess passes the pvRequest to a local channel provider which +then passes it to pvCopy. +
+The definition of the public members is:
+
+class CreateRequest {
+...
+ static CreateRequestPtr create();
+ virtual PVStructurePtr createRequest(std::string const &request);
+ std::string getMessage();
+};
+
+An example of how it is used is:
+
+CreateRequestPtr createRequest = CreateRequest::create();
+PVStructurePtr pvRequest = createRequest->createRequest(request);
+if(pvRequest==NULL) {
+ std::string error = createRequest->getMessage();
+ // take some action
+} else {
+ //success do something
+}
+
+The definition of the public members is:
+
+class epicsShareClass PVCopyTraverseMasterCallback
+{
+...
+ virtual void nextMasterPVField(PVFieldPtr const &pvField);
+};
+
+class class epicsShareClass PVCopy
+{
+...
+ static PVCopyPtr create(
+ PVStructurePtr const &pvMaster,
+ PVStructurePtr const &pvRequest,
+ std::string const & structureName);
+ virtual void destroy();
+ PVStructurePtr getPVMaster();
+ void traverseMaster(PVCopyTraverseMasterCallbackPtr const & callback);
+ StructureConstPtr getStructure();
+ PVStructurePtr createPVStructure();
+ size_t getCopyOffset(PVFieldPtr const &masterPVField);
+ size_t getCopyOffset(
+ PVStructurePtr const &masterPVStructure,
+ PVFieldPtr const &masterPVField);
+ PVFieldPtr getMasterPVField(std::size_t structureOffset);
+ void initCopy(
+ PVStructurePtr const ©PVStructure,
+ BitSetPtr const &bitSet);
+ void updateCopySetBitSet(
+ PVStructurePtr const ©PVStructure,
+ BitSetPtr const &bitSet);
+ void updateCopyFromBitSet(
+ PVStructurePtr const ©PVStructure,
+ BitSetPtr const &bitSet);
+ void updateMaster(
+ PVStructurePtr const ©PVStructure,
+ BitSetPtr const &bitSet);
+ PVStructurePtr getOptions(std::size_t fieldOffset);
+ std::string dump();
+...
+};
+
+where
+This consists of two components: +
+class MonitorElement {
+ MonitorElement(PVStructurePtr const & pvStructurePtr);
+ PVStructurePtr pvStructurePtr;
+ BitSetPtr changedBitSet;
+ BitSetPtr overrunBitSet;
+};
+
+class Monitor {
+ virtual Status start() = 0;
+ virtual Status stop() = 0;
+ virtual MonitorElementPtr poll() = 0;
+ virtual void release(MonitorElementPtr const & monitorElement) = 0;
+};
+
+class MonitorRequester : public virtual Requester {
+ virtual void monitorConnect(Status const & status,
+ MonitorPtr const & monitor, StructureConstPtr const & structure) = 0;
+ virtual void monitorEvent(MonitorPtr const & monitor) = 0;
+ virtual void unlisten(MonitorPtr const & monitor) = 0;
+};
+
+MonitorElement holds the data for one element of a monitor queue. +It has the fields: +
+A queue of monitor elements must be implemented by any channel provider that implements +Channel::createMonitor. +For an example implementation look at pvDatabaseCPP. +It has the following: +
+typedef Queue<MonitorElement> MonitorElementQueue;
+typedef std::tr1::shared_ptr<MonitorElementQueue> MonitorElementQueuePtr;
+
+class MultipleElementQueue :
+ public ElementQueue
+{
+public:
+ POINTER_DEFINITIONS(MultipleElementQueue);
+ virtual ~MultipleElementQueue(){}
+ MultipleElementQueue(
+ MonitorLocalPtr const &monitorLocal,
+ MonitorElementQueuePtr const &queue,
+ size_t nfields);
+ virtual void destroy(){}
+ virtual Status start();
+ virtual Status stop();
+ virtual bool dataChanged();
+ virtual MonitorElementPtr poll();
+ virtual void release(MonitorElementPtr const &monitorElement);
+...
+};
+
+Monitor must be implemented by any channel provider that implements +Channel::createMonitor. +Remote PVAccess also implements Monitor on the client side. +Note that each client has it's own queue that is not shared with other client. +
+Monitor has the following methods:
+This must be implemented by a pvAccess client. +It has the methods:
+
+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 must be implemented by the plugin implementation. +It has methods:
+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:
+MonitorPluginManager has the methods:
+NOTE: +Should the method causeMonitor +have arguments pvField and pvTop +be defined so that they can not be modfied. +This would be posssible 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 sufficent. +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. + +
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 + struvture display + structure voltage + double value + structure alarm + struvture display + structure current + double value + structure alarm + struvture 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 monotor +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);
+
+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);
+ }
+}
+
+
+
+