The main changes since release 4.0 are:
- -The following methods have been removed from PVStructure
- -Use template getSubField instead, e.g. use
- -getSubField< PVInt >(fieldName)
-in place of
- -getIntField(fieldName)
-Convert copy methods where moved and replaced with methods -on PVField classes, i.e.
- -PVField::copy(const PVField& from)
-Methods
- -PVField::copyUnchecked(const PVField& from)
-were added to allow unchecked copies, to gain performance -where checked are not needed (anymore).
- -In addition: -- isCompatibleXXX methods were removed in favour of Field::operator==. -- equals methods were remove in favour of PVField::operator==. -- operator== methods where moved to pvIntrospect.h and pvData.h
- -Before this method, depending on types for to and from, -sometimes did a shallow copy, i.e. just made to shared_ptr for to -share the same data as from. -Now it always copies between the subfield of to and from.
- -PVStructure has a new template member
- -getSubFieldT(std::string const &fieldName)
-that is like getSubField except that it throws a runtime_error -instead of returning null.
- -This was mainly used in the implementation of getSubField. With a change to -the latter, findSubField was removed.
- -New steam operators are available for Field and PVField. -Before to print a Field (or any extension) or a PVField (or any extension) -it was necessary to have code like:
- - void print(StructureConstPtr struc, PVStructurePtr pv)
- {
- if(struc) {
- cout << *struc << endl;
- } else {
- cout << "nullptr\n"
- }
- if(pv) {
- cout << *.struc << endl;
- } else {
- cout << "nullptr\n"
- }
- }
-Now it can be done as follows:
- - void print(StructureConstPtr struc, PVStructurePtr pv)
- {
- cout << struc << endl;
- cout << pv << endl;
- }
-A new template getField method has been added to Structure
- -template
Can be used, for example, as follows:
- -StructurePtr tsStruc = struc->getField<Structure>("timeStamp");
-Certain static builds (in particular Windows builds) of applications using -pvData had issues due to PVStructure::DEFAULT_ID being used before being initialised. This has been fixed.
- -createRequest could cause a SEGFAULT if passed a bad argument. -This has been changed so the it returns a null pvStructure -and provides an error.
- -The main changes since release 3.0.2 are:
- -PVScalarArray, PVStructureArray, and PVUnionArray all enforce COW (Copy On Write) Semantics. -In order to limit memory usage the storage for raw data is managed via a new sharedvector facility. -This allows multiple instances of array data to use the shared raw data. -COW is implemented via sharedvectors of const data, i. e. data that can not be modified.
- -This is replaced by std::string.
- -In timeStamp nanoSeconds is changed to nanoseconds.
- -In valueAlarm hysteresis is changed to hysteresis
- -pvData.h and pvIntrospect no longer defines toString -Instead they have stream support. -pvIntrospect uses method dump and pvData uses dumpValue. -For example:
- - PVDoublePtr pvValue;
- String buffer;
- pvValue->toString(&buffer);
- cout << buffer << endl;
- buffer.clear();
- pvValue->getField()->toString(&buffer);
- cout << buffer << evdl;
-is replaced by
- - PVDoublePtr pvValue;
- cout << *pvValue << endl
- cout << *pvValue->getField() << endl;
-There are two new basic types: union_t and unionArray.
- -A union is like a structure that has a single subfield. -There are two flavors:
- -The field type can be dynamically changed.
- -This consists of createRequest and pvCopy. -createRequest was moved from pvAccess to here. -pvCopy is moved from pvDatabaseCPP and now depends -only on pvData, i.e. it no longer has any knowledge of PVRecord.
- -This is for is for use by code that implements pvAccess monitors. -This is prototype and is subject to debate.
- -This was the starting point for RELEASE_NOTES
diff --git a/documentation/copyandmonitor.html b/documentation/copyandmonitor.html deleted file mode 100644 index 33286d3..0000000 --- a/documentation/copyandmonitor.html +++ /dev/null @@ -1,381 +0,0 @@ - - - - - -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 knowledge 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);
- 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);
-...
-};
-
-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:
-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 component.
-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 18-March-2016 version for the 5.1-development release 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 familiar 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 --Now you are ready to run the examples: -
-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 << 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 << endl;
-
-The easiest way to produce the structure is:
-- StructureConstPtr stringArrayEasy = - getStandardField()->scalarArray(pvString,"alarm,timeStamp"); - cout << *stringArrayEasy << "\n\n"; --These three ways produce: -
-hardest way -structure - double value - structure timeStamp - long secsPastEpoch - int nanoseconds - int userTag - -hard way -structure - double value - time_t timeStamp - long secsPastEpoch - int nanoseconds - int userTag - -easy way -epics:nt/NTScalarArray:1.0 - 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 << endl; --It produces : -
-epics:nt/NTScalarArray:1.0 - 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 subfields: -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("epics:nt/NTEnum:1.0")->
- add("value", enum_t)->
- addNestedStructure("timeStamp")->
- setId("time_t")->
- add("secondsPastEpoch", pvLong)->
- add("nanoseconds", pvInt)->
- add("userTag", pvInt)->
- endNested()->
- createStructure();
- cout << *ntEnumHard << endl;
-
-It produces:
--epics:nt/NTEnum:1.0 - 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 << *ntEnumEasy << endl;
-
-It produces:
--epics:nt/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 << endl;
-
- StructureConstPtr unionValue = standardField->regUnion(punion,"alarm,timeStamp");
- cout << *unionValue << endl;
-
-It produces:
--union - double doubleValue - int intValue - time_t timeStamp - long secondsPastEpoch - int nanoseconds - int userTag - -structure with value field being a union -epics:nt/NTUnion:1.0 - 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 << "\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 <<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 << endl;
- double value = doubleValue->getSubField<PVDouble>("value")->get();
- cout << "from get " << value << "\n\n";
-
-This produces:
--epics:nt/NTScalar:1.0 - 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 << 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:
--epics:nt/NTScalarArray:1.0 - 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 << "\n\n";
-
-This produces:
--epics:nt/NTEnum:1.0 - 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 << 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) << "\n";
- pvStructure->getSubField<PVUnion>("value")->select<PVDouble>(0)->put(1e5);
- cout << *pvStructure << "\n\n";
-
-This produces:
--epics:nt/NTUnion:1.0 - 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 -epics:nt/NTUnion:1.0 - 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 << "\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 << "\n\n";
-
-This produces:
--epics:nt/NTUnion:1.0 - 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 -epics:nt/NTUnion:1.0 - 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() << endl;
- cout << "data\n";
- cout << *pvStructure << "\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 << "\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 << "\n";
- cout << "value = " << pvDouble->get() << "\n";
-
-This produces:
--introspection -epics:nt/NTUnion:1.0 - 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 -epics:nt/NTUnion:1.0 - 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 -epics:nt/NTUnion:1.0 - 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 -epics:nt/NTUnion:1.0 - 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 available 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 src/pv has header files that completely describe pvData. -The implementation is provided in directory src/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 src/pv has the following header files:
-This provides C/C++ definitions for the pvData primitive types: boolean, -byte, short, int, long, ubyte, ushort, uint, ulong, 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 referred 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 BoundedString : public Scalar{
-public:
- POINTER_DEFINITIONS(BoundedString);
- virtual ~BoundedString();
- typedef BoundedString& reference;
- typedef const BoundedString& const_reference;
-
- std::size_t getMaximumLength() const;
- virtual std::string getID() const;
- virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
-...
-};
-
-class epicsShareClass Array : public Field{
-public:
- POINTER_DEFINITIONS(Array);
- virtual ~Array();
- typedef Array& reference;
- typedef const Array& const_reference;
- enum ArraySizeType { variable, fixed, bounded };
-
- virtual ArraySizeType getArraySizeType() const = 0;
- virtual std::size_t getMaximumCapacity() const = 0;
- ...
-};
-
-
-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 ArraySizeType getArraySizeType() const;
- virtual std::size_t getMaximumCapacity() 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 BoundedScalarArray : public ScalarArray{
-public:
- POINTER_DEFINITIONS(BoundedScalarArray);
- typedef BoundedScalarArray& reference;
- typedef const BoundedScalarArray& const_reference;
-
- BoundedScalarArray(ScalarType scalarType, std::size_t size);
- virtual ArraySizeType getArraySizeType() const;
- virtual std::size_t getMaximumCapacity() const;
- virtual std::string getID() const;
- virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
-...
-}
-
-class epicsShareClass FixedScalarArray : public ScalarArray{
-public:
- POINTER_DEFINITIONS(FixedScalarArray);
- typedef FixedScalarArray& reference;
- typedef const FixedScalarArray& const_reference;
-
- FixedScalarArray(ScalarType scalarType, std::size_t size);
- virtual ArraySizeType getArraySizeType() const {return Array::fixed;}
- virtual std::size_t getMaximumCapacity() const {return size;}
- virtual std::string getID() const;
- virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
-...
-};
-
-
-
-class StructureArray : public Field{
-public:
- POINTER_DEFINITIONS(StructureArray);
- typedef StructureArray& reference;
- typedef const StructureArray& const_reference;
-
- StructureConstPtr getStructure() const {return pstructure;}
- virtual ArraySizeType getArraySizeType() const;
- virtual std::size_t getMaximumCapacity() 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 UnionArray : public Field{
-public:
- POINTER_DEFINITIONS(UnionArray);
- typedef UnionArray& reference;
- typedef const UnionArray& const_reference;
- UnionConstPtr getUnion() const {return punion;}
- virtual ArraySizeType getArraySizeType() const;
- virtual std::size_t getMaximumCapacity() 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 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 addBoundedString(std::string const & name, std::size_t maxLength);
- FieldBuilderPtr add(std::string const & name, FieldConstPtr const & field);
- FieldBuilderPtr addArray(std::string const & name, ScalarType scalarType);
- FieldBuilderPtr addFixedArray(
- std::string const & name,
- ScalarType scalarType,
- std::size_t size);
- FieldBuilderPtr addBoundedArray(std::string const &
- name,ScalarType scalarType,
- std::size_t bound);
- 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;
- BoundedStringConstPtr createBoundedString(std::size_t maxLength) const;
- ScalarArrayConstPtr createScalarArray(ScalarType elementType) const;
- ScalarArrayConstPtr createFixedScalarArray(
- ScalarType elementType, std::size_t size) const
- ScalarArrayConstPtr createBoundedScalarArray(
- ScalarType elementType, std::size_t bound) 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. typedefs for "std::vector" and "std::tr1::shared_ptr".
--class PVField; -class PVScalar; -class PVScalarArray; -class PVStructure; -class PVStructureArray; -class PVUnion; - -template<typename T> class PVScalarValue; -template<typename T> class PVValueArray; - -typedef PVValueArray<PVUnionPtr> PVUnionArray; -typedef std::tr1::shared_ptr<PVUnionArray> PVUnionArrayPtr; - - -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<pvInt>(); --
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 variant union then any type is allowed and the -subfield name is normally any. -If it is not a variant 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);
- virtual std::ostream& dumpValue(std::ostream& o) const;
-};
-
-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 -template 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
-
- PVFieldPtr getSubFieldT(std::string const &fieldName) const;
-
- template<typename PVT>
- std::tr1::shared_ptr<PVT> getSubFieldT(std::string const &fieldName) const
-
- PVFieldPtr getSubFieldT(std::size_t fieldOffset) const;
-
- template<typename PVT>
- std::tr1::shared_ptr<PVT> getSubFieldT(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() {}
- virtual ArrayConstPtr getArray() const
- 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;
- ...
-}
-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<>
-class epicsShareClass PVValueArray<PVUnionPtr> : public detail::PVVectorStorage<PVUnionPtr,PVArray>
-{
- typedef detail::PVVectorStorage<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<PVUnionPtr> svector;
- typedef ::epics::pvData::shared_vector<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:
-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 if the element types do not match or calls the -other copy functions. The arguments are:
-An exception is thrown if:
--Often a field named "value" has 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 hierarchy 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 nanoseconds part is normalized, -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);
-};
-
-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);
- 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
-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 efficiency 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 constructor, or default -assignment constructor.
-/* 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 implement
- 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 available.
-
-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 network.
-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 contiguous 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 -completes 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 iterations 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 knowledge 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:
-