pvMisc
- BitSetUtil
- MultiChoice
@@ -195,12 +195,12 @@ CONTENTS
license described at the end of this document.
PVData is one of a set of related projects: pvData, pvAccess, and javaIOC.
-It describes and implements the data that the other project use. Thus it is not
-useful by itself but understanding pvData is required in order to understand
-the other projects. The reader should also become familar with pvAccess and
-javaIOC, which are located via the same sourceforge site as this project.
-Project PVAccess provides network support for transporting pvData. Project
-javaIOC provides a memory resident "smart" database of pvData data.
+It describes and implements the data that the other projects use. Thus it is
+not useful by itself but understanding pvData is required in order to
+understand the other projects. The reader should also become familar with
+pvAccess and javaIOC, which are located via the same sourceforge site as this
+project. Project PVAccess provides network support for transporting pvData.
+Project javaIOC provides a memory resident "smart" database of pvData data.
This document describes the C++ implementation of pvData, which was first
implemented in Java. A C++ implementation of pvAccess is being developed in
@@ -215,20 +215,21 @@ store, access, and transmit memory resident structured data.
description of pvData.
- implementation
- Directory factory provides a complete C++ definition for pvData. It
- also proivides abstract and base classes that support specialized
+ also provides abstract and base classes that support specialized
implementations of the data classes.
- efficient
- Small memory footprint, low cpu overhead, and concise code base.
- data storage
- - pvData defines separate introspection and data interfaces. The
- introspection interfaces provide access to immutable objects, which
- allows introspection instances to be freely shared. The introspection
- interface for a process variable can be accessed without requiring access
- to the data.
+ - pvData provides introspection and data interfaces. The introspection
+ interfaces provide access to immutable objects, which allows
+ introspection instances to be freely shared. The introspection interface
+ for a process variable can be accessed without requiring access to the
+ data.
- data access
- Client code can access pvData via the introspection and data
interfaces. For "well known" data, e.g. timeStamp, specialized interfaces
- can be provided without requiring any changes to the core software.
+ can be implemented without requiring any changes to the core
+ software.
- data transfer
- The separation of introspection and data interfaces allows for
efficient network data transfer. At connection time introspection
@@ -247,7 +248,7 @@ store, access, and transmit memory resident structured data.
array is a one dimensional array of structures where each element has the
same introspection interface. Since a field can have type structure
complex structures are supported. No other types are needed since
- structures can be defined that simulate complex types.
+ structures can be defined that simulate types.
The javaIOC implements a Process Variable (PV) Database, which is a memory
@@ -296,7 +297,7 @@ pvDataApp:
This section describes a meta language for describing pvData. Currently
there are no plans for a parser for the meta language. It is used for
documentation. Also the toString introspection and data methods described below
-do present data in this format.
+present data in this format.
Definition
@@ -360,11 +361,14 @@ line is a comment.
For structure fieldName each
fieldDef must have a unique
fieldName within the structure For structureName fieldName the structureName must be the fieldName of a previously defined
- top level structure
+ style="font-family: courier;">structure
+
+ For structureName fieldName
+ the structureName must be the
+ fieldName of a previously
+ defined top level structure
+
+
- structureArray
- A structureArray field has the definition:
structure[] fieldName
@@ -374,7 +378,7 @@ line is a comment.
Thus a structure array is an array where each element is a structure but
all elements have the same introspection interface. For introspection the
- structureDef appears once without and data valuies.
+ structureDef appears once without any data valuies.
Each field can optionally have data values assigned to it. The definition of
@@ -386,16 +390,16 @@ valid for the type.
false
- byte,...long
- Any valid integer or hex value, e.g. 3 0xff are valid values
+ style="font-family: courier;">3 and 0xff are valid values
- float,double
- - Any valid integer or real e.g. 3
- 3.0 3e0 are valid values
+ - Any valid integer or real e.g. 3,
+ 3.0, and 3e0 are valid values
- string
- The value can be an alphanumeric value or any set of characters
- enclosed in "" Within quotes a
- quote is expressed as \"
- Examples are aValue "a value" "a\"
- xxx" are valid values.
+ enclosed in "". Within quotes,
+ a quote is expressed as \"
+ Examples are aValue "a value" and
+ "a\" xxx" are valid values.
For scalar arrays the syntax is:
@@ -450,7 +454,7 @@ structure[] structureArrayExample
Directory pvDataApp/pv has header files that completely describe pvData. The
implementation is provided in directory pvDataApp/factory. Test programs
-appears on pvDataApp/pvTest.
+appears on testApp/pvTest.
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 PVField or an
@@ -465,14 +469,14 @@ converting and copying data between fields.
Directory pvDataApp/pv has the following header files:
- pvIntrospect.h
- - A cpmplete description of the introspection interfaces.
+ - A complete description of the introspection interfaces.
- pvData.h
- A complete description of the data interfaces.
- convert.h
- - The facility that converts between data fields.
+ - A facility that converts between data fields.
- standardField.h
- - Provides access to introspection interfaces for standard introspection
- structures like timeStamp, alarm, etc.
+ - Provides access to introspection interfaces for standard structures
+ like timeStamp, alarm, etc.
- standardPVField.h
- Cteates data interfaces for standard data structures like timeStamp,
alarm, etc.
@@ -480,14 +484,15 @@ converting and copying data between fields.
Process Variable Reflection
-This subsection describes pvIntrospect.h
+This subsection describes pvIntrospect.h
Given a pvname, which consists of a record name and field name, it is
possible to introspect the field without requiring access to data. The
reflection and data interfaces are separate because the data may not be
-available. For example when a client connects to a PV, 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
+available. For example when a pvAccess client connects to a PV, 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.
@@ -532,7 +537,7 @@ public:
- An array where every element has the same scalar type.
- structure
- A structure where each field has a name and a type. Within a structure
- each field name must be unique but the type can be different.
+ each field name must be unique but the types can be different.
- structureArray
- An array where each element is a structure. Each element has the same
structure introspection interface.
@@ -593,7 +598,9 @@ following:
- Has a name.
- Has a Type.
- - Can be converted to a string.
+ - Can be converted to a string.
+ Can be shared. A reference count is kept. When it becomes 0 the
+ instance is automatically deleted.
- Scalar
@@ -602,8 +609,8 @@ following:
- The element type is a scalarType
- StructureArray
- The field holds an array of structures. Each element has the same
- Structure interspection interface. A client can only get/put entire
- PVStructure elements NOT subfields of array elements.
+ Structure interspection interface. A pvAccess client can only get/put
+ entire PVStructure elements NOT subfields of array elements.
- Structure
- Has fields that can be any of the supported types.
- FieldCreate
@@ -623,6 +630,8 @@ public:
void incReferenceCount() const;
void decReferenceCount() const;
void dumpReferenceCount(StringBuilder buf,int indentLevel) const;
+ virtual bool operator==(const Field& field) const;
+ virtual bool operator!=(const Field& field) const;
protected:
Field(String fieldName,Type type);
virtual ~Field();
@@ -728,27 +737,34 @@ descriptions:
- Adds a report of the the current reference count for this field. If the
field is a structure then dumpReferenceCount is called for each sub
field.
+ - operator==
+ - Returns (false,true) if the two objects (do not,do) have the same
+ values. Thus means the same types and names.
+ - operator!=
+ - Returns (false,true) if the two objects (do,do not) have the same
+ values.
-Scalarhas the methods:
+Scalar has the methods:
- getScalarType
- Get that scalar type.
-ScalarArrayhas the methods:
+ScalarArray has the methods:
- getElementType
- Get the element type.
-StructureArrayhas the methods:
+StructureArray has the
+methods:
- getStructure
- Get the introspection interface that each element shares,
-Structurehas the methods:
+Structure has the methods:
- getNumberFields
- Get the number of immediate subfields.
@@ -761,20 +777,29 @@ descriptions:
- Get the array of introspection interfaces for the field,
-FieldCreatehas the methods:
+FieldCreate has the methods:
- create
- Given a field name and an existing introspection interface create a new
introspection object. The existing introspection interface can be any of
- the allowed types.
+ the allowed types. If the argument field is shared, i.e. has been
+ obtained from an existing oject, then field->incReferenceCount() must
+ be called before this method.
- createScalar
- Create a scalar introspection instance.
- createScalarArray
- Create a scalar array introspection instance.
- createStructure
- - Create a structure introspection instance.
+ - Create a structure introspection instance. The FieldConstPtrArray
+ fields MUST be allocated on the heap NOT on the stack. It will
+ automatically be deleted when the structure instance is deleted. For any
+ element of fields that is shared, i.e. has been obtained from an existing
+ onject, then fields[index]->incReferenceCount() must be called before
+ this method.
- createStructureArray
- - Create a structure array introspection instance.
+ - Create a structure array introspection instance. If the argument
+ structure is shared, i.e. has been obtained from an existing object, then
+ structure->incReferenceCount() must be called before this method.
Standard Fields
@@ -911,7 +936,7 @@ extern StandardField * getStandardField();
- floatAlarm
- doubleAlarm
- enumeratedAlarm
- - The above provide introspection interfaces fot standard properties. See
+
- The above provide introspection interfaces for standard properties. See
the section on Properties for a description of how these are defined.
@@ -1014,8 +1039,11 @@ are:
- renameField
- Rename the field name.
- postPut
- - If this field is a field of a record pvRecordField.postPut() is called.
- If not a field of a record nothing happens.
+ - If a postHandler is registered it is called otherwise no action is
+ taken.
+ - setPostHandler
+ - Set the postHandler for the record. Only a single handler can be
+ registered.
- toString
- Converts the field data to a string. This is mostly for debugging
purposes.
@@ -1288,7 +1316,7 @@ but is important for immutable arrays. For example pvData and the javaIOC
define many enumerated structures where an enumerated structure has two fields:
index and choices. Choices is a PVStringArray that holds the enumerated
choices. Index is a PVInt that is the index of the currently selected choice.
-For many enumerated structures the choices is immutable. Allowing the choices
+For many enumerated structures choices is immutable. Allowing the choices
internal String[] to be shared between all the instances of an enumerated
structure saves on storage. Another reason for allowing shared data is so that
an application which processes an array can be separated into multiple modules
@@ -1625,6 +1653,26 @@ private:
The other methods are similar to the methods for other array types.
+Important Note: Code that calls put must be aware of the fact that
+introsection interfaces are shared. When creating array elements the shared
+introspection interface must be used. The following shows an example:
+
void put(PVStructure* powerSupplyArrayStruct)
+{
+ PVStructurePtrArray structureArray = new PVStructurePtr[3];
+ StructureConstPtr structure =
+ powerSupplyArray->getStructureArray()->getStructure();
+ structure->incReferenceCount();
+ structureArray[0] = pvDataCreate->createPVStructure(0,structure);
+ structure->incReferenceCount();
+ structureArray[1] = pvDataCreate->createPVStructure(0,structure);
+ structure->incReferenceCount();
+ structureArray[2] = pvDataCreate->createPVStructure(0,structure);
+ powerSupplyArray->put(0,3,structureArray,0);
+}
+
+
+Note that incReferenceCount is called before each element is created.
+
PVDataCreate
PVDataCreate is an interface that provides methods that create PVField
@@ -1882,8 +1930,7 @@ Management
Namespace
-All include and definition files in project pvDataCPP appear in namespace:
-
+All code in project pvDataCPP appears in namespace:
namespace epics { namespace pvData {
// ...
}}
@@ -1926,7 +1973,7 @@ changes to pvInterspect.h without any changes to other code.
std::string is used to implement pvString. This works because std::string
implements COW (Copy On Write) semantics. Thus once created a String can be
-treated like an immutable object, which is what pvData require.
+treated like an immutable object, which is what pvData requires.
The remaining definitions are:
@@ -2006,7 +2053,7 @@ private:
Introspection objects are meant to be shared. The constructors and
destructors are all private or protected so that an introspection object can
-only be created via a call to one of the FieldCreate methods described below.
+only be created via a call to one of the FieldCreate methods described abofe.
The introspection implementation, together with AbstractPVField keeps reference
counts and automatically deletes objects when the reference count goes to 0.
Code that uses introspection objects always accesses introspection objects via
@@ -2096,7 +2143,7 @@ be extended. Thus they can only be created via "new" and must be destroyed via
Create an alarm structure the easy way.
StandardPVField *standardPVField = getStandardPVField();
- PVStructure *pvAlarm = standardPVField->alarm(0);
+ PVStructure *pvAlarm = standardPVField->alarm(parent);
Create a PVStructure with field name example that has a double value field
and a timeStamp and alarm. Do it the easy way.
@@ -2123,7 +2170,7 @@ structure hieraracy above a value field it is a property of the value field.
For example the following top level structure has a single value field. The
-value field has propertiess alarm, timeStamp, and display.
+value field has properties alarm, timeStamp, and display.
structure counterOutput
structure alarm
structure timeStamp
@@ -2371,7 +2418,7 @@ execute. This is done as follows:
TimeStamp endTime;
...
startTime.getCurrent();
- // code to measure time
+ // code to be measured for elapsed time
endTime.getCurrent();
double time = TimeStamp::diff(endTime,startTime);
@@ -2781,7 +2828,7 @@ public:
Overview
-Drectory factory has code that implements everything described by the
+
Directory factory has code that implements everything described by the
include files in directory pv
Factories
@@ -3284,7 +3331,7 @@ 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 = Mutex();
+ static Mutex mutex;
Lock xx(&mutex);
if(alreadyInitialized) return;
// initialization
@@ -3542,25 +3589,34 @@ To see an example of how this is implemented look at misc/thread.cpp.
The public methods of ConstructDestructCallback are:
- getConstructName
- - x
+ - Get the name for the facility keeping track of constructor and
+ destructor calls.
- getTotalConstruct
- - x
+ - Get the total number of objects created.
- getTotalDestruct
- - x
+ - Get the total number of objects destroyed.
- getTotalReferenceCount
- - x
+ - For reference counted objects get the total number of current
+ references.
The public methods of ShowConstructDestruct are:
- registerCallback
- - x
+ - Called by code that implements keeping track of constructor and
+ destructor calls. Any of the methods can be null.
- getConstructDestructCallback
- - x
+ - Given the name of a facility get it's ConstructDestructCallback. This
+ returns null if no facility with that name is registered.
- constuctDestructTotals
- - x
+ - Generate a report showing the status of each registered facility.
- showDeleteStaticExit
- - x
+ - Generate a report showing the status of each registered facility. Then
+ call the deleteFunc method of each facility. The delete method normally
+ deletes and object created at initializatuon time. NOTE THAT THIS IS
+ DANGEROUS. It is provided so the test code can be run under a facility,
+ like valgrind, that looks for memory leaks. THIS MUST ONLY BE CALLED
+ IMMEDIATELY BEFORE TERMINATION.
Status
@@ -3568,7 +3624,6 @@ To see an example of how this is implemented look at misc/thread.cpp.
Status provides a way to pass status back to client code. It is new and not
currently used by pvData but may be in the future. It is used by code that uses
pvData.
-NOT IMPLEMENTED
The Status methods are: