diff --git a/documentation/pvDataCPP_20120927.html b/documentation/pvDataCPP_20120927.html deleted file mode 100644 index 8c51250..0000000 --- a/documentation/pvDataCPP_20120927.html +++ /dev/null @@ -1,3584 +0,0 @@ - - - - - - EPICS pvDataCPP - - - - - - - - -
-

EPICS pvDataCPP

- - -

EPICS v4 Working Group, Working Draft, 03-Sep-2012

- -
-
Latest version:
-
pvDataCPP.html -
-
This version:
-
pvDataCPP_20120927.html -
-
Previous version:
-
None.
-
Editors:
-
Marty Kraimer, BNL
-
- -

This product is made available subject to acceptance of the EPICS open source -license.

-
-
- -

Abstract

- -

pvDataCPP is a computer software package for the efficient -storage, access, and communication, of structured data. It is specifically the -C++ implementation of pvData, which is one part of the set of related products in the EPICS -V4 control system programming environment:
-relatedDocumentsV4.html -

- -

Status of this Document

- -

This is the 03-Sep-2012 version of the Java implementation of pvData.

- -

The text describes software which is a complete implementation of pvData as -currently planned by the EPICS V4 Working Group.

- -

The following is a list of unresolved issues for pvDataCPP:

-
-
PVArray
-
The implementation of the different array types (PVBooleanArray, ..., - PVStructureArray) all store the data as a shared pointer holding a - vector. A test case should be created to make sure that vector.size() is - the same as getLength()
-
PVArray Examples
-
The following examples should be provided: 1) use all the get methods. - 2) create an example that makes data available in chunks.
-
pvType Example
-
Create an example of how to use the array typedefs
-
Convert test
-
How can this be better tested?
-
- -
-

Table of Contents

-
-
- - -

Introduction

- -

pvData is one of a set of related projects. It describes and implements the -data that the other projects support. Thus it is not useful by itself but -understanding pvData is required in order to understand the other projects. The -reader should also become familar with projects pvAccess and pvIOC, which are -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:

-
-
Introduction
-
A brief descripton of pvData.
-
PVData Meta Language
-
A language used to describe data.
-
- -

The material in these two chapters is NOT repeated in this documentation.

- -

Doxygen documentation is available at doxygenDoc

- -

Namespace and Memory Management

- -

Namespace

- -

All code in project pvDataCPP appears in namespace:

-
namespace epics { namespace pvData {
-     // ...
-}}
- -

Memory Managemment

- -

pvDataCPP introspection and data objects are designed to be shared. They are -made availiable via std::tr1::shared_ptr. In addition arrays are -implemented via std::vector. The following naming conventions are used -in typedefs:

-
-
Ptr
-
When Ptr appears it stands for std::tr1::shared_ptr.
-
Array
-
When Array appears it stands for std::vector.
-
- -

As an example pvType.h includes the following definitions:

-
typedef std::vector<double> DoubleArray;
-typedef std::tr1::shared_ptr<DoubleArray> DoubleArrayPtr;
-inline double * get(DoubleArray &value)
-{
-    return &value[0];
-}
-inline const double * get(const DoubleArray &value)
-{
-    return static_cast<const double *>(&value[0]);
-}
-typedef std::vector<double>::iterator DoubleArray_iterator;
-typedef std::vector<double>::const_iterator DoubleArray_const_iterator;
- -

where

-
-
DoubleArray
-
This defines a vector for an array of the primitive type "double".
-
DoubleArrayPtr
-
This devices a shared pointer to a vector for an array of the primitive - type "double".
-
get
-
This gets the raw array of doubles that the DoubleArray holds.
-
DoubleArray_iterator
-
This gets a iterator for the DoubleArray.
-
DoubleArray_const_iterator
-
This gets a constant iterator for the DoubleArray.
-
- -

pvDataApp/pv

- -

Overview

- -

Directory pvDataApp/pv has header files that completely describe pvData. The -implementation is provided in directory pvDataApp/factory. Test programs -appears in testApp/pv.

- -

NOTES:

-
-
interface
-
The documention uses the word interface. This is an analogy for - what the Java implementation implements, i. e. package pv provides Java - interfaces. C++ does not have interfaces but directory pv defines classes - with public members that are similar to the Java interfaces. Most of the - implementation is in factory.
-
Naming Convertions
-
The naming convertions for variables, methods, and classes follow the - Java convertions, i. e. class name begin with an upper case letter, - variables and methods begin with a lower case letter.
-
- -

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. This section describes the complete set of C++ -introspection and data interfaces for pvData.

- -

Class FieldCreate creates introspection objects. Class PVDataCreate creates -data objects. Class Convert provides a rich set of methods for converting and -copying data between fields.

- -

Directory pvDataApp/pv has the following header files:

-
-
pvType.h
-
C++ definitions for primitive types.
-
pvIntrospect.h
-
A complete description of the introspection interfaces.
-
pvData.h
-
A complete description of the data interfaces.
-
convert.h
-
A facility that converts between data fields.
-
standardField.h
-
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.
-
- -

pvType.h

- -

This provides C/C++ definitions for the pvData primitive types: boolean, -byte, short, int, long, ubyte,ushort, uint,u long,float, double, and string. -Because pvData is network data, the C++ implementation must implement the -proper semantics for the primitive types.

- -

pvType.h provides the proper semantics.

- -

It has the definitions:

-
typedef uint8_t  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::string String;
-
-/**
- * A boolean array.
- */
-typedef std::vector<uint8> BooleanArray;
-typedef std::tr1::shared_ptr<BooleanArray> BooleanArrayPtr;
-/* get is same is ubyte*/
-typedef std::vector<uint8>::iterator BooleanArray_iterator;
-typedef std::vector<uint8>::const_iterator BooleanArray_const_iterator;
-
-/**
- * A byte array.
- */
-typedef std::vector<int8> ByteArray;
-typedef std::tr1::shared_ptr<ByteArray> ByteArrayPtr;
-inline int8 * get(ByteArray &value);
-inline int8 const * get(ByteArray const &value);
-inline int8 * get(ByteArrayPtr &value);
-inline int8 const * get(ByteArrayPtr const &value);
-inline ByteArray & getVector(ByteArrayPtr &value);
-inline ByteArray const & getVector(ByteArrayPtr const &value);
-typedef std::vector<int8>::iterator ByteArray_iterator;
-typedef std::vector<int8>::const_iterator ByteArray_const_iterator;
-
-/* similar definitions are present for ALL the primitive types */
- -

where

-
-
boolean
-
A c++ bool has the semantics required for boolean. Only the name is - different. C++ code can use either bool or boolean.
-
int8,...,uint64
-
Integers present a problem because short, int, and long are C++ - reserved words but do not have a well defined number of bits. Thus for - C++ the definitions above are used in C++ code. The above definitions - have worked on all C++ implementations tested at present. If they break - in a future implementation they should be changes via "#ifdef" - preprocessor statements.
-
String
-
pvData requires that a string be an immutable string that is transfered - over the network as a UTF8 encoded string. Since std::string implements - copy on write semantics, it can be used for support for immutable - strings. It can also be serialized/deserialized as a UTF8 encoded string. - Because it is not a C++ primitive the first letter is capitalized. This - is the same convention the Java implementation uses.
-
StringBuilder
-
This is defined here because to is used by the toString methods defined - for both introsection and data objects. The definition above acts like - the Java StringBuilder class.
-
Array definitions
-
typedefs are provided for an array of each of the primitive types. Note - that string is treated like a primitive type/
-
- -

pvIntrospect.h

- -

This subsection describes pvIntrospect.h This file is quite big so rather -than showing the entire file, it will be described in parts.

- -

A primary reason 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 pvname if a unique name in the local network.

- -

Given a pvname PV), 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 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.

- -

Type Description

- -

Types are defined as:

-
enum Type {
-    scalar,
-    scalarArray,
-    structure,
-    structureArray;
-};
-
-class TypeFunc {
-public:
-    const char* name(Type);
-    static void toString(StringBuilder buf,const 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(String const &value);
-    const char* name(ScalarType);
-    void toString(StringBuilder buf,ScalarType scalarType);
-};
- -

Type is one of the following:

-
-
scalar
-
A scalar of one of the scalar types.
-
scalarArray
-
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 types can be different.
-
structureArray
-
An array where each element is a structure. Each element has the same - structure introspection interface.
-
- -

ScalarType is one of the following:

-
-
pvBoolean
-
Has the value false or true.
-
pvByte
-
A signed 8 bit integer.
-
pvShort
-
A signed 16 bit integer.
-
pvInt
-
A signed 32 bit integer.
-
pvLong
-
A signed 64 bit integer.
-
pvUByte
-
An unsigned 8 bit integer.
-
pvUShort
-
An unsigned 16 bit integer.
-
pvUInt
-
An unsigned 32 bit integer.
-
pvULong
-
An unsigned 64 bit integer.
-
pvFloat
-
A IEEE float.
-
pvDouble
-
A IEEE double,
-
pvString
-
An immutable string.
-
- -

TypeFunction is a set of convenience methods for Type

-
-
name
-
Returns the name of the type.
-
toString
-
Convert the type to a string.
-
- -

ScalarTypeFunction is a set of convenience methods for ScalarType

-
-
isInteger
-
Is the scalarType an integer type, i.e. one of pvByte,...pvULong.
-
isUInteger
-
Is the scalarType an unsigned integer type, i.e. one of - pvUByte,...pvULong
-
isNumeric
-
Is the scalarType numeric, i.e. pvByte,...,pvDouble.
-
isPrimitive
-
Is the scalarType primitive, i.e. not pvString
-
name
-
Returns the name of the scalarType.
-
getScalarType
-
Given a string of the form String("boolean"),...,String("string") - return the scalarType.
-
toString
-
Convert the scalar type to a string.
-
- -

Introspection Description

- -

This section describes the reflection interfaces which provide the -following:

-
-
Field
-
A field: -
    -
  • Has a Type.
    • -
  • Can be converted to a string.
    • -
  • Can be shared. A reference count is kept. When it becomes 0 the - instance is automatically deleted.
    • -
-
-
Scalar
-
A scalar has a scalarType
-
ScalarArray
-
The element type is a scalarType
-
StructureArray
-
The field holds an array of structures. Each element has the same - 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
-
This is an interface that provides methods to create introspection - interfaces. A factory is provides to create FieldCreate.
-
getFieldCreate
-
Gets a pointer to the single instance of FieldCreate.
-
-
class Field;
-class Scalar;
-class ScalarArray;
-class Structure;
-class StructureArray;
-
-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;
-
-
-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 String getID() const = 0;
-    virtual void toString(StringBuilder buf) const{toString(buf,0);}
-    virtual void toString(StringBuilder buf,int indentLevel) const;
- ...
-};
-
-class Scalar : public Field{
-public:
-    POINTER_DEFINITIONS(Scalar);
-    virtual ~Scalar();
-    typedef Scalar& reference;
-    typedef const Scalar& const_reference;
-
-    ScalarType getScalarType() const {return scalarType;}
-    virtual void toString(StringBuilder buf) const{toString(buf,0);}
-    virtual void toString(StringBuilder buf,int indentLevel) const;
-    virtual void toString(StringBuilder buf,int indentLevel) const;
-    virtual String getID() const;
-    virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
-    virtual void deserialize(ByteBuffer *buffer, DeserializableContol *control);
- ...
-};
-
-class ScalarArray : public Field{
-public:
-    POINTER_DEFINITIONS(ScalarArray);
-    typedef ScalarArray& reference;
-    typedef const ScalarArray& const_reference;
-
-    ScalarType  getElementType() const {return elementType;}
-    virtual void toString(StringBuilder buf) const{toString(buf,0);}
-    virtual void toString(StringBuilder buf,int indentLevel) const;
-    virtual String getID() const;
-    virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
-    virtual void deserialize(ByteBuffer *buffer, DeserializableControl *control);
- ...
-};
-
-class StructureArray : public Field{
-public:
-    POINTER_DEFINITIONS(StructureArray);
-    typedef StructureArray& reference;
-    typedef const StructureArray& const_reference;
-
-    StructureConstPtr  getStructure() const {return pstructure;}
-    virtual void toString(StringBuilder buf,int indentLevel=0) const;
-    virtual String getID() 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(String const & fieldName) const;
-   FieldConstPtr getField(std::size_t index) const;
-   std::size_t getFieldIndex(String const &fieldName) const;
-   FieldConstPtrArray const & getFields() const {return fields;}
-   StringArray const & getFieldNames() const;
-   void renameField(std::size_t fieldIndex,String const &newName);
-   String getFieldName(std::size_t fieldIndex);
-   virtual void toString(StringBuilder buf,int indentLevel) const;
-   virtual String getID() const;
-   virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
-   virtual void deserialize(ByteBuffer *buffer, DeserializableControl *control);
- ...
-};
-
-class FieldCreate  {
-public:
-    static FieldCreatePtr getFieldCreate();
-    ScalarConstPtr  createScalar(ScalarType scalarType) const
-    ScalarArrayConstPtr createScalarArray(ScalarType elementType) const;
-    StructureArrayConstPtr createStructureArray(StructureConstPtr const & structure) const;
-    StructureConstPtr createStructure (
-        StringArray const & fieldNames,
-        FieldConstPtrArray const & fields) const;
-    StructureConstPtr createStructure (
-        String const &id,
-        StringArray const & fieldNames,
-        FieldConstPtrArray const & fields) const;
-    StructureConstPtr appendField(
-        StructureConstPtr const & structure,
-        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;
- ...
-};
-
-extern FieldCreatePtr getFieldCreate();
-
-
Constructor
-
Note that all constructors are protected or private. The only way to - create instances is via FieldCreate. The implementation manages all - storage via shared pointers.
-
toString
-
Many classes provide this (actually two methods). This method is called - to get a string that uses the metadata syntax described in a previous - section.
-
- -
Field
-
-
getType
-
Get the field type.
-
getID
-
Get an ID for this introspection interface
-
- -
Scalar
-
-
getScalarType
-
Get that scalar type.
-
getID
-
For each scalarType there is one instance of Scalar. The ID for each is - the metadata name for the type, i. e. one of "boolean" , ... , "string". -
-
- -
ScalarArray
-
-
getElementType
-
Get the element type.
-
getID
-
For each elemnetType there is one instance of ScalarArray. The ID for - each is the metadata name for the type, i. e. one of "boolean[]" , ... , - "string[]".
-
- -
StructureArray
-
-
getStructure
-
Get the introspection interface that each element shares,
-
getID
-
This returns the ID[] where ID is the value returned by - structure->getID().
-
- -
Structure
-
-
getNumberFields
-
Get the number of immediate subfields.
-
getField
-
Given a name or an index get the introspection interface for the - field.
-
getFieldIndex
-
Given a name get the index, within the array returned by the next - method, of the field.
-
getFields
-
Get the array of introspection interfaces for the field,
-
getFieldNames
-
Get the array of field names for the subfields.
-
renameField
-
Rename the field.
-
getFieldName
-
Get the field name for the specified index.
-
- -
FieldCreate
-
-
getFieldCreate
-
Get the single instance of FieldCreate.
-
createScalar
-
Create a scalar introspection instance.
-
createScalarArray
-
Create a scalar array introspection instance.
-
createStructure
-
Create a structure introspection instance. Two methods are provided - where the only difference is that one provides an ID and the other does - not. The one without will result in ID "structure".
-
createStructureArray
-
Create a structure array introspection instance.
-
appendField
-
Append a field to a structure.
-
appendFields
-
Append fields to a structure.
-
deserialize
-
Deserialize from given byte buffer.
-
- -

standardField.h

- -

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,String const &properties);
-    StructureConstPtr scalarArray(
-        ScalarType elementType, String const &properties);
-    StructureConstPtr structureArray(
-        StructureConstPtr const & structure,String const &properties);
-    StructureConstPtr enumerated();
-    StructureConstPtr enumerated(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();
- ...
-};
-
-
scalar
-
Create a scalar with the specified scalar type and name. A structure - will be created with the first element being a scalar with the specified - scalar type and name value. The other fields in the structure will be the - corresponding property structures.
-
scalarArray
-
Create a scalarArray with each element having the specified scalar type - and name. A structure will be created with the first element being a - scalarArray with name value. The other fields in the structure will be - the corresponding property structures.
-
structureArray
-
Create a structureArray with the specified structure interface and - name. A structure will be created with the first element being a - structureArray with the specified structure interface and name value. The - other fields in the structure will be the corresponding property - structures.
-
structure
-
Create a structure with the specified name and fields specified by - numFields and fields. A structure will be created with the first element - being a structure with the name value and fields specified by numFields - and fields. The other fields in the structure will be the corresponding - property structures.
-
enumerated
-
Create a structure with the specified name and fields for an enumerated - structure. If properties are specified then a structure will be created - with the first element being a structure with the name value and fields - for an enumerated structure. The other fields in the structure will be - the corresponding property structures.
-
alarm
-
timeStamp
-
display
-
control
-
booleanAlarm
-
byteAlarm
-
shortAlarm
-
intAlarm
-
longAlarm
-
floatAlarm
-
doubleAlarm
-
enumeratedAlarm
-
The above provide introspection interfaces for standard properties. See - the section on Properties for a description of how these are defined.
-
- -

pvData.h

- -

This subsection describes pvData.h This file is quite big so rather than -showing the entire file, it will be described in parts.

- -

typedefs

- -

These are typedefs for Array and Ptr for the various pvData class -definitions, i.e. typdefs for "std::vector" and "std::tr1::shared_ptr".

-
class PVAuxInfo;
-class PostHandler;
-
-class PVField;
-class PVScalar;
-
-class PVScalarArray;
-
-class PVStructure;
-class PVStructureArray;
-
-typedef std::tr1::shared_ptr<PVAuxInfo> PVAuxInfoPtr;
-
-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 std::tr1::shared_ptr<PVStructureArray> PVStructureArrayPtrPostHandler
- -

PostHandler is a class that must be implemented by any code that calls -setPostHandler. It's single virtual method. postPut is called whenever -PVField::postPut is called.

-
class PostHandler :
-  public std::tr1::enable_shared_from_this<PostHandler>
-{
-public:
-    POINTER_DEFINITIONS(PostHandler);
-    virtual ~PostHandler(){}
-    virtual void postPut() = 0;
-};
- -

PVField

- -

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 PVField
-: virtual public Serializable,
-  public std::tr1::enable_shared_from_this<PVField>
-{
-public:
-   POINTER_DEFINITIONS(PVField);
-   virtual ~PVField();
-   virtual void message(String message,MessageType messageType);
-   String getFieldName() const ;
-   virtual void setRequester(RequesterPtr const &prequester);
-   std::size_t getFieldOffset() const;
-   std::size_t getNextFieldOffset() const;
-   std::size_t getNumberFields() const;
-   PVAuxInfoPtr & getPVAuxInfo()
-   bool isImmutable() const;
-   virtual void setImmutable();
-   const FieldConstPtr & getField() const ;
-   PVStructure * getParent() const 
-   void replacePVField(const PVFieldPtr&  newPVField);
-   void renameField(String const &newName);
-   void postPut() ;
-   void setPostHandler(PostHandlerPtr const &postHandler);
-   virtual bool equals(PVField &pv);
-   virtual void toString(StringBuilder buf) ;
-   virtual void toString(StringBuilder buf,int indentLevel);
-   std::ostream& dumpValue(std::ostream& o) const;
- ...
-}
- -

The public methods for PVField are:

-
-
~PVField
-
Destructor. Since shared pointers are used it should never be called by - user code.
-
message
-
Code attached to this field can call this method to report - problems.
-
getFieldName
-
Get the field name. If the field is a top level structure the field - name will be an empty string.
-
setRequester
-
Sets a requester to be called when message or getRequesterName are - called. This is only legal for the top level PVField.
-
getFieldOffset
-
Get offset of the PVField field within top level structure. Every field - within the PVStructure has a unique offset. The top level structure has - an offset of 0. The first field within the structure has offset equal to - 1. The other offsets are determined by recursively traversing each - structure of the tree.
-
getNextFieldOffset
-
Get the next offset. If the field is a scalar or array field then this - is just offset + 1. If the field is a structure it is the offset of the - next field after this structure. Thus (nextOffset - offset) is always - equal to the total number of fields within the field.
-
getNumberFields
-
Get the total number of fields in this field. This is nextFieldOffset - - fieldOffset.
-
getPVAuxInfo
-
Get the PVAuxInfo for this field. PVAuxInfo is described below.
-
isImmutable
-
Is the field immutable?
-
setImmutable
-
Make the field immutable. Once a field is immutable it can never be - changed since there is no method to again make it mutable. This is an - important design decision since it allows immutable array fields to share - the internal primitive data array.
-
getField
-
Get the reflection interface for the data.
-
getParent
-
Get the interface for the parent or null if this is the top level - PVStructure.
-
replacePVField
-
Replace the data implementation for the field.
-
renameField
-
Rename the field name.
-
postPut
-
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.
-
equals
-
Compare this field with another field. The result will be true only if - the fields have exactly the same field types and if the data values are - equal.
-
toString
-
Converts the field data to a string. This is mostly for debugging - purposes.
-
dumpValue
-
Method for streams I/O.
-
- -

PVAuxInfo

- -

AuxInfo (Auxillary Information) is information about a field that is -application specific. It will not be available outside the application that -implements the database. In particular it will not be made available to Channel -Access. It is used by the database itself to override the default -implementation of fields. The JavaIOC uses it for attaching support code. -Database Configuration and other tools can use it for configuration -information. Each Field and each PVField can have have an arbitrary number of -auxInfos. An auxInfo is a (key,PVScalar) pair where key is a string.

-
class PVAuxInfo : private NoDefaultMethods {
-public:
-    typedef std::map<String,PVScalarPtr> PVInfoMap;
-    typedef std::map<String,PVScalarPtr>::iterator PVInfoIter;
-    typedef std::pair<String,PVScalarPtr> PVInfoPair;
-
-    PVAuxInfo(PVField *pvField);
-    ~PVAuxInfo();
-    PVField * getPVField();
-    PVScalarPtr createInfo(String const &key,ScalarType scalarType);
-    PVScalarPtr getInfo(String const &key);
-    PVInfoMap & getInfoMap();
-    void toString(StringBuilder buf);
-    void toString(StringBuilder buf,int indentLevel);
- ...
-};
- -

where

-
-
getPVField
-
Get the PVField to which this PVAuxInfo is attached.
-
createInfo
-
Create a new PVScalar of type scalarType.
-
getInfo
-
Get the PVScalar with the specified key.
-
getInfoMap
-
Get the map of all the PVScalars that hold the info.
-
toString
-
Print all the auxInfos
-
- -

PVScalar

- -

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 ;
- ...
-}
- -

where

-
-
getScalar
-
Get the introspection interface for the PVScalar.
-
- -

PVScalarValue

- -

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;
-    virtual ~PVScalarValue() {}
-    virtual T get() const = 0;
-    virtual void put(T value) = 0;
- ...
-}
-
-// PVString is special case, since it implements SerializableArray
-class PVString : public PVScalarValue<String>, SerializableArray {
-public:
-    virtual ~PVString() {}
- ...
-};
- -

where

-
-
get
-
Get the value stored in the object.
-
put
-
Change the value stored in the object.
-
- -

PVArray

- -

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 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;
- ...
-};
-
-
setImmutable
-
Set the data immutable. Note that this is permanent since there is no - methods to make it mutable.
-
getLength
-
Get the current length. This is less than or equal to the capacity.
-
setLength
-
Set the length. If the PVField is not mutable then an exception is - thrown. If this is greater than the capacity setCapacity is called.
-
getCapacity
-
Get the capacity, i.e. this is the size of the underlying data - array.
-
setCapacity
-
Set the capacity. The semantics are implementation dependent but - typical semantics are as follows: If the capacity is not mutable an - exception is thrown. A new data array is created and data is copied from - the old array to the new array.
-
isCapacityMutable
-
Is the capacity mutable
-
setCapacityMutable
-
Specify if the capacity can be changed.
-
setCapacity
-
Set the capaciity.
-
- -

PVArrayData

- -

This is the argument to one of the get methods of PVValueArray.

-
template<typename T>
-class PVArrayData {
-private:
-    std::vector<T> init;
-public:
-    POINTER_DEFINITIONS(PVArrayData);
-    typedef T  value_type;
-    typedef T* pointer;
-    typedef const T* const_pointer;
-    std::vector<T> & data;
-    std::size_t offset;
-    PVArrayData()
-    : data(init)
-    {}
-};
- -

PVScalarArray

- -

PVScalarArray is the base class for scalar array data. PVValueArray is a -templete for the various scalar array data classes. There is a class for each -possible scalar type, i. e. PVBooleanArray, ..., PVStringArray.

-
class PVScalarArray : public PVArray {
-public:
-    POINTER_DEFINITIONS(PVScalarArray);
-    virtual ~PVScalarArray();
-    typedef PVScalarArray &reference;
-    typedef const PVScalarArray& const_reference;
-    const ScalarArrayConstPtr getScalarArray() const ;
-    virtual std::ostream& dumpValue(std::ostream& o, size_t index) const = 0;
- ...
-}
- -

where

-
-
getScalarArray
-
Get the introspection interface.
-
dumpValue
-
Method for streams I/O.
-
- -

PVValueArray

- -

This is a template class plus instances for PVBooleanArray, ..., -PVStringArray.

-
template<typename T>
-class PVValueArray : public PVScalarArray {
-public:
-    POINTER_DEFINITIONS(PVValueArray);
-    typedef T  value_type;
-    typedef T* pointer;
-    typedef const T* const_pointer;
-    typedef PVArrayData<T> ArrayDataType;
-    typedef std::vector<T> vector;
-    typedef const std::vector<T> const_vector;
-    typedef std::tr1::shared_ptr<vector> shared_vector;
-    typedef PVValueArray & reference;
-    typedef const PVValueArray & const_reference;
-
-    virtual ~PVValueArray() {}
-    virtual std::size_t get(
-         std::size_t offset, std::size_t length, ArrayDataType &data) = 0;
-    virtual std::size_t put(std::size_t offset,
-        std::size_t length, const_pointer from, std::size_t fromOffset) = 0;
-    virtual std::size_t put(std::size_t offset,
-        std::size_t length, const_vector &from, std::size_t fromOffset);
-    virtual void shareData(
-         shared_vector const & value,
-         std::size_t capacity,
-         std::size_t length) = 0;
-    virtual pointer get() = 0;
-    virtual pointer get() const = 0;
-    virtual vector const & getVector() = 0;
-    virtual shared_vector const & getSharedVector() = 0;
-    std::ostream& dumpValue(std::ostream& o) const;
-    std::ostream& dumpValue(std::ostream& o, size_t index) const;
-protected:
-    PVValueArray(ScalarArrayConstPtr const & scalar)
-    : PVScalarArray(scalar) {}
-    friend class PVDataCreate;
-};
-
-template<typename T>
-std::size_t PVValueArray<T>::put(
-    std::size_t offset,
-    std::size_t length,
-    const_vector &from,
-    std::size_t fromOffset)
-{ return put(offset,length, &from[0], fromOffset); }
-
-/**
- * Definitions for the various scalarArray types.
- */
-typedef PVArrayData<uint8> BooleanArrayData;
-typedef PVValueArray<uint8> PVBooleanArray;
-typedef std::tr1::shared_ptr<PVBooleanArray> PVBooleanArrayPtr;
-
-typedef PVArrayData<int8> ByteArrayData;
-typedef PVValueArray<int8> PVByteArray;
-typedef std::tr1::shared_ptr<PVByteArray> PVByteArrayPtr;
-
-typedef PVArrayData<int16> ShortArrayData;
-typedef PVValueArray<int16> PVShortArray;
-typedef std::tr1::shared_ptr<PVShortArray> PVShortArrayPtr;
-
-typedef PVArrayData<int32> IntArrayData;
-typedef PVValueArray<int32> PVIntArray;
-typedef std::tr1::shared_ptr<PVIntArray> PVIntArrayPtr;
-
-typedef PVArrayData<int64> LongArrayData;
-typedef PVValueArray<int64> PVLongArray;
-typedef std::tr1::shared_ptr<PVLongArray> PVLongArrayPtr;
-
-typedef PVArrayData<uint8> UByteArrayData;
-typedef PVValueArray<uint8> PVUByteArray;
-typedef std::tr1::shared_ptr<PVUByteArray> PVUByteArrayPtr;
-
-typedef PVArrayData<uint16> UShortArrayData;
-typedef PVValueArray<uint16> PVUShortArray;
-typedef std::tr1::shared_ptr<PVUShortArray> PVUShortArrayPtr;
-
-typedef PVArrayData<uint32> UIntArrayData;
-typedef PVValueArray<uint32> PVUIntArray;
-typedef std::tr1::shared_ptr<PVUIntArray> PVUIntArrayPtr;
-
-typedef PVArrayData<uint64> ULongArrayData;
-typedef PVValueArray<uint64> PVULongArray;
-typedef std::tr1::shared_ptr<PVULongArray> PVULongArrayPtr;
-
-typedef PVArrayData<float> FloatArrayData;
-typedef PVValueArray<float> PVFloatArray;
-typedef std::tr1::shared_ptr<PVFloatArray> PVFloatArrayPtr;
-
-typedef PVArrayData<double> DoubleArrayData;
-typedef PVValueArray<double> PVDoubleArray;
-typedef std::tr1::shared_ptr<PVDoubleArray> PVDoubleArrayPtr;
-
-typedef PVArrayData<String> StringArrayData;
-typedef PVValueArray<String> PVStringArray;
-typedef std::tr1::shared_ptr<PVStringArray> PVStringArrayPtr;
- -

where

-
-
get( std::size_t offset, std::size_t length, ArrayDataType &data) -
-
This method "exposes" it's internal array by setting data.data and - data.offset. The caller is responsible for copying the array elements. - This violates the principle that objects should not expose their internal - data but is done for efficency. For example it makes it possible to copy - between arrays with identical element types without requiring an - intermediate array.
-
put(std::size_t offset, std::size_t length, const_pointer from, - std::size_t fromOffset)
-
Put data into the array. from is a raw array.
-
put(std::size_t offset, std::size_t length, const_vector &from, - std::size_t fromOffset)
-
Put data into the array from a vector holding the raw array.
-
shareData( shared_vector const & value, std::size_t capacity, - std::size_t length)
-
Make the instance share the raw data from value. This is most useful - for immutable arrays. In this case the caller must set the PVArray to be - immutable. In the PVArray is not immutable then it is the applications - responsibility to coordinate access to the array. Again this violates the - principle that objects should not expose their internal data 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 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 that directly access the internal data array of a - PVArray. This can be required for minimizing CPU overhead. In this case - it is the applications responsibility to coordinate access to the - array.
-
get()
-
Get the raw array.
-
getVector()
-
Get the vector holding the raw array.
-
getSharedVector()
-
Get the shared vector holding the data.
-
dumpValue
-
Method for streams I/O.
-
- -

Both get and put return the number of elements actually transfered. The -arguments are:

-
-
offset
-
The offset in the PV array.
-
len
-
The maximum number of elements to transfer. The number actually - transfered will be less than or equal to this value.
-
data
-
Get sets data.data to it's internal array and data.offset to the offset - into the array. The caller is responsible for the actual data - transfer.
-
from
-
The array from which the data is taken. This array is supplied by the - caller
-
fromOffset
-
The offset in from
-
- -

The caller must be prepared to make multiple calls to retrieve or put an -entire array. A caller should accept or put partial arrays. For example the -following reads an entire array:

-
void getArray(PVDoubleArrayPtr & pv,DoubleArray const & to)
-{
-    size_t len = pv->getLength();
-    if(to.size()<len) to.resize(len);
-    DoubleArrayData data;
-    size_t offset = 0;
-    while(offset<len) {
-        size_t num = pv->get(offset,(len-offset),data);
-        DoubleArray &from = data.data;
-        size_t fromOffset = data.offset;
-        for(size_t i=0; i<num; i++) to[i+offset] = from[i + fromOffset];
-        offset += num;
-    }
-}
- -

- -

PVStructure

- -

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(String const &fieldName) const;
-    PVFieldPtr getSubField(std::size_t fieldOffset) const;
-    void appendPVField(
-        String const &fieldName,
-        PVFieldPtr const & pvField);
-    void appendPVFields(
-        StringArray const & fieldNames,
-        PVFieldPtrArray const & pvFields);
-    void removePVField(String const &fieldName);
-    PVBooleanPtr getBooleanField(String const &fieldName) ;
-    PVBytePtr getByteField(String const &fieldName) ;
-    PVShortPtr getShortField(String const &fieldName) ;
-    PVIntPtr getIntField(String const &fieldName) ;
-    PVLongPtr getLongField(String const &fieldName) ;
-    PVUBytePtr getUByteField(String const &fieldName) ;
-    PVUShortPtr getUShortField(String const &fieldName) ;
-    PVUIntPtr getUIntField(String const &fieldName) ;
-    PVULongPtr getULongField(String const &fieldName) ;
-    PVFloatPtr getFloatField(String const &fieldName) ;
-    PVDoublePtr getDoubleField(String const &fieldName) ;
-    PVStringPtr getStringField(String const &fieldName) ;
-    PVStructurePtr getStructureField(String const &fieldName) ;
-    PVScalarArrayPtr getScalarArrayField(
-        String const &fieldName,ScalarType elementType) ;
-    PVStructureArrayPtr getStructureArrayField(String const &fieldName) ;
-    String getExtendsStructureName() const;
-    bool putExtendsStructureName(
-        String const &extendsStructureName);
-    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);
-};
- -

where

-
-
getStructure
-
Get the introspection interface for the structure.
-
getPVFields
-
Returns the array of subfields. The set of subfields must all have - different field names.
-
getSubField(String fieldName)
-
Get a subField of a field. For a PVStructure a non-null result is - returned if fieldName is a field of the PVStructure. The fieldName can be - of the form name.name...
-
getSubField(int fieldOffset)
-
Get the field located a fieldOffset, where fieldOffset is relative to - the top level structure. This returns null if the specified field is not - located within this PVStructure.
-
appendPVField
-
Append pvField to the end of this PVStructure. This should NOT be - called if any code is attached to any of the fields in the top level - structure.
-
appendPVFields
-
Append an array of pvFields to the end of this structure. Note that if - the original number of fields is 0 than pvFields replaces the original. - Thus the caller must NOT reuse pvFields after calling this method. This - should NOT be called if any code is attached to any of the fields in the - top level structure
-
removePVField
-
Remove the specified field from this structure. This should NOT be - called if any code is attached to any of the fields in the top level - structure.
-
getBooleanField
-
Look for fieldName. If found and it has the correct type return the - interface. This and the following methods are convenience methods that - allow a user to get the interface to a subfield without requiring - introspection. fieldName can be of the form name.name...
-
getByteField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getShortField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getIntField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getLongField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getUByteField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getUShortField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getUIntField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getULongField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getFloatField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getDoubleField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getStringField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getStructureField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getScalarArrayField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getStructureArrayField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getExtendsStructureName
-
Get the name of structure that this structure extends.
-
putExtendsStructureName
-
Specify the structure that this structure extends.
-
- -

PVStructureArray

- -

The interface for an array of structures is:

-
typedef PVArrayData<PVStructurePtr> StructureArrayData;
-
-class PVStructureArray : public PVArray
-{
-public:
-    POINTER_DEFINITIONS(PVStructureArray);
-    typedef PVStructurePtr  value_type;
-    typedef PVStructurePtr* pointer;
-    typedef const PVStructurePtr* const_pointer;
-    typedef PVArrayData<PVStructurePtr> ArrayDataType;
-    typedef std::vector<PVStructurePtr> vector;
-    typedef const std::vector<PVStructurePtr> const_vector;
-    typedef std::tr1::shared_ptr<vector> shared_vector;
-    typedef PVStructureArray &reference;
-    typedef const PVStructureArray& const_reference;
-
-    virtual ~PVStructureArray() {}
-    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 std::size_t get(std::size_t offset, std::size_t length,
-        StructureArrayData &data);
-    virtual std::size_t put(std::size_t offset,std::size_t length,
-        const_vector const & from, std::size_t fromOffset);
-    virtual void shareData(
-         shared_vector const & value,
-         std::size_t capacity,
-         std::size_t length);
-    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 pointer get() { return &((*value.get())[0]); }
-    virtual pointer get() const { return &((*value.get())[0]); }
-    virtual vector const & getVector() {return *value;}
-    virtual shared_vector const & getSharedVector() {return value;}
- ...
-}
- -

where

-
-
getStructureArray
-
Get the introspection interface shared by each element.
-
append
-
Create new elements and append them to the end of the array. It returns - the index of the first new element.
-
remove
-
Remove the specfied set of elements. It returns (false,true) if the - elements (were not, were) removed. It will not removed any elements - unless all requested elements exist or are null. Note that this deletes - the element and sets the array element to null. It does not change the - array capacity.
-
compres
-
This moves all null elements and then changes the array capacity. When - done there are no null elements.
-
- -

The other methods are similar to the methods for other array types.

- -

PVDataCreate

- -

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);
-    PVScalarArrayPtr createPVScalarArray(ScalarArrayConstPtr const & scalarArray);
-    PVScalarArrayPtr createPVScalarArray(ScalarType elementType);
-    PVScalarArrayPtr createPVScalarArray(PVScalarArrayPtr const  & scalarArrayToClone);
-    PVStructureArrayPtr createPVStructureArray(StructureArrayConstPtr const & structureArray);
-    PVStructurePtr createPVStructure(StructureConstPtr const & structure);
-    PVStructurePtr createPVStructure(
-        StringArray const & fieldNames,PVFieldPtrArray const & pvFields);
-   PVStructurePtr createPVStructure(PVStructurePtr const & structToClone);
- ...
-};
-
-extern PVDataCreatePtr getPVDataCreate();
- -

where

-
-
createPVField
-
The PVField is created reusing the Field interface. Two methods are - provided. Each calls the corresponding createPVScalar, createPVArray, or - createPVStructure depending in the type of the last argument.
-
createPVScalar
-
Creates an instance of a PVScalar. Three versions are supplied. The - first is passed an introspection interface. The second provides the field - name and the scalarType. The last provides a field name and a PVScalar to - clone. The newly created PVScalar will have the same auxInfos as the - original.
-
createPVScalarArray
-
Create an instance of a PVArray. Three versions are supplied. The first - is passed an introspection interface. The second provides the field name - and the elementType. The last provides a field name and a PVArray to - clone. The newly created PVArray will have the same auxInfos as the - original.
-
createPVStructureArray
-
Create a PVStructureArray. It must be passed a structureToClone. This - will become the Structure interface for ALL elements of the - PVStructureArray. It MUST be used to create any new array elements.
-
createPVStructure
-
Create an instance of a PVStructure. Three methods are provided. The - first method uses a previously created structure introspection interface. - The second uses a PVField array to initialize the sub-fields. - The third initializes the subfields by cloning the fields contained in - structToClone. The newly created sub-fields will have the same values and - auxInfos as the original. If structToClone is null then the new structure - is initialized to have 0 sub-fields.
-
- -

standardPVField.h

- -

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,String const &properties);
-    PVStructurePtr scalarArray(ScalarType elementType, String const &properties);
-    PVStructurePtr structureArray(StructureConstPtr const &structure,String const &properties);
-    PVStructurePtr enumerated(StringArray const &choices);
-    PVStructurePtr enumerated(StringArray const &choices, String const &properties);
- ...
-}
-
-
-extern StandardPVFieldPtr getStandardPVField();
- -

convert.h

- -

NOTE about copying immutable array fields. If an entire immutable array -field is copied to another array that has the same elementType, both offsets -are 0, and the length is the length of the source array, then the shareData -method of the target array is called and the target array is set immutable. -Thus the source and target share the same primitive array.

- -

This section describes the supported conversions between data types.

- -
bool operator==(PVField&, PVField&);
-
-static inline bool operator!=(PVField& a, PVField& b)
-{return !(a==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&);
-
-static inline bool operator!=(const Field& a, const Field& b)
-{return !(a==b);}
-static inline bool operator!=(const Scalar& a, const Scalar& b)
-{return !(a==b);}
-static inline bool operator!=(const ScalarArray& a, const ScalarArray& b)
-{return !(a==b);}
-static inline bool operator!=(const Structure& a, const Structure& b)
-{return !(a==b);}
-static inline bool operator!=(const StructureArray& a, const StructureArray& b)
-{return !(a==b);}
-class Convert;
-typedef std::tr1::shared_ptr<Convert> ConvertPtr;
-
-class Convert {
-public:
-    static ConvertPtr getConvert();
-    ~Convert();
-    void getFullName(StringBuilder buf,PVFieldPtr const & pvField);
-    bool equals(PVFieldPtr const &a,PVFieldPtr const &b);
-    bool equals(PVField &a,PVField &b);
-    void getString(StringBuilder buf,PVFieldPtr const & pvField,int indentLevel);
-    void getString(StringBuilder buf,PVFieldPtr const & pvField);
-    void getString(StringBuilder buf,PVField const * pvField,int indentLevel);
-    void getString(StringBuilder buf,PVField const * pvField);
-    std::size_t fromString(
-        PVStructurePtr const &pv,
-        StringArray const & from,
-        std::size_t fromStartIndex = 0);
-    void fromString(PVScalarPtr const & pv, String const & from);
-    std::size_t fromString(PVScalarArrayPtr const & pv, 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);
-    std::size_t copyScalarArray(
-        PVScalarArrayPtr const & from,
-        std::size_t offset,
-        PVScalarArrayPtr const & to,
-        std::size_t toOffset,
-        std::size_t length);
-    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);
-    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);
-    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);
-    std::size_t toByteArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        int8* to,
-        std::size_t toOffset);
-    std::size_t toShortArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        int16* to,
-        std::size_t toOffset);
-    std::size_t toIntArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        int32* to,
-        std::size_t toOffset);
-    std::size_t toLongArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        int64* to,
-        std::size_t toOffset);
-    std::size_t toUByteArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        uint8* to,
-        std::size_t toOffset);
-    std::size_t toUShortArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        uint16* to,
-        std::size_t toOffset);
-    std::size_t toUIntArray(
-        PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        uint32* to,
-        std::size_t toOffset);
-    std::size_t toULongArray(
-        PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        uint64* to,
-        std::size_t toOffset);
-    std::size_t toFloatArray(
-        PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        float* to,
-        std::size_t toOffset);
-    std::size_t toDoubleArray(
-        PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        double* to, std::size_t
-        toOffset);
-    std::size_t fromByteArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const int8* from, std::size_t fromOffset);
-    std::size_t fromByteArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const ByteArray & from, std::size_t fromOffset);
-    std::size_t fromShortArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const int16* from, std::size_t fromOffset);
-    std::size_t fromShortArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const ShortArray & from, std::size_t fromOffset);
-    std::size_t fromIntArray(
-       PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-       const int32* from, std::size_t fromOffset);
-    std::size_t fromIntArray(
-       PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-       const IntArray & from, std::size_t fromOffset);
-    std::size_t fromLongArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const int64* from, std::size_t fromOffset);
-    std::size_t fromLongArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const LongArray & from, std::size_t fromOffset);
-    std::size_t fromUByteArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const uint8* from, std::size_t fromOffset);
-    std::size_t fromUByteArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const UByteArray & from, std::size_t fromOffset);
-    std::size_t fromUShortArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const uint16* from, std::size_t fromOffset);
-    std::size_t fromUShortArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const UShortArray & from, std::size_t fromOffset);
-    std::size_t fromUIntArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const uint32* from, std::size_t fromOffset);
-    std::size_t fromUIntArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const UIntArray & from, std::size_t fromOffset);
-    std::size_t fromULongArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const uint64* from, std::size_t fromOffset);
-    std::size_t fromULongArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const ULongArray & from, std::size_t fromOffset);
-    std::size_t fromFloatArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const float* from, std::size_t fromOffset);
-    std::size_t fromFloatArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const FloatArray & from, std::size_t fromOffset);
-    std::size_t fromDoubleArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const double* from, std::size_t fromOffset);
-    std::size_t fromDoubleArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const DoubleArray & from, std::size_t fromOffset);
-    void newLine(StringBuilder buf, int indentLevel);
- ...
-}
-
-extern ConvertPtr getConvert();
- -

The array methods all return the number of elements copied or converted. -This can be less than len if the PVField array contains less than len -elements.

- -

newLine is a convenience method for code that implements toString It -generates a newline and inserts blanks at the beginning of the newline.

- -

pvDataApp/property

- -

Definition of Property

- -

Only fields named "value" have properties. A record can have multiple value -fields, which can appear in the top level structure of a record or in a -substructure. All other fields in the structure containing a value field are -considered properties of the value field. The fieldname is also the property -name. The value field can have any type, i.e. scalar, scalarArray, or -structure. Typical property fields are timeStamp, alarm, display, control, and -history. The timeStamp is a special case. If it appears anywhere in the -structure hieraracy above a value field it is a property of the value field.

- -

For example the following top level structure has a single value field. The -value field has properties alarm, timeStamp, and display.

-
structure counterOutput
-    double value
-    alarm_t
-        int severity 0
-        int status 0
-        string message
-    double value
-    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
- -

Standard Properties

- -

The following field names have special meaning, i.e. support properties for -general purpose clients.

-
-
value
-
This is normally defined since most general purpose clients access this - field. All other fields in the structure support or describe the value - field. The type can any supported type but is usually one of the - following: -
-
scalar
-
Any of the scalar types.
-
scalarArray
-
An array with the elementType being a scalar type
-
enumerated structure
-
A structure that includes fields named index and choices. index - is an int that selects a choice. choices is an array of strings - that defines the complete set of choices.
-
other
-
Other structure or array types can also be defined if clients and - support code agree on the meaning. Some examples are: 1) A - structure defining a 2D matrix, 2) A structure defining an image, - 3) A structure that simulates a remote method, ...
-
-
-
timeStamp
-
The timeStamp. The type MUST be a timeStamp structure. Also if the - PVData structure does not have a timeStamp then a search up the parent - tree is made to find a timeStamp.
-
alarm
-
The alarm. The type MUST be an alarm structure.
-
display
-
A display structure as described below. It provides display - characteristics for the value field.
-
control
-
A control structure as described below. It provides control - characteristics for the value field.
-
history
-
Provides a history buffer for the value field. Note that currently - PVData does not define history suppoprt.
-
other
-
Other standard properties can be defined.
-
- -

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:

-
-
input
-
A field with support that changes the value field. This can be - anything. It can be a channel access link. It can obtain a value from - hardware. Etc.
-
valueAlarm
-
A field with support that looks for alarm conditions based on the - value.
-
output
-
A field with support that reads the current value and sends it - somewhere else. This can be anything. It can be a channel access link. It - can write a value to hardware. Etc.
-
- -

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. -

- -

Overview of Property Support

- -

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(String("testMessage"));
-    al.setSeverity(majorAlarm);
-    result = pvAlarm.set(al);
-    assert(result);
-    alarm = pvAlarm.get();
-     ...
-}
- -

timeStamp

- -

A timeStamp is represented by the following structure

-
structure timeStamp
-    long secondsPartEpoch
-    int nanoSeconds
-    int userTag
- -

The Epoch is the posix epoch, i.e. Jan 1, 1970 00:00:00 UTC. Both the -seconds and nanoSeconds are signed integers and thus can be negative. Since the -seconds is kept as a 64 bit integer, it allows for a time much greater than the -present age of the universe. Since the nanoSeconds portion is kept as a 32 bit -integer it is subject to overflow if a value that corresponds to a value that -is greater than a little more than 2 seconds of less that about -2 seconds. The -support code always adjust seconds so that the nanoSecconds part is normlized, -i. e. it has is 0<=nanoSeconds<nanoSecPerSec..

- -

Two header files are provided for manipulating time stamps:

-
-
timeStamp.h
-
Defines a time stamp independent of pvData, i.e. it is a generally - useful class for manipulating timeStamps.
-
pvTimeStamp.h
-
A class that can be attached to a time stamp pvData structure. It - provides get and set methods to get/set a TimeStamp as defined by - timeStamp.h
-
- -

timeStamp.h

- -

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

-
-
TimeStamp()
-
The defauly constuctor. Both seconds and nanoSeconds are set to 0.
-
TimeStamp(int64 secondsPastEpoch,int32 nanoSeconds = 0)
-
A constructor that gives initial values to seconds and nanoseconds.
-
normalize
-
Adjust seconds and nanoSeconds so that - 0<=nanoSeconds<nanoSecPerSec.
-
fromTime_t
-
Set time from standard C time.
-
toTime_t
-
Convert timeStamp to standard C time.
-
getSecondsPastEpoch
-
Get the number of seconds since the epoch.
-
getEpicsSecondsPastEpoch
-
Get the number of EPICS seconds since the epoch. EPICS uses Jan 1, 1990 - 00:00:00 UTC as the epoch.
-
getNanoSeconds
-
Get the number of nanoSeconds. This is always normalized.
-
getUserTag
-
Get the userTag.
-
setUserTag
-
Set the userTag.
-
put(int64 secondsPastEpoch,int32 nanoSeconds = 0)
-
Set the timeStamp value. If necessary it will be normalized.
-
put(int64 milliseconds)
-
Set the timeStamp with a value the is the number of milliSeconds since - the epoch.
-
getCurrent()
-
Set the timeStamp to the current time.
-
toSeconds()
-
Convert the timeStamp to a value that is the number of seconds since - the epocj
-
operator =
-
operator!=
-
operator<=
-
operator<
-
operator>=
-
operator>
-
Standard C++ operators.
-
diff
-
diff = a - b
-
getMilliseconds
-
Get the number of milliseconds since the epoch.
-
- -

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);
- -

pvTimeStamp.h

-
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

-
-
PVTimeStamp
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if a timeStamp - structure is found. It looks first at pvField itself and if is not an - appropriate pvData structure but the field name is value it looks up the - parent structure tree.
-
detach
-
Detach from the pvData structure.
-
isAttached
-
Is there an attachment to a timeStamp structure?
-
get
-
Copies data from the pvData structure to a TimeStamp. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from TimeStamp to the pvData structure. An exception is - thrown if not attached to a pvData structure.
-
- -

alarm

- -

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:

-
-
alarm.h
-
Defines an alarm independent of pvData, i.e. it is a generally useful - class for manipulating alarms.
-
pvAlarm.h
-
A class that can be attached to an alarm pvData structure. It provides - get and set methods to get/set alarm data as defined by alarm.h
-
- -

alarm.h

-
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 StringArray getSeverityNames();
-};
-
-class AlarmStatusFunc {
-public:
-    static AlarmStatus getStatus(int value);
-    static StringArray getStatusNames();
-};
-
-class Alarm {
-public:
-    Alarm();
-    //default constructors and destructor are OK
-    String getMessage();
-    void setMessage(String const &value);
-    AlarmSeverity getSeverity() const;
-    void setSeverity(AlarmSeverity value);
-    AlarmStatus getStatus() const;
-    void setStatus(AlarmStatus value);
-};
- -

Alarm Severity defines the possible alarm severities:

-
-
getSeverity
-
Get the alarm severity corresponding to the integer value.
-
getSeverityNames
-
Get the array of severity choices.
-
- -

Alarm Status defines the possible choices for alarm status:

-
-
getStatus
-
Get the alarm status corresponding to the integer value.
-
getStatusNames
-
Get the array of status choices.
-
- -

Alarm has the methods:

-
-
Alarm
-
The constructor. It sets the severity to no alarm and the message to - "".
-
getMessage
-
Get the message.
-
setMessage
-
Set the message.
-
getSeverity
-
Get the severity.
-
setSeverity
-
Set the severity.
-
getStatus
-
Get the status.
-
setStatus
-
Set the status.
-
- -

pvAlarm.h

-
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

-
-
PVAlarm
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if it found an - appropriate pvData structure. It looks first a pvField itself and if is - not an appropriate pvData structure but the field name is value it looks - to see if the parent structure has an appropriate sub structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to an alarm structure?
-
get
-
Copies data from the pvData structure to an Alarm. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from Alarm to the pvData structure. An exception is thrown - if not attached to a pvData structure.
-
- -

control

- -

Control information is represented by the following structure

-
structure control
-    double limitLow
-    double limitHigh
-    double minStep
- -

Two header files are provided for manipulating control:

-
-
control.h
-
Defines control independent of pvData, i.e. it is a generally useful - class for manipulating control.
-
pvControl.h
-
A class that can be attached to an control pvData structure. It - provides get and set methods to get/set control data as defined by - control.h
-
- -

control.h

-
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

-
-
Control
-
The default constructure.
-
getLow
-
Get the low limit.
-
getHigh
-
Get the high limit.
-
setLow
-
Set the low limit.
-
setHigh
-
Set the high limit.
-
setMinStep
-
Set the minimum step size.
-
getMinStep
-
Get he minimum step size.
-
- -

pvControl.h

-
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

-
-
PVControl
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if it found an - appropriate pvData structure. It looks first a pvField itself and if is - not an appropriate pvData structure but the field name is value it looks - to see if the parent structure has an appropriate sub structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to a control structure?
-
get
-
Copies data from the pvData structure to a Control. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from Control to the pvData structure. An exception is - thrown if not attached to a pvData structure.
-
- -

display

- -

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:

-
-
display.h
-
Defines display independent of pvData, i.e. it is a generally useful - class for manipulating display.
-
pvDisplay.h
-
A class that can be attached to an display pvData structure. It - provides get and set methods to get/set display data as defined by - display.h
-
- -

display.h

-
class Display {
-public:
-    Display();
-    //default constructors and destructor are OK
-    double getLow() const;
-    double getHigh() const;
-    void setLow(double value);
-    void setHigh(double value);
-    String getDescription() const;
-    void setDescription(String const &value);
-    String getFormat() const;
-    void setFormat(String const &value);
-    String getUnits() const;
-    void setUnits(String const &value);
-};
- -

where

-
-
Control
-
The default constructure.
-
getLow
-
Get the low limit.
-
getHigh
-
Get the high limit.
-
setLow
-
Set the low limit.
-
setHigh
-
Set the high limit.
-
getDescription
-
Get the description.
-
setDescription
-
Set the description.
-
getFormat
-
Get the format.
-
setFormat
-
Set the format.
-
getUnits
-
Get the units.
-
setUnits
-
Set the units.
-
- -

pvDisplay.h

-
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

-
-
PVDisplay
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if it found an - appropriate pvData structure. It looks first a pvField itself and if is - not an appropriate pvData structure but the field name is value it looks - to see if the parent structure has an appropriate sub structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to a display structure?
-
get
-
Copies data from the pvData structure to a Display. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from Display to the pvData structure. An exception is - thrown if not attached to a pvData structure.
-
- -

pvEnumerated.h

- -

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();
-    String getChoice();
-    bool choicesMutable();
-    StringArray getChoices();
-    int32 getNumberChoices();
-    bool setChoices(StringArray &choices,int32 numberChoices);
-};
- -

where

-
-
PVEnumerated
-
The default constructor. Attach must be called before any get or set - method can be called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if pvField (is - not, is) an enumerated structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to an enemerated structure?
-
setIndex
-
Set the index field in the pvData structure. An exception is thrown if - not attached to a pvData structure.
-
getIndex
-
Get the index field in the pvData structure.
-
getChoice
-
Get the String value corresponding to the current index field in the - pvData structure. An exception is thrown if not attached to a pvData - structure.
-
choicesMutable
-
Can the choices be changed? Note that this is often true. An exception - is thrown if not attached to a pvData structure.
-
getChoices
-
Get the array of choices. An exception is thrown if not attached to a - pvData structure.
-
getNumberChoices
-
Get the number of choices. An exception is thrown if not attached to a - pvData structure.
-
setChoices
-
Change the choices. An exception is thrown if not attached to a pvData - structure.
-
- -

Examples

- -

Accessing PVData

- -

Assume that code wants to print two fields from a PVStructure:

-
-
value
-
Must be a PVDouble.
-
timeStamp
-
Just look for field with this name.
-
- -

The following code uses introspection to get the desired information.

-
void getValueAndTimeStamp(PVStructurePtr pvStructure,StringBuilder buf) {
-   PVFieldPtr valuePV = pvStructure->getSubField(String("value"));
-   if(valuePV.get()==NULL) {
-       buf += "value field not found";
-       return;
-   }
-   buf += "value ";
-   valuePV->toString(&buf);
-   PVFieldPtr timeStampPV = pvStructure->getSubField(String("timeStamp"));
-   if(timeStampPV.get()==NULL) {
-       buf += "timeStamp field not found";
-       return;
-   }
-   buf += " timeStamp ";
-   timeStampPV->toString(&buf);
-}
- -

Creating PVData

- -

Example of creating a scalar field.

-
    PVDataCreatePtr pvDataCreate = getPVDataCreate();
-    PVDoublePtr pvValue = static_pointer_cast<PVDouble>(
-        pvDataCreate->createPVScalar(pvDouble));
- -

Create a structure with a value and an alarm the hard way

-
    FieldCreatePtr fieldCreate = getFieldCreate();
-    PVDataCreatePtr pvDataCreate = getPVDataCreate();
-    FieldConstPtrArray fields;
-    StringArray names;
-    fields.resize(3);
-    names.resize(3);
-    fields[0] = fieldCreate->createScalar(pvInt);
-    fields[1] = fieldCreate->createScalar(pvInt);
-    fields[2] = fieldCreate->createScalar(pvString);
-    names[0] = "severity";
-    names[0] = "status";
-    names[0] = "message";
-    StructureConstPtr alarmField =  
-        fieldCreate->createStructure(names,fields);
-    fields.resize(2);
-    names.resize(2);
-    fields[0] = fieldCreate->createScalar(pvDouble);
-    fields[1] = alarmField;
-    names[0] = "value";
-    names[0] = "alarm";
-    StructureConstPtr structure =
-        fieldCreate->createStructure(names,fields);
-    PVStructurePtr pv = pvDataCreate->createPVStructure(structure);
- -

Create an alarm structure the easy way.

-
    StandardPVFieldPtr standardPVField = getStandardPVField();
-    PVStructurePtr pv = standardPVField->scalar(pvDouble,"alarm");
- -

Create a PVStructure with field name example that has a double value field , -timeStamp, alarm, and display. Do it the easy way.

-
    StandardPVFieldPtr standardPVField = getStandardPVField();
-    PVStructurePtr pvStructure = standardPVField->scalar(
-        pvDouble,"timeStamp,alarm.display");
- -

pvDataApp/factory

- -

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.

- -

PVAuxInfoImpl.cpp implements auxInfo.

- -

Convert.cpp automatically creates a single instance of Convert and -implements getConvert.

- -

Other files implement PVData base classes

- -

pvDataAPP/misc

- -

Overview

- -

This package provides utility code:

-
-
bitSet.h
-
An implementation of BitSet that can be serialized.
-
byteBuffer.h
-
Used to serialize objects.
-
destroyable.h
-
Provides method destroy.
-
epicsException.h
-
Exception with stack trace.
-
event.h
-
Signal and wait for an event.
-
executor.h
-
Provides a thread for executing commands.
-
lock.h
-
Support for locking and unlocking.
-
messageQueue.h
-
Support for queuing messages to give to requesters.
-
noDefaultMethods.h
-
When privately extended prevents compiler from implementing default - methods.
-
queue.h
-
A queue implementation that allows the latest queue element to continue - to be used when no free element is available.
-
requester.h
-
Allows messages to be sent to a requester.
-
serialize.h
-
Support for serializing objects.
-
serializeHelper.h
-
More support for serializing objects.
-
sharedPtr.h
-
Defines POINTER_DEFINITIONS.
-
status.h
-
A way to pass status information to a client.
-
thread.h
-
Provides thread support.
-
timeFunction.h
-
Time how long a function call requires.
-
timer.h
-
An implementation of Timer that does not require an object to be - created for each timer request.
-
- -

Note that directory testApp/misc has test code for all the classes in misc. -The test code also can be used as examples.

- -

bitSet.h

- -

This is adapted from the java.util.BitSet. bitSet.h is:

-
class BitSet : public Serializable {
-public:
-    static BitSet::shared_pointer create(uint32 nbits);
-    BitSet();
-    BitSet(uint32 nbits);
-    virtual ~BitSet();
-    void flip(uint32 bitIndex);
-    void set(uint32 bitIndex);
-    void clear(uint32 bitIndex);
-    void set(uint32 bitIndex, bool value);
-    bool get(uint32 bitIndex) const;
-    void clear();
-    int32 nextSetBit(uint32 fromIndex) const;
-    int32 nextClearBit(uint32 fromIndex) const;
-    bool isEmpty() const;
-    uint32 cardinality() const;
-    uint32 size() const;
-    BitSet& operator&=(const BitSet& set);
-    BitSet& operator|=(const BitSet& set);
-    BitSet& operator^=(const BitSet& set);
-    BitSet& operator-=(const BitSet& set);
-    BitSet& operator=(const BitSet &set);
-    void or_and(const BitSet& set1, const BitSet& set2);
-    bool operator==(const BitSet &set) const;
-    bool operator!=(const BitSet &set) const;
-    void toString(StringBuilder buffer);
-    void toString(StringBuilder buffer, int indentLevel) const;
-private:
-};
- -

where

-
-
BitSet()
-
Creates a bitSet of initial size 64 bits. All bits initially false.
-
BitSet(uint32 nbits)
-
Creates a bitSet with the initial of the specified number of bits. All - bits initially false.
-
~BitSet()
-
Destructor.
-
flip(uint32 bitIndex)
-
Flip the specified bit.
-
set(uint32 bitIndex)
-
Set the specified bit true.
-
clear(uint32 bitIndex)
-
Set the specified bit false.
-
set(uint32 bitIndex, bool value)
-
Set the specified bit to value.
-
get(uint32 bitIndex)
-
Return the state of the specified bit.
-
clear()
-
Set all bits to false.
-
nextSetBit(uint32 fromIndex)
-
Get the index of the next true bit beginning with the specified - bit.
-
nextClearBit(uint32 fromIndex)
-
Get the index of the next false bit beginning with the specified - bit.
-
isEmpty()
-
Return (false,true) if (at least one bit true, all bits are false)
-
cardinality()
-
Return the number of true bits.
-
size()
-
Returns the number of bits of space actually in use.
-
operator&=(const BitSet& set)
-
Performs a logical and of this target bit set with the argument bit - set. This bit set is modified so that each bit in it has the value true - if and only if it both initially had the value true and the corresponding - bit in the bit set argument also had the value.
-
operator|=(const BitSet& set)
-
Performs a logical or of this target bit set with the argument bit - set.
-
operator^=(const BitSet& set)
-
Performs a logical exclusive or of this target bit set with the - argument bit set.
-
operator-=(const BitSet& set)
-

Clears all of the bits in this bitSet whose corresponding bit is set - in the specified bitSet.

-
-
operator=(const BitSet &set)
-
Assignment operator.
-
or_and(const BitSet& set1, const BitSet& set2)
-
Perform AND operation on set1 and set2, and then OR this bitSet with - the result.
-
operator==(const BitSet &set)
-
Does this bitSet have the same values as the argument.
-
operator!=(const BitSet &set)
-
Is this bitSet different than the argument.
-
toString(StringBuilder buffer)
-
Show the current values of the bitSet.
-
toString(StringBuilder buffer, int indentLevel)
-
Show the current values of the bitSet.
-
virtual void serialize(ByteBuffer *buffer,SerializableControl *flusher) - const;
-
Serialize the bitSet
-
virtual void deserialize(ByteBuffer *buffer,DeserializableControl - *flusher);
-
Deserialize the bitSet.
-
- -

byteBuffer.h

- -

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();
- ...
-};
- -

destroyable.h

-
class Destroyable  {
-public:
-    POINTER_DEFINITIONS(Destroyable);
-    virtual void destroy() = 0;
-    virtual ~Destroyable() {};
-};
- -

epicsException.h

-
/*
- * 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.
- */
- -

event.h

- -

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 */
-private:
-    epicsEventId id;
-};
- -

where

-
-
Event
-
The constructor. The initial value can be full or empty. The normal - first state is empty.
-
signal
-
The event becomes full. The current or next wait will complete.
-
wait
-
Wait until event is full or until timeout. The return value is - (false,true) if the wait completed because event (was not, was) full. A - false value normally means that that a timeout occured. It is also - returned if an error occurs or because the event is being deleted.
-
tryWait
-
returns (false,true) if the event is (empty,full)
-
- -

executor.h

- -

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(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:

-
-
Executor
-
The constructor. A thread name and priority must be specified.
-
~Executor
-
The destructor. If any commands remain in the execute list they are not - called. All ExecutorNodes that have been created are deleted.
-
execute
-
Request that command be executed. If it is already on the run list - nothing is done.
-
- -

lock.h

-
typedef epicsMutex Mutex;
-
-class Lock : private NoDefaultMethods {
-public:
-    explicit Lock(Mutex &pm);
-    ~Lock();
-    void lock();
-    void unlock();
-    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 xx(mutex);
-        if(alreadyInitialized) return;
-        // initialization
-    }
- -

messageQueue.h

- -

Definitions

- -

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:
-    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(String message,MessageType messageType,bool replaceLast);
-    bool isEmpty() ;
-    bool isFull() ;
-    int getClearOverrun();
- ...
-};
- -

A messageNode is a class with two public data members:

-
-
getMessage
-
The message.
-
getMessageType
-
The message type.
-
setMessageNull
-
Set the message to be a null string.
-
- -

A messageQueue is an interface with public methods:

-
-
MessageQueue
-
The constructor. The queue size must be specified.
-
~MessageQueue
-
The destructor.
-
put
-
Put a new message into the queue. False is returned if the queue was - full and true otherwise. If replaceLast is true then the last message is - replaced with this message.
-
get
-
Get the oldest queue element. If the queue is empty null is returned. - Before the next get can be issued release must be called.
-
release
-
Release the queue element returned by the last get.
-
isEmpty
-
Is the queue empty?
-
isFull
-
Is the queue full?
-
getClearOverrun
-
Get the number of times put has been called but no free element is - available.
-
- -

Look at miscTest/testMessageQueue.cpp for an example.

- -

noDefaultMethods.h

- -

If a class privately extends this class then the compiler can not create any -of the following: default constructor, default copy constructror, or default -assignment contructor.

-
/* This is based on Item 6 of
- * Effective C++, Third Edition, Scott Meyers
- */
-    class NoDefaultMethods {
-    protected:
-    // allow by derived objects
-    NoDefaultMethods(){};
-    ~NoDefaultMethods(){}
-    private:
-    // do not implment
-    NoDefaultMethods(const NoDefaultMethods&);
-    NoDefaultMethods & operator=(const NoDefaultMethods &);
-    };
- -

queue.h

- -

This provides a queue which has an immutable capacity. When the queue is -full the user code is expected to keep using the current element until a new -free element becomes avalable.

-
template <typename T>
-class Queue
-{   
-public:
-    POINTER_DEFINITIONS(Queue);
-    typedef std::tr1::shared_ptr<T> queueElementPtr;
-    typedef std::vector<queueElementPtr> queueElementPtrArray;
-    Queue(queueElementPtrArray &);
-    virtual ~Queue();
-    void clear();
-    int capacity();
-    int getNumberFree();
-    int getNumberUsed();
-    queueElementPtr & getFree();
-    void setUsed(queueElementPtr &element);
-    queueElementPtr & getUsed();
-    void releaseUsed(queueElementPtr &element);
- ...
-};
- -

testApp/misc/testQueue.cpp provides an example of how to define a queue.

- -

The queue methods are:

-
-
clear
-
Make the queue empty.
-
getNumberFree
-
Get the number of free elements in the queue.
-
capacity
-
Get the capacity, i.e. the maximun number of elements the queue can - hold.
-
getNumberFree
-
Get the number of free elements.
-
getNumberUsed
-
Get the number of elements used.
-
getFree
-
Get the next free element. Null is returned if no free elements are - available. If a non null value is returned then the element belongs to - the caller until setUsed is called.
-
setUsed
-
Set a queue element used. This must be the element returned by the last - call to getFree.
-
getUsed
-
Get the next used element of null if no more used elements are - available.
-
releaseUsed
-
Set a queue element free. This must be the element returned by the last - call to getUsed.
-
- -

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.h

- -

A PVField extends Requester. Requester is present so that when database -errors are found there is someplace to send a message.

-
enum MessageType {
-   infoMessage,warningMessage,errorMessage,fatalErrorMessage
-};
-
-extern String getMessageTypeName(MessageType messageType);
-extern const size_t messageTypeCount;
-class Requester {
-public:
-    POINTER_DEFINITIONS(Requester);
-    virtual ~Requester(){}
-    virtual String getRequesterName() = 0;
-    virtual void message(String const & message,MessageType messageType) = 0;
-};
- -

where

-
-
-
MessageType
-
Type of message.
-
messageTypeName
-
An array of strings of the message type names, i.e. - String("info"),String("warning"),String("error"),String("fatalError").
-
getRequesterName
-
Returns the requester name.
-
message
-
Gives a message to the requester.
-
- -

serialize.h

-
    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;
-    };
- -

serializeHelper.h

- -

This is a helper class for serialization, which is required for sending and -receiving pvData over the nerwork.

-
class SerializeHelper : public NoDefaultMethods {
-public:
-    static void writeSize(int s, ByteBuffer* buffer,
-        SerializableControl* flusher);
-    static int readSize(ByteBuffer* buffer,
-        DeserializableControl* control);
-    static void serializeString(const String& value,
-        ByteBuffer* buffer,SerializableControl* flusher);
-    static void serializeSubstring(const String& value, int offset,
-        int count, ByteBuffer* buffer,
-        SerializableControl* flusher);
-    static String deserializeString(ByteBuffer* buffer,
-        DeserializableControl* control);
- ...
-};
- -

where

-
-
writeSize
-
Serialize the size.
-
readSize
-
Deserialize the size.
-
serializeString
-
Serialize a String.
-
serializeSubstring
-
Serialize a substring.
-
deserializeString
-
Deserialize a string.
-
- -

sharedPtr.h

-
#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;
- -

status.h

- -

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, epics::pvData::String const & message);
-    Status(StatusType type, epics::pvData::String const & message, epics::pvData::String stackDump);
-    ~Status()
-    StatusType getType() const;
-    String getMessage() const;
-    String getStackDump() const;
-    bool isOK() const;
-    bool isSuccess() const;
-    String toString() const;
-    void toString(StringBuilder buffer, int indentLevel = 0) const;
-    void serialize(ByteBuffer *buffer, SerializableControl *flusher) const;
-    void serialize(ByteBuffer *buffer, SerializableControl *flusher) const;
-};
- -

The Status methods are:

-
-
StatusType
-
An enum for the status type.
-
getType
-
Get the statusType.
-
getMessage
-
Get a message explaining the error.
-
getStackDump
-
Get a stack dump.
-
- -

The StatusCreate methods are:

-
-
getStatusOK
-
Get a singleton that returns StatusType.OK and a null message and - stackDump.
-
createStatus
-
Create a new Status.
-
deserializeStatus
-
Use this method instead of Status.deserialize(), since this allows OK - status optimization.
-
- -

thread.h

- -

ThreadPriority

-
enum ThreadPriority {
-    lowestPriority,
-    lowerPriority,
-    lowPriority,
-    middlePriority,
-    highPriority,
-    higherPriority,
-    highestPriority
-};
- -

Thread

-
class Runnable {
-public:
-    virtual void run() = 0;
-};
-
-class Thread;
-
-class Thread : public epicsThread, private NoDefaultMethods {
-public:
-    Thread(
-        String name,
-        ThreadPriority priority,
-        Runnable *runnableReady,
-        epicsThreadStackSizeClass stkcls=epicsThreadStackSmall);
-    ~Thread();
- ...
-};
- -

Runnable must be implement by code that wants to be run via a thread. It has -one virtual method: run. Run is the code that is run as a thread. When run -compeletes it can not be restarted. If code wants to delete a thread then it -MUST arrange that the run returns before the thread can be deleted. An -exception is thrown if run remains active when delete is called.

- -

Thread has the methods:

-
-
Thread
-
The constructor. A thread name and priority must be specified. The run - methods of runnable is executed. When the run methods returns the thread - will no longer be active but the client code must still delete the - thread.
-
~Thread
-
The destructor. This is called as the result of: - 
    delete pthread;
-
-
- -

timeFunction.h

- -

TimeFunction is a facility that measures the average number of seconds a -function call requires. When timeCall is called, it calls function in a loop. -It starts with a loop of one iteration. If the total elapsed time is less then -.1 seconds it increases the number of iterrations by a factor of 10. It keeps -repeating until the elapsed time is greater than .1 seconds. It returns the -average number of seconds per call.

-
class TimeFunctionRequester;
-class TimeFunction;
-typedef std::tr1::shared_ptr<TimeFunctionRequester> TimeFunctionRequesterPtr;
-typedef std::tr1::shared_ptr<TimeFunction> TimeFunctionPtr;
-        
-class TimeFunctionRequester {
-public:              
-    POINTER_DEFINITIONS(TimeFunctionRequester);
-    virtual ~TimeFunctionRequester(){}
-    virtual void function() = 0;
-};  
-
-    
-class TimeFunction {
-public:    
-    POINTER_DEFINITIONS(TimeFunction);
-    TimeFunction(TimeFunctionRequesterPtr const & requester);
-    ~TimeFunction(); 
-    double timeCall();
- ...
-};
- -

TimeFunctionRequester must be implemented by code that wants to time how -long a function takes. It has the single method:

-
-
function
-
This is the function.
-
- -

TimeFunction has the methods:

-
-
TimeFunction
-
Constructor.
-
~TimeFunction
-
Destructor.
-
timeCall
-
Time how long it takes to execute the function. It starts by calling - the function one time. If it takes < 1 seconds to doubles the number - of times to call the function. It repeats this until it takes at least - one second to call it ntimes.
-
- -

timer.h

- -

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(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 toString(StringBuilder builder);
- ...
-};
- -

TimerCallback must be implemented by the user. It has the following methods: -

-
-
callback
-
This is called when a timer expires. This is called with no locks held. - When called a delay timer is no longer on the queue but a periodioc timer - is on a queue. Thus the callback for a delay timer can issue a new - schedule request but a periodic timer must not. Note the explaination of - TimerNode.cancel below.
-
timerStopped
-
Timer.stop was called when a timer request was queued. or if the timer - is stopped and a schedule request is made.
-
- -

In order to schedule a callback client code must allocate a TimerNode It can -be used to schedule multiple callbacks. It has the methods:

-
-
TimerNode
-
The constructor. User code must create a TimeNode in order to call a - schedule method.
-
~TimerNode
-
The destructor. This is called as a result of the client calling: - 
    delete timerNode;
-
-
cancel
-
This is called to cancel a timer request. If a callback has been - dequeued but the callback not called when cancel is called then a - callback may still happen. New schedule requests can be made after a - cancel request has been made.
-
isScheduled
-
Is the timerNode scheduled to be called.
-
- -

Timer has the methods:

-
-
Timer
-
The consttructor.
-
~Timer
-
The destructor. The queue is emptied and TimerCallback.timerStopped is - called for each element of the queue.
-
scheduleAfterDelay
-
A request to schedule a callback after a delay specified in - seconds.
-
schedulePeriodic
-
Schedule a periodic callback.
-
- -

pvDataApp/pvMisc

- -

bitSetUtil.h

- -

The following is also provided:

-
class BitSetUtil : private NoDefaultMethods {
-public:
-    static bool compress(BitSet *bitSet,PVStructure *pvStructure);
-};
- -

This provides functions that operate on a BitSet for a PVStructure. It -currently has only one method:

-
-
compress
-
Compress the bits in a BitSet related to a structure.
- For each structure: -
    -
  1. If the bit for the structure is set then the bit for all subfields - of the structure are cleared.
    2. -
  2. If the bit for the structure is not set but all immediate subfields - have their bit set then the bit for the structure is set and the bits - for all subfields are cleared.
    3. -
- Note that this is a recursive algorithm. That is if every immediate - subfield has it's offset bit set then the bits for ALL fields that reside - in the structure will be cleared.
-
Channel Access can call this before sending data. It can then pass - entire structures if the structure offset bit is set.
-
-
- - diff --git a/documentation/pvDataCPP_20121001.html b/documentation/pvDataCPP_20121001.html deleted file mode 100644 index ab2cc27..0000000 --- a/documentation/pvDataCPP_20121001.html +++ /dev/null @@ -1,3622 +0,0 @@ - - - - - - EPICS pvDataCPP - - - - - - - - -
-

EPICS pvDataCPP

- - -

EPICS v4 Working Group, Working Draft, 01-Oct-2012

- -
-
Latest version:
-
pvDataCPP.html -
-
This version:
-
pvDataCPP_20121001.html -
-
Previous version:
-
pvDataCPP_20120927.html -
-
Editors:
-
Marty Kraimer, BNL
-
- -

This product is made available subject to acceptance of the EPICS open source -license.

-
-
- -

Abstract

- -

pvDataCPP is a computer software package for the efficient -storage, access, and communication, of structured data. It is specifically the -C++ implementation of pvData, which is one part of the set of related products in the EPICS -V4 control system programming environment:
-relatedDocumentsV4.html -

- -

Status of this Document

- -

This is the 01-Oct-2012 version of the C++ implementation of pvData.

- -

The text describes software which is a complete implementation of pvData as -currently planned by the EPICS V4 Working Group.

- -

The following is a list of unresolved issues for pvDataCPP:

-
-
PVArray
-
The implementation of the different array types (PVBooleanArray, ..., - PVStructureArray) all store the data as a shared pointer holding a - vector. A test case should be created to make sure that vector.size() is - the same as getLength()
-
PVArray Examples
-
The following examples should be provided: 1) use all the get methods. - 2) create an example that makes data available in chunks.
-
pvType Example
-
Create an example of how to use the array typedefs
-
Convert test
-
How can this be better tested?
-
Structure and PVStructure
-
These two classes still keep data via std::vector. - Should they keep it as std::tr1::shared_ptr<std::vector<... ?
- In particular change -
-class Structure
-...
-StringArray fieldNames;
-FieldConstPtrArray fields
-
-class PVStructure
-...
-PVFieldPtrArray pvFields;
-
-To -
-class Structure
-...
-StringArrayPtr fieldNames;
-FieldConstPtrArrayPtr fields
-
-class PVStructure
-...
-PVFieldPtrArrayPtr pvFields;
-
-If these are changed several methods also change so that raw vectors are never passed as -argument or returned from methods.
-
- -
-

Table of Contents

-
-
- - -

Introduction

- -

pvData is one of a set of related projects. It describes and implements the -data that the other projects support. Thus it is not useful by itself but -understanding pvData is required in order to understand the other projects. The -reader should also become familar with projects pvAccess and pvIOC, which are -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:

-
-
Introduction
-
A brief descripton of pvData.
-
PVData Meta Language
-
A language used to describe data.
-
- -

The material in these two chapters is NOT repeated in this documentation.

- -

Doxygen documentation is available at doxygenDoc

- -

Namespace and Memory Management

- -

Namespace

- -

All code in project pvDataCPP appears in namespace:

-
namespace epics { namespace pvData {
-     // ...
-}}
- -

Memory Managemment

- -

pvDataCPP introspection and data objects are designed to be shared. They are -made availiable via std::tr1::shared_ptr. In addition arrays are -implemented via std::vector. The following naming conventions are used -in typedefs:

-
-
Ptr
-
When Ptr appears it stands for std::tr1::shared_ptr.
-
Array
-
When Array appears it stands for std::vector.
-
- -

As an example pvType.h includes the following definitions:

-
typedef std::vector<double> DoubleArray;
-typedef std::tr1::shared_ptr<DoubleArray> DoubleArrayPtr;
-inline double * get(DoubleArray &value)
-{
-    return &value[0];
-}
-inline const double * get(const DoubleArray &value)
-{
-    return static_cast<const double *>(&value[0]);
-}
-typedef std::vector<double>::iterator DoubleArray_iterator;
-typedef std::vector<double>::const_iterator DoubleArray_const_iterator;
- -

where

-
-
DoubleArray
-
This defines a vector for an array of the primitive type "double".
-
DoubleArrayPtr
-
This devices a shared pointer to a vector for an array of the primitive - type "double".
-
get
-
This gets the raw array of doubles that the DoubleArray holds.
-
DoubleArray_iterator
-
This gets a iterator for the DoubleArray.
-
DoubleArray_const_iterator
-
This gets a constant iterator for the DoubleArray.
-
- -

pvDataApp/pv

- -

Overview

- -

Directory pvDataApp/pv has header files that completely describe pvData. The -implementation is provided in directory pvDataApp/factory. Test programs -appears in testApp/pv.

- -

NOTES:

-
-
interface
-
The documention uses the word interface. This is an analogy for - what the Java implementation implements, i. e. package pv provides Java - interfaces. C++ does not have interfaces but directory pv defines classes - with public members that are similar to the Java interfaces. Most of the - implementation is in factory.
-
Naming Convertions
-
The naming convertions for variables, methods, and classes follow the - Java convertions, i. e. class name begin with an upper case letter, - variables and methods begin with a lower case letter.
-
- -

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. This section describes the complete set of C++ -introspection and data interfaces for pvData.

- -

Class FieldCreate creates introspection objects. Class PVDataCreate creates -data objects. Class Convert provides a rich set of methods for converting and -copying data between fields.

- -

Directory pvDataApp/pv has the following header files:

-
-
pvType.h
-
C++ definitions for primitive types.
-
pvIntrospect.h
-
A complete description of the introspection interfaces.
-
pvData.h
-
A complete description of the data interfaces.
-
convert.h
-
A facility that converts between data fields.
-
standardField.h
-
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.
-
- -

pvType.h

- -

This provides C/C++ definitions for the pvData primitive types: boolean, -byte, short, int, long, ubyte,ushort, uint,u long,float, double, and string. -Because pvData is network data, the C++ implementation must implement the -proper semantics for the primitive types.

- -

pvType.h provides the proper semantics.

- -

It has the definitions:

-
typedef uint8_t  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::string String;
-
-/**
- * A boolean array.
- */
-typedef std::vector<uint8> BooleanArray;
-typedef std::tr1::shared_ptr<BooleanArray> BooleanArrayPtr;
-/* get is same is ubyte*/
-typedef std::vector<uint8>::iterator BooleanArray_iterator;
-typedef std::vector<uint8>::const_iterator BooleanArray_const_iterator;
-
-/**
- * A byte array.
- */
-typedef std::vector<int8> ByteArray;
-typedef std::tr1::shared_ptr<ByteArray> ByteArrayPtr;
-inline int8 * get(ByteArray &value);
-inline int8 const * get(ByteArray const &value);
-inline int8 * get(ByteArrayPtr &value);
-inline int8 const * get(ByteArrayPtr const &value);
-inline ByteArray & getVector(ByteArrayPtr &value);
-inline ByteArray const & getVector(ByteArrayPtr const &value);
-typedef std::vector<int8>::iterator ByteArray_iterator;
-typedef std::vector<int8>::const_iterator ByteArray_const_iterator;
-
-/* similar definitions are present for ALL the primitive types */
- -

where

-
-
boolean
-
A c++ bool has the semantics required for boolean. Only the name is - different. C++ code can use either bool or boolean.
-
int8,...,uint64
-
Integers present a problem because short, int, and long are C++ - reserved words but do not have a well defined number of bits. Thus for - C++ the definitions above are used in C++ code. The above definitions - have worked on all C++ implementations tested at present. If they break - in a future implementation they should be changes via "#ifdef" - preprocessor statements.
-
String
-
pvData requires that a string be an immutable string that is transfered - over the network as a UTF8 encoded string. Since std::string implements - copy on write semantics, it can be used for support for immutable - strings. It can also be serialized/deserialized as a UTF8 encoded string. - Because it is not a C++ primitive the first letter is capitalized. This - is the same convention the Java implementation uses.
-
StringBuilder
-
This is defined here because to is used by the toString methods defined - for both introsection and data objects. The definition above acts like - the Java StringBuilder class.
-
Array definitions
-
typedefs are provided for an array of each of the primitive types. Note - that string is treated like a primitive type/
-
- -

pvIntrospect.h

- -

This subsection describes pvIntrospect.h This file is quite big so rather -than showing the entire file, it will be described in parts.

- -

A primary reason 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 pvname if a unique name in the local network.

- -

Given a pvname PV), 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 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.

- -

Type Description

- -

Types are defined as:

-
enum Type {
-    scalar,
-    scalarArray,
-    structure,
-    structureArray;
-};
-
-class TypeFunc {
-public:
-    const char* name(Type);
-    static void toString(StringBuilder buf,const 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(String const &value);
-    const char* name(ScalarType);
-    void toString(StringBuilder buf,ScalarType scalarType);
-};
- -

Type is one of the following:

-
-
scalar
-
A scalar of one of the scalar types.
-
scalarArray
-
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 types can be different.
-
structureArray
-
An array where each element is a structure. Each element has the same - structure introspection interface.
-
- -

ScalarType is one of the following:

-
-
pvBoolean
-
Has the value false or true.
-
pvByte
-
A signed 8 bit integer.
-
pvShort
-
A signed 16 bit integer.
-
pvInt
-
A signed 32 bit integer.
-
pvLong
-
A signed 64 bit integer.
-
pvUByte
-
An unsigned 8 bit integer.
-
pvUShort
-
An unsigned 16 bit integer.
-
pvUInt
-
An unsigned 32 bit integer.
-
pvULong
-
An unsigned 64 bit integer.
-
pvFloat
-
A IEEE float.
-
pvDouble
-
A IEEE double,
-
pvString
-
An immutable string.
-
- -

TypeFunction is a set of convenience methods for Type

-
-
name
-
Returns the name of the type.
-
toString
-
Convert the type to a string.
-
- -

ScalarTypeFunction is a set of convenience methods for ScalarType

-
-
isInteger
-
Is the scalarType an integer type, i.e. one of pvByte,...pvULong.
-
isUInteger
-
Is the scalarType an unsigned integer type, i.e. one of - pvUByte,...pvULong
-
isNumeric
-
Is the scalarType numeric, i.e. pvByte,...,pvDouble.
-
isPrimitive
-
Is the scalarType primitive, i.e. not pvString
-
name
-
Returns the name of the scalarType.
-
getScalarType
-
Given a string of the form String("boolean"),...,String("string") - return the scalarType.
-
toString
-
Convert the scalar type to a string.
-
- -

Introspection Description

- -

This section describes the reflection interfaces which provide the -following:

-
-
Field
-
A field: -
    -
  • Has a Type.
    • -
  • Can be converted to a string.
    • -
  • Can be shared. A reference count is kept. When it becomes 0 the - instance is automatically deleted.
    • -
-
-
Scalar
-
A scalar has a scalarType
-
ScalarArray
-
The element type is a scalarType
-
StructureArray
-
The field holds an array of structures. Each element has the same - 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
-
This is an interface that provides methods to create introspection - interfaces. A factory is provides to create FieldCreate.
-
getFieldCreate
-
Gets a pointer to the single instance of FieldCreate.
-
-
class Field;
-class Scalar;
-class ScalarArray;
-class Structure;
-class StructureArray;
-
-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;
-
-
-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 String getID() const = 0;
-    virtual void toString(StringBuilder buf) const{toString(buf,0);}
-    virtual void toString(StringBuilder buf,int indentLevel) const;
- ...
-};
-
-class Scalar : public Field{
-public:
-    POINTER_DEFINITIONS(Scalar);
-    virtual ~Scalar();
-    typedef Scalar& reference;
-    typedef const Scalar& const_reference;
-
-    ScalarType getScalarType() const {return scalarType;}
-    virtual void toString(StringBuilder buf) const{toString(buf,0);}
-    virtual void toString(StringBuilder buf,int indentLevel) const;
-    virtual String getID() const;
-    virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
-    virtual void deserialize(ByteBuffer *buffer, DeserializableContol *control);
- ...
-};
-
-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 void toString(StringBuilder buf) const{toString(buf,0);}
-    virtual void toString(StringBuilder buf,int indentLevel) const;
-    virtual String getID() const;
-    virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
-    virtual void deserialize(ByteBuffer *buffer, DeserializableControl *control);
- ...
-};
-
-class StructureArray : public Field{
-public:
-    POINTER_DEFINITIONS(StructureArray);
-    typedef StructureArray& reference;
-    typedef const StructureArray& const_reference;
-
-    StructureConstPtr  getStructure() const {return pstructure;}
-    virtual void toString(StringBuilder buf,int indentLevel=0) const;
-    virtual String getID() 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(String const & fieldName) const;
-   FieldConstPtr getField(std::size_t index) const;
-   std::size_t getFieldIndex(String const &fieldName) const;
-   FieldConstPtrArray const & getFields() const {return fields;}
-   StringArray const & getFieldNames() const;
-   void renameField(std::size_t fieldIndex,String const &newName);
-   String getFieldName(std::size_t fieldIndex);
-   virtual void toString(StringBuilder buf,int indentLevel) const;
-   virtual String getID() const;
-   virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
-   virtual void deserialize(ByteBuffer *buffer, DeserializableControl *control);
- ...
-};
-
-class FieldCreate  {
-public:
-    static FieldCreatePtr getFieldCreate();
-    ScalarConstPtr  createScalar(ScalarType scalarType) const
-    ScalarArrayConstPtr createScalarArray(ScalarType elementType) const;
-    StructureArrayConstPtr createStructureArray(StructureConstPtr const & structure) const;
-    StructureConstPtr createStructure (
-        StringArray const & fieldNames,
-        FieldConstPtrArray const & fields) const;
-    StructureConstPtr createStructure (
-        String const &id,
-        StringArray const & fieldNames,
-        FieldConstPtrArray const & fields) const;
-    StructureConstPtr appendField(
-        StructureConstPtr const & structure,
-        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;
- ...
-};
-
-extern FieldCreatePtr getFieldCreate();
-
-
Constructor
-
Note that all constructors are protected or private. The only way to - create instances is via FieldCreate. The implementation manages all - storage via shared pointers.
-
toString
-
Many classes provide this (actually two methods). This method is called - to get a string that uses the metadata syntax described in a previous - section.
-
- -
Field
-
-
getType
-
Get the field type.
-
getID
-
Get an ID for this introspection interface
-
- -
Scalar
-
-
getScalarType
-
Get that scalar type.
-
getID
-
For each scalarType there is one instance of Scalar. The ID for each is - the metadata name for the type, i. e. one of "boolean" , ... , "string". -
-
- -
ScalarArray
-
-
getElementType
-
Get the element type.
-
getID
-
For each elemnetType there is one instance of ScalarArray. The ID for - each is the metadata name for the type, i. e. one of "boolean[]" , ... , - "string[]".
-
- -
StructureArray
-
-
getStructure
-
Get the introspection interface that each element shares,
-
getID
-
This returns the ID[] where ID is the value returned by - structure->getID().
-
- -
Structure
-
-
getNumberFields
-
Get the number of immediate subfields.
-
getField
-
Given a name or an index get the introspection interface for the - field.
-
getFieldIndex
-
Given a name get the index, within the array returned by the next - method, of the field.
-
getFields
-
Get the array of introspection interfaces for the field,
-
getFieldNames
-
Get the array of field names for the subfields.
-
renameField
-
Rename the field.
-
getFieldName
-
Get the field name for the specified index.
-
- -
FieldCreate
-
-
getFieldCreate
-
Get the single instance of FieldCreate.
-
createScalar
-
Create a scalar introspection instance.
-
createScalarArray
-
Create a scalar array introspection instance.
-
createStructure
-
Create a structure introspection instance. Two methods are provided - where the only difference is that one provides an ID and the other does - not. The one without will result in ID "structure".
-
createStructureArray
-
Create a structure array introspection instance.
-
appendField
-
Append a field to a structure.
-
appendFields
-
Append fields to a structure.
-
deserialize
-
Deserialize from given byte buffer.
-
- -

standardField.h

- -

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,String const &properties);
-    StructureConstPtr scalarArray(
-        ScalarType elementType, String const &properties);
-    StructureConstPtr structureArray(
-        StructureConstPtr const & structure,String const &properties);
-    StructureConstPtr enumerated();
-    StructureConstPtr enumerated(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();
- ...
-};
-
-
scalar
-
Create a scalar with the specified scalar type and name. A structure - will be created with the first element being a scalar with the specified - scalar type and name value. The other fields in the structure will be the - corresponding property structures.
-
scalarArray
-
Create a scalarArray with each element having the specified scalar type - and name. A structure will be created with the first element being a - scalarArray with name value. The other fields in the structure will be - the corresponding property structures.
-
structureArray
-
Create a structureArray with the specified structure interface and - name. A structure will be created with the first element being a - structureArray with the specified structure interface and name value. The - other fields in the structure will be the corresponding property - structures.
-
structure
-
Create a structure with the specified name and fields specified by - numFields and fields. A structure will be created with the first element - being a structure with the name value and fields specified by numFields - and fields. The other fields in the structure will be the corresponding - property structures.
-
enumerated
-
Create a structure with the specified name and fields for an enumerated - structure. If properties are specified then a structure will be created - with the first element being a structure with the name value and fields - for an enumerated structure. The other fields in the structure will be - the corresponding property structures.
-
alarm
-
timeStamp
-
display
-
control
-
booleanAlarm
-
byteAlarm
-
shortAlarm
-
intAlarm
-
longAlarm
-
floatAlarm
-
doubleAlarm
-
enumeratedAlarm
-
The above provide introspection interfaces for standard properties. See - the section on Properties for a description of how these are defined.
-
- -

pvData.h

- -

This subsection describes pvData.h This file is quite big so rather than -showing the entire file, it will be described in parts.

- -

typedefs

- -

These are typedefs for Array and Ptr for the various pvData class -definitions, i.e. typdefs for "std::vector" and "std::tr1::shared_ptr".

-
class PVAuxInfo;
-class PostHandler;
-
-class PVField;
-class PVScalar;
-
-class PVScalarArray;
-
-class PVStructure;
-class PVStructureArray;
-
-typedef std::tr1::shared_ptr<PVAuxInfo> PVAuxInfoPtr;
-
-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 std::tr1::shared_ptr<PostHandler> PostHandlerPtr
- -

PostHandler is a class that must be implemented by any code that calls -setPostHandler. It's single virtual method. postPut is called whenever -PVField::postPut is called.

-
class PostHandler :
-  public std::tr1::enable_shared_from_this<PostHandler>
-{
-public:
-    POINTER_DEFINITIONS(PostHandler);
-    virtual ~PostHandler(){}
-    virtual void postPut() = 0;
-};
- -

PVField

- -

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 PVField
-: virtual public Serializable,
-  public std::tr1::enable_shared_from_this<PVField>
-{
-public:
-   POINTER_DEFINITIONS(PVField);
-   virtual ~PVField();
-   virtual void message(String message,MessageType messageType);
-   String getFieldName() const ;
-   virtual void setRequester(RequesterPtr const &prequester);
-   std::size_t getFieldOffset() const;
-   std::size_t getNextFieldOffset() const;
-   std::size_t getNumberFields() const;
-   PVAuxInfoPtr & getPVAuxInfo()
-   bool isImmutable() const;
-   virtual void setImmutable();
-   const FieldConstPtr & getField() const ;
-   PVStructure * getParent() const 
-   void replacePVField(const PVFieldPtr&  newPVField);
-   void renameField(String const &newName);
-   void postPut() ;
-   void setPostHandler(PostHandlerPtr const &postHandler);
-   virtual bool equals(PVField &pv);
-   virtual void toString(StringBuilder buf) ;
-   virtual void toString(StringBuilder buf,int indentLevel);
-   std::ostream& dumpValue(std::ostream& o) const;
- ...
-}
- -

The public methods for PVField are:

-
-
~PVField
-
Destructor. Since shared pointers are used it should never be called by - user code.
-
message
-
Code attached to this field can call this method to report - problems.
-
getFieldName
-
Get the field name. If the field is a top level structure the field - name will be an empty string.
-
setRequester
-
Sets a requester to be called when message or getRequesterName are - called. This is only legal for the top level PVField.
-
getFieldOffset
-
Get offset of the PVField field within top level structure. Every field - within the PVStructure has a unique offset. The top level structure has - an offset of 0. The first field within the structure has offset equal to - 1. The other offsets are determined by recursively traversing each - structure of the tree.
-
getNextFieldOffset
-
Get the next offset. If the field is a scalar or array field then this - is just offset + 1. If the field is a structure it is the offset of the - next field after this structure. Thus (nextOffset - offset) is always - equal to the total number of fields within the field.
-
getNumberFields
-
Get the total number of fields in this field. This is nextFieldOffset - - fieldOffset.
-
getPVAuxInfo
-
Get the PVAuxInfo for this field. PVAuxInfo is described below.
-
isImmutable
-
Is the field immutable?
-
setImmutable
-
Make the field immutable. Once a field is immutable it can never be - changed since there is no method to again make it mutable. This is an - important design decision since it allows immutable array fields to share - the internal primitive data array.
-
getField
-
Get the reflection interface for the data.
-
getParent
-
Get the interface for the parent or null if this is the top level - PVStructure.
-
replacePVField
-
Replace the data implementation for the field.
-
renameField
-
Rename the field name.
-
postPut
-
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.
-
equals
-
Compare this field with another field. The result will be true only if - the fields have exactly the same field types and if the data values are - equal.
-
toString
-
Converts the field data to a string. This is mostly for debugging - purposes.
-
dumpValue
-
Method for streams I/O.
-
- -

PVAuxInfo

- -

AuxInfo (Auxillary Information) is information about a field that is -application specific. It will not be available outside the application that -implements the database. In particular it will not be made available to Channel -Access. It is used by the database itself to override the default -implementation of fields. The JavaIOC uses it for attaching support code. -Database Configuration and other tools can use it for configuration -information. Each Field and each PVField can have have an arbitrary number of -auxInfos. An auxInfo is a (key,PVScalar) pair where key is a string.

-
class PVAuxInfo : private NoDefaultMethods {
-public:
-    typedef std::map<String,PVScalarPtr> PVInfoMap;
-    typedef std::map<String,PVScalarPtr>::iterator PVInfoIter;
-    typedef std::pair<String,PVScalarPtr> PVInfoPair;
-
-    PVAuxInfo(PVField *pvField);
-    ~PVAuxInfo();
-    PVField * getPVField();
-    PVScalarPtr createInfo(String const &key,ScalarType scalarType);
-    PVScalarPtr getInfo(String const &key);
-    PVInfoMap & getInfoMap();
-    void toString(StringBuilder buf);
-    void toString(StringBuilder buf,int indentLevel);
- ...
-};
- -

where

-
-
getPVField
-
Get the PVField to which this PVAuxInfo is attached.
-
createInfo
-
Create a new PVScalar of type scalarType.
-
getInfo
-
Get the PVScalar with the specified key.
-
getInfoMap
-
Get the map of all the PVScalars that hold the info.
-
toString
-
Print all the auxInfos
-
- -

PVScalar

- -

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 ;
- ...
-}
- -

where

-
-
getScalar
-
Get the introspection interface for the PVScalar.
-
- -

PVScalarValue

- -

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;
-    virtual ~PVScalarValue() {}
-    virtual T get() const = 0;
-    virtual void put(T value) = 0;
- ...
-}
-
-// PVString is special case, since it implements SerializableArray
-class PVString : public PVScalarValue<String>, SerializableArray {
-public:
-    virtual ~PVString() {}
- ...
-};
- -

where

-
-
get
-
Get the value stored in the object.
-
put
-
Change the value stored in the object.
-
- -

PVArray

- -

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 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;
- ...
-};
-
-
setImmutable
-
Set the data immutable. Note that this is permanent since there is no - methods to make it mutable.
-
getLength
-
Get the current length. This is less than or equal to the capacity.
-
setLength
-
Set the length. If the PVField is not mutable then an exception is - thrown. If this is greater than the capacity setCapacity is called.
-
getCapacity
-
Get the capacity, i.e. this is the size of the underlying data - array.
-
setCapacity
-
Set the capacity. The semantics are implementation dependent but - typical semantics are as follows: If the capacity is not mutable an - exception is thrown. A new data array is created and data is copied from - the old array to the new array.
-
isCapacityMutable
-
Is the capacity mutable
-
setCapacityMutable
-
Specify if the capacity can be changed.
-
setCapacity
-
Set the capaciity.
-
- -

PVArrayData

- -

This is the argument to one of the get methods of PVValueArray.

-
template<typename T>
-class PVArrayData {
-private:
-    std::vector<T> init;
-public:
-    POINTER_DEFINITIONS(PVArrayData);
-    typedef T  value_type;
-    typedef T* pointer;
-    typedef const T* const_pointer;
-    std::vector<T> & data;
-    std::size_t offset;
-    PVArrayData()
-    : data(init)
-    {}
-};
- -

PVScalarArray

- -

PVScalarArray is the base class for scalar array data. PVValueArray is a -templete for the various scalar array data classes. There is a class for each -possible scalar type, i. e. PVBooleanArray, ..., PVStringArray.

-
class PVScalarArray : public PVArray {
-public:
-    POINTER_DEFINITIONS(PVScalarArray);
-    virtual ~PVScalarArray();
-    typedef PVScalarArray &reference;
-    typedef const PVScalarArray& const_reference;
-    const ScalarArrayConstPtr getScalarArray() const ;
-    virtual std::ostream& dumpValue(std::ostream& o, size_t index) const = 0;
- ...
-}
- -

where

-
-
getScalarArray
-
Get the introspection interface.
-
dumpValue
-
Method for streams I/O.
-
- -

PVValueArray

- -

This is a template class plus instances for PVBooleanArray, ..., -PVStringArray.

-
template<typename T>
-class PVValueArray : public PVScalarArray {
-public:
-    POINTER_DEFINITIONS(PVValueArray);
-    typedef T  value_type;
-    typedef T* pointer;
-    typedef const T* const_pointer;
-    typedef PVArrayData<T> ArrayDataType;
-    typedef std::vector<T> vector;
-    typedef const std::vector<T> const_vector;
-    typedef std::tr1::shared_ptr<vector> shared_vector;
-    typedef PVValueArray & reference;
-    typedef const PVValueArray & const_reference;
-
-    virtual ~PVValueArray() {}
-    virtual std::size_t get(
-         std::size_t offset, std::size_t length, ArrayDataType &data) = 0;
-    virtual std::size_t put(std::size_t offset,
-        std::size_t length, const_pointer from, std::size_t fromOffset) = 0;
-    virtual std::size_t put(std::size_t offset,
-        std::size_t length, const_vector &from, std::size_t fromOffset);
-    virtual void shareData(
-         shared_vector const & value,
-         std::size_t capacity,
-         std::size_t length) = 0;
-    virtual pointer get() = 0;
-    virtual pointer get() const = 0;
-    virtual vector const & getVector() = 0;
-    virtual shared_vector const & getSharedVector() = 0;
-    std::ostream& dumpValue(std::ostream& o) const;
-    std::ostream& dumpValue(std::ostream& o, size_t index) const;
-protected:
-    PVValueArray(ScalarArrayConstPtr const & scalar)
-    : PVScalarArray(scalar) {}
-    friend class PVDataCreate;
-};
-
-template<typename T>
-std::size_t PVValueArray<T>::put(
-    std::size_t offset,
-    std::size_t length,
-    const_vector &from,
-    std::size_t fromOffset)
-{ return put(offset,length, &from[0], fromOffset); }
-
-/**
- * Definitions for the various scalarArray types.
- */
-typedef PVArrayData<uint8> BooleanArrayData;
-typedef PVValueArray<uint8> PVBooleanArray;
-typedef std::tr1::shared_ptr<PVBooleanArray> PVBooleanArrayPtr;
-
-typedef PVArrayData<int8> ByteArrayData;
-typedef PVValueArray<int8> PVByteArray;
-typedef std::tr1::shared_ptr<PVByteArray> PVByteArrayPtr;
-
-typedef PVArrayData<int16> ShortArrayData;
-typedef PVValueArray<int16> PVShortArray;
-typedef std::tr1::shared_ptr<PVShortArray> PVShortArrayPtr;
-
-typedef PVArrayData<int32> IntArrayData;
-typedef PVValueArray<int32> PVIntArray;
-typedef std::tr1::shared_ptr<PVIntArray> PVIntArrayPtr;
-
-typedef PVArrayData<int64> LongArrayData;
-typedef PVValueArray<int64> PVLongArray;
-typedef std::tr1::shared_ptr<PVLongArray> PVLongArrayPtr;
-
-typedef PVArrayData<uint8> UByteArrayData;
-typedef PVValueArray<uint8> PVUByteArray;
-typedef std::tr1::shared_ptr<PVUByteArray> PVUByteArrayPtr;
-
-typedef PVArrayData<uint16> UShortArrayData;
-typedef PVValueArray<uint16> PVUShortArray;
-typedef std::tr1::shared_ptr<PVUShortArray> PVUShortArrayPtr;
-
-typedef PVArrayData<uint32> UIntArrayData;
-typedef PVValueArray<uint32> PVUIntArray;
-typedef std::tr1::shared_ptr<PVUIntArray> PVUIntArrayPtr;
-
-typedef PVArrayData<uint64> ULongArrayData;
-typedef PVValueArray<uint64> PVULongArray;
-typedef std::tr1::shared_ptr<PVULongArray> PVULongArrayPtr;
-
-typedef PVArrayData<float> FloatArrayData;
-typedef PVValueArray<float> PVFloatArray;
-typedef std::tr1::shared_ptr<PVFloatArray> PVFloatArrayPtr;
-
-typedef PVArrayData<double> DoubleArrayData;
-typedef PVValueArray<double> PVDoubleArray;
-typedef std::tr1::shared_ptr<PVDoubleArray> PVDoubleArrayPtr;
-
-typedef PVArrayData<String> StringArrayData;
-typedef PVValueArray<String> PVStringArray;
-typedef std::tr1::shared_ptr<PVStringArray> PVStringArrayPtr;
- -

where

-
-
get( std::size_t offset, std::size_t length, ArrayDataType &data) -
-
This method "exposes" it's internal array by setting data.data and - data.offset. The caller is responsible for copying the array elements. - This violates the principle that objects should not expose their internal - data but is done for efficency. For example it makes it possible to copy - between arrays with identical element types without requiring an - intermediate array.
-
put(std::size_t offset, std::size_t length, const_pointer from, - std::size_t fromOffset)
-
Put data into the array. from is a raw array.
-
put(std::size_t offset, std::size_t length, const_vector &from, - std::size_t fromOffset)
-
Put data into the array from a vector holding the raw array.
-
shareData( shared_vector const & value, std::size_t capacity, - std::size_t length)
-
Make the instance share the raw data from value.
- One use is - for immutable arrays. In this case the caller must set the PVArray to be - immutable. In the PVArray is not immutable then it is the applications - responsibility to coordinate access to the array. Again this violates the - principle that objects should not expose their internal data 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 choices is immutable. Allowing the - choices internal String[] to be shared between all the instances of an - enumerated structure saves on storage.
- Another use for shared data is an application which processes an - array via multiple modules. Each accesses the internal data array of a - PVArray. In this case it is the applications responsibility - to coordinate access to the array.
-
get()
-
Get the raw array.
-
getVector()
-
Get the vector holding the raw array.
-
getSharedVector()
-
Get the shared vector holding the data.
-
dumpValue
-
Method for streams I/O.
-
- -

Both get and put return the number of elements actually transfered. The -arguments are:

-
-
offset
-
The offset in the PV array.
-
len
-
The maximum number of elements to transfer. The number actually - transfered will be less than or equal to this value.
-
data
-
Get sets data.data to it's internal array and data.offset to the offset - into the array. The caller is responsible for the actual data - transfer.
-
from
-
The array from which the data is taken. This array is supplied by the - caller
-
fromOffset
-
The offset in from
-
- -

The caller must be prepared to make multiple calls to retrieve or put an -entire array. A caller should accept or put partial arrays. For example the -following reads an entire array:

-
void getArray(PVDoubleArrayPtr & pv,DoubleArray const & to)
-{
-    size_t len = pv->getLength();
-    if(to.size()<len) to.resize(len);
-    DoubleArrayData data;
-    size_t offset = 0;
-    while(offset<len) {
-        size_t num = pv->get(offset,(len-offset),data);
-        DoubleArray &from = data.data;
-        size_t fromOffset = data.offset;
-        for(size_t i=0; i<num; i++) to[i+offset] = from[i + fromOffset];
-        offset += num;
-    }
-}
- -

- -

PVStructure

- -

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(String const &fieldName) const;
-    PVFieldPtr getSubField(std::size_t fieldOffset) const;
-    void appendPVField(
-        String const &fieldName,
-        PVFieldPtr const & pvField);
-    void appendPVFields(
-        StringArray const & fieldNames,
-        PVFieldPtrArray const & pvFields);
-    void removePVField(String const &fieldName);
-    PVBooleanPtr getBooleanField(String const &fieldName) ;
-    PVBytePtr getByteField(String const &fieldName) ;
-    PVShortPtr getShortField(String const &fieldName) ;
-    PVIntPtr getIntField(String const &fieldName) ;
-    PVLongPtr getLongField(String const &fieldName) ;
-    PVUBytePtr getUByteField(String const &fieldName) ;
-    PVUShortPtr getUShortField(String const &fieldName) ;
-    PVUIntPtr getUIntField(String const &fieldName) ;
-    PVULongPtr getULongField(String const &fieldName) ;
-    PVFloatPtr getFloatField(String const &fieldName) ;
-    PVDoublePtr getDoubleField(String const &fieldName) ;
-    PVStringPtr getStringField(String const &fieldName) ;
-    PVStructurePtr getStructureField(String const &fieldName) ;
-    PVScalarArrayPtr getScalarArrayField(
-        String const &fieldName,ScalarType elementType) ;
-    PVStructureArrayPtr getStructureArrayField(String const &fieldName) ;
-    String getExtendsStructureName() const;
-    bool putExtendsStructureName(
-        String const &extendsStructureName);
-    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);
-};
- -

where

-
-
getStructure
-
Get the introspection interface for the structure.
-
getPVFields
-
Returns the array of subfields. The set of subfields must all have - different field names.
-
getSubField(String fieldName)
-
Get a subField of a field. For a PVStructure a non-null result is - returned if fieldName is a field of the PVStructure. The fieldName can be - of the form name.name... - If the field does not exist the a Ptr to a NULL value is returned - without any error message being generated. -
-
getSubField(int fieldOffset)
-
Get the field located a fieldOffset, where fieldOffset is relative to - the top level structure. This returns null if the specified field is not - located within this PVStructure.
-
appendPVField
-
Append pvField to the end of this PVStructure. This should NOT be - called if any code is attached to any of the fields in the top level - structure.
-
appendPVFields
-
Append an array of pvFields to the end of this structure. Note that if - the original number of fields is 0 than pvFields replaces the original. - Thus the caller must NOT reuse pvFields after calling this method. This - should NOT be called if any code is attached to any of the fields in the - top level structure
-
removePVField
-
Remove the specified field from this structure. This should NOT be - called if any code is attached to any of the fields in the top level - structure.
-
getBooleanField
-
Look for fieldName. If found and it has the correct type return the - interface. This and the following methods are convenience methods that - allow a user to get the interface to a subfield without requiring - introspection. fieldName can be of the form name.name... - If the field does not exist or has the wrong type then - message will be called and a Ptr to NULL is returned. -
-
getByteField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getShortField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getIntField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getLongField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getUByteField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getUShortField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getUIntField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getULongField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getFloatField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getDoubleField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getStringField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getStructureField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getScalarArrayField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getStructureArrayField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getExtendsStructureName
-
Get the name of structure that this structure extends.
-
putExtendsStructureName
-
Specify the structure that this structure extends.
-
- -

PVStructureArray

- -

The interface for an array of structures is:

-
typedef PVArrayData<PVStructurePtr> StructureArrayData;
-
-class PVStructureArray : public PVArray
-{
-public:
-    POINTER_DEFINITIONS(PVStructureArray);
-    typedef PVStructurePtr  value_type;
-    typedef PVStructurePtr* pointer;
-    typedef const PVStructurePtr* const_pointer;
-    typedef PVArrayData<PVStructurePtr> ArrayDataType;
-    typedef std::vector<PVStructurePtr> vector;
-    typedef const std::vector<PVStructurePtr> const_vector;
-    typedef std::tr1::shared_ptr<vector> shared_vector;
-    typedef PVStructureArray &reference;
-    typedef const PVStructureArray& const_reference;
-
-    virtual ~PVStructureArray() {}
-    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 std::size_t get(std::size_t offset, std::size_t length,
-        StructureArrayData &data);
-    virtual std::size_t put(std::size_t offset,std::size_t length,
-        const_vector const & from, std::size_t fromOffset);
-    virtual void shareData(
-         shared_vector const & value,
-         std::size_t capacity,
-         std::size_t length);
-    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 pointer get() { return &((*value.get())[0]); }
-    virtual pointer get() const { return &((*value.get())[0]); }
-    virtual vector const & getVector() {return *value;}
-    virtual shared_vector const & getSharedVector() {return value;}
- ...
-}
- -

where

-
-
getStructureArray
-
Get the introspection interface shared by each element.
-
append
-
Create new elements and append them to the end of the array. It returns - the index of the first new element.
-
remove
-
Remove the specfied set of elements. It returns (false,true) if the - elements (were not, were) removed. It will not removed any elements - unless all requested elements exist or are null. Note that this deletes - the element and sets the array element to null. It does not change the - array capacity.
-
compress
-
This moves all null elements and then changes the array capacity. When - done there are no null elements.
-
- -

The other methods are similar to the methods for other array types.

- -

PVDataCreate

- -

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);
-    PVScalarArrayPtr createPVScalarArray(ScalarArrayConstPtr const & scalarArray);
-    PVScalarArrayPtr createPVScalarArray(ScalarType elementType);
-    PVScalarArrayPtr createPVScalarArray(PVScalarArrayPtr const  & scalarArrayToClone);
-    PVStructureArrayPtr createPVStructureArray(StructureArrayConstPtr const & structureArray);
-    PVStructurePtr createPVStructure(StructureConstPtr const & structure);
-    PVStructurePtr createPVStructure(
-        StringArray const & fieldNames,PVFieldPtrArray const & pvFields);
-   PVStructurePtr createPVStructure(PVStructurePtr const & structToClone);
- ...
-};
-
-extern PVDataCreatePtr getPVDataCreate();
- -

where

-
-
createPVField
-
The PVField is created reusing the Field interface. Two methods are - provided. Each calls the corresponding createPVScalar, createPVArray, or - createPVStructure depending in the type of the last argument.
-
createPVScalar
-
Creates an instance of a PVScalar. Three versions are supplied. The - first is passed an introspection interface. The second provides the field - name and the scalarType. The last provides a field name and a PVScalar to - clone. The newly created PVScalar will have the same auxInfos as the - original.
-
createPVScalarArray
-
Create an instance of a PVArray. Three versions are supplied. The first - is passed an introspection interface. The second provides the field name - and the elementType. The last provides a field name and a PVArray to - clone. The newly created PVArray will have the same auxInfos as the - original.
-
createPVStructureArray
-
Create a PVStructureArray. It must be passed a structureToClone. This - will become the Structure interface for ALL elements of the - PVStructureArray. It MUST be used to create any new array elements.
-
createPVStructure
-
Create an instance of a PVStructure. Three methods are provided. The - first method uses a previously created structure introspection interface. - The second uses a PVField array to initialize the sub-fields. - The third initializes the subfields by cloning the fields contained in - structToClone. The newly created sub-fields will have the same values and - auxInfos as the original. If structToClone is null then the new structure - is initialized to have 0 sub-fields.
-
- -

standardPVField.h

- -

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,String const &properties);
-    PVStructurePtr scalarArray(ScalarType elementType, String const &properties);
-    PVStructurePtr structureArray(StructureConstPtr const &structure,String const &properties);
-    PVStructurePtr enumerated(StringArray const &choices);
-    PVStructurePtr enumerated(StringArray const &choices, String const &properties);
- ...
-}
-
-
-extern StandardPVFieldPtr getStandardPVField();
- -

convert.h

- -

NOTE about copying immutable array fields. If an entire immutable array -field is copied to another array that has the same elementType, both offsets -are 0, and the length is the length of the source array, then the shareData -method of the target array is called and the target array is set immutable. -Thus the source and target share the same primitive array.

- -

This section describes the supported conversions between data types.

- -
bool operator==(PVField&, PVField&);
-
-static inline bool operator!=(PVField& a, PVField& b)
-{return !(a==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&);
-
-static inline bool operator!=(const Field& a, const Field& b)
-{return !(a==b);}
-static inline bool operator!=(const Scalar& a, const Scalar& b)
-{return !(a==b);}
-static inline bool operator!=(const ScalarArray& a, const ScalarArray& b)
-{return !(a==b);}
-static inline bool operator!=(const Structure& a, const Structure& b)
-{return !(a==b);}
-static inline bool operator!=(const StructureArray& a, const StructureArray& b)
-{return !(a==b);}
-class Convert;
-typedef std::tr1::shared_ptr<Convert> ConvertPtr;
-
-class Convert {
-public:
-    static ConvertPtr getConvert();
-    ~Convert();
-    void getFullName(StringBuilder buf,PVFieldPtr const & pvField);
-    bool equals(PVFieldPtr const &a,PVFieldPtr const &b);
-    bool equals(PVField &a,PVField &b);
-    void getString(StringBuilder buf,PVFieldPtr const & pvField,int indentLevel);
-    void getString(StringBuilder buf,PVFieldPtr const & pvField);
-    void getString(StringBuilder buf,PVField const * pvField,int indentLevel);
-    void getString(StringBuilder buf,PVField const * pvField);
-    std::size_t fromString(
-        PVStructurePtr const &pv,
-        StringArray const & from,
-        std::size_t fromStartIndex = 0);
-    void fromString(PVScalarPtr const & pv, String const & from);
-    std::size_t fromString(PVScalarArrayPtr const & pv, 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);
-    std::size_t copyScalarArray(
-        PVScalarArrayPtr const & from,
-        std::size_t offset,
-        PVScalarArrayPtr const & to,
-        std::size_t toOffset,
-        std::size_t length);
-    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);
-    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);
-    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);
-    std::size_t toByteArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        int8* to,
-        std::size_t toOffset);
-    std::size_t toShortArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        int16* to,
-        std::size_t toOffset);
-    std::size_t toIntArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        int32* to,
-        std::size_t toOffset);
-    std::size_t toLongArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        int64* to,
-        std::size_t toOffset);
-    std::size_t toUByteArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        uint8* to,
-        std::size_t toOffset);
-    std::size_t toUShortArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        uint16* to,
-        std::size_t toOffset);
-    std::size_t toUIntArray(
-        PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        uint32* to,
-        std::size_t toOffset);
-    std::size_t toULongArray(
-        PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        uint64* to,
-        std::size_t toOffset);
-    std::size_t toFloatArray(
-        PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        float* to,
-        std::size_t toOffset);
-    std::size_t toDoubleArray(
-        PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        double* to, std::size_t
-        toOffset);
-    std::size_t fromByteArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const int8* from, std::size_t fromOffset);
-    std::size_t fromByteArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const ByteArray & from, std::size_t fromOffset);
-    std::size_t fromShortArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const int16* from, std::size_t fromOffset);
-    std::size_t fromShortArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const ShortArray & from, std::size_t fromOffset);
-    std::size_t fromIntArray(
-       PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-       const int32* from, std::size_t fromOffset);
-    std::size_t fromIntArray(
-       PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-       const IntArray & from, std::size_t fromOffset);
-    std::size_t fromLongArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const int64* from, std::size_t fromOffset);
-    std::size_t fromLongArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const LongArray & from, std::size_t fromOffset);
-    std::size_t fromUByteArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const uint8* from, std::size_t fromOffset);
-    std::size_t fromUByteArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const UByteArray & from, std::size_t fromOffset);
-    std::size_t fromUShortArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const uint16* from, std::size_t fromOffset);
-    std::size_t fromUShortArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const UShortArray & from, std::size_t fromOffset);
-    std::size_t fromUIntArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const uint32* from, std::size_t fromOffset);
-    std::size_t fromUIntArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const UIntArray & from, std::size_t fromOffset);
-    std::size_t fromULongArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const uint64* from, std::size_t fromOffset);
-    std::size_t fromULongArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const ULongArray & from, std::size_t fromOffset);
-    std::size_t fromFloatArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const float* from, std::size_t fromOffset);
-    std::size_t fromFloatArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const FloatArray & from, std::size_t fromOffset);
-    std::size_t fromDoubleArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const double* from, std::size_t fromOffset);
-    std::size_t fromDoubleArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const DoubleArray & from, std::size_t fromOffset);
-    void newLine(StringBuilder buf, int indentLevel);
- ...
-}
-
-extern ConvertPtr getConvert();
- -

The array methods all return the number of elements copied or converted. -This can be less than len if the PVField array contains less than len -elements.

- -

newLine is a convenience method for code that implements toString It -generates a newline and inserts blanks at the beginning of the newline.

- -

pvDataApp/property

- -

Definition of Property

- -

Only fields named "value" have properties. A record can have multiple value -fields, which can appear in the top level structure of a record or in a -substructure. All other fields in the structure containing a value field are -considered properties of the value field. The fieldname is also the property -name. The value field can have any type, i.e. scalar, scalarArray, or -structure. Typical property fields are timeStamp, alarm, display, control, and -history. The timeStamp is a special case. If it appears anywhere in the -structure hieraracy above a value field it is a property of the value field.

- -

For example the following top level structure has a single value field. The -value field has properties alarm, timeStamp, and display.

-
structure counterOutput
-    double value
-    alarm_t
-        int severity 0
-        int status 0
-        string message
-    timeStamp_t
-        long secondsPastEpoch
-        int nanoSeconds
-        int userTag
-    display_t
-        double limitLow 0.0
-        double limitHigh 10.0
-        string description "Sample Description"
-        string format "%f"
-        string units volts
- -

The following example has three value fields each with properties alarm and -timeStamp. Voltage, Current, and Power each have a different alarms but all -share the timeStamp.

-
structure powerSupplyValue
-    double value
-    alarm_t
-        int severity 0
-        int status 0
-        string message
-
-structure powerSupplySimple
-    alarm_t
-        int severity 0
-        int status 0
-        string message
-    timeStamp_t
-        long secondsPastEpoch
-        int nanoSeconds
-        int userTag
-    powerSupplyValue_t voltage
-        double value
-        alarm_t
-            int severity 0
-            int status 0
-            string message
-    powerSupplyValue_t power
-        double value
-        alarm_t
-            int severity 0
-            int status 0
-            string message
-    powerSupplyValue_t current
-        double value
-        alarm_t
-            int severity 0
-            int status 0
-            string message
- -

Standard Properties

- -

The following field names have special meaning, i.e. support properties for -general purpose clients.

-
-
value
-
This is normally defined since most general purpose clients access this - field. All other fields in the structure support or describe the value - field. The type can any supported type but is usually one of the - following: -
-
scalar
-
Any of the scalar types.
-
scalarArray
-
An array with the elementType being a scalar type
-
enumerated structure
-
A structure that includes fields named index and choices. index - is an int that selects a choice. choices is an array of strings - that defines the complete set of choices.
-
other
-
Other structure or array types can also be defined if clients and - support code agree on the meaning. Some examples are: 1) A - structure defining a 2D matrix, 2) A structure defining an image, - 3) A structure that simulates a remote method, ...
-
-
-
timeStamp
-
The timeStamp. The type MUST be a timeStamp structure. Also if the - PVData structure does not have a timeStamp then a search up the parent - tree is made to find a timeStamp.
-
alarm
-
The alarm. The type MUST be an alarm structure.
-
display
-
A display structure as described below. It provides display - characteristics for the value field.
-
control
-
A control structure as described below. It provides control - characteristics for the value field.
-
history
-
Provides a history buffer for the value field. Note that currently - PVData does not define history suppoprt.
-
other
-
Other standard properties can be defined.
-
- -

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:

-
-
input
-
A field with support that changes the value field. This can be - anything. It can be a channel access link. It can obtain a value from - hardware. Etc.
-
valueAlarm
-
A field with support that looks for alarm conditions based on the - value.
-
output
-
A field with support that reads the current value and sends it - somewhere else. This can be anything. It can be a channel access link. It - can write a value to hardware. Etc.
-
- -

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. -

- -

Overview of Property Support

- -

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(String("testMessage"));
-    al.setSeverity(majorAlarm);
-    result = pvAlarm.set(al);
-    assert(result);
-    alarm = pvAlarm.get();
-     ...
-}
- -

timeStamp

- -

A timeStamp is represented by the following structure

-
structure timeStamp
-    long secondsPartEpoch
-    int nanoSeconds
-    int userTag
- -

The Epoch is the posix epoch, i.e. Jan 1, 1970 00:00:00 UTC. Both the -seconds and nanoSeconds are signed integers and thus can be negative. Since the -seconds is kept as a 64 bit integer, it allows for a time much greater than the -present age of the universe. Since the nanoSeconds portion is kept as a 32 bit -integer it is subject to overflow if a value that corresponds to a value that -is greater than a little more than 2 seconds of less that about -2 seconds. The -support code always adjust seconds so that the nanoSecconds part is normlized, -i. e. it has is 0<=nanoSeconds<nanoSecPerSec..

- -

Two header files are provided for manipulating time stamps:

-
-
timeStamp.h
-
Defines a time stamp independent of pvData, i.e. it is a generally - useful class for manipulating timeStamps.
-
pvTimeStamp.h
-
A class that can be attached to a time stamp pvData structure. It - provides get and set methods to get/set a TimeStamp as defined by - timeStamp.h
-
- -

timeStamp.h

- -

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

-
-
TimeStamp()
-
The defauly constuctor. Both seconds and nanoSeconds are set to 0.
-
TimeStamp(int64 secondsPastEpoch,int32 nanoSeconds = 0)
-
A constructor that gives initial values to seconds and nanoseconds.
-
normalize
-
Adjust seconds and nanoSeconds so that - 0<=nanoSeconds<nanoSecPerSec.
-
fromTime_t
-
Set time from standard C time.
-
toTime_t
-
Convert timeStamp to standard C time.
-
getSecondsPastEpoch
-
Get the number of seconds since the epoch.
-
getEpicsSecondsPastEpoch
-
Get the number of EPICS seconds since the epoch. EPICS uses Jan 1, 1990 - 00:00:00 UTC as the epoch.
-
getNanoSeconds
-
Get the number of nanoSeconds. This is always normalized.
-
getUserTag
-
Get the userTag.
-
setUserTag
-
Set the userTag.
-
put(int64 secondsPastEpoch,int32 nanoSeconds = 0)
-
Set the timeStamp value. If necessary it will be normalized.
-
put(int64 milliseconds)
-
Set the timeStamp with a value the is the number of milliSeconds since - the epoch.
-
getCurrent()
-
Set the timeStamp to the current time.
-
toSeconds()
-
Convert the timeStamp to a value that is the number of seconds since - the epocj
-
operator =
-
operator!=
-
operator<=
-
operator<
-
operator>=
-
operator>
-
Standard C++ operators.
-
diff
-
diff = a - b
-
getMilliseconds
-
Get the number of milliseconds since the epoch.
-
- -

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);
- -

pvTimeStamp.h

-
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

-
-
PVTimeStamp
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if a timeStamp - structure is found. It looks first at pvField itself and if is not an - appropriate pvData structure but the field name is value it looks up the - parent structure tree.
-
detach
-
Detach from the pvData structure.
-
isAttached
-
Is there an attachment to a timeStamp structure?
-
get
-
Copies data from the pvData structure to a TimeStamp. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from TimeStamp to the pvData structure. An exception is - thrown if not attached to a pvData structure.
-
- -

alarm

- -

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:

-
-
alarm.h
-
Defines an alarm independent of pvData, i.e. it is a generally useful - class for manipulating alarms.
-
pvAlarm.h
-
A class that can be attached to an alarm pvData structure. It provides - get and set methods to get/set alarm data as defined by alarm.h
-
- -

alarm.h

-
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 StringArray getSeverityNames();
-};
-
-class AlarmStatusFunc {
-public:
-    static AlarmStatus getStatus(int value);
-    static StringArray getStatusNames();
-};
-
-class Alarm {
-public:
-    Alarm();
-    //default constructors and destructor are OK
-    String getMessage();
-    void setMessage(String const &value);
-    AlarmSeverity getSeverity() const;
-    void setSeverity(AlarmSeverity value);
-    AlarmStatus getStatus() const;
-    void setStatus(AlarmStatus value);
-};
- -

Alarm Severity defines the possible alarm severities:

-
-
getSeverity
-
Get the alarm severity corresponding to the integer value.
-
getSeverityNames
-
Get the array of severity choices.
-
- -

Alarm Status defines the possible choices for alarm status:

-
-
getStatus
-
Get the alarm status corresponding to the integer value.
-
getStatusNames
-
Get the array of status choices.
-
- -

Alarm has the methods:

-
-
Alarm
-
The constructor. It sets the severity to no alarm and the message to - "".
-
getMessage
-
Get the message.
-
setMessage
-
Set the message.
-
getSeverity
-
Get the severity.
-
setSeverity
-
Set the severity.
-
getStatus
-
Get the status.
-
setStatus
-
Set the status.
-
- -

pvAlarm.h

-
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

-
-
PVAlarm
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if it found an - appropriate pvData structure. It looks first a pvField itself and if is - not an appropriate pvData structure but the field name is value it looks - to see if the parent structure has an appropriate sub structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to an alarm structure?
-
get
-
Copies data from the pvData structure to an Alarm. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from Alarm to the pvData structure. An exception is thrown - if not attached to a pvData structure.
-
- -

control

- -

Control information is represented by the following structure

-
structure control
-    double limitLow
-    double limitHigh
-    double minStep
- -

Two header files are provided for manipulating control:

-
-
control.h
-
Defines control independent of pvData, i.e. it is a generally useful - class for manipulating control.
-
pvControl.h
-
A class that can be attached to an control pvData structure. It - provides get and set methods to get/set control data as defined by - control.h
-
- -

control.h

-
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

-
-
Control
-
The default constructure.
-
getLow
-
Get the low limit.
-
getHigh
-
Get the high limit.
-
setLow
-
Set the low limit.
-
setHigh
-
Set the high limit.
-
setMinStep
-
Set the minimum step size.
-
getMinStep
-
Get he minimum step size.
-
- -

pvControl.h

-
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

-
-
PVControl
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if it found an - appropriate pvData structure. It looks first a pvField itself and if is - not an appropriate pvData structure but the field name is value it looks - to see if the parent structure has an appropriate sub structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to a control structure?
-
get
-
Copies data from the pvData structure to a Control. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from Control to the pvData structure. An exception is - thrown if not attached to a pvData structure.
-
- -

display

- -

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:

-
-
display.h
-
Defines display independent of pvData, i.e. it is a generally useful - class for manipulating display.
-
pvDisplay.h
-
A class that can be attached to an display pvData structure. It - provides get and set methods to get/set display data as defined by - display.h
-
- -

display.h

-
class Display {
-public:
-    Display();
-    //default constructors and destructor are OK
-    double getLow() const;
-    double getHigh() const;
-    void setLow(double value);
-    void setHigh(double value);
-    String getDescription() const;
-    void setDescription(String const &value);
-    String getFormat() const;
-    void setFormat(String const &value);
-    String getUnits() const;
-    void setUnits(String const &value);
-};
- -

where

-
-
Control
-
The default constructure.
-
getLow
-
Get the low limit.
-
getHigh
-
Get the high limit.
-
setLow
-
Set the low limit.
-
setHigh
-
Set the high limit.
-
getDescription
-
Get the description.
-
setDescription
-
Set the description.
-
getFormat
-
Get the format.
-
setFormat
-
Set the format.
-
getUnits
-
Get the units.
-
setUnits
-
Set the units.
-
- -

pvDisplay.h

-
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

-
-
PVDisplay
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if it found an - appropriate pvData structure. It looks first a pvField itself and if is - not an appropriate pvData structure but the field name is value it looks - to see if the parent structure has an appropriate sub structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to a display structure?
-
get
-
Copies data from the pvData structure to a Display. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from Display to the pvData structure. An exception is - thrown if not attached to a pvData structure.
-
- -

pvEnumerated.h

- -

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();
-    String getChoice();
-    bool choicesMutable();
-    StringArray getChoices();
-    int32 getNumberChoices();
-    bool setChoices(StringArray &choices,int32 numberChoices);
-};
- -

where

-
-
PVEnumerated
-
The default constructor. Attach must be called before any get or set - method can be called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if pvField (is - not, is) an enumerated structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to an enemerated structure?
-
setIndex
-
Set the index field in the pvData structure. An exception is thrown if - not attached to a pvData structure.
-
getIndex
-
Get the index field in the pvData structure.
-
getChoice
-
Get the String value corresponding to the current index field in the - pvData structure. An exception is thrown if not attached to a pvData - structure.
-
choicesMutable
-
Can the choices be changed? Note that this is often true. An exception - is thrown if not attached to a pvData structure.
-
getChoices
-
Get the array of choices. An exception is thrown if not attached to a - pvData structure.
-
getNumberChoices
-
Get the number of choices. An exception is thrown if not attached to a - pvData structure.
-
setChoices
-
Change the choices. An exception is thrown if not attached to a pvData - structure.
-
- -

Examples

- -

Accessing PVData

- -

Assume that code wants to print two fields from a PVStructure:

-
-
value
-
Must be a PVDouble.
-
timeStamp
-
Just look for field with this name.
-
- -

The following code uses introspection to get the desired information.

-
void getValueAndTimeStamp(PVStructurePtr pvStructure,StringBuilder buf) {
-   PVFieldPtr valuePV = pvStructure->getSubField(String("value"));
-   if(valuePV.get()==NULL) {
-       buf += "value field not found";
-       return;
-   }
-   buf += "value ";
-   valuePV->toString(&buf);
-   PVFieldPtr timeStampPV = pvStructure->getSubField(String("timeStamp"));
-   if(timeStampPV.get()==NULL) {
-       buf += "timeStamp field not found";
-       return;
-   }
-   buf += " timeStamp ";
-   timeStampPV->toString(&buf);
-}
- -

Creating PVData

- -

Example of creating a scalar field.

-
    PVDataCreatePtr pvDataCreate = getPVDataCreate();
-    PVDoublePtr pvValue = static_pointer_cast<PVDouble>(
-        pvDataCreate->createPVScalar(pvDouble));
- -

Create a structure with a value and an alarm the hard way

-
    FieldCreatePtr fieldCreate = getFieldCreate();
-    PVDataCreatePtr pvDataCreate = getPVDataCreate();
-    FieldConstPtrArray fields;
-    StringArray names;
-    fields.resize(3);
-    names.resize(3);
-    fields[0] = fieldCreate->createScalar(pvInt);
-    fields[1] = fieldCreate->createScalar(pvInt);
-    fields[2] = fieldCreate->createScalar(pvString);
-    names[0] = "severity";
-    names[0] = "status";
-    names[0] = "message";
-    StructureConstPtr alarmField =  
-        fieldCreate->createStructure(names,fields);
-    fields.resize(2);
-    names.resize(2);
-    fields[0] = fieldCreate->createScalar(pvDouble);
-    fields[1] = alarmField;
-    names[0] = "value";
-    names[0] = "alarm";
-    StructureConstPtr structure =
-        fieldCreate->createStructure(names,fields);
-    PVStructurePtr pv = pvDataCreate->createPVStructure(structure);
- -

Create an alarm structure the easy way.

-
    StandardPVFieldPtr standardPVField = getStandardPVField();
-    PVStructurePtr pv = standardPVField->scalar(pvDouble,"alarm");
- -

Create a PVStructure with field name example that has a double value field , -timeStamp, alarm, and display. Do it the easy way.

-
    StandardPVFieldPtr standardPVField = getStandardPVField();
-    PVStructurePtr pvStructure = standardPVField->scalar(
-        pvDouble,"timeStamp,alarm.display");
- -

pvDataApp/factory

- -

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.

- -

PVAuxInfoImpl.cpp implements auxInfo.

- -

Convert.cpp automatically creates a single instance of Convert and -implements getConvert.

- -

Other files implement PVData base classes

- -

pvDataAPP/misc

- -

Overview

- -

This package provides utility code:

-
-
bitSet.h
-
An implementation of BitSet that can be serialized.
-
byteBuffer.h
-
Used to serialize objects.
-
destroyable.h
-
Provides method destroy.
-
epicsException.h
-
Exception with stack trace.
-
event.h
-
Signal and wait for an event.
-
executor.h
-
Provides a thread for executing commands.
-
lock.h
-
Support for locking and unlocking.
-
messageQueue.h
-
Support for queuing messages to give to requesters.
-
noDefaultMethods.h
-
When privately extended prevents compiler from implementing default - methods.
-
queue.h
-
A queue implementation that allows the latest queue element to continue - to be used when no free element is available.
-
requester.h
-
Allows messages to be sent to a requester.
-
serialize.h
-
Support for serializing objects.
-
serializeHelper.h
-
More support for serializing objects.
-
sharedPtr.h
-
Defines POINTER_DEFINITIONS.
-
status.h
-
A way to pass status information to a client.
-
thread.h
-
Provides thread support.
-
timeFunction.h
-
Time how long a function call requires.
-
timer.h
-
An implementation of Timer that does not require an object to be - created for each timer request.
-
- -

Note that directory testApp/misc has test code for all the classes in misc. -The test code also can be used as examples.

- -

bitSet.h

- -

This is adapted from the java.util.BitSet. bitSet.h is:

-
class BitSet : public Serializable {
-public:
-    static BitSet::shared_pointer create(uint32 nbits);
-    BitSet();
-    BitSet(uint32 nbits);
-    virtual ~BitSet();
-    void flip(uint32 bitIndex);
-    void set(uint32 bitIndex);
-    void clear(uint32 bitIndex);
-    void set(uint32 bitIndex, bool value);
-    bool get(uint32 bitIndex) const;
-    void clear();
-    int32 nextSetBit(uint32 fromIndex) const;
-    int32 nextClearBit(uint32 fromIndex) const;
-    bool isEmpty() const;
-    uint32 cardinality() const;
-    uint32 size() const;
-    BitSet& operator&=(const BitSet& set);
-    BitSet& operator|=(const BitSet& set);
-    BitSet& operator^=(const BitSet& set);
-    BitSet& operator-=(const BitSet& set);
-    BitSet& operator=(const BitSet &set);
-    void or_and(const BitSet& set1, const BitSet& set2);
-    bool operator==(const BitSet &set) const;
-    bool operator!=(const BitSet &set) const;
-    void toString(StringBuilder buffer);
-    void toString(StringBuilder buffer, int indentLevel) const;
-private:
-};
- -

where

-
-
BitSet()
-
Creates a bitSet of initial size 64 bits. All bits initially false.
-
BitSet(uint32 nbits)
-
Creates a bitSet with the initial of the specified number of bits. All - bits initially false.
-
~BitSet()
-
Destructor.
-
flip(uint32 bitIndex)
-
Flip the specified bit.
-
set(uint32 bitIndex)
-
Set the specified bit true.
-
clear(uint32 bitIndex)
-
Set the specified bit false.
-
set(uint32 bitIndex, bool value)
-
Set the specified bit to value.
-
get(uint32 bitIndex)
-
Return the state of the specified bit.
-
clear()
-
Set all bits to false.
-
nextSetBit(uint32 fromIndex)
-
Get the index of the next true bit beginning with the specified - bit.
-
nextClearBit(uint32 fromIndex)
-
Get the index of the next false bit beginning with the specified - bit.
-
isEmpty()
-
Return (false,true) if (at least one bit true, all bits are false)
-
cardinality()
-
Return the number of true bits.
-
size()
-
Returns the number of bits of space actually in use.
-
operator&=(const BitSet& set)
-
Performs a logical and of this target bit set with the argument bit - set. This bit set is modified so that each bit in it has the value true - if and only if it both initially had the value true and the corresponding - bit in the bit set argument also had the value.
-
operator|=(const BitSet& set)
-
Performs a logical or of this target bit set with the argument bit - set.
-
operator^=(const BitSet& set)
-
Performs a logical exclusive or of this target bit set with the - argument bit set.
-
operator-=(const BitSet& set)
-

Clears all of the bits in this bitSet whose corresponding bit is set - in the specified bitSet.

-
-
operator=(const BitSet &set)
-
Assignment operator.
-
or_and(const BitSet& set1, const BitSet& set2)
-
Perform AND operation on set1 and set2, and then OR this bitSet with - the result.
-
operator==(const BitSet &set)
-
Does this bitSet have the same values as the argument.
-
operator!=(const BitSet &set)
-
Is this bitSet different than the argument.
-
toString(StringBuilder buffer)
-
Show the current values of the bitSet.
-
toString(StringBuilder buffer, int indentLevel)
-
Show the current values of the bitSet.
-
virtual void serialize(ByteBuffer *buffer,SerializableControl *flusher) - const;
-
Serialize the bitSet
-
virtual void deserialize(ByteBuffer *buffer,DeserializableControl - *flusher);
-
Deserialize the bitSet.
-
- -

byteBuffer.h

- -

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();
- ...
-};
- -

destroyable.h

-
class Destroyable  {
-public:
-    POINTER_DEFINITIONS(Destroyable);
-    virtual void destroy() = 0;
-    virtual ~Destroyable() {};
-};
- -

epicsException.h

-
/*
- * 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.
- */
- -

event.h

- -

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 */
-private:
-    epicsEventId id;
-};
- -

where

-
-
Event
-
The constructor. The initial value can be full or empty. The normal - first state is empty.
-
signal
-
The event becomes full. The current or next wait will complete.
-
wait
-
Wait until event is full or until timeout. The return value is - (false,true) if the wait completed because event (was not, was) full. A - false value normally means that that a timeout occured. It is also - returned if an error occurs or because the event is being deleted.
-
tryWait
-
returns (false,true) if the event is (empty,full)
-
- -

executor.h

- -

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(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:

-
-
Executor
-
The constructor. A thread name and priority must be specified.
-
~Executor
-
The destructor. If any commands remain in the execute list they are not - called. All ExecutorNodes that have been created are deleted.
-
execute
-
Request that command be executed. If it is already on the run list - nothing is done.
-
- -

lock.h

-
typedef epicsMutex Mutex;
-
-class Lock : private NoDefaultMethods {
-public:
-    explicit Lock(Mutex &pm);
-    ~Lock();
-    void lock();
-    void unlock();
-    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 xx(mutex);
-        if(alreadyInitialized) return;
-        // initialization
-    }
- -

messageQueue.h

- -

Definitions

- -

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:
-    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(String message,MessageType messageType,bool replaceLast);
-    bool isEmpty() ;
-    bool isFull() ;
-    int getClearOverrun();
- ...
-};
- -

A messageNode is a class with two public data members:

-
-
getMessage
-
The message.
-
getMessageType
-
The message type.
-
setMessageNull
-
Set the message to be a null string.
-
- -

A messageQueue is an interface with public methods:

-
-
MessageQueue
-
The constructor. The queue size must be specified.
-
~MessageQueue
-
The destructor.
-
put
-
Put a new message into the queue. False is returned if the queue was - full and true otherwise. If replaceLast is true then the last message is - replaced with this message.
-
get
-
Get the oldest queue element. If the queue is empty null is returned. - Before the next get can be issued release must be called.
-
release
-
Release the queue element returned by the last get.
-
isEmpty
-
Is the queue empty?
-
isFull
-
Is the queue full?
-
getClearOverrun
-
Get the number of times put has been called but no free element is - available.
-
- -

Look at miscTest/testMessageQueue.cpp for an example.

- -

noDefaultMethods.h

- -

If a class privately extends this class then the compiler can not create any -of the following: default constructor, default copy constructror, or default -assignment contructor.

-
/* This is based on Item 6 of
- * Effective C++, Third Edition, Scott Meyers
- */
-    class NoDefaultMethods {
-    protected:
-    // allow by derived objects
-    NoDefaultMethods(){};
-    ~NoDefaultMethods(){}
-    private:
-    // do not implment
-    NoDefaultMethods(const NoDefaultMethods&);
-    NoDefaultMethods & operator=(const NoDefaultMethods &);
-    };
- -

queue.h

- -

This provides a queue which has an immutable capacity. When the queue is -full the user code is expected to keep using the current element until a new -free element becomes avalable.

-
template <typename T>
-class Queue
-{   
-public:
-    POINTER_DEFINITIONS(Queue);
-    typedef std::tr1::shared_ptr<T> queueElementPtr;
-    typedef std::vector<queueElementPtr> queueElementPtrArray;
-    Queue(queueElementPtrArray &);
-    virtual ~Queue();
-    void clear();
-    int capacity();
-    int getNumberFree();
-    int getNumberUsed();
-    queueElementPtr & getFree();
-    void setUsed(queueElementPtr &element);
-    queueElementPtr & getUsed();
-    void releaseUsed(queueElementPtr &element);
- ...
-};
- -

testApp/misc/testQueue.cpp provides an example of how to define a queue.

- -

The queue methods are:

-
-
clear
-
Make the queue empty.
-
getNumberFree
-
Get the number of free elements in the queue.
-
capacity
-
Get the capacity, i.e. the maximun number of elements the queue can - hold.
-
getNumberFree
-
Get the number of free elements.
-
getNumberUsed
-
Get the number of elements used.
-
getFree
-
Get the next free element. Null is returned if no free elements are - available. If a non null value is returned then the element belongs to - the caller until setUsed is called.
-
setUsed
-
Set a queue element used. This must be the element returned by the last - call to getFree.
-
getUsed
-
Get the next used element of null if no more used elements are - available.
-
releaseUsed
-
Set a queue element free. This must be the element returned by the last - call to getUsed.
-
- -

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.h

- -

A PVField extends Requester. Requester is present so that when database -errors are found there is someplace to send a message.

-
enum MessageType {
-   infoMessage,warningMessage,errorMessage,fatalErrorMessage
-};
-
-extern String getMessageTypeName(MessageType messageType);
-extern const size_t messageTypeCount;
-class Requester {
-public:
-    POINTER_DEFINITIONS(Requester);
-    virtual ~Requester(){}
-    virtual String getRequesterName() = 0;
-    virtual void message(String const & message,MessageType messageType) = 0;
-};
- -

where

-
-
-
MessageType
-
Type of message.
-
messageTypeName
-
An array of strings of the message type names, i.e. - String("info"),String("warning"),String("error"),String("fatalError").
-
getRequesterName
-
Returns the requester name.
-
message
-
Gives a message to the requester.
-
- -

serialize.h

-
    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;
-    };
- -

serializeHelper.h

- -

This is a helper class for serialization, which is required for sending and -receiving pvData over the nerwork.

-
class SerializeHelper : public NoDefaultMethods {
-public:
-    static void writeSize(int s, ByteBuffer* buffer,
-        SerializableControl* flusher);
-    static int readSize(ByteBuffer* buffer,
-        DeserializableControl* control);
-    static void serializeString(const String& value,
-        ByteBuffer* buffer,SerializableControl* flusher);
-    static void serializeSubstring(const String& value, int offset,
-        int count, ByteBuffer* buffer,
-        SerializableControl* flusher);
-    static String deserializeString(ByteBuffer* buffer,
-        DeserializableControl* control);
- ...
-};
- -

where

-
-
writeSize
-
Serialize the size.
-
readSize
-
Deserialize the size.
-
serializeString
-
Serialize a String.
-
serializeSubstring
-
Serialize a substring.
-
deserializeString
-
Deserialize a string.
-
- -

sharedPtr.h

-
#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;
- -

status.h

- -

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, epics::pvData::String const & message);
-    Status(StatusType type, epics::pvData::String const & message, epics::pvData::String stackDump);
-    ~Status()
-    StatusType getType() const;
-    String getMessage() const;
-    String getStackDump() const;
-    bool isOK() const;
-    bool isSuccess() const;
-    String toString() const;
-    void toString(StringBuilder buffer, int indentLevel = 0) const;
-    void serialize(ByteBuffer *buffer, SerializableControl *flusher) const;
-    void serialize(ByteBuffer *buffer, SerializableControl *flusher) const;
-};
- -

The Status methods are:

-
-
StatusType
-
An enum for the status type.
-
getType
-
Get the statusType.
-
getMessage
-
Get a message explaining the error.
-
getStackDump
-
Get a stack dump.
-
- -

The StatusCreate methods are:

-
-
getStatusOK
-
Get a singleton that returns StatusType.OK and a null message and - stackDump.
-
createStatus
-
Create a new Status.
-
deserializeStatus
-
Use this method instead of Status.deserialize(), since this allows OK - status optimization.
-
- -

thread.h

- -

ThreadPriority

-
enum ThreadPriority {
-    lowestPriority,
-    lowerPriority,
-    lowPriority,
-    middlePriority,
-    highPriority,
-    higherPriority,
-    highestPriority
-};
- -

Thread

-
class Runnable {
-public:
-    virtual void run() = 0;
-};
-
-class Thread;
-
-class Thread : public epicsThread, private NoDefaultMethods {
-public:
-    Thread(
-        String name,
-        ThreadPriority priority,
-        Runnable *runnableReady,
-        epicsThreadStackSizeClass stkcls=epicsThreadStackSmall);
-    ~Thread();
- ...
-};
- -

Runnable must be implement by code that wants to be run via a thread. It has -one virtual method: run. Run is the code that is run as a thread. When run -compeletes it can not be restarted. If code wants to delete a thread then it -MUST arrange that the run returns before the thread can be deleted. An -exception is thrown if run remains active when delete is called.

- -

Thread has the methods:

-
-
Thread
-
The constructor. A thread name and priority must be specified. The run - methods of runnable is executed. When the run methods returns the thread - will no longer be active but the client code must still delete the - thread.
-
~Thread
-
The destructor. This is called as the result of: - 
    delete pthread;
-
-
- -

timeFunction.h

- -

TimeFunction is a facility that measures the average number of seconds a -function call requires. When timeCall is called, it calls function in a loop. -It starts with a loop of one iteration. If the total elapsed time is less then -.1 seconds it increases the number of iterrations by a factor of 10. It keeps -repeating until the elapsed time is greater than .1 seconds. It returns the -average number of seconds per call.

-
class TimeFunctionRequester;
-class TimeFunction;
-typedef std::tr1::shared_ptr<TimeFunctionRequester> TimeFunctionRequesterPtr;
-typedef std::tr1::shared_ptr<TimeFunction> TimeFunctionPtr;
-        
-class TimeFunctionRequester {
-public:              
-    POINTER_DEFINITIONS(TimeFunctionRequester);
-    virtual ~TimeFunctionRequester(){}
-    virtual void function() = 0;
-};  
-
-    
-class TimeFunction {
-public:    
-    POINTER_DEFINITIONS(TimeFunction);
-    TimeFunction(TimeFunctionRequesterPtr const & requester);
-    ~TimeFunction(); 
-    double timeCall();
- ...
-};
- -

TimeFunctionRequester must be implemented by code that wants to time how -long a function takes. It has the single method:

-
-
function
-
This is the function.
-
- -

TimeFunction has the methods:

-
-
TimeFunction
-
Constructor.
-
~TimeFunction
-
Destructor.
-
timeCall
-
Time how long it takes to execute the function. It starts by calling - the function one time. If it takes < 1 seconds to doubles the number - of times to call the function. It repeats this until it takes at least - one second to call it ntimes.
-
- -

timer.h

- -

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(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 toString(StringBuilder builder);
- ...
-};
- -

TimerCallback must be implemented by the user. It has the following methods: -

-
-
callback
-
This is called when a timer expires. This is called with no locks held. - When called a delay timer is no longer on the queue but a periodioc timer - is on a queue. Thus the callback for a delay timer can issue a new - schedule request but a periodic timer must not. Note the explaination of - TimerNode.cancel below.
-
timerStopped
-
Timer.stop was called when a timer request was queued. or if the timer - is stopped and a schedule request is made.
-
- -

In order to schedule a callback client code must allocate a TimerNode It can -be used to schedule multiple callbacks. It has the methods:

-
-
TimerNode
-
The constructor. User code must create a TimeNode in order to call a - schedule method.
-
~TimerNode
-
The destructor. This is called as a result of the client calling: - 
    delete timerNode;
-
-
cancel
-
This is called to cancel a timer request. If a callback has been - dequeued but the callback not called when cancel is called then a - callback may still happen. New schedule requests can be made after a - cancel request has been made.
-
isScheduled
-
Is the timerNode scheduled to be called.
-
- -

Timer has the methods:

-
-
Timer
-
The consttructor.
-
~Timer
-
The destructor. The queue is emptied and TimerCallback.timerStopped is - called for each element of the queue.
-
scheduleAfterDelay
-
A request to schedule a callback after a delay specified in - seconds.
-
schedulePeriodic
-
Schedule a periodic callback.
-
- -

pvDataApp/pvMisc

- -

bitSetUtil.h

- -

The following is also provided:

-
class BitSetUtil : private NoDefaultMethods {
-public:
-    static bool compress(BitSet *bitSet,PVStructure *pvStructure);
-};
- -

This provides functions that operate on a BitSet for a PVStructure. It -currently has only one method:

-
-
compress
-
Compress the bits in a BitSet related to a structure.
- For each structure: -
    -
  1. If the bit for the structure is set then the bit for all subfields - of the structure are cleared.
    2. -
  2. If the bit for the structure is not set but all immediate subfields - have their bit set then the bit for the structure is set and the bits - for all subfields are cleared.
    3. -
- Note that this is a recursive algorithm. That is if every immediate - subfield has it's offset bit set then the bits for ALL fields that reside - in the structure will be cleared.
-
Channel Access can call this before sending data. It can then pass - entire structures if the structure offset bit is set.
-
-
- - diff --git a/documentation/pvDataCPP_20121026.html b/documentation/pvDataCPP_20121026.html deleted file mode 100644 index 560ec62..0000000 --- a/documentation/pvDataCPP_20121026.html +++ /dev/null @@ -1,3622 +0,0 @@ - - - - - - EPICS pvDataCPP - - - - - - - - -
-

EPICS pvDataCPP

- - -

EPICS v4 Working Group, Working Draft, 01-Oct-2012

- -
-
Latest version:
-
pvDataCPP.html -
-
This version:
-
pvDataCPP_20121026html -
-
Previous version:
-
pvDataCPP_20121001.html -
-
Editors:
-
Marty Kraimer, BNL
-
- -

This product is made available subject to acceptance of the EPICS open source -license.

-
-
- -

Abstract

- -

pvDataCPP is a computer software package for the efficient -storage, access, and communication, of structured data. It is specifically the -C++ implementation of pvData, which is one part of the set of related products in the EPICS -V4 control system programming environment:
-relatedDocumentsV4.html -

- -

Status of this Document

- -

This is the 01-Oct-2012 version of the C++ implementation of pvData.

- -

The text describes software which is a complete implementation of pvData as -currently planned by the EPICS V4 Working Group.

- -

The following is a list of unresolved issues for pvDataCPP:

-
-
PVArray
-
The implementation of the different array types (PVBooleanArray, ..., - PVStructureArray) all store the data as a shared pointer holding a - vector. A test case should be created to make sure that vector.size() is - the same as getLength()
-
PVArray Examples
-
The following examples should be provided: 1) use all the get methods. - 2) create an example that makes data available in chunks.
-
pvType Example
-
Create an example of how to use the array typedefs
-
Convert test
-
How can this be better tested?
-
Structure and PVStructure
-
These two classes still keep data via std::vector. - Should they keep it as std::tr1::shared_ptr<std::vector<... ?
- In particular change -
-class Structure
-...
-StringArray fieldNames;
-FieldConstPtrArray fields
-
-class PVStructure
-...
-PVFieldPtrArray pvFields;
-
-To -
-class Structure
-...
-StringArrayPtr fieldNames;
-FieldConstPtrArrayPtr fields
-
-class PVStructure
-...
-PVFieldPtrArrayPtr pvFields;
-
-If these are changed several methods also change so that raw vectors are never passed as -argument or returned from methods.
-
- -
-

Table of Contents

-
-
- - -

Introduction

- -

pvData is one of a set of related projects. It describes and implements the -data that the other projects support. Thus it is not useful by itself but -understanding pvData is required in order to understand the other projects. The -reader should also become familar with projects pvAccess and pvIOC, which are -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:

-
-
Introduction
-
A brief descripton of pvData.
-
PVData Meta Language
-
A language used to describe data.
-
- -

The material in these two chapters is NOT repeated in this documentation.

- -

Doxygen documentation is available at doxygenDoc

- -

Namespace and Memory Management

- -

Namespace

- -

All code in project pvDataCPP appears in namespace:

-
namespace epics { namespace pvData {
-     // ...
-}}
- -

Memory Managemment

- -

pvDataCPP introspection and data objects are designed to be shared. They are -made availiable via std::tr1::shared_ptr. In addition arrays are -implemented via std::vector. The following naming conventions are used -in typedefs:

-
-
Ptr
-
When Ptr appears it stands for std::tr1::shared_ptr.
-
Array
-
When Array appears it stands for std::vector.
-
- -

As an example pvType.h includes the following definitions:

-
typedef std::vector<double> DoubleArray;
-typedef std::tr1::shared_ptr<DoubleArray> DoubleArrayPtr;
-inline double * get(DoubleArray &value)
-{
-    return &value[0];
-}
-inline const double * get(const DoubleArray &value)
-{
-    return static_cast<const double *>(&value[0]);
-}
-typedef std::vector<double>::iterator DoubleArray_iterator;
-typedef std::vector<double>::const_iterator DoubleArray_const_iterator;
- -

where

-
-
DoubleArray
-
This defines a vector for an array of the primitive type "double".
-
DoubleArrayPtr
-
This devices a shared pointer to a vector for an array of the primitive - type "double".
-
get
-
This gets the raw array of doubles that the DoubleArray holds.
-
DoubleArray_iterator
-
This gets a iterator for the DoubleArray.
-
DoubleArray_const_iterator
-
This gets a constant iterator for the DoubleArray.
-
- -

pvDataApp/pv

- -

Overview

- -

Directory pvDataApp/pv has header files that completely describe pvData. The -implementation is provided in directory pvDataApp/factory. Test programs -appears in testApp/pv.

- -

NOTES:

-
-
interface
-
The documention uses the word interface. This is an analogy for - what the Java implementation implements, i. e. package pv provides Java - interfaces. C++ does not have interfaces but directory pv defines classes - with public members that are similar to the Java interfaces. Most of the - implementation is in factory.
-
Naming Convertions
-
The naming convertions for variables, methods, and classes follow the - Java convertions, i. e. class name begin with an upper case letter, - variables and methods begin with a lower case letter.
-
- -

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. This section describes the complete set of C++ -introspection and data interfaces for pvData.

- -

Class FieldCreate creates introspection objects. Class PVDataCreate creates -data objects. Class Convert provides a rich set of methods for converting and -copying data between fields.

- -

Directory pvDataApp/pv has the following header files:

-
-
pvType.h
-
C++ definitions for primitive types.
-
pvIntrospect.h
-
A complete description of the introspection interfaces.
-
pvData.h
-
A complete description of the data interfaces.
-
convert.h
-
A facility that converts between data fields.
-
standardField.h
-
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.
-
- -

pvType.h

- -

This provides C/C++ definitions for the pvData primitive types: boolean, -byte, short, int, long, ubyte,ushort, uint,u long,float, double, and string. -Because pvData is network data, the C++ implementation must implement the -proper semantics for the primitive types.

- -

pvType.h provides the proper semantics.

- -

It has the definitions:

-
typedef uint8_t  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::string String;
-
-/**
- * A boolean array.
- */
-typedef std::vector<uint8> BooleanArray;
-typedef std::tr1::shared_ptr<BooleanArray> BooleanArrayPtr;
-/* get is same is ubyte*/
-typedef std::vector<uint8>::iterator BooleanArray_iterator;
-typedef std::vector<uint8>::const_iterator BooleanArray_const_iterator;
-
-/**
- * A byte array.
- */
-typedef std::vector<int8> ByteArray;
-typedef std::tr1::shared_ptr<ByteArray> ByteArrayPtr;
-inline int8 * get(ByteArray &value);
-inline int8 const * get(ByteArray const &value);
-inline int8 * get(ByteArrayPtr &value);
-inline int8 const * get(ByteArrayPtr const &value);
-inline ByteArray & getVector(ByteArrayPtr &value);
-inline ByteArray const & getVector(ByteArrayPtr const &value);
-typedef std::vector<int8>::iterator ByteArray_iterator;
-typedef std::vector<int8>::const_iterator ByteArray_const_iterator;
-
-/* similar definitions are present for ALL the primitive types */
- -

where

-
-
boolean
-
A c++ bool has the semantics required for boolean. Only the name is - different. C++ code can use either bool or boolean.
-
int8,...,uint64
-
Integers present a problem because short, int, and long are C++ - reserved words but do not have a well defined number of bits. Thus for - C++ the definitions above are used in C++ code. The above definitions - have worked on all C++ implementations tested at present. If they break - in a future implementation they should be changes via "#ifdef" - preprocessor statements.
-
String
-
pvData requires that a string be an immutable string that is transfered - over the network as a UTF8 encoded string. Since std::string implements - copy on write semantics, it can be used for support for immutable - strings. It can also be serialized/deserialized as a UTF8 encoded string. - Because it is not a C++ primitive the first letter is capitalized. This - is the same convention the Java implementation uses.
-
StringBuilder
-
This is defined here because to is used by the toString methods defined - for both introsection and data objects. The definition above acts like - the Java StringBuilder class.
-
Array definitions
-
typedefs are provided for an array of each of the primitive types. Note - that string is treated like a primitive type/
-
- -

pvIntrospect.h

- -

This subsection describes pvIntrospect.h This file is quite big so rather -than showing the entire file, it will be described in parts.

- -

A primary reason 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 pvname if a unique name in the local network.

- -

Given a pvname PV), 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 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.

- -

Type Description

- -

Types are defined as:

-
enum Type {
-    scalar,
-    scalarArray,
-    structure,
-    structureArray;
-};
-
-class TypeFunc {
-public:
-    const char* name(Type);
-    static void toString(StringBuilder buf,const 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(String const &value);
-    const char* name(ScalarType);
-    void toString(StringBuilder buf,ScalarType scalarType);
-};
- -

Type is one of the following:

-
-
scalar
-
A scalar of one of the scalar types.
-
scalarArray
-
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 types can be different.
-
structureArray
-
An array where each element is a structure. Each element has the same - structure introspection interface.
-
- -

ScalarType is one of the following:

-
-
pvBoolean
-
Has the value false or true.
-
pvByte
-
A signed 8 bit integer.
-
pvShort
-
A signed 16 bit integer.
-
pvInt
-
A signed 32 bit integer.
-
pvLong
-
A signed 64 bit integer.
-
pvUByte
-
An unsigned 8 bit integer.
-
pvUShort
-
An unsigned 16 bit integer.
-
pvUInt
-
An unsigned 32 bit integer.
-
pvULong
-
An unsigned 64 bit integer.
-
pvFloat
-
A IEEE float.
-
pvDouble
-
A IEEE double,
-
pvString
-
An immutable string.
-
- -

TypeFunction is a set of convenience methods for Type

-
-
name
-
Returns the name of the type.
-
toString
-
Convert the type to a string.
-
- -

ScalarTypeFunction is a set of convenience methods for ScalarType

-
-
isInteger
-
Is the scalarType an integer type, i.e. one of pvByte,...pvULong.
-
isUInteger
-
Is the scalarType an unsigned integer type, i.e. one of - pvUByte,...pvULong
-
isNumeric
-
Is the scalarType numeric, i.e. pvByte,...,pvDouble.
-
isPrimitive
-
Is the scalarType primitive, i.e. not pvString
-
name
-
Returns the name of the scalarType.
-
getScalarType
-
Given a string of the form String("boolean"),...,String("string") - return the scalarType.
-
toString
-
Convert the scalar type to a string.
-
- -

Introspection Description

- -

This section describes the reflection interfaces which provide the -following:

-
-
Field
-
A field: -
    -
  • Has a Type.
    • -
  • Can be converted to a string.
    • -
  • Can be shared. A reference count is kept. When it becomes 0 the - instance is automatically deleted.
    • -
-
-
Scalar
-
A scalar has a scalarType
-
ScalarArray
-
The element type is a scalarType
-
StructureArray
-
The field holds an array of structures. Each element has the same - 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
-
This is an interface that provides methods to create introspection - interfaces. A factory is provides to create FieldCreate.
-
getFieldCreate
-
Gets a pointer to the single instance of FieldCreate.
-
-
class Field;
-class Scalar;
-class ScalarArray;
-class Structure;
-class StructureArray;
-
-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;
-
-
-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 String getID() const = 0;
-    virtual void toString(StringBuilder buf) const{toString(buf,0);}
-    virtual void toString(StringBuilder buf,int indentLevel) const;
- ...
-};
-
-class Scalar : public Field{
-public:
-    POINTER_DEFINITIONS(Scalar);
-    virtual ~Scalar();
-    typedef Scalar& reference;
-    typedef const Scalar& const_reference;
-
-    ScalarType getScalarType() const {return scalarType;}
-    virtual void toString(StringBuilder buf) const{toString(buf,0);}
-    virtual void toString(StringBuilder buf,int indentLevel) const;
-    virtual String getID() const;
-    virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
-    virtual void deserialize(ByteBuffer *buffer, DeserializableContol *control);
- ...
-};
-
-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 void toString(StringBuilder buf) const{toString(buf,0);}
-    virtual void toString(StringBuilder buf,int indentLevel) const;
-    virtual String getID() const;
-    virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
-    virtual void deserialize(ByteBuffer *buffer, DeserializableControl *control);
- ...
-};
-
-class StructureArray : public Field{
-public:
-    POINTER_DEFINITIONS(StructureArray);
-    typedef StructureArray& reference;
-    typedef const StructureArray& const_reference;
-
-    StructureConstPtr  getStructure() const {return pstructure;}
-    virtual void toString(StringBuilder buf,int indentLevel=0) const;
-    virtual String getID() 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(String const & fieldName) const;
-   FieldConstPtr getField(std::size_t index) const;
-   std::size_t getFieldIndex(String const &fieldName) const;
-   FieldConstPtrArray const & getFields() const {return fields;}
-   StringArray const & getFieldNames() const;
-   void renameField(std::size_t fieldIndex,String const &newName);
-   String getFieldName(std::size_t fieldIndex);
-   virtual void toString(StringBuilder buf,int indentLevel) const;
-   virtual String getID() const;
-   virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
-   virtual void deserialize(ByteBuffer *buffer, DeserializableControl *control);
- ...
-};
-
-class FieldCreate  {
-public:
-    static FieldCreatePtr getFieldCreate();
-    ScalarConstPtr  createScalar(ScalarType scalarType) const
-    ScalarArrayConstPtr createScalarArray(ScalarType elementType) const;
-    StructureArrayConstPtr createStructureArray(StructureConstPtr const & structure) const;
-    StructureConstPtr createStructure (
-        StringArray const & fieldNames,
-        FieldConstPtrArray const & fields) const;
-    StructureConstPtr createStructure (
-        String const &id,
-        StringArray const & fieldNames,
-        FieldConstPtrArray const & fields) const;
-    StructureConstPtr appendField(
-        StructureConstPtr const & structure,
-        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;
- ...
-};
-
-extern FieldCreatePtr getFieldCreate();
-
-
Constructor
-
Note that all constructors are protected or private. The only way to - create instances is via FieldCreate. The implementation manages all - storage via shared pointers.
-
toString
-
Many classes provide this (actually two methods). This method is called - to get a string that uses the metadata syntax described in a previous - section.
-
- -
Field
-
-
getType
-
Get the field type.
-
getID
-
Get an ID for this introspection interface
-
- -
Scalar
-
-
getScalarType
-
Get that scalar type.
-
getID
-
For each scalarType there is one instance of Scalar. The ID for each is - the metadata name for the type, i. e. one of "boolean" , ... , "string". -
-
- -
ScalarArray
-
-
getElementType
-
Get the element type.
-
getID
-
For each elemnetType there is one instance of ScalarArray. The ID for - each is the metadata name for the type, i. e. one of "boolean[]" , ... , - "string[]".
-
- -
StructureArray
-
-
getStructure
-
Get the introspection interface that each element shares,
-
getID
-
This returns the ID[] where ID is the value returned by - structure->getID().
-
- -
Structure
-
-
getNumberFields
-
Get the number of immediate subfields.
-
getField
-
Given a name or an index get the introspection interface for the - field.
-
getFieldIndex
-
Given a name get the index, within the array returned by the next - method, of the field.
-
getFields
-
Get the array of introspection interfaces for the field,
-
getFieldNames
-
Get the array of field names for the subfields.
-
renameField
-
Rename the field.
-
getFieldName
-
Get the field name for the specified index.
-
- -
FieldCreate
-
-
getFieldCreate
-
Get the single instance of FieldCreate.
-
createScalar
-
Create a scalar introspection instance.
-
createScalarArray
-
Create a scalar array introspection instance.
-
createStructure
-
Create a structure introspection instance. Two methods are provided - where the only difference is that one provides an ID and the other does - not. The one without will result in ID "structure".
-
createStructureArray
-
Create a structure array introspection instance.
-
appendField
-
Append a field to a structure.
-
appendFields
-
Append fields to a structure.
-
deserialize
-
Deserialize from given byte buffer.
-
- -

standardField.h

- -

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,String const &properties);
-    StructureConstPtr scalarArray(
-        ScalarType elementType, String const &properties);
-    StructureConstPtr structureArray(
-        StructureConstPtr const & structure,String const &properties);
-    StructureConstPtr enumerated();
-    StructureConstPtr enumerated(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();
- ...
-};
-
-
scalar
-
Create a scalar with the specified scalar type and name. A structure - will be created with the first element being a scalar with the specified - scalar type and name value. The other fields in the structure will be the - corresponding property structures.
-
scalarArray
-
Create a scalarArray with each element having the specified scalar type - and name. A structure will be created with the first element being a - scalarArray with name value. The other fields in the structure will be - the corresponding property structures.
-
structureArray
-
Create a structureArray with the specified structure interface and - name. A structure will be created with the first element being a - structureArray with the specified structure interface and name value. The - other fields in the structure will be the corresponding property - structures.
-
structure
-
Create a structure with the specified name and fields specified by - numFields and fields. A structure will be created with the first element - being a structure with the name value and fields specified by numFields - and fields. The other fields in the structure will be the corresponding - property structures.
-
enumerated
-
Create a structure with the specified name and fields for an enumerated - structure. If properties are specified then a structure will be created - with the first element being a structure with the name value and fields - for an enumerated structure. The other fields in the structure will be - the corresponding property structures.
-
alarm
-
timeStamp
-
display
-
control
-
booleanAlarm
-
byteAlarm
-
shortAlarm
-
intAlarm
-
longAlarm
-
floatAlarm
-
doubleAlarm
-
enumeratedAlarm
-
The above provide introspection interfaces for standard properties. See - the section on Properties for a description of how these are defined.
-
- -

pvData.h

- -

This subsection describes pvData.h This file is quite big so rather than -showing the entire file, it will be described in parts.

- -

typedefs

- -

These are typedefs for Array and Ptr for the various pvData class -definitions, i.e. typdefs for "std::vector" and "std::tr1::shared_ptr".

-
class PVAuxInfo;
-class PostHandler;
-
-class PVField;
-class PVScalar;
-
-class PVScalarArray;
-
-class PVStructure;
-class PVStructureArray;
-
-typedef std::tr1::shared_ptr<PVAuxInfo> PVAuxInfoPtr;
-
-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 std::tr1::shared_ptr<PostHandler> PostHandlerPtr
- -

PostHandler is a class that must be implemented by any code that calls -setPostHandler. It's single virtual method. postPut is called whenever -PVField::postPut is called.

-
class PostHandler :
-  public std::tr1::enable_shared_from_this<PostHandler>
-{
-public:
-    POINTER_DEFINITIONS(PostHandler);
-    virtual ~PostHandler(){}
-    virtual void postPut() = 0;
-};
- -

PVField

- -

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 PVField
-: virtual public Serializable,
-  public std::tr1::enable_shared_from_this<PVField>
-{
-public:
-   POINTER_DEFINITIONS(PVField);
-   virtual ~PVField();
-   virtual void message(String message,MessageType messageType);
-   String getFieldName() const ;
-   virtual void setRequester(RequesterPtr const &prequester);
-   std::size_t getFieldOffset() const;
-   std::size_t getNextFieldOffset() const;
-   std::size_t getNumberFields() const;
-   PVAuxInfoPtr & getPVAuxInfo()
-   bool isImmutable() const;
-   virtual void setImmutable();
-   const FieldConstPtr & getField() const ;
-   PVStructure * getParent() const 
-   void replacePVField(const PVFieldPtr&  newPVField);
-   void renameField(String const &newName);
-   void postPut() ;
-   void setPostHandler(PostHandlerPtr const &postHandler);
-   virtual bool equals(PVField &pv);
-   virtual void toString(StringBuilder buf) ;
-   virtual void toString(StringBuilder buf,int indentLevel);
-   std::ostream& dumpValue(std::ostream& o) const;
- ...
-}
- -

The public methods for PVField are:

-
-
~PVField
-
Destructor. Since shared pointers are used it should never be called by - user code.
-
message
-
Code attached to this field can call this method to report - problems.
-
getFieldName
-
Get the field name. If the field is a top level structure the field - name will be an empty string.
-
setRequester
-
Sets a requester to be called when message or getRequesterName are - called. This is only legal for the top level PVField.
-
getFieldOffset
-
Get offset of the PVField field within top level structure. Every field - within the PVStructure has a unique offset. The top level structure has - an offset of 0. The first field within the structure has offset equal to - 1. The other offsets are determined by recursively traversing each - structure of the tree.
-
getNextFieldOffset
-
Get the next offset. If the field is a scalar or array field then this - is just offset + 1. If the field is a structure it is the offset of the - next field after this structure. Thus (nextOffset - offset) is always - equal to the total number of fields within the field.
-
getNumberFields
-
Get the total number of fields in this field. This is nextFieldOffset - - fieldOffset.
-
getPVAuxInfo
-
Get the PVAuxInfo for this field. PVAuxInfo is described below.
-
isImmutable
-
Is the field immutable?
-
setImmutable
-
Make the field immutable. Once a field is immutable it can never be - changed since there is no method to again make it mutable. This is an - important design decision since it allows immutable array fields to share - the internal primitive data array.
-
getField
-
Get the reflection interface for the data.
-
getParent
-
Get the interface for the parent or null if this is the top level - PVStructure.
-
replacePVField
-
Replace the data implementation for the field.
-
renameField
-
Rename the field name.
-
postPut
-
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.
-
equals
-
Compare this field with another field. The result will be true only if - the fields have exactly the same field types and if the data values are - equal.
-
toString
-
Converts the field data to a string. This is mostly for debugging - purposes.
-
dumpValue
-
Method for streams I/O.
-
- -

PVAuxInfo

- -

AuxInfo (Auxillary Information) is information about a field that is -application specific. It will not be available outside the application that -implements the database. In particular it will not be made available to Channel -Access. It is used by the database itself to override the default -implementation of fields. The JavaIOC uses it for attaching support code. -Database Configuration and other tools can use it for configuration -information. Each Field and each PVField can have have an arbitrary number of -auxInfos. An auxInfo is a (key,PVScalar) pair where key is a string.

-
class PVAuxInfo : private NoDefaultMethods {
-public:
-    typedef std::map<String,PVScalarPtr> PVInfoMap;
-    typedef std::map<String,PVScalarPtr>::iterator PVInfoIter;
-    typedef std::pair<String,PVScalarPtr> PVInfoPair;
-
-    PVAuxInfo(PVField *pvField);
-    ~PVAuxInfo();
-    PVField * getPVField();
-    PVScalarPtr createInfo(String const &key,ScalarType scalarType);
-    PVScalarPtr getInfo(String const &key);
-    PVInfoMap & getInfoMap();
-    void toString(StringBuilder buf);
-    void toString(StringBuilder buf,int indentLevel);
- ...
-};
- -

where

-
-
getPVField
-
Get the PVField to which this PVAuxInfo is attached.
-
createInfo
-
Create a new PVScalar of type scalarType.
-
getInfo
-
Get the PVScalar with the specified key.
-
getInfoMap
-
Get the map of all the PVScalars that hold the info.
-
toString
-
Print all the auxInfos
-
- -

PVScalar

- -

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 ;
- ...
-}
- -

where

-
-
getScalar
-
Get the introspection interface for the PVScalar.
-
- -

PVScalarValue

- -

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;
-    virtual ~PVScalarValue() {}
-    virtual T get() const = 0;
-    virtual void put(T value) = 0;
- ...
-}
-
-// PVString is special case, since it implements SerializableArray
-class PVString : public PVScalarValue<String>, SerializableArray {
-public:
-    virtual ~PVString() {}
- ...
-};
- -

where

-
-
get
-
Get the value stored in the object.
-
put
-
Change the value stored in the object.
-
- -

PVArray

- -

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 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;
- ...
-};
-
-
setImmutable
-
Set the data immutable. Note that this is permanent since there is no - methods to make it mutable.
-
getLength
-
Get the current length. This is less than or equal to the capacity.
-
setLength
-
Set the length. If the PVField is not mutable then an exception is - thrown. If this is greater than the capacity setCapacity is called.
-
getCapacity
-
Get the capacity, i.e. this is the size of the underlying data - array.
-
setCapacity
-
Set the capacity. The semantics are implementation dependent but - typical semantics are as follows: If the capacity is not mutable an - exception is thrown. A new data array is created and data is copied from - the old array to the new array.
-
isCapacityMutable
-
Is the capacity mutable
-
setCapacityMutable
-
Specify if the capacity can be changed.
-
setCapacity
-
Set the capaciity.
-
- -

PVArrayData

- -

This is the argument to one of the get methods of PVValueArray.

-
template<typename T>
-class PVArrayData {
-private:
-    std::vector<T> init;
-public:
-    POINTER_DEFINITIONS(PVArrayData);
-    typedef T  value_type;
-    typedef T* pointer;
-    typedef const T* const_pointer;
-    std::vector<T> & data;
-    std::size_t offset;
-    PVArrayData()
-    : data(init)
-    {}
-};
- -

PVScalarArray

- -

PVScalarArray is the base class for scalar array data. PVValueArray is a -templete for the various scalar array data classes. There is a class for each -possible scalar type, i. e. PVBooleanArray, ..., PVStringArray.

-
class PVScalarArray : public PVArray {
-public:
-    POINTER_DEFINITIONS(PVScalarArray);
-    virtual ~PVScalarArray();
-    typedef PVScalarArray &reference;
-    typedef const PVScalarArray& const_reference;
-    const ScalarArrayConstPtr getScalarArray() const ;
-    virtual std::ostream& dumpValue(std::ostream& o, size_t index) const = 0;
- ...
-}
- -

where

-
-
getScalarArray
-
Get the introspection interface.
-
dumpValue
-
Method for streams I/O.
-
- -

PVValueArray

- -

This is a template class plus instances for PVBooleanArray, ..., -PVStringArray.

-
template<typename T>
-class PVValueArray : public PVScalarArray {
-public:
-    POINTER_DEFINITIONS(PVValueArray);
-    typedef T  value_type;
-    typedef T* pointer;
-    typedef const T* const_pointer;
-    typedef PVArrayData<T> ArrayDataType;
-    typedef std::vector<T> vector;
-    typedef const std::vector<T> const_vector;
-    typedef std::tr1::shared_ptr<vector> shared_vector;
-    typedef PVValueArray & reference;
-    typedef const PVValueArray & const_reference;
-
-    virtual ~PVValueArray() {}
-    virtual std::size_t get(
-         std::size_t offset, std::size_t length, ArrayDataType &data) = 0;
-    virtual std::size_t put(std::size_t offset,
-        std::size_t length, const_pointer from, std::size_t fromOffset) = 0;
-    virtual std::size_t put(std::size_t offset,
-        std::size_t length, const_vector &from, std::size_t fromOffset);
-    virtual void shareData(
-         shared_vector const & value,
-         std::size_t capacity,
-         std::size_t length) = 0;
-    virtual pointer get() = 0;
-    virtual pointer get() const = 0;
-    virtual vector const & getVector() = 0;
-    virtual shared_vector const & getSharedVector() = 0;
-    std::ostream& dumpValue(std::ostream& o) const;
-    std::ostream& dumpValue(std::ostream& o, size_t index) const;
-protected:
-    PVValueArray(ScalarArrayConstPtr const & scalar)
-    : PVScalarArray(scalar) {}
-    friend class PVDataCreate;
-};
-
-template<typename T>
-std::size_t PVValueArray<T>::put(
-    std::size_t offset,
-    std::size_t length,
-    const_vector &from,
-    std::size_t fromOffset)
-{ return put(offset,length, &from[0], fromOffset); }
-
-/**
- * Definitions for the various scalarArray types.
- */
-typedef PVArrayData<uint8> BooleanArrayData;
-typedef PVValueArray<uint8> PVBooleanArray;
-typedef std::tr1::shared_ptr<PVBooleanArray> PVBooleanArrayPtr;
-
-typedef PVArrayData<int8> ByteArrayData;
-typedef PVValueArray<int8> PVByteArray;
-typedef std::tr1::shared_ptr<PVByteArray> PVByteArrayPtr;
-
-typedef PVArrayData<int16> ShortArrayData;
-typedef PVValueArray<int16> PVShortArray;
-typedef std::tr1::shared_ptr<PVShortArray> PVShortArrayPtr;
-
-typedef PVArrayData<int32> IntArrayData;
-typedef PVValueArray<int32> PVIntArray;
-typedef std::tr1::shared_ptr<PVIntArray> PVIntArrayPtr;
-
-typedef PVArrayData<int64> LongArrayData;
-typedef PVValueArray<int64> PVLongArray;
-typedef std::tr1::shared_ptr<PVLongArray> PVLongArrayPtr;
-
-typedef PVArrayData<uint8> UByteArrayData;
-typedef PVValueArray<uint8> PVUByteArray;
-typedef std::tr1::shared_ptr<PVUByteArray> PVUByteArrayPtr;
-
-typedef PVArrayData<uint16> UShortArrayData;
-typedef PVValueArray<uint16> PVUShortArray;
-typedef std::tr1::shared_ptr<PVUShortArray> PVUShortArrayPtr;
-
-typedef PVArrayData<uint32> UIntArrayData;
-typedef PVValueArray<uint32> PVUIntArray;
-typedef std::tr1::shared_ptr<PVUIntArray> PVUIntArrayPtr;
-
-typedef PVArrayData<uint64> ULongArrayData;
-typedef PVValueArray<uint64> PVULongArray;
-typedef std::tr1::shared_ptr<PVULongArray> PVULongArrayPtr;
-
-typedef PVArrayData<float> FloatArrayData;
-typedef PVValueArray<float> PVFloatArray;
-typedef std::tr1::shared_ptr<PVFloatArray> PVFloatArrayPtr;
-
-typedef PVArrayData<double> DoubleArrayData;
-typedef PVValueArray<double> PVDoubleArray;
-typedef std::tr1::shared_ptr<PVDoubleArray> PVDoubleArrayPtr;
-
-typedef PVArrayData<String> StringArrayData;
-typedef PVValueArray<String> PVStringArray;
-typedef std::tr1::shared_ptr<PVStringArray> PVStringArrayPtr;
- -

where

-
-
get( std::size_t offset, std::size_t length, ArrayDataType &data) -
-
This method "exposes" it's internal array by setting data.data and - data.offset. The caller is responsible for copying the array elements. - This violates the principle that objects should not expose their internal - data but is done for efficency. For example it makes it possible to copy - between arrays with identical element types without requiring an - intermediate array.
-
put(std::size_t offset, std::size_t length, const_pointer from, - std::size_t fromOffset)
-
Put data into the array. from is a raw array.
-
put(std::size_t offset, std::size_t length, const_vector &from, - std::size_t fromOffset)
-
Put data into the array from a vector holding the raw array.
-
shareData( shared_vector const & value, std::size_t capacity, - std::size_t length)
-
Make the instance share the raw data from value.
- One use is - for immutable arrays. In this case the caller must set the PVArray to be - immutable. In the PVArray is not immutable then it is the applications - responsibility to coordinate access to the array. Again this violates the - principle that objects should not expose their internal data 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 choices is immutable. Allowing the - choices internal String[] to be shared between all the instances of an - enumerated structure saves on storage.
- Another use for shared data is an application which processes an - array via multiple modules. Each accesses the internal data array of a - PVArray. In this case it is the applications responsibility - to coordinate access to the array.
-
get()
-
Get the raw array.
-
getVector()
-
Get the vector holding the raw array.
-
getSharedVector()
-
Get the shared vector holding the data.
-
dumpValue
-
Method for streams I/O.
-
- -

Both get and put return the number of elements actually transfered. The -arguments are:

-
-
offset
-
The offset in the PV array.
-
len
-
The maximum number of elements to transfer. The number actually - transfered will be less than or equal to this value.
-
data
-
Get sets data.data to it's internal array and data.offset to the offset - into the array. The caller is responsible for the actual data - transfer.
-
from
-
The array from which the data is taken. This array is supplied by the - caller
-
fromOffset
-
The offset in from
-
- -

The caller must be prepared to make multiple calls to retrieve or put an -entire array. A caller should accept or put partial arrays. For example the -following reads an entire array:

-
void getArray(PVDoubleArrayPtr & pv,DoubleArray const & to)
-{
-    size_t len = pv->getLength();
-    if(to.size()<len) to.resize(len);
-    DoubleArrayData data;
-    size_t offset = 0;
-    while(offset<len) {
-        size_t num = pv->get(offset,(len-offset),data);
-        DoubleArray &from = data.data;
-        size_t fromOffset = data.offset;
-        for(size_t i=0; i<num; i++) to[i+offset] = from[i + fromOffset];
-        offset += num;
-    }
-}
- -

- -

PVStructure

- -

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(String const &fieldName) const;
-    PVFieldPtr getSubField(std::size_t fieldOffset) const;
-    void appendPVField(
-        String const &fieldName,
-        PVFieldPtr const & pvField);
-    void appendPVFields(
-        StringArray const & fieldNames,
-        PVFieldPtrArray const & pvFields);
-    void removePVField(String const &fieldName);
-    PVBooleanPtr getBooleanField(String const &fieldName) ;
-    PVBytePtr getByteField(String const &fieldName) ;
-    PVShortPtr getShortField(String const &fieldName) ;
-    PVIntPtr getIntField(String const &fieldName) ;
-    PVLongPtr getLongField(String const &fieldName) ;
-    PVUBytePtr getUByteField(String const &fieldName) ;
-    PVUShortPtr getUShortField(String const &fieldName) ;
-    PVUIntPtr getUIntField(String const &fieldName) ;
-    PVULongPtr getULongField(String const &fieldName) ;
-    PVFloatPtr getFloatField(String const &fieldName) ;
-    PVDoublePtr getDoubleField(String const &fieldName) ;
-    PVStringPtr getStringField(String const &fieldName) ;
-    PVStructurePtr getStructureField(String const &fieldName) ;
-    PVScalarArrayPtr getScalarArrayField(
-        String const &fieldName,ScalarType elementType) ;
-    PVStructureArrayPtr getStructureArrayField(String const &fieldName) ;
-    String getExtendsStructureName() const;
-    bool putExtendsStructureName(
-        String const &extendsStructureName);
-    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);
-};
- -

where

-
-
getStructure
-
Get the introspection interface for the structure.
-
getPVFields
-
Returns the array of subfields. The set of subfields must all have - different field names.
-
getSubField(String fieldName)
-
Get a subField of a field. For a PVStructure a non-null result is - returned if fieldName is a field of the PVStructure. The fieldName can be - of the form name.name... - If the field does not exist the a Ptr to a NULL value is returned - without any error message being generated. -
-
getSubField(int fieldOffset)
-
Get the field located a fieldOffset, where fieldOffset is relative to - the top level structure. This returns null if the specified field is not - located within this PVStructure.
-
appendPVField
-
Append pvField to the end of this PVStructure. This should NOT be - called if any code is attached to any of the fields in the top level - structure.
-
appendPVFields
-
Append an array of pvFields to the end of this structure. Note that if - the original number of fields is 0 than pvFields replaces the original. - Thus the caller must NOT reuse pvFields after calling this method. This - should NOT be called if any code is attached to any of the fields in the - top level structure
-
removePVField
-
Remove the specified field from this structure. This should NOT be - called if any code is attached to any of the fields in the top level - structure.
-
getBooleanField
-
Look for fieldName. If found and it has the correct type return the - interface. This and the following methods are convenience methods that - allow a user to get the interface to a subfield without requiring - introspection. fieldName can be of the form name.name... - If the field does not exist or has the wrong type then - message will be called and a Ptr to NULL is returned. -
-
getByteField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getShortField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getIntField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getLongField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getUByteField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getUShortField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getUIntField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getULongField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getFloatField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getDoubleField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getStringField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getStructureField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getScalarArrayField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getStructureArrayField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getExtendsStructureName
-
Get the name of structure that this structure extends.
-
putExtendsStructureName
-
Specify the structure that this structure extends.
-
- -

PVStructureArray

- -

The interface for an array of structures is:

-
typedef PVArrayData<PVStructurePtr> StructureArrayData;
-
-class PVStructureArray : public PVArray
-{
-public:
-    POINTER_DEFINITIONS(PVStructureArray);
-    typedef PVStructurePtr  value_type;
-    typedef PVStructurePtr* pointer;
-    typedef const PVStructurePtr* const_pointer;
-    typedef PVArrayData<PVStructurePtr> ArrayDataType;
-    typedef std::vector<PVStructurePtr> vector;
-    typedef const std::vector<PVStructurePtr> const_vector;
-    typedef std::tr1::shared_ptr<vector> shared_vector;
-    typedef PVStructureArray &reference;
-    typedef const PVStructureArray& const_reference;
-
-    virtual ~PVStructureArray() {}
-    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 std::size_t get(std::size_t offset, std::size_t length,
-        StructureArrayData &data);
-    virtual std::size_t put(std::size_t offset,std::size_t length,
-        const_vector const & from, std::size_t fromOffset);
-    virtual void shareData(
-         shared_vector const & value,
-         std::size_t capacity,
-         std::size_t length);
-    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 pointer get() { return &((*value.get())[0]); }
-    virtual pointer get() const { return &((*value.get())[0]); }
-    virtual vector const & getVector() {return *value;}
-    virtual shared_vector const & getSharedVector() {return value;}
- ...
-}
- -

where

-
-
getStructureArray
-
Get the introspection interface shared by each element.
-
append
-
Create new elements and append them to the end of the array. It returns - the index of the first new element.
-
remove
-
Remove the specfied set of elements. It returns (false,true) if the - elements (were not, were) removed. It will not removed any elements - unless all requested elements exist or are null. Note that this deletes - the element and sets the array element to null. It does not change the - array capacity.
-
compress
-
This moves all null elements and then changes the array capacity. When - done there are no null elements.
-
- -

The other methods are similar to the methods for other array types.

- -

PVDataCreate

- -

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);
-    PVScalarArrayPtr createPVScalarArray(ScalarArrayConstPtr const & scalarArray);
-    PVScalarArrayPtr createPVScalarArray(ScalarType elementType);
-    PVScalarArrayPtr createPVScalarArray(PVScalarArrayPtr const  & scalarArrayToClone);
-    PVStructureArrayPtr createPVStructureArray(StructureArrayConstPtr const & structureArray);
-    PVStructurePtr createPVStructure(StructureConstPtr const & structure);
-    PVStructurePtr createPVStructure(
-        StringArray const & fieldNames,PVFieldPtrArray const & pvFields);
-   PVStructurePtr createPVStructure(PVStructurePtr const & structToClone);
- ...
-};
-
-extern PVDataCreatePtr getPVDataCreate();
- -

where

-
-
createPVField
-
The PVField is created reusing the Field interface. Two methods are - provided. Each calls the corresponding createPVScalar, createPVArray, or - createPVStructure depending in the type of the last argument.
-
createPVScalar
-
Creates an instance of a PVScalar. Three versions are supplied. The - first is passed an introspection interface. The second provides the field - name and the scalarType. The last provides a field name and a PVScalar to - clone. The newly created PVScalar will have the same auxInfos as the - original.
-
createPVScalarArray
-
Create an instance of a PVArray. Three versions are supplied. The first - is passed an introspection interface. The second provides the field name - and the elementType. The last provides a field name and a PVArray to - clone. The newly created PVArray will have the same auxInfos as the - original.
-
createPVStructureArray
-
Create a PVStructureArray. It must be passed a structureToClone. This - will become the Structure interface for ALL elements of the - PVStructureArray. It MUST be used to create any new array elements.
-
createPVStructure
-
Create an instance of a PVStructure. Three methods are provided. The - first method uses a previously created structure introspection interface. - The second uses a PVField array to initialize the sub-fields. - The third initializes the subfields by cloning the fields contained in - structToClone. The newly created sub-fields will have the same values and - auxInfos as the original. If structToClone is null then the new structure - is initialized to have 0 sub-fields.
-
- -

standardPVField.h

- -

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,String const &properties);
-    PVStructurePtr scalarArray(ScalarType elementType, String const &properties);
-    PVStructurePtr structureArray(StructureConstPtr const &structure,String const &properties);
-    PVStructurePtr enumerated(StringArray const &choices);
-    PVStructurePtr enumerated(StringArray const &choices, String const &properties);
- ...
-}
-
-
-extern StandardPVFieldPtr getStandardPVField();
- -

convert.h

- -

NOTE about copying immutable array fields. If an entire immutable array -field is copied to another array that has the same elementType, both offsets -are 0, and the length is the length of the source array, then the shareData -method of the target array is called and the target array is set immutable. -Thus the source and target share the same primitive array.

- -

This section describes the supported conversions between data types.

- -
bool operator==(PVField&, PVField&);
-
-static inline bool operator!=(PVField& a, PVField& b)
-{return !(a==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&);
-
-static inline bool operator!=(const Field& a, const Field& b)
-{return !(a==b);}
-static inline bool operator!=(const Scalar& a, const Scalar& b)
-{return !(a==b);}
-static inline bool operator!=(const ScalarArray& a, const ScalarArray& b)
-{return !(a==b);}
-static inline bool operator!=(const Structure& a, const Structure& b)
-{return !(a==b);}
-static inline bool operator!=(const StructureArray& a, const StructureArray& b)
-{return !(a==b);}
-class Convert;
-typedef std::tr1::shared_ptr<Convert> ConvertPtr;
-
-class Convert {
-public:
-    static ConvertPtr getConvert();
-    ~Convert();
-    void getFullName(StringBuilder buf,PVFieldPtr const & pvField);
-    bool equals(PVFieldPtr const &a,PVFieldPtr const &b);
-    bool equals(PVField &a,PVField &b);
-    void getString(StringBuilder buf,PVFieldPtr const & pvField,int indentLevel);
-    void getString(StringBuilder buf,PVFieldPtr const & pvField);
-    void getString(StringBuilder buf,PVField const * pvField,int indentLevel);
-    void getString(StringBuilder buf,PVField const * pvField);
-    std::size_t fromString(
-        PVStructurePtr const &pv,
-        StringArray const & from,
-        std::size_t fromStartIndex = 0);
-    void fromString(PVScalarPtr const & pv, String const & from);
-    std::size_t fromString(PVScalarArrayPtr const & pv, 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);
-    std::size_t copyScalarArray(
-        PVScalarArrayPtr const & from,
-        std::size_t offset,
-        PVScalarArrayPtr const & to,
-        std::size_t toOffset,
-        std::size_t length);
-    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);
-    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);
-    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);
-    std::size_t toByteArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        int8* to,
-        std::size_t toOffset);
-    std::size_t toShortArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        int16* to,
-        std::size_t toOffset);
-    std::size_t toIntArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        int32* to,
-        std::size_t toOffset);
-    std::size_t toLongArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        int64* to,
-        std::size_t toOffset);
-    std::size_t toUByteArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        uint8* to,
-        std::size_t toOffset);
-    std::size_t toUShortArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        uint16* to,
-        std::size_t toOffset);
-    std::size_t toUIntArray(
-        PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        uint32* to,
-        std::size_t toOffset);
-    std::size_t toULongArray(
-        PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        uint64* to,
-        std::size_t toOffset);
-    std::size_t toFloatArray(
-        PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        float* to,
-        std::size_t toOffset);
-    std::size_t toDoubleArray(
-        PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        double* to, std::size_t
-        toOffset);
-    std::size_t fromByteArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const int8* from, std::size_t fromOffset);
-    std::size_t fromByteArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const ByteArray & from, std::size_t fromOffset);
-    std::size_t fromShortArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const int16* from, std::size_t fromOffset);
-    std::size_t fromShortArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const ShortArray & from, std::size_t fromOffset);
-    std::size_t fromIntArray(
-       PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-       const int32* from, std::size_t fromOffset);
-    std::size_t fromIntArray(
-       PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-       const IntArray & from, std::size_t fromOffset);
-    std::size_t fromLongArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const int64* from, std::size_t fromOffset);
-    std::size_t fromLongArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const LongArray & from, std::size_t fromOffset);
-    std::size_t fromUByteArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const uint8* from, std::size_t fromOffset);
-    std::size_t fromUByteArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const UByteArray & from, std::size_t fromOffset);
-    std::size_t fromUShortArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const uint16* from, std::size_t fromOffset);
-    std::size_t fromUShortArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const UShortArray & from, std::size_t fromOffset);
-    std::size_t fromUIntArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const uint32* from, std::size_t fromOffset);
-    std::size_t fromUIntArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const UIntArray & from, std::size_t fromOffset);
-    std::size_t fromULongArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const uint64* from, std::size_t fromOffset);
-    std::size_t fromULongArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const ULongArray & from, std::size_t fromOffset);
-    std::size_t fromFloatArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const float* from, std::size_t fromOffset);
-    std::size_t fromFloatArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const FloatArray & from, std::size_t fromOffset);
-    std::size_t fromDoubleArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const double* from, std::size_t fromOffset);
-    std::size_t fromDoubleArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const DoubleArray & from, std::size_t fromOffset);
-    void newLine(StringBuilder buf, int indentLevel);
- ...
-}
-
-extern ConvertPtr getConvert();
- -

The array methods all return the number of elements copied or converted. -This can be less than len if the PVField array contains less than len -elements.

- -

newLine is a convenience method for code that implements toString It -generates a newline and inserts blanks at the beginning of the newline.

- -

pvDataApp/property

- -

Definition of Property

- -

Only fields named "value" have properties. A record can have multiple value -fields, which can appear in the top level structure of a record or in a -substructure. All other fields in the structure containing a value field are -considered properties of the value field. The fieldname is also the property -name. The value field can have any type, i.e. scalar, scalarArray, or -structure. Typical property fields are timeStamp, alarm, display, control, and -history. The timeStamp is a special case. If it appears anywhere in the -structure hieraracy above a value field it is a property of the value field.

- -

For example the following top level structure has a single value field. The -value field has properties alarm, timeStamp, and display.

-
structure counterOutput
-    double value
-    alarm_t
-        int severity 0
-        int status 0
-        string message
-    timeStamp_t
-        long secondsPastEpoch
-        int nanoSeconds
-        int userTag
-    display_t
-        double limitLow 0.0
-        double limitHigh 10.0
-        string description "Sample Description"
-        string format "%f"
-        string units volts
- -

The following example has three value fields each with properties alarm and -timeStamp. Voltage, Current, and Power each have a different alarms but all -share the timeStamp.

-
structure powerSupplyValue
-    double value
-    alarm_t
-        int severity 0
-        int status 0
-        string message
-
-structure powerSupplySimple
-    alarm_t
-        int severity 0
-        int status 0
-        string message
-    timeStamp_t
-        long secondsPastEpoch
-        int nanoSeconds
-        int userTag
-    powerSupplyValue_t voltage
-        double value
-        alarm_t
-            int severity 0
-            int status 0
-            string message
-    powerSupplyValue_t power
-        double value
-        alarm_t
-            int severity 0
-            int status 0
-            string message
-    powerSupplyValue_t current
-        double value
-        alarm_t
-            int severity 0
-            int status 0
-            string message
- -

Standard Properties

- -

The following field names have special meaning, i.e. support properties for -general purpose clients.

-
-
value
-
This is normally defined since most general purpose clients access this - field. All other fields in the structure support or describe the value - field. The type can any supported type but is usually one of the - following: -
-
scalar
-
Any of the scalar types.
-
scalarArray
-
An array with the elementType being a scalar type
-
enumerated structure
-
A structure that includes fields named index and choices. index - is an int that selects a choice. choices is an array of strings - that defines the complete set of choices.
-
other
-
Other structure or array types can also be defined if clients and - support code agree on the meaning. Some examples are: 1) A - structure defining a 2D matrix, 2) A structure defining an image, - 3) A structure that simulates a remote method, ...
-
-
-
timeStamp
-
The timeStamp. The type MUST be a timeStamp structure. Also if the - PVData structure does not have a timeStamp then a search up the parent - tree is made to find a timeStamp.
-
alarm
-
The alarm. The type MUST be an alarm structure.
-
display
-
A display structure as described below. It provides display - characteristics for the value field.
-
control
-
A control structure as described below. It provides control - characteristics for the value field.
-
history
-
Provides a history buffer for the value field. Note that currently - PVData does not define history suppoprt.
-
other
-
Other standard properties can be defined.
-
- -

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:

-
-
input
-
A field with support that changes the value field. This can be - anything. It can be a channel access link. It can obtain a value from - hardware. Etc.
-
valueAlarm
-
A field with support that looks for alarm conditions based on the - value.
-
output
-
A field with support that reads the current value and sends it - somewhere else. This can be anything. It can be a channel access link. It - can write a value to hardware. Etc.
-
- -

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. -

- -

Overview of Property Support

- -

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(String("testMessage"));
-    al.setSeverity(majorAlarm);
-    result = pvAlarm.set(al);
-    assert(result);
-    alarm = pvAlarm.get();
-     ...
-}
- -

timeStamp

- -

A timeStamp is represented by the following structure

-
structure timeStamp
-    long secondsPartEpoch
-    int nanoSeconds
-    int userTag
- -

The Epoch is the posix epoch, i.e. Jan 1, 1970 00:00:00 UTC. Both the -seconds and nanoSeconds are signed integers and thus can be negative. Since the -seconds is kept as a 64 bit integer, it allows for a time much greater than the -present age of the universe. Since the nanoSeconds portion is kept as a 32 bit -integer it is subject to overflow if a value that corresponds to a value that -is greater than a little more than 2 seconds of less that about -2 seconds. The -support code always adjust seconds so that the nanoSecconds part is normlized, -i. e. it has is 0<=nanoSeconds<nanoSecPerSec..

- -

Two header files are provided for manipulating time stamps:

-
-
timeStamp.h
-
Defines a time stamp independent of pvData, i.e. it is a generally - useful class for manipulating timeStamps.
-
pvTimeStamp.h
-
A class that can be attached to a time stamp pvData structure. It - provides get and set methods to get/set a TimeStamp as defined by - timeStamp.h
-
- -

timeStamp.h

- -

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

-
-
TimeStamp()
-
The defauly constuctor. Both seconds and nanoSeconds are set to 0.
-
TimeStamp(int64 secondsPastEpoch,int32 nanoSeconds = 0)
-
A constructor that gives initial values to seconds and nanoseconds.
-
normalize
-
Adjust seconds and nanoSeconds so that - 0<=nanoSeconds<nanoSecPerSec.
-
fromTime_t
-
Set time from standard C time.
-
toTime_t
-
Convert timeStamp to standard C time.
-
getSecondsPastEpoch
-
Get the number of seconds since the epoch.
-
getEpicsSecondsPastEpoch
-
Get the number of EPICS seconds since the epoch. EPICS uses Jan 1, 1990 - 00:00:00 UTC as the epoch.
-
getNanoSeconds
-
Get the number of nanoSeconds. This is always normalized.
-
getUserTag
-
Get the userTag.
-
setUserTag
-
Set the userTag.
-
put(int64 secondsPastEpoch,int32 nanoSeconds = 0)
-
Set the timeStamp value. If necessary it will be normalized.
-
put(int64 milliseconds)
-
Set the timeStamp with a value the is the number of milliSeconds since - the epoch.
-
getCurrent()
-
Set the timeStamp to the current time.
-
toSeconds()
-
Convert the timeStamp to a value that is the number of seconds since - the epocj
-
operator =
-
operator!=
-
operator<=
-
operator<
-
operator>=
-
operator>
-
Standard C++ operators.
-
diff
-
diff = a - b
-
getMilliseconds
-
Get the number of milliseconds since the epoch.
-
- -

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);
- -

pvTimeStamp.h

-
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

-
-
PVTimeStamp
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if a timeStamp - structure is found. It looks first at pvField itself and if is not an - appropriate pvData structure but the field name is value it looks up the - parent structure tree.
-
detach
-
Detach from the pvData structure.
-
isAttached
-
Is there an attachment to a timeStamp structure?
-
get
-
Copies data from the pvData structure to a TimeStamp. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from TimeStamp to the pvData structure. An exception is - thrown if not attached to a pvData structure.
-
- -

alarm

- -

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:

-
-
alarm.h
-
Defines an alarm independent of pvData, i.e. it is a generally useful - class for manipulating alarms.
-
pvAlarm.h
-
A class that can be attached to an alarm pvData structure. It provides - get and set methods to get/set alarm data as defined by alarm.h
-
- -

alarm.h

-
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
-    String getMessage();
-    void setMessage(String const &value);
-    AlarmSeverity getSeverity() const;
-    void setSeverity(AlarmSeverity value);
-    AlarmStatus getStatus() const;
-    void setStatus(AlarmStatus value);
-};
- -

Alarm Severity defines the possible alarm severities:

-
-
getSeverity
-
Get the alarm severity corresponding to the integer value.
-
getSeverityNames
-
Get the array of severity choices.
-
- -

Alarm Status defines the possible choices for alarm status:

-
-
getStatus
-
Get the alarm status corresponding to the integer value.
-
getStatusNames
-
Get the array of status choices.
-
- -

Alarm has the methods:

-
-
Alarm
-
The constructor. It sets the severity to no alarm and the message to - "".
-
getMessage
-
Get the message.
-
setMessage
-
Set the message.
-
getSeverity
-
Get the severity.
-
setSeverity
-
Set the severity.
-
getStatus
-
Get the status.
-
setStatus
-
Set the status.
-
- -

pvAlarm.h

-
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

-
-
PVAlarm
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if it found an - appropriate pvData structure. It looks first a pvField itself and if is - not an appropriate pvData structure but the field name is value it looks - to see if the parent structure has an appropriate sub structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to an alarm structure?
-
get
-
Copies data from the pvData structure to an Alarm. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from Alarm to the pvData structure. An exception is thrown - if not attached to a pvData structure.
-
- -

control

- -

Control information is represented by the following structure

-
structure control
-    double limitLow
-    double limitHigh
-    double minStep
- -

Two header files are provided for manipulating control:

-
-
control.h
-
Defines control independent of pvData, i.e. it is a generally useful - class for manipulating control.
-
pvControl.h
-
A class that can be attached to an control pvData structure. It - provides get and set methods to get/set control data as defined by - control.h
-
- -

control.h

-
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

-
-
Control
-
The default constructure.
-
getLow
-
Get the low limit.
-
getHigh
-
Get the high limit.
-
setLow
-
Set the low limit.
-
setHigh
-
Set the high limit.
-
setMinStep
-
Set the minimum step size.
-
getMinStep
-
Get he minimum step size.
-
- -

pvControl.h

-
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

-
-
PVControl
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if it found an - appropriate pvData structure. It looks first a pvField itself and if is - not an appropriate pvData structure but the field name is value it looks - to see if the parent structure has an appropriate sub structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to a control structure?
-
get
-
Copies data from the pvData structure to a Control. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from Control to the pvData structure. An exception is - thrown if not attached to a pvData structure.
-
- -

display

- -

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:

-
-
display.h
-
Defines display independent of pvData, i.e. it is a generally useful - class for manipulating display.
-
pvDisplay.h
-
A class that can be attached to an display pvData structure. It - provides get and set methods to get/set display data as defined by - display.h
-
- -

display.h

-
class Display {
-public:
-    Display();
-    //default constructors and destructor are OK
-    double getLow() const;
-    double getHigh() const;
-    void setLow(double value);
-    void setHigh(double value);
-    String getDescription() const;
-    void setDescription(String const &value);
-    String getFormat() const;
-    void setFormat(String const &value);
-    String getUnits() const;
-    void setUnits(String const &value);
-};
- -

where

-
-
Control
-
The default constructure.
-
getLow
-
Get the low limit.
-
getHigh
-
Get the high limit.
-
setLow
-
Set the low limit.
-
setHigh
-
Set the high limit.
-
getDescription
-
Get the description.
-
setDescription
-
Set the description.
-
getFormat
-
Get the format.
-
setFormat
-
Set the format.
-
getUnits
-
Get the units.
-
setUnits
-
Set the units.
-
- -

pvDisplay.h

-
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

-
-
PVDisplay
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if it found an - appropriate pvData structure. It looks first a pvField itself and if is - not an appropriate pvData structure but the field name is value it looks - to see if the parent structure has an appropriate sub structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to a display structure?
-
get
-
Copies data from the pvData structure to a Display. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from Display to the pvData structure. An exception is - thrown if not attached to a pvData structure.
-
- -

pvEnumerated.h

- -

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();
-    String getChoice();
-    bool choicesMutable();
-    StringArrayPtr const & getChoices();
-    int32 getNumberChoices();
-    bool setChoices(StringArray &choices,int32 numberChoices);
-};
- -

where

-
-
PVEnumerated
-
The default constructor. Attach must be called before any get or set - method can be called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if pvField (is - not, is) an enumerated structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to an enemerated structure?
-
setIndex
-
Set the index field in the pvData structure. An exception is thrown if - not attached to a pvData structure.
-
getIndex
-
Get the index field in the pvData structure.
-
getChoice
-
Get the String value corresponding to the current index field in the - pvData structure. An exception is thrown if not attached to a pvData - structure.
-
choicesMutable
-
Can the choices be changed? Note that this is often true. An exception - is thrown if not attached to a pvData structure.
-
getChoices
-
Get the array of choices. An exception is thrown if not attached to a - pvData structure.
-
getNumberChoices
-
Get the number of choices. An exception is thrown if not attached to a - pvData structure.
-
setChoices
-
Change the choices. An exception is thrown if not attached to a pvData - structure.
-
- -

Examples

- -

Accessing PVData

- -

Assume that code wants to print two fields from a PVStructure:

-
-
value
-
Must be a PVDouble.
-
timeStamp
-
Just look for field with this name.
-
- -

The following code uses introspection to get the desired information.

-
void getValueAndTimeStamp(PVStructurePtr pvStructure,StringBuilder buf) {
-   PVFieldPtr valuePV = pvStructure->getSubField(String("value"));
-   if(valuePV.get()==NULL) {
-       buf += "value field not found";
-       return;
-   }
-   buf += "value ";
-   valuePV->toString(&buf);
-   PVFieldPtr timeStampPV = pvStructure->getSubField(String("timeStamp"));
-   if(timeStampPV.get()==NULL) {
-       buf += "timeStamp field not found";
-       return;
-   }
-   buf += " timeStamp ";
-   timeStampPV->toString(&buf);
-}
- -

Creating PVData

- -

Example of creating a scalar field.

-
    PVDataCreatePtr pvDataCreate = getPVDataCreate();
-    PVDoublePtr pvValue = static_pointer_cast<PVDouble>(
-        pvDataCreate->createPVScalar(pvDouble));
- -

Create a structure with a value and an alarm the hard way

-
    FieldCreatePtr fieldCreate = getFieldCreate();
-    PVDataCreatePtr pvDataCreate = getPVDataCreate();
-    FieldConstPtrArray fields;
-    StringArray names;
-    fields.resize(3);
-    names.resize(3);
-    fields[0] = fieldCreate->createScalar(pvInt);
-    fields[1] = fieldCreate->createScalar(pvInt);
-    fields[2] = fieldCreate->createScalar(pvString);
-    names[0] = "severity";
-    names[0] = "status";
-    names[0] = "message";
-    StructureConstPtr alarmField =  
-        fieldCreate->createStructure(names,fields);
-    fields.resize(2);
-    names.resize(2);
-    fields[0] = fieldCreate->createScalar(pvDouble);
-    fields[1] = alarmField;
-    names[0] = "value";
-    names[0] = "alarm";
-    StructureConstPtr structure =
-        fieldCreate->createStructure(names,fields);
-    PVStructurePtr pv = pvDataCreate->createPVStructure(structure);
- -

Create an alarm structure the easy way.

-
    StandardPVFieldPtr standardPVField = getStandardPVField();
-    PVStructurePtr pv = standardPVField->scalar(pvDouble,"alarm");
- -

Create a PVStructure with field name example that has a double value field , -timeStamp, alarm, and display. Do it the easy way.

-
    StandardPVFieldPtr standardPVField = getStandardPVField();
-    PVStructurePtr pvStructure = standardPVField->scalar(
-        pvDouble,"timeStamp,alarm.display");
- -

pvDataApp/factory

- -

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.

- -

PVAuxInfoImpl.cpp implements auxInfo.

- -

Convert.cpp automatically creates a single instance of Convert and -implements getConvert.

- -

Other files implement PVData base classes

- -

pvDataAPP/misc

- -

Overview

- -

This package provides utility code:

-
-
bitSet.h
-
An implementation of BitSet that can be serialized.
-
byteBuffer.h
-
Used to serialize objects.
-
destroyable.h
-
Provides method destroy.
-
epicsException.h
-
Exception with stack trace.
-
event.h
-
Signal and wait for an event.
-
executor.h
-
Provides a thread for executing commands.
-
lock.h
-
Support for locking and unlocking.
-
messageQueue.h
-
Support for queuing messages to give to requesters.
-
noDefaultMethods.h
-
When privately extended prevents compiler from implementing default - methods.
-
queue.h
-
A queue implementation that allows the latest queue element to continue - to be used when no free element is available.
-
requester.h
-
Allows messages to be sent to a requester.
-
serialize.h
-
Support for serializing objects.
-
serializeHelper.h
-
More support for serializing objects.
-
sharedPtr.h
-
Defines POINTER_DEFINITIONS.
-
status.h
-
A way to pass status information to a client.
-
thread.h
-
Provides thread support.
-
timeFunction.h
-
Time how long a function call requires.
-
timer.h
-
An implementation of Timer that does not require an object to be - created for each timer request.
-
- -

Note that directory testApp/misc has test code for all the classes in misc. -The test code also can be used as examples.

- -

bitSet.h

- -

This is adapted from the java.util.BitSet. bitSet.h is:

-
class BitSet : public Serializable {
-public:
-    static BitSet::shared_pointer create(uint32 nbits);
-    BitSet();
-    BitSet(uint32 nbits);
-    virtual ~BitSet();
-    void flip(uint32 bitIndex);
-    void set(uint32 bitIndex);
-    void clear(uint32 bitIndex);
-    void set(uint32 bitIndex, bool value);
-    bool get(uint32 bitIndex) const;
-    void clear();
-    int32 nextSetBit(uint32 fromIndex) const;
-    int32 nextClearBit(uint32 fromIndex) const;
-    bool isEmpty() const;
-    uint32 cardinality() const;
-    uint32 size() const;
-    BitSet& operator&=(const BitSet& set);
-    BitSet& operator|=(const BitSet& set);
-    BitSet& operator^=(const BitSet& set);
-    BitSet& operator-=(const BitSet& set);
-    BitSet& operator=(const BitSet &set);
-    void or_and(const BitSet& set1, const BitSet& set2);
-    bool operator==(const BitSet &set) const;
-    bool operator!=(const BitSet &set) const;
-    void toString(StringBuilder buffer);
-    void toString(StringBuilder buffer, int indentLevel) const;
-private:
-};
- -

where

-
-
BitSet()
-
Creates a bitSet of initial size 64 bits. All bits initially false.
-
BitSet(uint32 nbits)
-
Creates a bitSet with the initial of the specified number of bits. All - bits initially false.
-
~BitSet()
-
Destructor.
-
flip(uint32 bitIndex)
-
Flip the specified bit.
-
set(uint32 bitIndex)
-
Set the specified bit true.
-
clear(uint32 bitIndex)
-
Set the specified bit false.
-
set(uint32 bitIndex, bool value)
-
Set the specified bit to value.
-
get(uint32 bitIndex)
-
Return the state of the specified bit.
-
clear()
-
Set all bits to false.
-
nextSetBit(uint32 fromIndex)
-
Get the index of the next true bit beginning with the specified - bit.
-
nextClearBit(uint32 fromIndex)
-
Get the index of the next false bit beginning with the specified - bit.
-
isEmpty()
-
Return (false,true) if (at least one bit true, all bits are false)
-
cardinality()
-
Return the number of true bits.
-
size()
-
Returns the number of bits of space actually in use.
-
operator&=(const BitSet& set)
-
Performs a logical and of this target bit set with the argument bit - set. This bit set is modified so that each bit in it has the value true - if and only if it both initially had the value true and the corresponding - bit in the bit set argument also had the value.
-
operator|=(const BitSet& set)
-
Performs a logical or of this target bit set with the argument bit - set.
-
operator^=(const BitSet& set)
-
Performs a logical exclusive or of this target bit set with the - argument bit set.
-
operator-=(const BitSet& set)
-

Clears all of the bits in this bitSet whose corresponding bit is set - in the specified bitSet.

-
-
operator=(const BitSet &set)
-
Assignment operator.
-
or_and(const BitSet& set1, const BitSet& set2)
-
Perform AND operation on set1 and set2, and then OR this bitSet with - the result.
-
operator==(const BitSet &set)
-
Does this bitSet have the same values as the argument.
-
operator!=(const BitSet &set)
-
Is this bitSet different than the argument.
-
toString(StringBuilder buffer)
-
Show the current values of the bitSet.
-
toString(StringBuilder buffer, int indentLevel)
-
Show the current values of the bitSet.
-
virtual void serialize(ByteBuffer *buffer,SerializableControl *flusher) - const;
-
Serialize the bitSet
-
virtual void deserialize(ByteBuffer *buffer,DeserializableControl - *flusher);
-
Deserialize the bitSet.
-
- -

byteBuffer.h

- -

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();
- ...
-};
- -

destroyable.h

-
class Destroyable  {
-public:
-    POINTER_DEFINITIONS(Destroyable);
-    virtual void destroy() = 0;
-    virtual ~Destroyable() {};
-};
- -

epicsException.h

-
/*
- * 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.
- */
- -

event.h

- -

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 */
-private:
-    epicsEventId id;
-};
- -

where

-
-
Event
-
The constructor. The initial value can be full or empty. The normal - first state is empty.
-
signal
-
The event becomes full. The current or next wait will complete.
-
wait
-
Wait until event is full or until timeout. The return value is - (false,true) if the wait completed because event (was not, was) full. A - false value normally means that that a timeout occured. It is also - returned if an error occurs or because the event is being deleted.
-
tryWait
-
returns (false,true) if the event is (empty,full)
-
- -

executor.h

- -

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(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:

-
-
Executor
-
The constructor. A thread name and priority must be specified.
-
~Executor
-
The destructor. If any commands remain in the execute list they are not - called. All ExecutorNodes that have been created are deleted.
-
execute
-
Request that command be executed. If it is already on the run list - nothing is done.
-
- -

lock.h

-
typedef epicsMutex Mutex;
-
-class Lock : private NoDefaultMethods {
-public:
-    explicit Lock(Mutex &pm);
-    ~Lock();
-    void lock();
-    void unlock();
-    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 xx(mutex);
-        if(alreadyInitialized) return;
-        // initialization
-    }
- -

messageQueue.h

- -

Definitions

- -

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:
-    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(String message,MessageType messageType,bool replaceLast);
-    bool isEmpty() ;
-    bool isFull() ;
-    int getClearOverrun();
- ...
-};
- -

A messageNode is a class with two public data members:

-
-
getMessage
-
The message.
-
getMessageType
-
The message type.
-
setMessageNull
-
Set the message to be a null string.
-
- -

A messageQueue is an interface with public methods:

-
-
MessageQueue
-
The constructor. The queue size must be specified.
-
~MessageQueue
-
The destructor.
-
put
-
Put a new message into the queue. False is returned if the queue was - full and true otherwise. If replaceLast is true then the last message is - replaced with this message.
-
get
-
Get the oldest queue element. If the queue is empty null is returned. - Before the next get can be issued release must be called.
-
release
-
Release the queue element returned by the last get.
-
isEmpty
-
Is the queue empty?
-
isFull
-
Is the queue full?
-
getClearOverrun
-
Get the number of times put has been called but no free element is - available.
-
- -

Look at miscTest/testMessageQueue.cpp for an example.

- -

noDefaultMethods.h

- -

If a class privately extends this class then the compiler can not create any -of the following: default constructor, default copy constructror, or default -assignment contructor.

-
/* This is based on Item 6 of
- * Effective C++, Third Edition, Scott Meyers
- */
-    class NoDefaultMethods {
-    protected:
-    // allow by derived objects
-    NoDefaultMethods(){};
-    ~NoDefaultMethods(){}
-    private:
-    // do not implment
-    NoDefaultMethods(const NoDefaultMethods&);
-    NoDefaultMethods & operator=(const NoDefaultMethods &);
-    };
- -

queue.h

- -

This provides a queue which has an immutable capacity. When the queue is -full the user code is expected to keep using the current element until a new -free element becomes avalable.

-
template <typename T>
-class Queue
-{   
-public:
-    POINTER_DEFINITIONS(Queue);
-    typedef std::tr1::shared_ptr<T> queueElementPtr;
-    typedef std::vector<queueElementPtr> queueElementPtrArray;
-    Queue(queueElementPtrArray &);
-    virtual ~Queue();
-    void clear();
-    int capacity();
-    int getNumberFree();
-    int getNumberUsed();
-    queueElementPtr & getFree();
-    void setUsed(queueElementPtr &element);
-    queueElementPtr & getUsed();
-    void releaseUsed(queueElementPtr &element);
- ...
-};
- -

testApp/misc/testQueue.cpp provides an example of how to define a queue.

- -

The queue methods are:

-
-
clear
-
Make the queue empty.
-
getNumberFree
-
Get the number of free elements in the queue.
-
capacity
-
Get the capacity, i.e. the maximun number of elements the queue can - hold.
-
getNumberFree
-
Get the number of free elements.
-
getNumberUsed
-
Get the number of elements used.
-
getFree
-
Get the next free element. Null is returned if no free elements are - available. If a non null value is returned then the element belongs to - the caller until setUsed is called.
-
setUsed
-
Set a queue element used. This must be the element returned by the last - call to getFree.
-
getUsed
-
Get the next used element of null if no more used elements are - available.
-
releaseUsed
-
Set a queue element free. This must be the element returned by the last - call to getUsed.
-
- -

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.h

- -

A PVField extends Requester. Requester is present so that when database -errors are found there is someplace to send a message.

-
enum MessageType {
-   infoMessage,warningMessage,errorMessage,fatalErrorMessage
-};
-
-extern String getMessageTypeName(MessageType messageType);
-extern const size_t messageTypeCount;
-class Requester {
-public:
-    POINTER_DEFINITIONS(Requester);
-    virtual ~Requester(){}
-    virtual String getRequesterName() = 0;
-    virtual void message(String const & message,MessageType messageType) = 0;
-};
- -

where

-
-
-
MessageType
-
Type of message.
-
messageTypeName
-
An array of strings of the message type names, i.e. - String("info"),String("warning"),String("error"),String("fatalError").
-
getRequesterName
-
Returns the requester name.
-
message
-
Gives a message to the requester.
-
- -

serialize.h

-
    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;
-    };
- -

serializeHelper.h

- -

This is a helper class for serialization, which is required for sending and -receiving pvData over the nerwork.

-
class SerializeHelper : public NoDefaultMethods {
-public:
-    static void writeSize(int s, ByteBuffer* buffer,
-        SerializableControl* flusher);
-    static int readSize(ByteBuffer* buffer,
-        DeserializableControl* control);
-    static void serializeString(const String& value,
-        ByteBuffer* buffer,SerializableControl* flusher);
-    static void serializeSubstring(const String& value, int offset,
-        int count, ByteBuffer* buffer,
-        SerializableControl* flusher);
-    static String deserializeString(ByteBuffer* buffer,
-        DeserializableControl* control);
- ...
-};
- -

where

-
-
writeSize
-
Serialize the size.
-
readSize
-
Deserialize the size.
-
serializeString
-
Serialize a String.
-
serializeSubstring
-
Serialize a substring.
-
deserializeString
-
Deserialize a string.
-
- -

sharedPtr.h

-
#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;
- -

status.h

- -

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, epics::pvData::String const & message);
-    Status(StatusType type, epics::pvData::String const & message, epics::pvData::String stackDump);
-    ~Status()
-    StatusType getType() const;
-    String getMessage() const;
-    String getStackDump() const;
-    bool isOK() const;
-    bool isSuccess() const;
-    String toString() const;
-    void toString(StringBuilder buffer, int indentLevel = 0) const;
-    void serialize(ByteBuffer *buffer, SerializableControl *flusher) const;
-    void serialize(ByteBuffer *buffer, SerializableControl *flusher) const;
-};
- -

The Status methods are:

-
-
StatusType
-
An enum for the status type.
-
getType
-
Get the statusType.
-
getMessage
-
Get a message explaining the error.
-
getStackDump
-
Get a stack dump.
-
- -

The StatusCreate methods are:

-
-
getStatusOK
-
Get a singleton that returns StatusType.OK and a null message and - stackDump.
-
createStatus
-
Create a new Status.
-
deserializeStatus
-
Use this method instead of Status.deserialize(), since this allows OK - status optimization.
-
- -

thread.h

- -

ThreadPriority

-
enum ThreadPriority {
-    lowestPriority,
-    lowerPriority,
-    lowPriority,
-    middlePriority,
-    highPriority,
-    higherPriority,
-    highestPriority
-};
- -

Thread

-
class Runnable {
-public:
-    virtual void run() = 0;
-};
-
-class Thread;
-
-class Thread : public epicsThread, private NoDefaultMethods {
-public:
-    Thread(
-        String name,
-        ThreadPriority priority,
-        Runnable *runnableReady,
-        epicsThreadStackSizeClass stkcls=epicsThreadStackSmall);
-    ~Thread();
- ...
-};
- -

Runnable must be implement by code that wants to be run via a thread. It has -one virtual method: run. Run is the code that is run as a thread. When run -compeletes it can not be restarted. If code wants to delete a thread then it -MUST arrange that the run returns before the thread can be deleted. An -exception is thrown if run remains active when delete is called.

- -

Thread has the methods:

-
-
Thread
-
The constructor. A thread name and priority must be specified. The run - methods of runnable is executed. When the run methods returns the thread - will no longer be active but the client code must still delete the - thread.
-
~Thread
-
The destructor. This is called as the result of: - 
    delete pthread;
-
-
- -

timeFunction.h

- -

TimeFunction is a facility that measures the average number of seconds a -function call requires. When timeCall is called, it calls function in a loop. -It starts with a loop of one iteration. If the total elapsed time is less then -.1 seconds it increases the number of iterrations by a factor of 10. It keeps -repeating until the elapsed time is greater than .1 seconds. It returns the -average number of seconds per call.

-
class TimeFunctionRequester;
-class TimeFunction;
-typedef std::tr1::shared_ptr<TimeFunctionRequester> TimeFunctionRequesterPtr;
-typedef std::tr1::shared_ptr<TimeFunction> TimeFunctionPtr;
-        
-class TimeFunctionRequester {
-public:              
-    POINTER_DEFINITIONS(TimeFunctionRequester);
-    virtual ~TimeFunctionRequester(){}
-    virtual void function() = 0;
-};  
-
-    
-class TimeFunction {
-public:    
-    POINTER_DEFINITIONS(TimeFunction);
-    TimeFunction(TimeFunctionRequesterPtr const & requester);
-    ~TimeFunction(); 
-    double timeCall();
- ...
-};
- -

TimeFunctionRequester must be implemented by code that wants to time how -long a function takes. It has the single method:

-
-
function
-
This is the function.
-
- -

TimeFunction has the methods:

-
-
TimeFunction
-
Constructor.
-
~TimeFunction
-
Destructor.
-
timeCall
-
Time how long it takes to execute the function. It starts by calling - the function one time. If it takes < 1 seconds to doubles the number - of times to call the function. It repeats this until it takes at least - one second to call it ntimes.
-
- -

timer.h

- -

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(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 toString(StringBuilder builder);
- ...
-};
- -

TimerCallback must be implemented by the user. It has the following methods: -

-
-
callback
-
This is called when a timer expires. This is called with no locks held. - When called a delay timer is no longer on the queue but a periodioc timer - is on a queue. Thus the callback for a delay timer can issue a new - schedule request but a periodic timer must not. Note the explaination of - TimerNode.cancel below.
-
timerStopped
-
Timer.stop was called when a timer request was queued. or if the timer - is stopped and a schedule request is made.
-
- -

In order to schedule a callback client code must allocate a TimerNode It can -be used to schedule multiple callbacks. It has the methods:

-
-
TimerNode
-
The constructor. User code must create a TimeNode in order to call a - schedule method.
-
~TimerNode
-
The destructor. This is called as a result of the client calling: - 
    delete timerNode;
-
-
cancel
-
This is called to cancel a timer request. If a callback has been - dequeued but the callback not called when cancel is called then a - callback may still happen. New schedule requests can be made after a - cancel request has been made.
-
isScheduled
-
Is the timerNode scheduled to be called.
-
- -

Timer has the methods:

-
-
Timer
-
The consttructor.
-
~Timer
-
The destructor. The queue is emptied and TimerCallback.timerStopped is - called for each element of the queue.
-
scheduleAfterDelay
-
A request to schedule a callback after a delay specified in - seconds.
-
schedulePeriodic
-
Schedule a periodic callback.
-
- -

pvDataApp/pvMisc

- -

bitSetUtil.h

- -

The following is also provided:

-
class BitSetUtil : private NoDefaultMethods {
-public:
-    static bool compress(BitSet *bitSet,PVStructure *pvStructure);
-};
- -

This provides functions that operate on a BitSet for a PVStructure. It -currently has only one method:

-
-
compress
-
Compress the bits in a BitSet related to a structure.
- For each structure: -
    -
  1. If the bit for the structure is set then the bit for all subfields - of the structure are cleared.
    2. -
  2. If the bit for the structure is not set but all immediate subfields - have their bit set then the bit for the structure is set and the bits - for all subfields are cleared.
    3. -
- Note that this is a recursive algorithm. That is if every immediate - subfield has it's offset bit set then the bits for ALL fields that reside - in the structure will be cleared.
-
Channel Access can call this before sending data. It can then pass - entire structures if the structure offset bit is set.
-
-
- - diff --git a/documentation/pvDataCPP_20121212.html b/documentation/pvDataCPP_20121212.html deleted file mode 100644 index bba7caf..0000000 --- a/documentation/pvDataCPP_20121212.html +++ /dev/null @@ -1,3622 +0,0 @@ - - - - - - EPICS pvDataCPP - - - - - - - - -
-

EPICS pvDataCPP

- - -

EPICS v4 Working Group, Working Draft, 12-Dec-2012

- -
-
Latest version:
-
pvDataCPP.html -
-
This version:
-
pvDataCPP_20121212.html -
-
Previous version:
-
pvDataCPP_20121026.html -
-
Editors:
-
Marty Kraimer, BNL
-
- -

This product is made available subject to acceptance of the EPICS open source -license.

-
-
- -

Abstract

- -

pvDataCPP is a computer software package for the efficient -storage, access, and communication, of structured data. It is specifically the -C++ implementation of pvData, which is one part of the set of related products in the EPICS -V4 control system programming environment:
-relatedDocumentsV4.html -

- -

Status of this Document

- -

This is the 12-Dec-2012 version of the C++ implementation of pvData.

- -

The text describes software which is a complete implementation of pvData as -currently planned by the EPICS V4 Working Group.

- -

The following is a list of unresolved issues for pvDataCPP:

-
-
PVArray
-
The implementation of the different array types (PVBooleanArray, ..., - PVStructureArray) all store the data as a shared pointer holding a - vector. A test case should be created to make sure that vector.size() is - the same as getLength()
-
PVArray Examples
-
The following examples should be provided: 1) use all the get methods. - 2) create an example that makes data available in chunks.
-
pvType Example
-
Create an example of how to use the array typedefs
-
Convert test
-
How can this be better tested?
-
Structure and PVStructure
-
These two classes still keep data via std::vector. - Should they keep it as std::tr1::shared_ptr<std::vector<... ?
- In particular change -
-class Structure
-...
-StringArray fieldNames;
-FieldConstPtrArray fields
-
-class PVStructure
-...
-PVFieldPtrArray pvFields;
-
-To -
-class Structure
-...
-StringArrayPtr fieldNames;
-FieldConstPtrArrayPtr fields
-
-class PVStructure
-...
-PVFieldPtrArrayPtr pvFields;
-
-If these are changed several methods also change so that raw vectors are never passed as -argument or returned from methods.
-
- -
-

Table of Contents

-
-
- - -

Introduction

- -

pvData is one of a set of related projects. It describes and implements the -data that the other projects support. Thus it is not useful by itself but -understanding pvData is required in order to understand the other projects. The -reader should also become familar with projects pvAccess and pvIOC, which are -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:

-
-
Introduction
-
A brief descripton of pvData.
-
PVData Meta Language
-
A language used to describe data.
-
- -

The material in these two chapters is NOT repeated in this documentation.

- -

Doxygen documentation is available at doxygenDoc

- -

Namespace and Memory Management

- -

Namespace

- -

All code in project pvDataCPP appears in namespace:

-
namespace epics { namespace pvData {
-     // ...
-}}
- -

Memory Managemment

- -

pvDataCPP introspection and data objects are designed to be shared. They are -made availiable via std::tr1::shared_ptr. In addition arrays are -implemented via std::vector. The following naming conventions are used -in typedefs:

-
-
Ptr
-
When Ptr appears it stands for std::tr1::shared_ptr.
-
Array
-
When Array appears it stands for std::vector.
-
- -

As an example pvType.h includes the following definitions:

-
typedef std::vector<double> DoubleArray;
-typedef std::tr1::shared_ptr<DoubleArray> DoubleArrayPtr;
-inline double * get(DoubleArray &value)
-{
-    return &value[0];
-}
-inline const double * get(const DoubleArray &value)
-{
-    return static_cast<const double *>(&value[0]);
-}
-typedef std::vector<double>::iterator DoubleArray_iterator;
-typedef std::vector<double>::const_iterator DoubleArray_const_iterator;
- -

where

-
-
DoubleArray
-
This defines a vector for an array of the primitive type "double".
-
DoubleArrayPtr
-
This devices a shared pointer to a vector for an array of the primitive - type "double".
-
get
-
This gets the raw array of doubles that the DoubleArray holds.
-
DoubleArray_iterator
-
This gets a iterator for the DoubleArray.
-
DoubleArray_const_iterator
-
This gets a constant iterator for the DoubleArray.
-
- -

pvDataApp/pv

- -

Overview

- -

Directory pvDataApp/pv has header files that completely describe pvData. The -implementation is provided in directory pvDataApp/factory. Test programs -appears in testApp/pv.

- -

NOTES:

-
-
interface
-
The documention uses the word interface. This is an analogy for - what the Java implementation implements, i. e. package pv provides Java - interfaces. C++ does not have interfaces but directory pv defines classes - with public members that are similar to the Java interfaces. Most of the - implementation is in factory.
-
Naming Convertions
-
The naming convertions for variables, methods, and classes follow the - Java convertions, i. e. class name begin with an upper case letter, - variables and methods begin with a lower case letter.
-
- -

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. This section describes the complete set of C++ -introspection and data interfaces for pvData.

- -

Class FieldCreate creates introspection objects. Class PVDataCreate creates -data objects. Class Convert provides a rich set of methods for converting and -copying data between fields.

- -

Directory pvDataApp/pv has the following header files:

-
-
pvType.h
-
C++ definitions for primitive types.
-
pvIntrospect.h
-
A complete description of the introspection interfaces.
-
pvData.h
-
A complete description of the data interfaces.
-
convert.h
-
A facility that converts between data fields.
-
standardField.h
-
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.
-
- -

pvType.h

- -

This provides C/C++ definitions for the pvData primitive types: boolean, -byte, short, int, long, ubyte,ushort, uint,u long,float, double, and string. -Because pvData is network data, the C++ implementation must implement the -proper semantics for the primitive types.

- -

pvType.h provides the proper semantics.

- -

It has the definitions:

-
typedef uint8_t  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::string String;
-
-/**
- * A boolean array.
- */
-typedef std::vector<uint8> BooleanArray;
-typedef std::tr1::shared_ptr<BooleanArray> BooleanArrayPtr;
-/* get is same is ubyte*/
-typedef std::vector<uint8>::iterator BooleanArray_iterator;
-typedef std::vector<uint8>::const_iterator BooleanArray_const_iterator;
-
-/**
- * A byte array.
- */
-typedef std::vector<int8> ByteArray;
-typedef std::tr1::shared_ptr<ByteArray> ByteArrayPtr;
-inline int8 * get(ByteArray &value);
-inline int8 const * get(ByteArray const &value);
-inline int8 * get(ByteArrayPtr &value);
-inline int8 const * get(ByteArrayPtr const &value);
-inline ByteArray & getVector(ByteArrayPtr &value);
-inline ByteArray const & getVector(ByteArrayPtr const &value);
-typedef std::vector<int8>::iterator ByteArray_iterator;
-typedef std::vector<int8>::const_iterator ByteArray_const_iterator;
-
-/* similar definitions are present for ALL the primitive types */
- -

where

-
-
boolean
-
A c++ bool has the semantics required for boolean. Only the name is - different. C++ code can use either bool or boolean.
-
int8,...,uint64
-
Integers present a problem because short, int, and long are C++ - reserved words but do not have a well defined number of bits. Thus for - C++ the definitions above are used in C++ code. The above definitions - have worked on all C++ implementations tested at present. If they break - in a future implementation they should be changes via "#ifdef" - preprocessor statements.
-
String
-
pvData requires that a string be an immutable string that is transfered - over the network as a UTF8 encoded string. Since std::string implements - copy on write semantics, it can be used for support for immutable - strings. It can also be serialized/deserialized as a UTF8 encoded string. - Because it is not a C++ primitive the first letter is capitalized. This - is the same convention the Java implementation uses.
-
StringBuilder
-
This is defined here because to is used by the toString methods defined - for both introsection and data objects. The definition above acts like - the Java StringBuilder class.
-
Array definitions
-
typedefs are provided for an array of each of the primitive types. Note - that string is treated like a primitive type/
-
- -

pvIntrospect.h

- -

This subsection describes pvIntrospect.h This file is quite big so rather -than showing the entire file, it will be described in parts.

- -

A primary reason 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 pvname if a unique name in the local network.

- -

Given a pvname PV), 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 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.

- -

Type Description

- -

Types are defined as:

-
enum Type {
-    scalar,
-    scalarArray,
-    structure,
-    structureArray;
-};
-
-class TypeFunc {
-public:
-    const char* name(Type);
-    static void toString(StringBuilder buf,const 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(String const &value);
-    const char* name(ScalarType);
-    void toString(StringBuilder buf,ScalarType scalarType);
-};
- -

Type is one of the following:

-
-
scalar
-
A scalar of one of the scalar types.
-
scalarArray
-
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 types can be different.
-
structureArray
-
An array where each element is a structure. Each element has the same - structure introspection interface.
-
- -

ScalarType is one of the following:

-
-
pvBoolean
-
Has the value false or true.
-
pvByte
-
A signed 8 bit integer.
-
pvShort
-
A signed 16 bit integer.
-
pvInt
-
A signed 32 bit integer.
-
pvLong
-
A signed 64 bit integer.
-
pvUByte
-
An unsigned 8 bit integer.
-
pvUShort
-
An unsigned 16 bit integer.
-
pvUInt
-
An unsigned 32 bit integer.
-
pvULong
-
An unsigned 64 bit integer.
-
pvFloat
-
A IEEE float.
-
pvDouble
-
A IEEE double,
-
pvString
-
An immutable string.
-
- -

TypeFunction is a set of convenience methods for Type

-
-
name
-
Returns the name of the type.
-
toString
-
Convert the type to a string.
-
- -

ScalarTypeFunction is a set of convenience methods for ScalarType

-
-
isInteger
-
Is the scalarType an integer type, i.e. one of pvByte,...pvULong.
-
isUInteger
-
Is the scalarType an unsigned integer type, i.e. one of - pvUByte,...pvULong
-
isNumeric
-
Is the scalarType numeric, i.e. pvByte,...,pvDouble.
-
isPrimitive
-
Is the scalarType primitive, i.e. not pvString
-
name
-
Returns the name of the scalarType.
-
getScalarType
-
Given a string of the form String("boolean"),...,String("string") - return the scalarType.
-
toString
-
Convert the scalar type to a string.
-
- -

Introspection Description

- -

This section describes the reflection interfaces which provide the -following:

-
-
Field
-
A field: -
    -
  • Has a Type.
    • -
  • Can be converted to a string.
    • -
  • Can be shared. A reference count is kept. When it becomes 0 the - instance is automatically deleted.
    • -
-
-
Scalar
-
A scalar has a scalarType
-
ScalarArray
-
The element type is a scalarType
-
StructureArray
-
The field holds an array of structures. Each element has the same - 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
-
This is an interface that provides methods to create introspection - interfaces. A factory is provides to create FieldCreate.
-
getFieldCreate
-
Gets a pointer to the single instance of FieldCreate.
-
-
class Field;
-class Scalar;
-class ScalarArray;
-class Structure;
-class StructureArray;
-
-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;
-
-
-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 String getID() const = 0;
-    virtual void toString(StringBuilder buf) const{toString(buf,0);}
-    virtual void toString(StringBuilder buf,int indentLevel) const;
- ...
-};
-
-class Scalar : public Field{
-public:
-    POINTER_DEFINITIONS(Scalar);
-    virtual ~Scalar();
-    typedef Scalar& reference;
-    typedef const Scalar& const_reference;
-
-    ScalarType getScalarType() const {return scalarType;}
-    virtual void toString(StringBuilder buf) const{toString(buf,0);}
-    virtual void toString(StringBuilder buf,int indentLevel) const;
-    virtual String getID() const;
-    virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
-    virtual void deserialize(ByteBuffer *buffer, DeserializableContol *control);
- ...
-};
-
-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 void toString(StringBuilder buf) const{toString(buf,0);}
-    virtual void toString(StringBuilder buf,int indentLevel) const;
-    virtual String getID() const;
-    virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
-    virtual void deserialize(ByteBuffer *buffer, DeserializableControl *control);
- ...
-};
-
-class StructureArray : public Field{
-public:
-    POINTER_DEFINITIONS(StructureArray);
-    typedef StructureArray& reference;
-    typedef const StructureArray& const_reference;
-
-    StructureConstPtr  getStructure() const {return pstructure;}
-    virtual void toString(StringBuilder buf,int indentLevel=0) const;
-    virtual String getID() 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(String const & fieldName) const;
-   FieldConstPtr getField(std::size_t index) const;
-   std::size_t getFieldIndex(String const &fieldName) const;
-   FieldConstPtrArray const & getFields() const {return fields;}
-   StringArray const & getFieldNames() const;
-   void renameField(std::size_t fieldIndex,String const &newName);
-   String getFieldName(std::size_t fieldIndex);
-   virtual void toString(StringBuilder buf,int indentLevel) const;
-   virtual String getID() const;
-   virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
-   virtual void deserialize(ByteBuffer *buffer, DeserializableControl *control);
- ...
-};
-
-class FieldCreate  {
-public:
-    static FieldCreatePtr getFieldCreate();
-    ScalarConstPtr  createScalar(ScalarType scalarType) const
-    ScalarArrayConstPtr createScalarArray(ScalarType elementType) const;
-    StructureArrayConstPtr createStructureArray(StructureConstPtr const & structure) const;
-    StructureConstPtr createStructure (
-        StringArray const & fieldNames,
-        FieldConstPtrArray const & fields) const;
-    StructureConstPtr createStructure (
-        String const &id,
-        StringArray const & fieldNames,
-        FieldConstPtrArray const & fields) const;
-    StructureConstPtr appendField(
-        StructureConstPtr const & structure,
-        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;
- ...
-};
-
-extern FieldCreatePtr getFieldCreate();
-
-
Constructor
-
Note that all constructors are protected or private. The only way to - create instances is via FieldCreate. The implementation manages all - storage via shared pointers.
-
toString
-
Many classes provide this (actually two methods). This method is called - to get a string that uses the metadata syntax described in a previous - section.
-
- -
Field
-
-
getType
-
Get the field type.
-
getID
-
Get an ID for this introspection interface
-
- -
Scalar
-
-
getScalarType
-
Get that scalar type.
-
getID
-
For each scalarType there is one instance of Scalar. The ID for each is - the metadata name for the type, i. e. one of "boolean" , ... , "string". -
-
- -
ScalarArray
-
-
getElementType
-
Get the element type.
-
getID
-
For each elemnetType there is one instance of ScalarArray. The ID for - each is the metadata name for the type, i. e. one of "boolean[]" , ... , - "string[]".
-
- -
StructureArray
-
-
getStructure
-
Get the introspection interface that each element shares,
-
getID
-
This returns the ID[] where ID is the value returned by - structure->getID().
-
- -
Structure
-
-
getNumberFields
-
Get the number of immediate subfields.
-
getField
-
Given a name or an index get the introspection interface for the - field.
-
getFieldIndex
-
Given a name get the index, within the array returned by the next - method, of the field.
-
getFields
-
Get the array of introspection interfaces for the field,
-
getFieldNames
-
Get the array of field names for the subfields.
-
renameField
-
Rename the field.
-
getFieldName
-
Get the field name for the specified index.
-
- -
FieldCreate
-
-
getFieldCreate
-
Get the single instance of FieldCreate.
-
createScalar
-
Create a scalar introspection instance.
-
createScalarArray
-
Create a scalar array introspection instance.
-
createStructure
-
Create a structure introspection instance. Two methods are provided - where the only difference is that one provides an ID and the other does - not. The one without will result in ID "structure".
-
createStructureArray
-
Create a structure array introspection instance.
-
appendField
-
Append a field to a structure.
-
appendFields
-
Append fields to a structure.
-
deserialize
-
Deserialize from given byte buffer.
-
- -

standardField.h

- -

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,String const &properties);
-    StructureConstPtr scalarArray(
-        ScalarType elementType, String const &properties);
-    StructureConstPtr structureArray(
-        StructureConstPtr const & structure,String const &properties);
-    StructureConstPtr enumerated();
-    StructureConstPtr enumerated(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();
- ...
-};
-
-
scalar
-
Create a scalar with the specified scalar type and name. A structure - will be created with the first element being a scalar with the specified - scalar type and name value. The other fields in the structure will be the - corresponding property structures.
-
scalarArray
-
Create a scalarArray with each element having the specified scalar type - and name. A structure will be created with the first element being a - scalarArray with name value. The other fields in the structure will be - the corresponding property structures.
-
structureArray
-
Create a structureArray with the specified structure interface and - name. A structure will be created with the first element being a - structureArray with the specified structure interface and name value. The - other fields in the structure will be the corresponding property - structures.
-
structure
-
Create a structure with the specified name and fields specified by - numFields and fields. A structure will be created with the first element - being a structure with the name value and fields specified by numFields - and fields. The other fields in the structure will be the corresponding - property structures.
-
enumerated
-
Create a structure with the specified name and fields for an enumerated - structure. If properties are specified then a structure will be created - with the first element being a structure with the name value and fields - for an enumerated structure. The other fields in the structure will be - the corresponding property structures.
-
alarm
-
timeStamp
-
display
-
control
-
booleanAlarm
-
byteAlarm
-
shortAlarm
-
intAlarm
-
longAlarm
-
floatAlarm
-
doubleAlarm
-
enumeratedAlarm
-
The above provide introspection interfaces for standard properties. See - the section on Properties for a description of how these are defined.
-
- -

pvData.h

- -

This subsection describes pvData.h This file is quite big so rather than -showing the entire file, it will be described in parts.

- -

typedefs

- -

These are typedefs for Array and Ptr for the various pvData class -definitions, i.e. typdefs for "std::vector" and "std::tr1::shared_ptr".

-
class PVAuxInfo;
-class PostHandler;
-
-class PVField;
-class PVScalar;
-
-class PVScalarArray;
-
-class PVStructure;
-class PVStructureArray;
-
-typedef std::tr1::shared_ptr<PVAuxInfo> PVAuxInfoPtr;
-
-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 std::tr1::shared_ptr<PostHandler> PostHandlerPtr
- -

PostHandler is a class that must be implemented by any code that calls -setPostHandler. It's single virtual method. postPut is called whenever -PVField::postPut is called.

-
class PostHandler 
-{
-public:
-    POINTER_DEFINITIONS(PostHandler);
-    virtual ~PostHandler(){}
-    virtual void postPut() = 0;
-};
- -

PVField

- -

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 PVField
-: virtual public Serializable,
-  public std::tr1::enable_shared_from_this<PVField>
-{
-public:
-   POINTER_DEFINITIONS(PVField);
-   virtual ~PVField();
-   virtual void message(String message,MessageType messageType);
-   String getFieldName() const ;
-   virtual void setRequester(RequesterPtr const &prequester);
-   std::size_t getFieldOffset() const;
-   std::size_t getNextFieldOffset() const;
-   std::size_t getNumberFields() const;
-   PVAuxInfoPtr & getPVAuxInfo()
-   bool isImmutable() const;
-   virtual void setImmutable();
-   const FieldConstPtr & getField() const ;
-   PVStructure * getParent() const 
-   void replacePVField(const PVFieldPtr&  newPVField);
-   void renameField(String const &newName);
-   void postPut() ;
-   void setPostHandler(PostHandlerPtr const &postHandler);
-   virtual bool equals(PVField &pv);
-   virtual void toString(StringBuilder buf) ;
-   virtual void toString(StringBuilder buf,int indentLevel);
-   std::ostream& dumpValue(std::ostream& o) const;
- ...
-}
- -

The public methods for PVField are:

-
-
~PVField
-
Destructor. Since shared pointers are used it should never be called by - user code.
-
message
-
Code attached to this field can call this method to report - problems.
-
getFieldName
-
Get the field name. If the field is a top level structure the field - name will be an empty string.
-
setRequester
-
Sets a requester to be called when message or getRequesterName are - called. This is only legal for the top level PVField.
-
getFieldOffset
-
Get offset of the PVField field within top level structure. Every field - within the PVStructure has a unique offset. The top level structure has - an offset of 0. The first field within the structure has offset equal to - 1. The other offsets are determined by recursively traversing each - structure of the tree.
-
getNextFieldOffset
-
Get the next offset. If the field is a scalar or array field then this - is just offset + 1. If the field is a structure it is the offset of the - next field after this structure. Thus (nextOffset - offset) is always - equal to the total number of fields within the field.
-
getNumberFields
-
Get the total number of fields in this field. This is nextFieldOffset - - fieldOffset.
-
getPVAuxInfo
-
Get the PVAuxInfo for this field. PVAuxInfo is described below.
-
isImmutable
-
Is the field immutable?
-
setImmutable
-
Make the field immutable. Once a field is immutable it can never be - changed since there is no method to again make it mutable. This is an - important design decision since it allows immutable array fields to share - the internal primitive data array.
-
getField
-
Get the reflection interface for the data.
-
getParent
-
Get the interface for the parent or null if this is the top level - PVStructure.
-
replacePVField
-
Replace the data implementation for the field.
-
renameField
-
Rename the field name.
-
postPut
-
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.
-
equals
-
Compare this field with another field. The result will be true only if - the fields have exactly the same field types and if the data values are - equal.
-
toString
-
Converts the field data to a string. This is mostly for debugging - purposes.
-
dumpValue
-
Method for streams I/O.
-
- -

PVAuxInfo

- -

AuxInfo (Auxillary Information) is information about a field that is -application specific. It will not be available outside the application that -implements the database. In particular it will not be made available to Channel -Access. It is used by the database itself to override the default -implementation of fields. The JavaIOC uses it for attaching support code. -Database Configuration and other tools can use it for configuration -information. Each Field and each PVField can have have an arbitrary number of -auxInfos. An auxInfo is a (key,PVScalar) pair where key is a string.

-
class PVAuxInfo : private NoDefaultMethods {
-public:
-    typedef std::map<String,PVScalarPtr> PVInfoMap;
-    typedef std::map<String,PVScalarPtr>::iterator PVInfoIter;
-    typedef std::pair<String,PVScalarPtr> PVInfoPair;
-
-    PVAuxInfo(PVField *pvField);
-    ~PVAuxInfo();
-    PVField * getPVField();
-    PVScalarPtr createInfo(String const &key,ScalarType scalarType);
-    PVScalarPtr getInfo(String const &key);
-    PVInfoMap & getInfoMap();
-    void toString(StringBuilder buf);
-    void toString(StringBuilder buf,int indentLevel);
- ...
-};
- -

where

-
-
getPVField
-
Get the PVField to which this PVAuxInfo is attached.
-
createInfo
-
Create a new PVScalar of type scalarType.
-
getInfo
-
Get the PVScalar with the specified key.
-
getInfoMap
-
Get the map of all the PVScalars that hold the info.
-
toString
-
Print all the auxInfos
-
- -

PVScalar

- -

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 ;
- ...
-}
- -

where

-
-
getScalar
-
Get the introspection interface for the PVScalar.
-
- -

PVScalarValue

- -

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;
-    virtual ~PVScalarValue() {}
-    virtual T get() const = 0;
-    virtual void put(T value) = 0;
- ...
-}
-
-// PVString is special case, since it implements SerializableArray
-class PVString : public PVScalarValue<String>, SerializableArray {
-public:
-    virtual ~PVString() {}
- ...
-};
- -

where

-
-
get
-
Get the value stored in the object.
-
put
-
Change the value stored in the object.
-
- -

PVArray

- -

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 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;
- ...
-};
-
-
setImmutable
-
Set the data immutable. Note that this is permanent since there is no - methods to make it mutable.
-
getLength
-
Get the current length. This is less than or equal to the capacity.
-
setLength
-
Set the length. If the PVField is not mutable then an exception is - thrown. If this is greater than the capacity setCapacity is called.
-
getCapacity
-
Get the capacity, i.e. this is the size of the underlying data - array.
-
setCapacity
-
Set the capacity. The semantics are implementation dependent but - typical semantics are as follows: If the capacity is not mutable an - exception is thrown. A new data array is created and data is copied from - the old array to the new array.
-
isCapacityMutable
-
Is the capacity mutable
-
setCapacityMutable
-
Specify if the capacity can be changed.
-
setCapacity
-
Set the capaciity.
-
- -

PVArrayData

- -

This is the argument to one of the get methods of PVValueArray.

-
template<typename T>
-class PVArrayData {
-private:
-    std::vector<T> init;
-public:
-    POINTER_DEFINITIONS(PVArrayData);
-    typedef T  value_type;
-    typedef T* pointer;
-    typedef const T* const_pointer;
-    std::vector<T> & data;
-    std::size_t offset;
-    PVArrayData()
-    : data(init)
-    {}
-};
- -

PVScalarArray

- -

PVScalarArray is the base class for scalar array data. PVValueArray is a -templete for the various scalar array data classes. There is a class for each -possible scalar type, i. e. PVBooleanArray, ..., PVStringArray.

-
class PVScalarArray : public PVArray {
-public:
-    POINTER_DEFINITIONS(PVScalarArray);
-    virtual ~PVScalarArray();
-    typedef PVScalarArray &reference;
-    typedef const PVScalarArray& const_reference;
-    const ScalarArrayConstPtr getScalarArray() const ;
-    virtual std::ostream& dumpValue(std::ostream& o, size_t index) const = 0;
- ...
-}
- -

where

-
-
getScalarArray
-
Get the introspection interface.
-
dumpValue
-
Method for streams I/O.
-
- -

PVValueArray

- -

This is a template class plus instances for PVBooleanArray, ..., -PVStringArray.

-
template<typename T>
-class PVValueArray : public PVScalarArray {
-public:
-    POINTER_DEFINITIONS(PVValueArray);
-    typedef T  value_type;
-    typedef T* pointer;
-    typedef const T* const_pointer;
-    typedef PVArrayData<T> ArrayDataType;
-    typedef std::vector<T> vector;
-    typedef const std::vector<T> const_vector;
-    typedef std::tr1::shared_ptr<vector> shared_vector;
-    typedef PVValueArray & reference;
-    typedef const PVValueArray & const_reference;
-
-    virtual ~PVValueArray() {}
-    virtual std::size_t get(
-         std::size_t offset, std::size_t length, ArrayDataType &data) = 0;
-    virtual std::size_t put(std::size_t offset,
-        std::size_t length, const_pointer from, std::size_t fromOffset) = 0;
-    virtual std::size_t put(std::size_t offset,
-        std::size_t length, const_vector &from, std::size_t fromOffset);
-    virtual void shareData(
-         shared_vector const & value,
-         std::size_t capacity,
-         std::size_t length) = 0;
-    virtual pointer get() = 0;
-    virtual pointer get() const = 0;
-    virtual vector const & getVector() = 0;
-    virtual shared_vector const & getSharedVector() = 0;
-    std::ostream& dumpValue(std::ostream& o) const;
-    std::ostream& dumpValue(std::ostream& o, size_t index) const;
-protected:
-    PVValueArray(ScalarArrayConstPtr const & scalar)
-    : PVScalarArray(scalar) {}
-    friend class PVDataCreate;
-};
-
-template<typename T>
-std::size_t PVValueArray<T>::put(
-    std::size_t offset,
-    std::size_t length,
-    const_vector &from,
-    std::size_t fromOffset)
-{ return put(offset,length, &from[0], fromOffset); }
-
-/**
- * Definitions for the various scalarArray types.
- */
-typedef PVArrayData<uint8> BooleanArrayData;
-typedef PVValueArray<uint8> PVBooleanArray;
-typedef std::tr1::shared_ptr<PVBooleanArray> PVBooleanArrayPtr;
-
-typedef PVArrayData<int8> ByteArrayData;
-typedef PVValueArray<int8> PVByteArray;
-typedef std::tr1::shared_ptr<PVByteArray> PVByteArrayPtr;
-
-typedef PVArrayData<int16> ShortArrayData;
-typedef PVValueArray<int16> PVShortArray;
-typedef std::tr1::shared_ptr<PVShortArray> PVShortArrayPtr;
-
-typedef PVArrayData<int32> IntArrayData;
-typedef PVValueArray<int32> PVIntArray;
-typedef std::tr1::shared_ptr<PVIntArray> PVIntArrayPtr;
-
-typedef PVArrayData<int64> LongArrayData;
-typedef PVValueArray<int64> PVLongArray;
-typedef std::tr1::shared_ptr<PVLongArray> PVLongArrayPtr;
-
-typedef PVArrayData<uint8> UByteArrayData;
-typedef PVValueArray<uint8> PVUByteArray;
-typedef std::tr1::shared_ptr<PVUByteArray> PVUByteArrayPtr;
-
-typedef PVArrayData<uint16> UShortArrayData;
-typedef PVValueArray<uint16> PVUShortArray;
-typedef std::tr1::shared_ptr<PVUShortArray> PVUShortArrayPtr;
-
-typedef PVArrayData<uint32> UIntArrayData;
-typedef PVValueArray<uint32> PVUIntArray;
-typedef std::tr1::shared_ptr<PVUIntArray> PVUIntArrayPtr;
-
-typedef PVArrayData<uint64> ULongArrayData;
-typedef PVValueArray<uint64> PVULongArray;
-typedef std::tr1::shared_ptr<PVULongArray> PVULongArrayPtr;
-
-typedef PVArrayData<float> FloatArrayData;
-typedef PVValueArray<float> PVFloatArray;
-typedef std::tr1::shared_ptr<PVFloatArray> PVFloatArrayPtr;
-
-typedef PVArrayData<double> DoubleArrayData;
-typedef PVValueArray<double> PVDoubleArray;
-typedef std::tr1::shared_ptr<PVDoubleArray> PVDoubleArrayPtr;
-
-typedef PVArrayData<String> StringArrayData;
-typedef PVValueArray<String> PVStringArray;
-typedef std::tr1::shared_ptr<PVStringArray> PVStringArrayPtr;
- -

where

-
-
get( std::size_t offset, std::size_t length, ArrayDataType &data) -
-
This method "exposes" it's internal array by setting data.data and - data.offset. The caller is responsible for copying the array elements. - This violates the principle that objects should not expose their internal - data but is done for efficency. For example it makes it possible to copy - between arrays with identical element types without requiring an - intermediate array.
-
put(std::size_t offset, std::size_t length, const_pointer from, - std::size_t fromOffset)
-
Put data into the array. from is a raw array.
-
put(std::size_t offset, std::size_t length, const_vector &from, - std::size_t fromOffset)
-
Put data into the array from a vector holding the raw array.
-
shareData( shared_vector const & value, std::size_t capacity, - std::size_t length)
-
Make the instance share the raw data from value.
- One use is - for immutable arrays. In this case the caller must set the PVArray to be - immutable. In the PVArray is not immutable then it is the applications - responsibility to coordinate access to the array. Again this violates the - principle that objects should not expose their internal data 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 choices is immutable. Allowing the - choices internal String[] to be shared between all the instances of an - enumerated structure saves on storage.
- Another use for shared data is an application which processes an - array via multiple modules. Each accesses the internal data array of a - PVArray. In this case it is the applications responsibility - to coordinate access to the array.
-
get()
-
Get the raw array.
-
getVector()
-
Get the vector holding the raw array.
-
getSharedVector()
-
Get the shared vector holding the data.
-
dumpValue
-
Method for streams I/O.
-
- -

Both get and put return the number of elements actually transfered. The -arguments are:

-
-
offset
-
The offset in the PV array.
-
len
-
The maximum number of elements to transfer. The number actually - transfered will be less than or equal to this value.
-
data
-
Get sets data.data to it's internal array and data.offset to the offset - into the array. The caller is responsible for the actual data - transfer.
-
from
-
The array from which the data is taken. This array is supplied by the - caller
-
fromOffset
-
The offset in from
-
- -

The caller must be prepared to make multiple calls to retrieve or put an -entire array. A caller should accept or put partial arrays. For example the -following reads an entire array:

-
void getArray(PVDoubleArrayPtr & pv,DoubleArray const & to)
-{
-    size_t len = pv->getLength();
-    if(to.size()<len) to.resize(len);
-    DoubleArrayData data;
-    size_t offset = 0;
-    while(offset<len) {
-        size_t num = pv->get(offset,(len-offset),data);
-        DoubleArray &from = data.data;
-        size_t fromOffset = data.offset;
-        for(size_t i=0; i<num; i++) to[i+offset] = from[i + fromOffset];
-        offset += num;
-    }
-}
- -

- -

PVStructure

- -

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(String const &fieldName) const;
-    PVFieldPtr getSubField(std::size_t fieldOffset) const;
-    void appendPVField(
-        String const &fieldName,
-        PVFieldPtr const & pvField);
-    void appendPVFields(
-        StringArray const & fieldNames,
-        PVFieldPtrArray const & pvFields);
-    void removePVField(String const &fieldName);
-    PVBooleanPtr getBooleanField(String const &fieldName) ;
-    PVBytePtr getByteField(String const &fieldName) ;
-    PVShortPtr getShortField(String const &fieldName) ;
-    PVIntPtr getIntField(String const &fieldName) ;
-    PVLongPtr getLongField(String const &fieldName) ;
-    PVUBytePtr getUByteField(String const &fieldName) ;
-    PVUShortPtr getUShortField(String const &fieldName) ;
-    PVUIntPtr getUIntField(String const &fieldName) ;
-    PVULongPtr getULongField(String const &fieldName) ;
-    PVFloatPtr getFloatField(String const &fieldName) ;
-    PVDoublePtr getDoubleField(String const &fieldName) ;
-    PVStringPtr getStringField(String const &fieldName) ;
-    PVStructurePtr getStructureField(String const &fieldName) ;
-    PVScalarArrayPtr getScalarArrayField(
-        String const &fieldName,ScalarType elementType) ;
-    PVStructureArrayPtr getStructureArrayField(String const &fieldName) ;
-    String getExtendsStructureName() const;
-    bool putExtendsStructureName(
-        String const &extendsStructureName);
-    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);
-};
- -

where

-
-
getStructure
-
Get the introspection interface for the structure.
-
getPVFields
-
Returns the array of subfields. The set of subfields must all have - different field names.
-
getSubField(String fieldName)
-
Get a subField of a field. For a PVStructure a non-null result is - returned if fieldName is a field of the PVStructure. The fieldName can be - of the form name.name... - If the field does not exist the a Ptr to a NULL value is returned - without any error message being generated. -
-
getSubField(int fieldOffset)
-
Get the field located a fieldOffset, where fieldOffset is relative to - the top level structure. This returns null if the specified field is not - located within this PVStructure.
-
appendPVField
-
Append pvField to the end of this PVStructure. This should NOT be - called if any code is attached to any of the fields in the top level - structure.
-
appendPVFields
-
Append an array of pvFields to the end of this structure. Note that if - the original number of fields is 0 than pvFields replaces the original. - Thus the caller must NOT reuse pvFields after calling this method. This - should NOT be called if any code is attached to any of the fields in the - top level structure
-
removePVField
-
Remove the specified field from this structure. This should NOT be - called if any code is attached to any of the fields in the top level - structure.
-
getBooleanField
-
Look for fieldName. If found and it has the correct type return the - interface. This and the following methods are convenience methods that - allow a user to get the interface to a subfield without requiring - introspection. fieldName can be of the form name.name... - If the field does not exist or has the wrong type then - message will be called and a Ptr to NULL is returned. -
-
getByteField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getShortField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getIntField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getLongField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getUByteField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getUShortField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getUIntField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getULongField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getFloatField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getDoubleField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getStringField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getStructureField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getScalarArrayField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getStructureArrayField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getExtendsStructureName
-
Get the name of structure that this structure extends.
-
putExtendsStructureName
-
Specify the structure that this structure extends.
-
- -

PVStructureArray

- -

The interface for an array of structures is:

-
typedef PVArrayData<PVStructurePtr> StructureArrayData;
-
-class PVStructureArray : public PVArray
-{
-public:
-    POINTER_DEFINITIONS(PVStructureArray);
-    typedef PVStructurePtr  value_type;
-    typedef PVStructurePtr* pointer;
-    typedef const PVStructurePtr* const_pointer;
-    typedef PVArrayData<PVStructurePtr> ArrayDataType;
-    typedef std::vector<PVStructurePtr> vector;
-    typedef const std::vector<PVStructurePtr> const_vector;
-    typedef std::tr1::shared_ptr<vector> shared_vector;
-    typedef PVStructureArray &reference;
-    typedef const PVStructureArray& const_reference;
-
-    virtual ~PVStructureArray() {}
-    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 std::size_t get(std::size_t offset, std::size_t length,
-        StructureArrayData &data);
-    virtual std::size_t put(std::size_t offset,std::size_t length,
-        const_vector const & from, std::size_t fromOffset);
-    virtual void shareData(
-         shared_vector const & value,
-         std::size_t capacity,
-         std::size_t length);
-    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 pointer get() { return &((*value.get())[0]); }
-    virtual pointer get() const { return &((*value.get())[0]); }
-    virtual vector const & getVector() {return *value;}
-    virtual shared_vector const & getSharedVector() {return value;}
- ...
-}
- -

where

-
-
getStructureArray
-
Get the introspection interface shared by each element.
-
append
-
Create new elements and append them to the end of the array. It returns - the index of the first new element.
-
remove
-
Remove the specfied set of elements. It returns (false,true) if the - elements (were not, were) removed. It will not removed any elements - unless all requested elements exist or are null. Note that this deletes - the element and sets the array element to null. It does not change the - array capacity.
-
compress
-
This moves all null elements and then changes the array capacity. When - done there are no null elements.
-
- -

The other methods are similar to the methods for other array types.

- -

PVDataCreate

- -

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);
-    PVScalarArrayPtr createPVScalarArray(ScalarArrayConstPtr const & scalarArray);
-    PVScalarArrayPtr createPVScalarArray(ScalarType elementType);
-    PVScalarArrayPtr createPVScalarArray(PVScalarArrayPtr const  & scalarArrayToClone);
-    PVStructureArrayPtr createPVStructureArray(StructureArrayConstPtr const & structureArray);
-    PVStructurePtr createPVStructure(StructureConstPtr const & structure);
-    PVStructurePtr createPVStructure(
-        StringArray const & fieldNames,PVFieldPtrArray const & pvFields);
-   PVStructurePtr createPVStructure(PVStructurePtr const & structToClone);
- ...
-};
-
-extern PVDataCreatePtr getPVDataCreate();
- -

where

-
-
createPVField
-
The PVField is created reusing the Field interface. Two methods are - provided. Each calls the corresponding createPVScalar, createPVArray, or - createPVStructure depending in the type of the last argument.
-
createPVScalar
-
Creates an instance of a PVScalar. Three versions are supplied. The - first is passed an introspection interface. The second provides the field - name and the scalarType. The last provides a field name and a PVScalar to - clone. The newly created PVScalar will have the same auxInfos as the - original.
-
createPVScalarArray
-
Create an instance of a PVArray. Three versions are supplied. The first - is passed an introspection interface. The second provides the field name - and the elementType. The last provides a field name and a PVArray to - clone. The newly created PVArray will have the same auxInfos as the - original.
-
createPVStructureArray
-
Create a PVStructureArray. It must be passed a structureToClone. This - will become the Structure interface for ALL elements of the - PVStructureArray. It MUST be used to create any new array elements.
-
createPVStructure
-
Create an instance of a PVStructure. Three methods are provided. The - first method uses a previously created structure introspection interface. - The second uses a PVField array to initialize the sub-fields. - The third initializes the subfields by cloning the fields contained in - structToClone. The newly created sub-fields will have the same values and - auxInfos as the original. If structToClone is null then the new structure - is initialized to have 0 sub-fields.
-
- -

standardPVField.h

- -

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,String const &properties);
-    PVStructurePtr scalarArray(ScalarType elementType, String const &properties);
-    PVStructurePtr structureArray(StructureConstPtr const &structure,String const &properties);
-    PVStructurePtr enumerated(StringArray const &choices);
-    PVStructurePtr enumerated(StringArray const &choices, String const &properties);
- ...
-}
-
-
-extern StandardPVFieldPtr getStandardPVField();
- -

convert.h

- -

NOTE about copying immutable array fields. If an entire immutable array -field is copied to another array that has the same elementType, both offsets -are 0, and the length is the length of the source array, then the shareData -method of the target array is called and the target array is set immutable. -Thus the source and target share the same primitive array.

- -

This section describes the supported conversions between data types.

- -
bool operator==(PVField&, PVField&);
-
-static inline bool operator!=(PVField& a, PVField& b)
-{return !(a==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&);
-
-static inline bool operator!=(const Field& a, const Field& b)
-{return !(a==b);}
-static inline bool operator!=(const Scalar& a, const Scalar& b)
-{return !(a==b);}
-static inline bool operator!=(const ScalarArray& a, const ScalarArray& b)
-{return !(a==b);}
-static inline bool operator!=(const Structure& a, const Structure& b)
-{return !(a==b);}
-static inline bool operator!=(const StructureArray& a, const StructureArray& b)
-{return !(a==b);}
-class Convert;
-typedef std::tr1::shared_ptr<Convert> ConvertPtr;
-
-class Convert {
-public:
-    static ConvertPtr getConvert();
-    ~Convert();
-    void getFullName(StringBuilder buf,PVFieldPtr const & pvField);
-    bool equals(PVFieldPtr const &a,PVFieldPtr const &b);
-    bool equals(PVField &a,PVField &b);
-    void getString(StringBuilder buf,PVFieldPtr const & pvField,int indentLevel);
-    void getString(StringBuilder buf,PVFieldPtr const & pvField);
-    void getString(StringBuilder buf,PVField const * pvField,int indentLevel);
-    void getString(StringBuilder buf,PVField const * pvField);
-    std::size_t fromString(
-        PVStructurePtr const &pv,
-        StringArray const & from,
-        std::size_t fromStartIndex = 0);
-    void fromString(PVScalarPtr const & pv, String const & from);
-    std::size_t fromString(PVScalarArrayPtr const & pv, 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);
-    std::size_t copyScalarArray(
-        PVScalarArrayPtr const & from,
-        std::size_t offset,
-        PVScalarArrayPtr const & to,
-        std::size_t toOffset,
-        std::size_t length);
-    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);
-    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);
-    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);
-    std::size_t toByteArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        int8* to,
-        std::size_t toOffset);
-    std::size_t toShortArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        int16* to,
-        std::size_t toOffset);
-    std::size_t toIntArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        int32* to,
-        std::size_t toOffset);
-    std::size_t toLongArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        int64* to,
-        std::size_t toOffset);
-    std::size_t toUByteArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        uint8* to,
-        std::size_t toOffset);
-    std::size_t toUShortArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        uint16* to,
-        std::size_t toOffset);
-    std::size_t toUIntArray(
-        PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        uint32* to,
-        std::size_t toOffset);
-    std::size_t toULongArray(
-        PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        uint64* to,
-        std::size_t toOffset);
-    std::size_t toFloatArray(
-        PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        float* to,
-        std::size_t toOffset);
-    std::size_t toDoubleArray(
-        PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        double* to, std::size_t
-        toOffset);
-    std::size_t fromByteArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const int8* from, std::size_t fromOffset);
-    std::size_t fromByteArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const ByteArray & from, std::size_t fromOffset);
-    std::size_t fromShortArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const int16* from, std::size_t fromOffset);
-    std::size_t fromShortArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const ShortArray & from, std::size_t fromOffset);
-    std::size_t fromIntArray(
-       PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-       const int32* from, std::size_t fromOffset);
-    std::size_t fromIntArray(
-       PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-       const IntArray & from, std::size_t fromOffset);
-    std::size_t fromLongArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const int64* from, std::size_t fromOffset);
-    std::size_t fromLongArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const LongArray & from, std::size_t fromOffset);
-    std::size_t fromUByteArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const uint8* from, std::size_t fromOffset);
-    std::size_t fromUByteArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const UByteArray & from, std::size_t fromOffset);
-    std::size_t fromUShortArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const uint16* from, std::size_t fromOffset);
-    std::size_t fromUShortArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const UShortArray & from, std::size_t fromOffset);
-    std::size_t fromUIntArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const uint32* from, std::size_t fromOffset);
-    std::size_t fromUIntArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const UIntArray & from, std::size_t fromOffset);
-    std::size_t fromULongArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const uint64* from, std::size_t fromOffset);
-    std::size_t fromULongArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const ULongArray & from, std::size_t fromOffset);
-    std::size_t fromFloatArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const float* from, std::size_t fromOffset);
-    std::size_t fromFloatArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const FloatArray & from, std::size_t fromOffset);
-    std::size_t fromDoubleArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const double* from, std::size_t fromOffset);
-    std::size_t fromDoubleArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const DoubleArray & from, std::size_t fromOffset);
-    void newLine(StringBuilder buf, int indentLevel);
- ...
-}
-
-extern ConvertPtr getConvert();
- -

The array methods all return the number of elements copied or converted. -This can be less than len if the PVField array contains less than len -elements.

- -

newLine is a convenience method for code that implements toString It -generates a newline and inserts blanks at the beginning of the newline.

- -

pvDataApp/property

- -

Definition of Property

- -

Only fields named "value" have properties. A record can have multiple value -fields, which can appear in the top level structure of a record or in a -substructure. All other fields in the structure containing a value field are -considered properties of the value field. The fieldname is also the property -name. The value field can have any type, i.e. scalar, scalarArray, or -structure. Typical property fields are timeStamp, alarm, display, control, and -history. The timeStamp is a special case. If it appears anywhere in the -structure hieraracy above a value field it is a property of the value field.

- -

For example the following top level structure has a single value field. The -value field has properties alarm, timeStamp, and display.

-
structure counterOutput
-    double value
-    alarm_t
-        int severity 0
-        int status 0
-        string message
-    timeStamp_t
-        long secondsPastEpoch
-        int nanoSeconds
-        int userTag
-    display_t
-        double limitLow 0.0
-        double limitHigh 10.0
-        string description "Sample Description"
-        string format "%f"
-        string units volts
- -

The following example has three value fields each with properties alarm and -timeStamp. Voltage, Current, and Power each have a different alarms but all -share the timeStamp.

-
structure powerSupplyValue
-    double value
-    alarm_t
-        int severity 0
-        int status 0
-        string message
-
-structure powerSupplySimple
-    alarm_t
-        int severity 0
-        int status 0
-        string message
-    timeStamp_t
-        long secondsPastEpoch
-        int nanoSeconds
-        int userTag
-    powerSupplyValue_t voltage
-        double value
-        alarm_t
-            int severity 0
-            int status 0
-            string message
-    powerSupplyValue_t power
-        double value
-        alarm_t
-            int severity 0
-            int status 0
-            string message
-    powerSupplyValue_t current
-        double value
-        alarm_t
-            int severity 0
-            int status 0
-            string message
- -

Standard Properties

- -

The following field names have special meaning, i.e. support properties for -general purpose clients.

-
-
value
-
This is normally defined since most general purpose clients access this - field. All other fields in the structure support or describe the value - field. The type can any supported type but is usually one of the - following: -
-
scalar
-
Any of the scalar types.
-
scalarArray
-
An array with the elementType being a scalar type
-
enumerated structure
-
A structure that includes fields named index and choices. index - is an int that selects a choice. choices is an array of strings - that defines the complete set of choices.
-
other
-
Other structure or array types can also be defined if clients and - support code agree on the meaning. Some examples are: 1) A - structure defining a 2D matrix, 2) A structure defining an image, - 3) A structure that simulates a remote method, ...
-
-
-
timeStamp
-
The timeStamp. The type MUST be a timeStamp structure. Also if the - PVData structure does not have a timeStamp then a search up the parent - tree is made to find a timeStamp.
-
alarm
-
The alarm. The type MUST be an alarm structure.
-
display
-
A display structure as described below. It provides display - characteristics for the value field.
-
control
-
A control structure as described below. It provides control - characteristics for the value field.
-
history
-
Provides a history buffer for the value field. Note that currently - PVData does not define history suppoprt.
-
other
-
Other standard properties can be defined.
-
- -

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:

-
-
input
-
A field with support that changes the value field. This can be - anything. It can be a channel access link. It can obtain a value from - hardware. Etc.
-
valueAlarm
-
A field with support that looks for alarm conditions based on the - value.
-
output
-
A field with support that reads the current value and sends it - somewhere else. This can be anything. It can be a channel access link. It - can write a value to hardware. Etc.
-
- -

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. -

- -

Overview of Property Support

- -

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(String("testMessage"));
-    al.setSeverity(majorAlarm);
-    result = pvAlarm.set(al);
-    assert(result);
-    alarm = pvAlarm.get();
-     ...
-}
- -

timeStamp

- -

A timeStamp is represented by the following structure

-
structure timeStamp
-    long secondsPartEpoch
-    int nanoSeconds
-    int userTag
- -

The Epoch is the posix epoch, i.e. Jan 1, 1970 00:00:00 UTC. Both the -seconds and nanoSeconds are signed integers and thus can be negative. Since the -seconds is kept as a 64 bit integer, it allows for a time much greater than the -present age of the universe. Since the nanoSeconds portion is kept as a 32 bit -integer it is subject to overflow if a value that corresponds to a value that -is greater than a little more than 2 seconds of less that about -2 seconds. The -support code always adjust seconds so that the nanoSecconds part is normlized, -i. e. it has is 0<=nanoSeconds<nanoSecPerSec..

- -

Two header files are provided for manipulating time stamps:

-
-
timeStamp.h
-
Defines a time stamp independent of pvData, i.e. it is a generally - useful class for manipulating timeStamps.
-
pvTimeStamp.h
-
A class that can be attached to a time stamp pvData structure. It - provides get and set methods to get/set a TimeStamp as defined by - timeStamp.h
-
- -

timeStamp.h

- -

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

-
-
TimeStamp()
-
The defauly constuctor. Both seconds and nanoSeconds are set to 0.
-
TimeStamp(int64 secondsPastEpoch,int32 nanoSeconds = 0)
-
A constructor that gives initial values to seconds and nanoseconds.
-
normalize
-
Adjust seconds and nanoSeconds so that - 0<=nanoSeconds<nanoSecPerSec.
-
fromTime_t
-
Set time from standard C time.
-
toTime_t
-
Convert timeStamp to standard C time.
-
getSecondsPastEpoch
-
Get the number of seconds since the epoch.
-
getEpicsSecondsPastEpoch
-
Get the number of EPICS seconds since the epoch. EPICS uses Jan 1, 1990 - 00:00:00 UTC as the epoch.
-
getNanoSeconds
-
Get the number of nanoSeconds. This is always normalized.
-
getUserTag
-
Get the userTag.
-
setUserTag
-
Set the userTag.
-
put(int64 secondsPastEpoch,int32 nanoSeconds = 0)
-
Set the timeStamp value. If necessary it will be normalized.
-
put(int64 milliseconds)
-
Set the timeStamp with a value the is the number of milliSeconds since - the epoch.
-
getCurrent()
-
Set the timeStamp to the current time.
-
toSeconds()
-
Convert the timeStamp to a value that is the number of seconds since - the epocj
-
operator =
-
operator!=
-
operator<=
-
operator<
-
operator>=
-
operator>
-
Standard C++ operators.
-
diff
-
diff = a - b
-
getMilliseconds
-
Get the number of milliseconds since the epoch.
-
- -

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);
- -

pvTimeStamp.h

-
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

-
-
PVTimeStamp
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if a timeStamp - structure is found. It looks first at pvField itself and if is not an - appropriate pvData structure but the field name is value it looks up the - parent structure tree.
-
detach
-
Detach from the pvData structure.
-
isAttached
-
Is there an attachment to a timeStamp structure?
-
get
-
Copies data from the pvData structure to a TimeStamp. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from TimeStamp to the pvData structure. An exception is - thrown if not attached to a pvData structure.
-
- -

alarm

- -

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:

-
-
alarm.h
-
Defines an alarm independent of pvData, i.e. it is a generally useful - class for manipulating alarms.
-
pvAlarm.h
-
A class that can be attached to an alarm pvData structure. It provides - get and set methods to get/set alarm data as defined by alarm.h
-
- -

alarm.h

-
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
-    String getMessage();
-    void setMessage(String const &value);
-    AlarmSeverity getSeverity() const;
-    void setSeverity(AlarmSeverity value);
-    AlarmStatus getStatus() const;
-    void setStatus(AlarmStatus value);
-};
- -

Alarm Severity defines the possible alarm severities:

-
-
getSeverity
-
Get the alarm severity corresponding to the integer value.
-
getSeverityNames
-
Get the array of severity choices.
-
- -

Alarm Status defines the possible choices for alarm status:

-
-
getStatus
-
Get the alarm status corresponding to the integer value.
-
getStatusNames
-
Get the array of status choices.
-
- -

Alarm has the methods:

-
-
Alarm
-
The constructor. It sets the severity to no alarm and the message to - "".
-
getMessage
-
Get the message.
-
setMessage
-
Set the message.
-
getSeverity
-
Get the severity.
-
setSeverity
-
Set the severity.
-
getStatus
-
Get the status.
-
setStatus
-
Set the status.
-
- -

pvAlarm.h

-
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

-
-
PVAlarm
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if it found an - appropriate pvData structure. It looks first a pvField itself and if is - not an appropriate pvData structure but the field name is value it looks - to see if the parent structure has an appropriate sub structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to an alarm structure?
-
get
-
Copies data from the pvData structure to an Alarm. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from Alarm to the pvData structure. An exception is thrown - if not attached to a pvData structure.
-
- -

control

- -

Control information is represented by the following structure

-
structure control
-    double limitLow
-    double limitHigh
-    double minStep
- -

Two header files are provided for manipulating control:

-
-
control.h
-
Defines control independent of pvData, i.e. it is a generally useful - class for manipulating control.
-
pvControl.h
-
A class that can be attached to an control pvData structure. It - provides get and set methods to get/set control data as defined by - control.h
-
- -

control.h

-
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

-
-
Control
-
The default constructure.
-
getLow
-
Get the low limit.
-
getHigh
-
Get the high limit.
-
setLow
-
Set the low limit.
-
setHigh
-
Set the high limit.
-
setMinStep
-
Set the minimum step size.
-
getMinStep
-
Get he minimum step size.
-
- -

pvControl.h

-
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

-
-
PVControl
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if it found an - appropriate pvData structure. It looks first a pvField itself and if is - not an appropriate pvData structure but the field name is value it looks - to see if the parent structure has an appropriate sub structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to a control structure?
-
get
-
Copies data from the pvData structure to a Control. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from Control to the pvData structure. An exception is - thrown if not attached to a pvData structure.
-
- -

display

- -

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:

-
-
display.h
-
Defines display independent of pvData, i.e. it is a generally useful - class for manipulating display.
-
pvDisplay.h
-
A class that can be attached to an display pvData structure. It - provides get and set methods to get/set display data as defined by - display.h
-
- -

display.h

-
class Display {
-public:
-    Display();
-    //default constructors and destructor are OK
-    double getLow() const;
-    double getHigh() const;
-    void setLow(double value);
-    void setHigh(double value);
-    String getDescription() const;
-    void setDescription(String const &value);
-    String getFormat() const;
-    void setFormat(String const &value);
-    String getUnits() const;
-    void setUnits(String const &value);
-};
- -

where

-
-
Control
-
The default constructure.
-
getLow
-
Get the low limit.
-
getHigh
-
Get the high limit.
-
setLow
-
Set the low limit.
-
setHigh
-
Set the high limit.
-
getDescription
-
Get the description.
-
setDescription
-
Set the description.
-
getFormat
-
Get the format.
-
setFormat
-
Set the format.
-
getUnits
-
Get the units.
-
setUnits
-
Set the units.
-
- -

pvDisplay.h

-
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

-
-
PVDisplay
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if it found an - appropriate pvData structure. It looks first a pvField itself and if is - not an appropriate pvData structure but the field name is value it looks - to see if the parent structure has an appropriate sub structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to a display structure?
-
get
-
Copies data from the pvData structure to a Display. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from Display to the pvData structure. An exception is - thrown if not attached to a pvData structure.
-
- -

pvEnumerated.h

- -

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();
-    String getChoice();
-    bool choicesMutable();
-    StringArrayPtr const & getChoices();
-    int32 getNumberChoices();
-    bool setChoices(StringArray &choices,int32 numberChoices);
-};
- -

where

-
-
PVEnumerated
-
The default constructor. Attach must be called before any get or set - method can be called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if pvField (is - not, is) an enumerated structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to an enemerated structure?
-
setIndex
-
Set the index field in the pvData structure. An exception is thrown if - not attached to a pvData structure.
-
getIndex
-
Get the index field in the pvData structure.
-
getChoice
-
Get the String value corresponding to the current index field in the - pvData structure. An exception is thrown if not attached to a pvData - structure.
-
choicesMutable
-
Can the choices be changed? Note that this is often true. An exception - is thrown if not attached to a pvData structure.
-
getChoices
-
Get the array of choices. An exception is thrown if not attached to a - pvData structure.
-
getNumberChoices
-
Get the number of choices. An exception is thrown if not attached to a - pvData structure.
-
setChoices
-
Change the choices. An exception is thrown if not attached to a pvData - structure.
-
- -

Examples

- -

Accessing PVData

- -

Assume that code wants to print two fields from a PVStructure:

-
-
value
-
Must be a PVDouble.
-
timeStamp
-
Just look for field with this name.
-
- -

The following code uses introspection to get the desired information.

-
void getValueAndTimeStamp(PVStructurePtr pvStructure,StringBuilder buf) {
-   PVFieldPtr valuePV = pvStructure->getSubField(String("value"));
-   if(valuePV.get()==NULL) {
-       buf += "value field not found";
-       return;
-   }
-   buf += "value ";
-   valuePV->toString(&buf);
-   PVFieldPtr timeStampPV = pvStructure->getSubField(String("timeStamp"));
-   if(timeStampPV.get()==NULL) {
-       buf += "timeStamp field not found";
-       return;
-   }
-   buf += " timeStamp ";
-   timeStampPV->toString(&buf);
-}
- -

Creating PVData

- -

Example of creating a scalar field.

-
    PVDataCreatePtr pvDataCreate = getPVDataCreate();
-    PVDoublePtr pvValue = static_pointer_cast<PVDouble>(
-        pvDataCreate->createPVScalar(pvDouble));
- -

Create a structure with a value and an alarm the hard way

-
    FieldCreatePtr fieldCreate = getFieldCreate();
-    PVDataCreatePtr pvDataCreate = getPVDataCreate();
-    FieldConstPtrArray fields;
-    StringArray names;
-    fields.resize(3);
-    names.resize(3);
-    fields[0] = fieldCreate->createScalar(pvInt);
-    fields[1] = fieldCreate->createScalar(pvInt);
-    fields[2] = fieldCreate->createScalar(pvString);
-    names[0] = "severity";
-    names[0] = "status";
-    names[0] = "message";
-    StructureConstPtr alarmField =  
-        fieldCreate->createStructure(names,fields);
-    fields.resize(2);
-    names.resize(2);
-    fields[0] = fieldCreate->createScalar(pvDouble);
-    fields[1] = alarmField;
-    names[0] = "value";
-    names[0] = "alarm";
-    StructureConstPtr structure =
-        fieldCreate->createStructure(names,fields);
-    PVStructurePtr pv = pvDataCreate->createPVStructure(structure);
- -

Create an alarm structure the easy way.

-
    StandardPVFieldPtr standardPVField = getStandardPVField();
-    PVStructurePtr pv = standardPVField->scalar(pvDouble,"alarm");
- -

Create a PVStructure with field name example that has a double value field , -timeStamp, alarm, and display. Do it the easy way.

-
    StandardPVFieldPtr standardPVField = getStandardPVField();
-    PVStructurePtr pvStructure = standardPVField->scalar(
-        pvDouble,"timeStamp,alarm.display");
- -

pvDataApp/factory

- -

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.

- -

PVAuxInfoImpl.cpp implements auxInfo.

- -

Convert.cpp automatically creates a single instance of Convert and -implements getConvert.

- -

Other files implement PVData base classes

- -

pvDataAPP/misc

- -

Overview

- -

This package provides utility code:

-
-
bitSet.h
-
An implementation of BitSet that can be serialized.
-
byteBuffer.h
-
Used to serialize objects.
-
destroyable.h
-
Provides method destroy.
-
epicsException.h
-
Exception with stack trace.
-
event.h
-
Signal and wait for an event.
-
executor.h
-
Provides a thread for executing commands.
-
lock.h
-
Support for locking and unlocking.
-
messageQueue.h
-
Support for queuing messages to give to requesters.
-
noDefaultMethods.h
-
When privately extended prevents compiler from implementing default - methods.
-
queue.h
-
A queue implementation that allows the latest queue element to continue - to be used when no free element is available.
-
requester.h
-
Allows messages to be sent to a requester.
-
serialize.h
-
Support for serializing objects.
-
serializeHelper.h
-
More support for serializing objects.
-
sharedPtr.h
-
Defines POINTER_DEFINITIONS.
-
status.h
-
A way to pass status information to a client.
-
thread.h
-
Provides thread support.
-
timeFunction.h
-
Time how long a function call requires.
-
timer.h
-
An implementation of Timer that does not require an object to be - created for each timer request.
-
- -

Note that directory testApp/misc has test code for all the classes in misc. -The test code also can be used as examples.

- -

bitSet.h

- -

This is adapted from the java.util.BitSet. bitSet.h is:

-
class BitSet : public Serializable {
-public:
-    static BitSet::shared_pointer create(uint32 nbits);
-    BitSet();
-    BitSet(uint32 nbits);
-    virtual ~BitSet();
-    void flip(uint32 bitIndex);
-    void set(uint32 bitIndex);
-    void clear(uint32 bitIndex);
-    void set(uint32 bitIndex, bool value);
-    bool get(uint32 bitIndex) const;
-    void clear();
-    int32 nextSetBit(uint32 fromIndex) const;
-    int32 nextClearBit(uint32 fromIndex) const;
-    bool isEmpty() const;
-    uint32 cardinality() const;
-    uint32 size() const;
-    BitSet& operator&=(const BitSet& set);
-    BitSet& operator|=(const BitSet& set);
-    BitSet& operator^=(const BitSet& set);
-    BitSet& operator-=(const BitSet& set);
-    BitSet& operator=(const BitSet &set);
-    void or_and(const BitSet& set1, const BitSet& set2);
-    bool operator==(const BitSet &set) const;
-    bool operator!=(const BitSet &set) const;
-    void toString(StringBuilder buffer);
-    void toString(StringBuilder buffer, int indentLevel) const;
-private:
-};
- -

where

-
-
BitSet()
-
Creates a bitSet of initial size 64 bits. All bits initially false.
-
BitSet(uint32 nbits)
-
Creates a bitSet with the initial of the specified number of bits. All - bits initially false.
-
~BitSet()
-
Destructor.
-
flip(uint32 bitIndex)
-
Flip the specified bit.
-
set(uint32 bitIndex)
-
Set the specified bit true.
-
clear(uint32 bitIndex)
-
Set the specified bit false.
-
set(uint32 bitIndex, bool value)
-
Set the specified bit to value.
-
get(uint32 bitIndex)
-
Return the state of the specified bit.
-
clear()
-
Set all bits to false.
-
nextSetBit(uint32 fromIndex)
-
Get the index of the next true bit beginning with the specified - bit.
-
nextClearBit(uint32 fromIndex)
-
Get the index of the next false bit beginning with the specified - bit.
-
isEmpty()
-
Return (false,true) if (at least one bit true, all bits are false)
-
cardinality()
-
Return the number of true bits.
-
size()
-
Returns the number of bits of space actually in use.
-
operator&=(const BitSet& set)
-
Performs a logical and of this target bit set with the argument bit - set. This bit set is modified so that each bit in it has the value true - if and only if it both initially had the value true and the corresponding - bit in the bit set argument also had the value.
-
operator|=(const BitSet& set)
-
Performs a logical or of this target bit set with the argument bit - set.
-
operator^=(const BitSet& set)
-
Performs a logical exclusive or of this target bit set with the - argument bit set.
-
operator-=(const BitSet& set)
-

Clears all of the bits in this bitSet whose corresponding bit is set - in the specified bitSet.

-
-
operator=(const BitSet &set)
-
Assignment operator.
-
or_and(const BitSet& set1, const BitSet& set2)
-
Perform AND operation on set1 and set2, and then OR this bitSet with - the result.
-
operator==(const BitSet &set)
-
Does this bitSet have the same values as the argument.
-
operator!=(const BitSet &set)
-
Is this bitSet different than the argument.
-
toString(StringBuilder buffer)
-
Show the current values of the bitSet.
-
toString(StringBuilder buffer, int indentLevel)
-
Show the current values of the bitSet.
-
virtual void serialize(ByteBuffer *buffer,SerializableControl *flusher) - const;
-
Serialize the bitSet
-
virtual void deserialize(ByteBuffer *buffer,DeserializableControl - *flusher);
-
Deserialize the bitSet.
-
- -

byteBuffer.h

- -

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();
- ...
-};
- -

destroyable.h

-
class Destroyable  {
-public:
-    POINTER_DEFINITIONS(Destroyable);
-    virtual void destroy() = 0;
-    virtual ~Destroyable() {};
-};
- -

epicsException.h

-
/*
- * 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.
- */
- -

event.h

- -

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 */
-private:
-    epicsEventId id;
-};
- -

where

-
-
Event
-
The constructor. The initial value can be full or empty. The normal - first state is empty.
-
signal
-
The event becomes full. The current or next wait will complete.
-
wait
-
Wait until event is full or until timeout. The return value is - (false,true) if the wait completed because event (was not, was) full. A - false value normally means that that a timeout occured. It is also - returned if an error occurs or because the event is being deleted.
-
tryWait
-
returns (false,true) if the event is (empty,full)
-
- -

executor.h

- -

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(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:

-
-
Executor
-
The constructor. A thread name and priority must be specified.
-
~Executor
-
The destructor. If any commands remain in the execute list they are not - called. All ExecutorNodes that have been created are deleted.
-
execute
-
Request that command be executed. If it is already on the run list - nothing is done.
-
- -

lock.h

-
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 xx(mutex);
-        if(alreadyInitialized) return;
-        // initialization
-    }
- -

messageQueue.h

- -

Definitions

- -

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:
-    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(String message,MessageType messageType,bool replaceLast);
-    bool isEmpty() ;
-    bool isFull() ;
-    int getClearOverrun();
- ...
-};
- -

A messageNode is a class with two public data members:

-
-
getMessage
-
The message.
-
getMessageType
-
The message type.
-
setMessageNull
-
Set the message to be a null string.
-
- -

A messageQueue is an interface with public methods:

-
-
MessageQueue
-
The constructor. The queue size must be specified.
-
~MessageQueue
-
The destructor.
-
put
-
Put a new message into the queue. False is returned if the queue was - full and true otherwise. If replaceLast is true then the last message is - replaced with this message.
-
get
-
Get the oldest queue element. If the queue is empty null is returned. - Before the next get can be issued release must be called.
-
release
-
Release the queue element returned by the last get.
-
isEmpty
-
Is the queue empty?
-
isFull
-
Is the queue full?
-
getClearOverrun
-
Get the number of times put has been called but no free element is - available.
-
- -

Look at miscTest/testMessageQueue.cpp for an example.

- -

noDefaultMethods.h

- -

If a class privately extends this class then the compiler can not create any -of the following: default constructor, default copy constructror, or default -assignment contructor.

-
/* This is based on Item 6 of
- * Effective C++, Third Edition, Scott Meyers
- */
-    class NoDefaultMethods {
-    protected:
-    // allow by derived objects
-    NoDefaultMethods(){};
-    ~NoDefaultMethods(){}
-    private:
-    // do not implment
-    NoDefaultMethods(const NoDefaultMethods&);
-    NoDefaultMethods & operator=(const NoDefaultMethods &);
-    };
- -

queue.h

- -

This provides a queue which has an immutable capacity. When the queue is -full the user code is expected to keep using the current element until a new -free element becomes avalable.

-
template <typename T>
-class Queue
-{   
-public:
-    POINTER_DEFINITIONS(Queue);
-    typedef std::tr1::shared_ptr<T> queueElementPtr;
-    typedef std::vector<queueElementPtr> queueElementPtrArray;
-    Queue(queueElementPtrArray &);
-    virtual ~Queue();
-    void clear();
-    int capacity();
-    int getNumberFree();
-    int getNumberUsed();
-    queueElementPtr & getFree();
-    void setUsed(queueElementPtr &element);
-    queueElementPtr & getUsed();
-    void releaseUsed(queueElementPtr &element);
- ...
-};
- -

testApp/misc/testQueue.cpp provides an example of how to define a queue.

- -

The queue methods are:

-
-
clear
-
Make the queue empty.
-
getNumberFree
-
Get the number of free elements in the queue.
-
capacity
-
Get the capacity, i.e. the maximun number of elements the queue can - hold.
-
getNumberFree
-
Get the number of free elements.
-
getNumberUsed
-
Get the number of elements used.
-
getFree
-
Get the next free element. Null is returned if no free elements are - available. If a non null value is returned then the element belongs to - the caller until setUsed is called.
-
setUsed
-
Set a queue element used. This must be the element returned by the last - call to getFree.
-
getUsed
-
Get the next used element of null if no more used elements are - available.
-
releaseUsed
-
Set a queue element free. This must be the element returned by the last - call to getUsed.
-
- -

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.h

- -

A PVField extends Requester. Requester is present so that when database -errors are found there is someplace to send a message.

-
enum MessageType {
-   infoMessage,warningMessage,errorMessage,fatalErrorMessage
-};
-
-extern String getMessageTypeName(MessageType messageType);
-extern const size_t messageTypeCount;
-class Requester {
-public:
-    POINTER_DEFINITIONS(Requester);
-    virtual ~Requester(){}
-    virtual String getRequesterName() = 0;
-    virtual void message(String const & message,MessageType messageType) = 0;
-};
- -

where

-
-
-
MessageType
-
Type of message.
-
messageTypeName
-
An array of strings of the message type names, i.e. - String("info"),String("warning"),String("error"),String("fatalError").
-
getRequesterName
-
Returns the requester name.
-
message
-
Gives a message to the requester.
-
- -

serialize.h

-
    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;
-    };
- -

serializeHelper.h

- -

This is a helper class for serialization, which is required for sending and -receiving pvData over the nerwork.

-
class SerializeHelper : public NoDefaultMethods {
-public:
-    static void writeSize(int s, ByteBuffer* buffer,
-        SerializableControl* flusher);
-    static int readSize(ByteBuffer* buffer,
-        DeserializableControl* control);
-    static void serializeString(const String& value,
-        ByteBuffer* buffer,SerializableControl* flusher);
-    static void serializeSubstring(const String& value, int offset,
-        int count, ByteBuffer* buffer,
-        SerializableControl* flusher);
-    static String deserializeString(ByteBuffer* buffer,
-        DeserializableControl* control);
- ...
-};
- -

where

-
-
writeSize
-
Serialize the size.
-
readSize
-
Deserialize the size.
-
serializeString
-
Serialize a String.
-
serializeSubstring
-
Serialize a substring.
-
deserializeString
-
Deserialize a string.
-
- -

sharedPtr.h

-
#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;
- -

status.h

- -

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, epics::pvData::String const & message);
-    Status(StatusType type, epics::pvData::String const & message, epics::pvData::String stackDump);
-    ~Status()
-    StatusType getType() const;
-    String getMessage() const;
-    String getStackDump() const;
-    bool isOK() const;
-    bool isSuccess() const;
-    String toString() const;
-    void toString(StringBuilder buffer, int indentLevel = 0) const;
-    void serialize(ByteBuffer *buffer, SerializableControl *flusher) const;
-    void serialize(ByteBuffer *buffer, SerializableControl *flusher) const;
-};
- -

The Status methods are:

-
-
StatusType
-
An enum for the status type.
-
getType
-
Get the statusType.
-
getMessage
-
Get a message explaining the error.
-
getStackDump
-
Get a stack dump.
-
- -

The StatusCreate methods are:

-
-
getStatusOK
-
Get a singleton that returns StatusType.OK and a null message and - stackDump.
-
createStatus
-
Create a new Status.
-
deserializeStatus
-
Use this method instead of Status.deserialize(), since this allows OK - status optimization.
-
- -

thread.h

- -

ThreadPriority

-
enum ThreadPriority {
-    lowestPriority,
-    lowerPriority,
-    lowPriority,
-    middlePriority,
-    highPriority,
-    higherPriority,
-    highestPriority
-};
- -

Thread

-
class Runnable {
-public:
-    virtual void run() = 0;
-};
-
-class Thread;
-
-class Thread : public epicsThread, private NoDefaultMethods {
-public:
-    Thread(
-        String name,
-        ThreadPriority priority,
-        Runnable *runnableReady,
-        epicsThreadStackSizeClass stkcls=epicsThreadStackSmall);
-    ~Thread();
- ...
-};
- -

Runnable must be implement by code that wants to be run via a thread. It has -one virtual method: run. Run is the code that is run as a thread. When run -compeletes it can not be restarted. If code wants to delete a thread then it -MUST arrange that the run returns before the thread can be deleted. An -exception is thrown if run remains active when delete is called.

- -

Thread has the methods:

-
-
Thread
-
The constructor. A thread name and priority must be specified. The run - methods of runnable is executed. When the run methods returns the thread - will no longer be active but the client code must still delete the - thread.
-
~Thread
-
The destructor. This is called as the result of: - 
    delete pthread;
-
-
- -

timeFunction.h

- -

TimeFunction is a facility that measures the average number of seconds a -function call requires. When timeCall is called, it calls function in a loop. -It starts with a loop of one iteration. If the total elapsed time is less then -.1 seconds it increases the number of iterrations by a factor of 10. It keeps -repeating until the elapsed time is greater than .1 seconds. It returns the -average number of seconds per call.

-
class TimeFunctionRequester;
-class TimeFunction;
-typedef std::tr1::shared_ptr<TimeFunctionRequester> TimeFunctionRequesterPtr;
-typedef std::tr1::shared_ptr<TimeFunction> TimeFunctionPtr;
-        
-class TimeFunctionRequester {
-public:              
-    POINTER_DEFINITIONS(TimeFunctionRequester);
-    virtual ~TimeFunctionRequester(){}
-    virtual void function() = 0;
-};  
-
-    
-class TimeFunction {
-public:    
-    POINTER_DEFINITIONS(TimeFunction);
-    TimeFunction(TimeFunctionRequesterPtr const & requester);
-    ~TimeFunction(); 
-    double timeCall();
- ...
-};
- -

TimeFunctionRequester must be implemented by code that wants to time how -long a function takes. It has the single method:

-
-
function
-
This is the function.
-
- -

TimeFunction has the methods:

-
-
TimeFunction
-
Constructor.
-
~TimeFunction
-
Destructor.
-
timeCall
-
Time how long it takes to execute the function. It starts by calling - the function one time. If it takes < 1 seconds to doubles the number - of times to call the function. It repeats this until it takes at least - one second to call it ntimes.
-
- -

timer.h

- -

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(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 toString(StringBuilder builder);
- ...
-};
- -

TimerCallback must be implemented by the user. It has the following methods: -

-
-
callback
-
This is called when a timer expires. This is called with no locks held. - When called a delay timer is no longer on the queue but a periodioc timer - is on a queue. Thus the callback for a delay timer can issue a new - schedule request but a periodic timer must not. Note the explaination of - TimerNode.cancel below.
-
timerStopped
-
Timer.stop was called when a timer request was queued. or if the timer - is stopped and a schedule request is made.
-
- -

In order to schedule a callback client code must allocate a TimerNode It can -be used to schedule multiple callbacks. It has the methods:

-
-
TimerNode
-
The constructor. User code must create a TimeNode in order to call a - schedule method.
-
~TimerNode
-
The destructor. This is called as a result of the client calling: - 
    delete timerNode;
-
-
cancel
-
This is called to cancel a timer request. If a callback has been - dequeued but the callback not called when cancel is called then a - callback may still happen. New schedule requests can be made after a - cancel request has been made.
-
isScheduled
-
Is the timerNode scheduled to be called.
-
- -

Timer has the methods:

-
-
Timer
-
The consttructor.
-
~Timer
-
The destructor. The queue is emptied and TimerCallback.timerStopped is - called for each element of the queue.
-
scheduleAfterDelay
-
A request to schedule a callback after a delay specified in - seconds.
-
schedulePeriodic
-
Schedule a periodic callback.
-
- -

pvDataApp/pvMisc

- -

bitSetUtil.h

- -

The following is also provided:

-
class BitSetUtil : private NoDefaultMethods {
-public:
-    static bool compress(BitSet *bitSet,PVStructure *pvStructure);
-};
- -

This provides functions that operate on a BitSet for a PVStructure. It -currently has only one method:

-
-
compress
-
Compress the bits in a BitSet related to a structure.
- For each structure: -
    -
  1. If the bit for the structure is set then the bit for all subfields - of the structure are cleared.
    2. -
  2. If the bit for the structure is not set but all immediate subfields - have their bit set then the bit for the structure is set and the bits - for all subfields are cleared.
    3. -
- Note that this is a recursive algorithm. That is if every immediate - subfield has it's offset bit set then the bits for ALL fields that reside - in the structure will be cleared.
-
Channel Access can call this before sending data. It can then pass - entire structures if the structure offset bit is set.
-
-
- - diff --git a/documentation/pvDataCPP_20130516.html b/documentation/pvDataCPP_20130516.html deleted file mode 100644 index 312e958..0000000 --- a/documentation/pvDataCPP_20130516.html +++ /dev/null @@ -1,3625 +0,0 @@ - - - - - - EPICS pvDataCPP - - - - - - - - -
-

EPICS pvDataCPP

- - -

EPICS v4 Working Group, Working Draft, 16-May-2013

- -
-
Latest version:
-
pvDataCPP.html -
-
This version:
-
pvDataCPP_20130516.html -
-
Previous version:
-
pvDataCPP_20121212.html -
-
Editors:
-
Marty Kraimer, BNL
-
- -

This product is made available subject to acceptance of the EPICS open source -license.

-
-
- -

Abstract

- -

pvDataCPP is a computer software package for the efficient -storage, access, and communication, of structured data. It is specifically the -C++ implementation of pvData, which is one part of the set of related products in the EPICS -V4 control system programming environment:
-relatedDocumentsV4.html -

- - -

Status of this Document

- -

This is the 16-May-2013 version of the C++ implementation of pvData. -Since the last version changes were made to queue and to bitSetUtil. -

- -

The text describes software which is a complete implementation of pvData as -currently planned by the EPICS V4 Working Group.

- -

The following is a list of unresolved issues for pvDataCPP:

-
-
PVArray
-
The implementation of the different array types (PVBooleanArray, ..., - PVStructureArray) all store the data as a shared pointer holding a - vector. A test case should be created to make sure that vector.size() is - the same as getLength()
-
PVArray Examples
-
The following examples should be provided: 1) use all the get methods. - 2) create an example that makes data available in chunks.
-
pvType Example
-
Create an example of how to use the array typedefs
-
Convert test
-
How can this be better tested?
-
Structure and PVStructure
-
These two classes still keep data via std::vector. - Should they keep it as std::tr1::shared_ptr<std::vector<... ?
- In particular change -
-class Structure
-...
-StringArray fieldNames;
-FieldConstPtrArray fields
-
-class PVStructure
-...
-PVFieldPtrArray pvFields;
-
-To -
-class Structure
-...
-StringArrayPtr fieldNames;
-FieldConstPtrArrayPtr fields
-
-class PVStructure
-...
-PVFieldPtrArrayPtr pvFields;
-
-If these are changed several methods also change so that raw vectors are never passed as -argument or returned from methods.
-
- -
-

Table of Contents

-
-
- - -

Introduction

- -

pvData is one of a set of related projects. It describes and implements the -data that the other projects support. Thus it is not useful by itself but -understanding pvData is required in order to understand the other projects. The -reader should also become familar with projects pvAccess and pvIOC, which are -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:

-
-
Introduction
-
A brief descripton of pvData.
-
PVData Meta Language
-
A language used to describe data.
-
- -

The material in these two chapters is NOT repeated in this documentation.

- -

Doxygen documentation is available at doxygenDoc

- -

Namespace and Memory Management

- -

Namespace

- -

All code in project pvDataCPP appears in namespace:

-
namespace epics { namespace pvData {
-     // ...
-}}
- -

Memory Managemment

- -

pvDataCPP introspection and data objects are designed to be shared. They are -made availiable via std::tr1::shared_ptr. In addition arrays are -implemented via std::vector. The following naming conventions are used -in typedefs:

-
-
Ptr
-
When Ptr appears it stands for std::tr1::shared_ptr.
-
Array
-
When Array appears it stands for std::vector.
-
- -

As an example pvType.h includes the following definitions:

-
typedef std::vector<double> DoubleArray;
-typedef std::tr1::shared_ptr<DoubleArray> DoubleArrayPtr;
-inline double * get(DoubleArray &value)
-{
-    return &value[0];
-}
-inline const double * get(const DoubleArray &value)
-{
-    return static_cast<const double *>(&value[0]);
-}
-typedef std::vector<double>::iterator DoubleArray_iterator;
-typedef std::vector<double>::const_iterator DoubleArray_const_iterator;
- -

where

-
-
DoubleArray
-
This defines a vector for an array of the primitive type "double".
-
DoubleArrayPtr
-
This devices a shared pointer to a vector for an array of the primitive - type "double".
-
get
-
This gets the raw array of doubles that the DoubleArray holds.
-
DoubleArray_iterator
-
This gets a iterator for the DoubleArray.
-
DoubleArray_const_iterator
-
This gets a constant iterator for the DoubleArray.
-
- -

pvDataApp/pv

- -

Overview

- -

Directory pvDataApp/pv has header files that completely describe pvData. The -implementation is provided in directory pvDataApp/factory. Test programs -appears in testApp/pv.

- -

NOTES:

-
-
interface
-
The documention uses the word interface. This is an analogy for - what the Java implementation implements, i. e. package pv provides Java - interfaces. C++ does not have interfaces but directory pv defines classes - with public members that are similar to the Java interfaces. Most of the - implementation is in factory.
-
Naming Convertions
-
The naming convertions for variables, methods, and classes follow the - Java convertions, i. e. class name begin with an upper case letter, - variables and methods begin with a lower case letter.
-
- -

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. This section describes the complete set of C++ -introspection and data interfaces for pvData.

- -

Class FieldCreate creates introspection objects. Class PVDataCreate creates -data objects. Class Convert provides a rich set of methods for converting and -copying data between fields.

- -

Directory pvDataApp/pv has the following header files:

-
-
pvType.h
-
C++ definitions for primitive types.
-
pvIntrospect.h
-
A complete description of the introspection interfaces.
-
pvData.h
-
A complete description of the data interfaces.
-
convert.h
-
A facility that converts between data fields.
-
standardField.h
-
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.
-
- -

pvType.h

- -

This provides C/C++ definitions for the pvData primitive types: boolean, -byte, short, int, long, ubyte,ushort, uint,u long,float, double, and string. -Because pvData is network data, the C++ implementation must implement the -proper semantics for the primitive types.

- -

pvType.h provides the proper semantics.

- -

It has the definitions:

-
typedef uint8_t  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::string String;
-
-/**
- * A boolean array.
- */
-typedef std::vector<uint8> BooleanArray;
-typedef std::tr1::shared_ptr<BooleanArray> BooleanArrayPtr;
-/* get is same is ubyte*/
-typedef std::vector<uint8>::iterator BooleanArray_iterator;
-typedef std::vector<uint8>::const_iterator BooleanArray_const_iterator;
-
-/**
- * A byte array.
- */
-typedef std::vector<int8> ByteArray;
-typedef std::tr1::shared_ptr<ByteArray> ByteArrayPtr;
-inline int8 * get(ByteArray &value);
-inline int8 const * get(ByteArray const &value);
-inline int8 * get(ByteArrayPtr &value);
-inline int8 const * get(ByteArrayPtr const &value);
-inline ByteArray & getVector(ByteArrayPtr &value);
-inline ByteArray const & getVector(ByteArrayPtr const &value);
-typedef std::vector<int8>::iterator ByteArray_iterator;
-typedef std::vector<int8>::const_iterator ByteArray_const_iterator;
-
-/* similar definitions are present for ALL the primitive types */
- -

where

-
-
boolean
-
A c++ bool has the semantics required for boolean. Only the name is - different. C++ code can use either bool or boolean.
-
int8,...,uint64
-
Integers present a problem because short, int, and long are C++ - reserved words but do not have a well defined number of bits. Thus for - C++ the definitions above are used in C++ code. The above definitions - have worked on all C++ implementations tested at present. If they break - in a future implementation they should be changes via "#ifdef" - preprocessor statements.
-
String
-
pvData requires that a string be an immutable string that is transfered - over the network as a UTF8 encoded string. Since std::string implements - copy on write semantics, it can be used for support for immutable - strings. It can also be serialized/deserialized as a UTF8 encoded string. - Because it is not a C++ primitive the first letter is capitalized. This - is the same convention the Java implementation uses.
-
StringBuilder
-
This is defined here because to is used by the toString methods defined - for both introsection and data objects. The definition above acts like - the Java StringBuilder class.
-
Array definitions
-
typedefs are provided for an array of each of the primitive types. Note - that string is treated like a primitive type/
-
- -

pvIntrospect.h

- -

This subsection describes pvIntrospect.h This file is quite big so rather -than showing the entire file, it will be described in parts.

- -

A primary reason 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 pvname if a unique name in the local network.

- -

Given a pvname PV), 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 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.

- -

Type Description

- -

Types are defined as:

-
enum Type {
-    scalar,
-    scalarArray,
-    structure,
-    structureArray;
-};
-
-class TypeFunc {
-public:
-    const char* name(Type);
-    static void toString(StringBuilder buf,const 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(String const &value);
-    const char* name(ScalarType);
-    void toString(StringBuilder buf,ScalarType scalarType);
-};
- -

Type is one of the following:

-
-
scalar
-
A scalar of one of the scalar types.
-
scalarArray
-
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 types can be different.
-
structureArray
-
An array where each element is a structure. Each element has the same - structure introspection interface.
-
- -

ScalarType is one of the following:

-
-
pvBoolean
-
Has the value false or true.
-
pvByte
-
A signed 8 bit integer.
-
pvShort
-
A signed 16 bit integer.
-
pvInt
-
A signed 32 bit integer.
-
pvLong
-
A signed 64 bit integer.
-
pvUByte
-
An unsigned 8 bit integer.
-
pvUShort
-
An unsigned 16 bit integer.
-
pvUInt
-
An unsigned 32 bit integer.
-
pvULong
-
An unsigned 64 bit integer.
-
pvFloat
-
A IEEE float.
-
pvDouble
-
A IEEE double,
-
pvString
-
An immutable string.
-
- -

TypeFunction is a set of convenience methods for Type

-
-
name
-
Returns the name of the type.
-
toString
-
Convert the type to a string.
-
- -

ScalarTypeFunction is a set of convenience methods for ScalarType

-
-
isInteger
-
Is the scalarType an integer type, i.e. one of pvByte,...pvULong.
-
isUInteger
-
Is the scalarType an unsigned integer type, i.e. one of - pvUByte,...pvULong
-
isNumeric
-
Is the scalarType numeric, i.e. pvByte,...,pvDouble.
-
isPrimitive
-
Is the scalarType primitive, i.e. not pvString
-
name
-
Returns the name of the scalarType.
-
getScalarType
-
Given a string of the form String("boolean"),...,String("string") - return the scalarType.
-
toString
-
Convert the scalar type to a string.
-
- -

Introspection Description

- -

This section describes the reflection interfaces which provide the -following:

-
-
Field
-
A field: -
    -
  • Has a Type.
    • -
  • Can be converted to a string.
    • -
  • Can be shared. A reference count is kept. When it becomes 0 the - instance is automatically deleted.
    • -
-
-
Scalar
-
A scalar has a scalarType
-
ScalarArray
-
The element type is a scalarType
-
StructureArray
-
The field holds an array of structures. Each element has the same - 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
-
This is an interface that provides methods to create introspection - interfaces. A factory is provides to create FieldCreate.
-
getFieldCreate
-
Gets a pointer to the single instance of FieldCreate.
-
-
class Field;
-class Scalar;
-class ScalarArray;
-class Structure;
-class StructureArray;
-
-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;
-
-
-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 String getID() const = 0;
-    virtual void toString(StringBuilder buf) const{toString(buf,0);}
-    virtual void toString(StringBuilder buf,int indentLevel) const;
- ...
-};
-
-class Scalar : public Field{
-public:
-    POINTER_DEFINITIONS(Scalar);
-    virtual ~Scalar();
-    typedef Scalar& reference;
-    typedef const Scalar& const_reference;
-
-    ScalarType getScalarType() const {return scalarType;}
-    virtual void toString(StringBuilder buf) const{toString(buf,0);}
-    virtual void toString(StringBuilder buf,int indentLevel) const;
-    virtual String getID() const;
-    virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
-    virtual void deserialize(ByteBuffer *buffer, DeserializableContol *control);
- ...
-};
-
-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 void toString(StringBuilder buf) const{toString(buf,0);}
-    virtual void toString(StringBuilder buf,int indentLevel) const;
-    virtual String getID() const;
-    virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
-    virtual void deserialize(ByteBuffer *buffer, DeserializableControl *control);
- ...
-};
-
-class StructureArray : public Field{
-public:
-    POINTER_DEFINITIONS(StructureArray);
-    typedef StructureArray& reference;
-    typedef const StructureArray& const_reference;
-
-    StructureConstPtr  getStructure() const {return pstructure;}
-    virtual void toString(StringBuilder buf,int indentLevel=0) const;
-    virtual String getID() 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(String const & fieldName) const;
-   FieldConstPtr getField(std::size_t index) const;
-   std::size_t getFieldIndex(String const &fieldName) const;
-   FieldConstPtrArray const & getFields() const {return fields;}
-   StringArray const & getFieldNames() const;
-   void renameField(std::size_t fieldIndex,String const &newName);
-   String getFieldName(std::size_t fieldIndex);
-   virtual void toString(StringBuilder buf,int indentLevel) const;
-   virtual String getID() const;
-   virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
-   virtual void deserialize(ByteBuffer *buffer, DeserializableControl *control);
- ...
-};
-
-class FieldCreate  {
-public:
-    static FieldCreatePtr getFieldCreate();
-    ScalarConstPtr  createScalar(ScalarType scalarType) const
-    ScalarArrayConstPtr createScalarArray(ScalarType elementType) const;
-    StructureArrayConstPtr createStructureArray(StructureConstPtr const & structure) const;
-    StructureConstPtr createStructure (
-        StringArray const & fieldNames,
-        FieldConstPtrArray const & fields) const;
-    StructureConstPtr createStructure (
-        String const &id,
-        StringArray const & fieldNames,
-        FieldConstPtrArray const & fields) const;
-    StructureConstPtr appendField(
-        StructureConstPtr const & structure,
-        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;
- ...
-};
-
-extern FieldCreatePtr getFieldCreate();
-
-
Constructor
-
Note that all constructors are protected or private. The only way to - create instances is via FieldCreate. The implementation manages all - storage via shared pointers.
-
toString
-
Many classes provide this (actually two methods). This method is called - to get a string that uses the metadata syntax described in a previous - section.
-
- -
Field
-
-
getType
-
Get the field type.
-
getID
-
Get an ID for this introspection interface
-
- -
Scalar
-
-
getScalarType
-
Get that scalar type.
-
getID
-
For each scalarType there is one instance of Scalar. The ID for each is - the metadata name for the type, i. e. one of "boolean" , ... , "string". -
-
- -
ScalarArray
-
-
getElementType
-
Get the element type.
-
getID
-
For each elemnetType there is one instance of ScalarArray. The ID for - each is the metadata name for the type, i. e. one of "boolean[]" , ... , - "string[]".
-
- -
StructureArray
-
-
getStructure
-
Get the introspection interface that each element shares,
-
getID
-
This returns the ID[] where ID is the value returned by - structure->getID().
-
- -
Structure
-
-
getNumberFields
-
Get the number of immediate subfields.
-
getField
-
Given a name or an index get the introspection interface for the - field.
-
getFieldIndex
-
Given a name get the index, within the array returned by the next - method, of the field.
-
getFields
-
Get the array of introspection interfaces for the field,
-
getFieldNames
-
Get the array of field names for the subfields.
-
renameField
-
Rename the field.
-
getFieldName
-
Get the field name for the specified index.
-
- -
FieldCreate
-
-
getFieldCreate
-
Get the single instance of FieldCreate.
-
createScalar
-
Create a scalar introspection instance.
-
createScalarArray
-
Create a scalar array introspection instance.
-
createStructure
-
Create a structure introspection instance. Two methods are provided - where the only difference is that one provides an ID and the other does - not. The one without will result in ID "structure".
-
createStructureArray
-
Create a structure array introspection instance.
-
appendField
-
Append a field to a structure.
-
appendFields
-
Append fields to a structure.
-
deserialize
-
Deserialize from given byte buffer.
-
- -

standardField.h

- -

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,String const &properties);
-    StructureConstPtr scalarArray(
-        ScalarType elementType, String const &properties);
-    StructureConstPtr structureArray(
-        StructureConstPtr const & structure,String const &properties);
-    StructureConstPtr enumerated();
-    StructureConstPtr enumerated(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();
- ...
-};
-
-
scalar
-
Create a scalar with the specified scalar type and name. A structure - will be created with the first element being a scalar with the specified - scalar type and name value. The other fields in the structure will be the - corresponding property structures.
-
scalarArray
-
Create a scalarArray with each element having the specified scalar type - and name. A structure will be created with the first element being a - scalarArray with name value. The other fields in the structure will be - the corresponding property structures.
-
structureArray
-
Create a structureArray with the specified structure interface and - name. A structure will be created with the first element being a - structureArray with the specified structure interface and name value. The - other fields in the structure will be the corresponding property - structures.
-
structure
-
Create a structure with the specified name and fields specified by - numFields and fields. A structure will be created with the first element - being a structure with the name value and fields specified by numFields - and fields. The other fields in the structure will be the corresponding - property structures.
-
enumerated
-
Create a structure with the specified name and fields for an enumerated - structure. If properties are specified then a structure will be created - with the first element being a structure with the name value and fields - for an enumerated structure. The other fields in the structure will be - the corresponding property structures.
-
alarm
-
timeStamp
-
display
-
control
-
booleanAlarm
-
byteAlarm
-
shortAlarm
-
intAlarm
-
longAlarm
-
floatAlarm
-
doubleAlarm
-
enumeratedAlarm
-
The above provide introspection interfaces for standard properties. See - the section on Properties for a description of how these are defined.
-
- -

pvData.h

- -

This subsection describes pvData.h This file is quite big so rather than -showing the entire file, it will be described in parts.

- -

typedefs

- -

These are typedefs for Array and Ptr for the various pvData class -definitions, i.e. typdefs for "std::vector" and "std::tr1::shared_ptr".

-
class PVAuxInfo;
-class PostHandler;
-
-class PVField;
-class PVScalar;
-
-class PVScalarArray;
-
-class PVStructure;
-class PVStructureArray;
-
-typedef std::tr1::shared_ptr<PVAuxInfo> PVAuxInfoPtr;
-
-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 std::tr1::shared_ptr<PostHandler> PostHandlerPtr
- -

PostHandler is a class that must be implemented by any code that calls -setPostHandler. It's single virtual method. postPut is called whenever -PVField::postPut is called.

-
class PostHandler 
-{
-public:
-    POINTER_DEFINITIONS(PostHandler);
-    virtual ~PostHandler(){}
-    virtual void postPut() = 0;
-};
- -

PVField

- -

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 PVField
-: virtual public Serializable,
-  public std::tr1::enable_shared_from_this<PVField>
-{
-public:
-   POINTER_DEFINITIONS(PVField);
-   virtual ~PVField();
-   virtual void message(String message,MessageType messageType);
-   String getFieldName() const ;
-   virtual void setRequester(RequesterPtr const &prequester);
-   std::size_t getFieldOffset() const;
-   std::size_t getNextFieldOffset() const;
-   std::size_t getNumberFields() const;
-   PVAuxInfoPtr & getPVAuxInfo()
-   bool isImmutable() const;
-   virtual void setImmutable();
-   const FieldConstPtr & getField() const ;
-   PVStructure * getParent() const 
-   void replacePVField(const PVFieldPtr&  newPVField);
-   void renameField(String const &newName);
-   void postPut() ;
-   void setPostHandler(PostHandlerPtr const &postHandler);
-   virtual bool equals(PVField &pv);
-   virtual void toString(StringBuilder buf) ;
-   virtual void toString(StringBuilder buf,int indentLevel);
-   std::ostream& dumpValue(std::ostream& o) const;
- ...
-}
- -

The public methods for PVField are:

-
-
~PVField
-
Destructor. Since shared pointers are used it should never be called by - user code.
-
message
-
Code attached to this field can call this method to report - problems.
-
getFieldName
-
Get the field name. If the field is a top level structure the field - name will be an empty string.
-
setRequester
-
Sets a requester to be called when message or getRequesterName are - called. This is only legal for the top level PVField.
-
getFieldOffset
-
Get offset of the PVField field within top level structure. Every field - within the PVStructure has a unique offset. The top level structure has - an offset of 0. The first field within the structure has offset equal to - 1. The other offsets are determined by recursively traversing each - structure of the tree.
-
getNextFieldOffset
-
Get the next offset. If the field is a scalar or array field then this - is just offset + 1. If the field is a structure it is the offset of the - next field after this structure. Thus (nextOffset - offset) is always - equal to the total number of fields within the field.
-
getNumberFields
-
Get the total number of fields in this field. This is nextFieldOffset - - fieldOffset.
-
getPVAuxInfo
-
Get the PVAuxInfo for this field. PVAuxInfo is described below.
-
isImmutable
-
Is the field immutable?
-
setImmutable
-
Make the field immutable. Once a field is immutable it can never be - changed since there is no method to again make it mutable. This is an - important design decision since it allows immutable array fields to share - the internal primitive data array.
-
getField
-
Get the reflection interface for the data.
-
getParent
-
Get the interface for the parent or null if this is the top level - PVStructure.
-
replacePVField
-
Replace the data implementation for the field.
-
renameField
-
Rename the field name.
-
postPut
-
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.
-
equals
-
Compare this field with another field. The result will be true only if - the fields have exactly the same field types and if the data values are - equal.
-
toString
-
Converts the field data to a string. This is mostly for debugging - purposes.
-
dumpValue
-
Method for streams I/O.
-
- -

PVAuxInfo

- -

AuxInfo (Auxillary Information) is information about a field that is -application specific. It will not be available outside the application that -implements the database. In particular it will not be made available to Channel -Access. It is used by the database itself to override the default -implementation of fields. The JavaIOC uses it for attaching support code. -Database Configuration and other tools can use it for configuration -information. Each Field and each PVField can have have an arbitrary number of -auxInfos. An auxInfo is a (key,PVScalar) pair where key is a string.

-
class PVAuxInfo : private NoDefaultMethods {
-public:
-    typedef std::map<String,PVScalarPtr> PVInfoMap;
-    typedef std::map<String,PVScalarPtr>::iterator PVInfoIter;
-    typedef std::pair<String,PVScalarPtr> PVInfoPair;
-
-    PVAuxInfo(PVField *pvField);
-    ~PVAuxInfo();
-    PVField * getPVField();
-    PVScalarPtr createInfo(String const &key,ScalarType scalarType);
-    PVScalarPtr getInfo(String const &key);
-    PVInfoMap & getInfoMap();
-    void toString(StringBuilder buf);
-    void toString(StringBuilder buf,int indentLevel);
- ...
-};
- -

where

-
-
getPVField
-
Get the PVField to which this PVAuxInfo is attached.
-
createInfo
-
Create a new PVScalar of type scalarType.
-
getInfo
-
Get the PVScalar with the specified key.
-
getInfoMap
-
Get the map of all the PVScalars that hold the info.
-
toString
-
Print all the auxInfos
-
- -

PVScalar

- -

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 ;
- ...
-}
- -

where

-
-
getScalar
-
Get the introspection interface for the PVScalar.
-
- -

PVScalarValue

- -

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;
-    virtual ~PVScalarValue() {}
-    virtual T get() const = 0;
-    virtual void put(T value) = 0;
- ...
-}
-
-// PVString is special case, since it implements SerializableArray
-class PVString : public PVScalarValue<String>, SerializableArray {
-public:
-    virtual ~PVString() {}
- ...
-};
- -

where

-
-
get
-
Get the value stored in the object.
-
put
-
Change the value stored in the object.
-
- -

PVArray

- -

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 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;
- ...
-};
-
-
setImmutable
-
Set the data immutable. Note that this is permanent since there is no - methods to make it mutable.
-
getLength
-
Get the current length. This is less than or equal to the capacity.
-
setLength
-
Set the length. If the PVField is not mutable then an exception is - thrown. If this is greater than the capacity setCapacity is called.
-
getCapacity
-
Get the capacity, i.e. this is the size of the underlying data - array.
-
setCapacity
-
Set the capacity. The semantics are implementation dependent but - typical semantics are as follows: If the capacity is not mutable an - exception is thrown. A new data array is created and data is copied from - the old array to the new array.
-
isCapacityMutable
-
Is the capacity mutable
-
setCapacityMutable
-
Specify if the capacity can be changed.
-
setCapacity
-
Set the capaciity.
-
- -

PVArrayData

- -

This is the argument to one of the get methods of PVValueArray.

-
template<typename T>
-class PVArrayData {
-private:
-    std::vector<T> init;
-public:
-    POINTER_DEFINITIONS(PVArrayData);
-    typedef T  value_type;
-    typedef T* pointer;
-    typedef const T* const_pointer;
-    std::vector<T> & data;
-    std::size_t offset;
-    PVArrayData()
-    : data(init)
-    {}
-};
- -

PVScalarArray

- -

PVScalarArray is the base class for scalar array data. PVValueArray is a -templete for the various scalar array data classes. There is a class for each -possible scalar type, i. e. PVBooleanArray, ..., PVStringArray.

-
class PVScalarArray : public PVArray {
-public:
-    POINTER_DEFINITIONS(PVScalarArray);
-    virtual ~PVScalarArray();
-    typedef PVScalarArray &reference;
-    typedef const PVScalarArray& const_reference;
-    const ScalarArrayConstPtr getScalarArray() const ;
-    virtual std::ostream& dumpValue(std::ostream& o, size_t index) const = 0;
- ...
-}
- -

where

-
-
getScalarArray
-
Get the introspection interface.
-
dumpValue
-
Method for streams I/O.
-
- -

PVValueArray

- -

This is a template class plus instances for PVBooleanArray, ..., -PVStringArray.

-
template<typename T>
-class PVValueArray : public PVScalarArray {
-public:
-    POINTER_DEFINITIONS(PVValueArray);
-    typedef T  value_type;
-    typedef T* pointer;
-    typedef const T* const_pointer;
-    typedef PVArrayData<T> ArrayDataType;
-    typedef std::vector<T> vector;
-    typedef const std::vector<T> const_vector;
-    typedef std::tr1::shared_ptr<vector> shared_vector;
-    typedef PVValueArray & reference;
-    typedef const PVValueArray & const_reference;
-
-    virtual ~PVValueArray() {}
-    virtual std::size_t get(
-         std::size_t offset, std::size_t length, ArrayDataType &data) = 0;
-    virtual std::size_t put(std::size_t offset,
-        std::size_t length, const_pointer from, std::size_t fromOffset) = 0;
-    virtual std::size_t put(std::size_t offset,
-        std::size_t length, const_vector &from, std::size_t fromOffset);
-    virtual void shareData(
-         shared_vector const & value,
-         std::size_t capacity,
-         std::size_t length) = 0;
-    virtual pointer get() = 0;
-    virtual pointer get() const = 0;
-    virtual vector const & getVector() = 0;
-    virtual shared_vector const & getSharedVector() = 0;
-    std::ostream& dumpValue(std::ostream& o) const;
-    std::ostream& dumpValue(std::ostream& o, size_t index) const;
-protected:
-    PVValueArray(ScalarArrayConstPtr const & scalar)
-    : PVScalarArray(scalar) {}
-    friend class PVDataCreate;
-};
-
-template<typename T>
-std::size_t PVValueArray<T>::put(
-    std::size_t offset,
-    std::size_t length,
-    const_vector &from,
-    std::size_t fromOffset)
-{ return put(offset,length, &from[0], fromOffset); }
-
-/**
- * Definitions for the various scalarArray types.
- */
-typedef PVArrayData<uint8> BooleanArrayData;
-typedef PVValueArray<uint8> PVBooleanArray;
-typedef std::tr1::shared_ptr<PVBooleanArray> PVBooleanArrayPtr;
-
-typedef PVArrayData<int8> ByteArrayData;
-typedef PVValueArray<int8> PVByteArray;
-typedef std::tr1::shared_ptr<PVByteArray> PVByteArrayPtr;
-
-typedef PVArrayData<int16> ShortArrayData;
-typedef PVValueArray<int16> PVShortArray;
-typedef std::tr1::shared_ptr<PVShortArray> PVShortArrayPtr;
-
-typedef PVArrayData<int32> IntArrayData;
-typedef PVValueArray<int32> PVIntArray;
-typedef std::tr1::shared_ptr<PVIntArray> PVIntArrayPtr;
-
-typedef PVArrayData<int64> LongArrayData;
-typedef PVValueArray<int64> PVLongArray;
-typedef std::tr1::shared_ptr<PVLongArray> PVLongArrayPtr;
-
-typedef PVArrayData<uint8> UByteArrayData;
-typedef PVValueArray<uint8> PVUByteArray;
-typedef std::tr1::shared_ptr<PVUByteArray> PVUByteArrayPtr;
-
-typedef PVArrayData<uint16> UShortArrayData;
-typedef PVValueArray<uint16> PVUShortArray;
-typedef std::tr1::shared_ptr<PVUShortArray> PVUShortArrayPtr;
-
-typedef PVArrayData<uint32> UIntArrayData;
-typedef PVValueArray<uint32> PVUIntArray;
-typedef std::tr1::shared_ptr<PVUIntArray> PVUIntArrayPtr;
-
-typedef PVArrayData<uint64> ULongArrayData;
-typedef PVValueArray<uint64> PVULongArray;
-typedef std::tr1::shared_ptr<PVULongArray> PVULongArrayPtr;
-
-typedef PVArrayData<float> FloatArrayData;
-typedef PVValueArray<float> PVFloatArray;
-typedef std::tr1::shared_ptr<PVFloatArray> PVFloatArrayPtr;
-
-typedef PVArrayData<double> DoubleArrayData;
-typedef PVValueArray<double> PVDoubleArray;
-typedef std::tr1::shared_ptr<PVDoubleArray> PVDoubleArrayPtr;
-
-typedef PVArrayData<String> StringArrayData;
-typedef PVValueArray<String> PVStringArray;
-typedef std::tr1::shared_ptr<PVStringArray> PVStringArrayPtr;
- -

where

-
-
get( std::size_t offset, std::size_t length, ArrayDataType &data) -
-
This method "exposes" it's internal array by setting data.data and - data.offset. The caller is responsible for copying the array elements. - This violates the principle that objects should not expose their internal - data but is done for efficency. For example it makes it possible to copy - between arrays with identical element types without requiring an - intermediate array.
-
put(std::size_t offset, std::size_t length, const_pointer from, - std::size_t fromOffset)
-
Put data into the array. from is a raw array.
-
put(std::size_t offset, std::size_t length, const_vector &from, - std::size_t fromOffset)
-
Put data into the array from a vector holding the raw array.
-
shareData( shared_vector const & value, std::size_t capacity, - std::size_t length)
-
Make the instance share the raw data from value.
- One use is - for immutable arrays. In this case the caller must set the PVArray to be - immutable. In the PVArray is not immutable then it is the applications - responsibility to coordinate access to the array. Again this violates the - principle that objects should not expose their internal data 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 choices is immutable. Allowing the - choices internal String[] to be shared between all the instances of an - enumerated structure saves on storage.
- Another use for shared data is an application which processes an - array via multiple modules. Each accesses the internal data array of a - PVArray. In this case it is the applications responsibility - to coordinate access to the array.
-
get()
-
Get the raw array.
-
getVector()
-
Get the vector holding the raw array.
-
getSharedVector()
-
Get the shared vector holding the data.
-
dumpValue
-
Method for streams I/O.
-
- -

Both get and put return the number of elements actually transfered. The -arguments are:

-
-
offset
-
The offset in the PV array.
-
len
-
The maximum number of elements to transfer. The number actually - transfered will be less than or equal to this value.
-
data
-
Get sets data.data to it's internal array and data.offset to the offset - into the array. The caller is responsible for the actual data - transfer.
-
from
-
The array from which the data is taken. This array is supplied by the - caller
-
fromOffset
-
The offset in from
-
- -

The caller must be prepared to make multiple calls to retrieve or put an -entire array. A caller should accept or put partial arrays. For example the -following reads an entire array:

-
void getArray(PVDoubleArrayPtr & pv,DoubleArray const & to)
-{
-    size_t len = pv->getLength();
-    if(to.size()<len) to.resize(len);
-    DoubleArrayData data;
-    size_t offset = 0;
-    while(offset<len) {
-        size_t num = pv->get(offset,(len-offset),data);
-        DoubleArray &from = data.data;
-        size_t fromOffset = data.offset;
-        for(size_t i=0; i<num; i++) to[i+offset] = from[i + fromOffset];
-        offset += num;
-    }
-}
- -

- -

PVStructure

- -

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(String const &fieldName) const;
-    PVFieldPtr getSubField(std::size_t fieldOffset) const;
-    void appendPVField(
-        String const &fieldName,
-        PVFieldPtr const & pvField);
-    void appendPVFields(
-        StringArray const & fieldNames,
-        PVFieldPtrArray const & pvFields);
-    void removePVField(String const &fieldName);
-    PVBooleanPtr getBooleanField(String const &fieldName) ;
-    PVBytePtr getByteField(String const &fieldName) ;
-    PVShortPtr getShortField(String const &fieldName) ;
-    PVIntPtr getIntField(String const &fieldName) ;
-    PVLongPtr getLongField(String const &fieldName) ;
-    PVUBytePtr getUByteField(String const &fieldName) ;
-    PVUShortPtr getUShortField(String const &fieldName) ;
-    PVUIntPtr getUIntField(String const &fieldName) ;
-    PVULongPtr getULongField(String const &fieldName) ;
-    PVFloatPtr getFloatField(String const &fieldName) ;
-    PVDoublePtr getDoubleField(String const &fieldName) ;
-    PVStringPtr getStringField(String const &fieldName) ;
-    PVStructurePtr getStructureField(String const &fieldName) ;
-    PVScalarArrayPtr getScalarArrayField(
-        String const &fieldName,ScalarType elementType) ;
-    PVStructureArrayPtr getStructureArrayField(String const &fieldName) ;
-    String getExtendsStructureName() const;
-    bool putExtendsStructureName(
-        String const &extendsStructureName);
-    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);
-};
- -

where

-
-
getStructure
-
Get the introspection interface for the structure.
-
getPVFields
-
Returns the array of subfields. The set of subfields must all have - different field names.
-
getSubField(String fieldName)
-
Get a subField of a field. For a PVStructure a non-null result is - returned if fieldName is a field of the PVStructure. The fieldName can be - of the form name.name... - If the field does not exist the a Ptr to a NULL value is returned - without any error message being generated. -
-
getSubField(int fieldOffset)
-
Get the field located a fieldOffset, where fieldOffset is relative to - the top level structure. This returns null if the specified field is not - located within this PVStructure.
-
appendPVField
-
Append pvField to the end of this PVStructure. This should NOT be - called if any code is attached to any of the fields in the top level - structure.
-
appendPVFields
-
Append an array of pvFields to the end of this structure. Note that if - the original number of fields is 0 than pvFields replaces the original. - Thus the caller must NOT reuse pvFields after calling this method. This - should NOT be called if any code is attached to any of the fields in the - top level structure
-
removePVField
-
Remove the specified field from this structure. This should NOT be - called if any code is attached to any of the fields in the top level - structure.
-
getBooleanField
-
Look for fieldName. If found and it has the correct type return the - interface. This and the following methods are convenience methods that - allow a user to get the interface to a subfield without requiring - introspection. fieldName can be of the form name.name... - If the field does not exist or has the wrong type then - message will be called and a Ptr to NULL is returned. -
-
getByteField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getShortField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getIntField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getLongField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getUByteField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getUShortField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getUIntField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getULongField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getFloatField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getDoubleField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getStringField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getStructureField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getScalarArrayField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getStructureArrayField
-
Look for fieldName. If found and it has the correct type return the - interface.
-
getExtendsStructureName
-
Get the name of structure that this structure extends.
-
putExtendsStructureName
-
Specify the structure that this structure extends.
-
- -

PVStructureArray

- -

The interface for an array of structures is:

-
typedef PVArrayData<PVStructurePtr> StructureArrayData;
-
-class PVStructureArray : public PVArray
-{
-public:
-    POINTER_DEFINITIONS(PVStructureArray);
-    typedef PVStructurePtr  value_type;
-    typedef PVStructurePtr* pointer;
-    typedef const PVStructurePtr* const_pointer;
-    typedef PVArrayData<PVStructurePtr> ArrayDataType;
-    typedef std::vector<PVStructurePtr> vector;
-    typedef const std::vector<PVStructurePtr> const_vector;
-    typedef std::tr1::shared_ptr<vector> shared_vector;
-    typedef PVStructureArray &reference;
-    typedef const PVStructureArray& const_reference;
-
-    virtual ~PVStructureArray() {}
-    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 std::size_t get(std::size_t offset, std::size_t length,
-        StructureArrayData &data);
-    virtual std::size_t put(std::size_t offset,std::size_t length,
-        const_vector const & from, std::size_t fromOffset);
-    virtual void shareData(
-         shared_vector const & value,
-         std::size_t capacity,
-         std::size_t length);
-    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 pointer get() { return &((*value.get())[0]); }
-    virtual pointer get() const { return &((*value.get())[0]); }
-    virtual vector const & getVector() {return *value;}
-    virtual shared_vector const & getSharedVector() {return value;}
- ...
-}
- -

where

-
-
getStructureArray
-
Get the introspection interface shared by each element.
-
append
-
Create new elements and append them to the end of the array. It returns - the index of the first new element.
-
remove
-
Remove the specfied set of elements. It returns (false,true) if the - elements (were not, were) removed. It will not removed any elements - unless all requested elements exist or are null. Note that this deletes - the element and sets the array element to null. It does not change the - array capacity.
-
compress
-
This moves all null elements and then changes the array capacity. When - done there are no null elements.
-
- -

The other methods are similar to the methods for other array types.

- -

PVDataCreate

- -

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);
-    PVScalarArrayPtr createPVScalarArray(ScalarArrayConstPtr const & scalarArray);
-    PVScalarArrayPtr createPVScalarArray(ScalarType elementType);
-    PVScalarArrayPtr createPVScalarArray(PVScalarArrayPtr const  & scalarArrayToClone);
-    PVStructureArrayPtr createPVStructureArray(StructureArrayConstPtr const & structureArray);
-    PVStructurePtr createPVStructure(StructureConstPtr const & structure);
-    PVStructurePtr createPVStructure(
-        StringArray const & fieldNames,PVFieldPtrArray const & pvFields);
-   PVStructurePtr createPVStructure(PVStructurePtr const & structToClone);
- ...
-};
-
-extern PVDataCreatePtr getPVDataCreate();
- -

where

-
-
createPVField
-
The PVField is created reusing the Field interface. Two methods are - provided. Each calls the corresponding createPVScalar, createPVArray, or - createPVStructure depending in the type of the last argument.
-
createPVScalar
-
Creates an instance of a PVScalar. Three versions are supplied. The - first is passed an introspection interface. The second provides the field - name and the scalarType. The last provides a field name and a PVScalar to - clone. The newly created PVScalar will have the same auxInfos as the - original.
-
createPVScalarArray
-
Create an instance of a PVArray. Three versions are supplied. The first - is passed an introspection interface. The second provides the field name - and the elementType. The last provides a field name and a PVArray to - clone. The newly created PVArray will have the same auxInfos as the - original.
-
createPVStructureArray
-
Create a PVStructureArray. It must be passed a structureToClone. This - will become the Structure interface for ALL elements of the - PVStructureArray. It MUST be used to create any new array elements.
-
createPVStructure
-
Create an instance of a PVStructure. Three methods are provided. The - first method uses a previously created structure introspection interface. - The second uses a PVField array to initialize the sub-fields. - The third initializes the subfields by cloning the fields contained in - structToClone. The newly created sub-fields will have the same values and - auxInfos as the original. If structToClone is null then the new structure - is initialized to have 0 sub-fields.
-
- -

standardPVField.h

- -

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,String const &properties);
-    PVStructurePtr scalarArray(ScalarType elementType, String const &properties);
-    PVStructurePtr structureArray(StructureConstPtr const &structure,String const &properties);
-    PVStructurePtr enumerated(StringArray const &choices);
-    PVStructurePtr enumerated(StringArray const &choices, String const &properties);
- ...
-}
-
-
-extern StandardPVFieldPtr getStandardPVField();
- -

convert.h

- -

NOTE about copying immutable array fields. If an entire immutable array -field is copied to another array that has the same elementType, both offsets -are 0, and the length is the length of the source array, then the shareData -method of the target array is called and the target array is set immutable. -Thus the source and target share the same primitive array.

- -

This section describes the supported conversions between data types.

- -
bool operator==(PVField&, PVField&);
-
-static inline bool operator!=(PVField& a, PVField& b)
-{return !(a==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&);
-
-static inline bool operator!=(const Field& a, const Field& b)
-{return !(a==b);}
-static inline bool operator!=(const Scalar& a, const Scalar& b)
-{return !(a==b);}
-static inline bool operator!=(const ScalarArray& a, const ScalarArray& b)
-{return !(a==b);}
-static inline bool operator!=(const Structure& a, const Structure& b)
-{return !(a==b);}
-static inline bool operator!=(const StructureArray& a, const StructureArray& b)
-{return !(a==b);}
-class Convert;
-typedef std::tr1::shared_ptr<Convert> ConvertPtr;
-
-class Convert {
-public:
-    static ConvertPtr getConvert();
-    ~Convert();
-    void getFullName(StringBuilder buf,PVFieldPtr const & pvField);
-    bool equals(PVFieldPtr const &a,PVFieldPtr const &b);
-    bool equals(PVField &a,PVField &b);
-    void getString(StringBuilder buf,PVFieldPtr const & pvField,int indentLevel);
-    void getString(StringBuilder buf,PVFieldPtr const & pvField);
-    void getString(StringBuilder buf,PVField const * pvField,int indentLevel);
-    void getString(StringBuilder buf,PVField const * pvField);
-    std::size_t fromString(
-        PVStructurePtr const &pv,
-        StringArray const & from,
-        std::size_t fromStartIndex = 0);
-    void fromString(PVScalarPtr const & pv, String const & from);
-    std::size_t fromString(PVScalarArrayPtr const & pv, 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);
-    std::size_t copyScalarArray(
-        PVScalarArrayPtr const & from,
-        std::size_t offset,
-        PVScalarArrayPtr const & to,
-        std::size_t toOffset,
-        std::size_t length);
-    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);
-    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);
-    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);
-    std::size_t toByteArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        int8* to,
-        std::size_t toOffset);
-    std::size_t toShortArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        int16* to,
-        std::size_t toOffset);
-    std::size_t toIntArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        int32* to,
-        std::size_t toOffset);
-    std::size_t toLongArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        int64* to,
-        std::size_t toOffset);
-    std::size_t toUByteArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        uint8* to,
-        std::size_t toOffset);
-    std::size_t toUShortArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        uint16* to,
-        std::size_t toOffset);
-    std::size_t toUIntArray(
-        PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        uint32* to,
-        std::size_t toOffset);
-    std::size_t toULongArray(
-        PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        uint64* to,
-        std::size_t toOffset);
-    std::size_t toFloatArray(
-        PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        float* to,
-        std::size_t toOffset);
-    std::size_t toDoubleArray(
-        PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        double* to, std::size_t
-        toOffset);
-    std::size_t fromByteArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const int8* from, std::size_t fromOffset);
-    std::size_t fromByteArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const ByteArray & from, std::size_t fromOffset);
-    std::size_t fromShortArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const int16* from, std::size_t fromOffset);
-    std::size_t fromShortArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const ShortArray & from, std::size_t fromOffset);
-    std::size_t fromIntArray(
-       PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-       const int32* from, std::size_t fromOffset);
-    std::size_t fromIntArray(
-       PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-       const IntArray & from, std::size_t fromOffset);
-    std::size_t fromLongArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const int64* from, std::size_t fromOffset);
-    std::size_t fromLongArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const LongArray & from, std::size_t fromOffset);
-    std::size_t fromUByteArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const uint8* from, std::size_t fromOffset);
-    std::size_t fromUByteArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const UByteArray & from, std::size_t fromOffset);
-    std::size_t fromUShortArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const uint16* from, std::size_t fromOffset);
-    std::size_t fromUShortArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const UShortArray & from, std::size_t fromOffset);
-    std::size_t fromUIntArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const uint32* from, std::size_t fromOffset);
-    std::size_t fromUIntArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const UIntArray & from, std::size_t fromOffset);
-    std::size_t fromULongArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const uint64* from, std::size_t fromOffset);
-    std::size_t fromULongArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const ULongArray & from, std::size_t fromOffset);
-    std::size_t fromFloatArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const float* from, std::size_t fromOffset);
-    std::size_t fromFloatArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const FloatArray & from, std::size_t fromOffset);
-    std::size_t fromDoubleArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const double* from, std::size_t fromOffset);
-    std::size_t fromDoubleArray(
-        PVScalarArrayPtr & pv, std::size_t offset, std::size_t length,
-        const DoubleArray & from, std::size_t fromOffset);
-    void newLine(StringBuilder buf, int indentLevel);
- ...
-}
-
-extern ConvertPtr getConvert();
- -

The array methods all return the number of elements copied or converted. -This can be less than len if the PVField array contains less than len -elements.

- -

newLine is a convenience method for code that implements toString It -generates a newline and inserts blanks at the beginning of the newline.

- -

pvDataApp/property

- -

Definition of Property

- -

Only fields named "value" have properties. A record can have multiple value -fields, which can appear in the top level structure of a record or in a -substructure. All other fields in the structure containing a value field are -considered properties of the value field. The fieldname is also the property -name. The value field can have any type, i.e. scalar, scalarArray, or -structure. Typical property fields are timeStamp, alarm, display, control, and -history. The timeStamp is a special case. If it appears anywhere in the -structure hieraracy above a value field it is a property of the value field.

- -

For example the following top level structure has a single value field. The -value field has properties alarm, timeStamp, and display.

-
structure counterOutput
-    double value
-    alarm_t
-        int severity 0
-        int status 0
-        string message
-    timeStamp_t
-        long secondsPastEpoch
-        int nanoSeconds
-        int userTag
-    display_t
-        double limitLow 0.0
-        double limitHigh 10.0
-        string description "Sample Description"
-        string format "%f"
-        string units volts
- -

The following example has three value fields each with properties alarm and -timeStamp. Voltage, Current, and Power each have a different alarms but all -share the timeStamp.

-
structure powerSupplyValue
-    double value
-    alarm_t
-        int severity 0
-        int status 0
-        string message
-
-structure powerSupplySimple
-    alarm_t
-        int severity 0
-        int status 0
-        string message
-    timeStamp_t
-        long secondsPastEpoch
-        int nanoSeconds
-        int userTag
-    powerSupplyValue_t voltage
-        double value
-        alarm_t
-            int severity 0
-            int status 0
-            string message
-    powerSupplyValue_t power
-        double value
-        alarm_t
-            int severity 0
-            int status 0
-            string message
-    powerSupplyValue_t current
-        double value
-        alarm_t
-            int severity 0
-            int status 0
-            string message
- -

Standard Properties

- -

The following field names have special meaning, i.e. support properties for -general purpose clients.

-
-
value
-
This is normally defined since most general purpose clients access this - field. All other fields in the structure support or describe the value - field. The type can any supported type but is usually one of the - following: -
-
scalar
-
Any of the scalar types.
-
scalarArray
-
An array with the elementType being a scalar type
-
enumerated structure
-
A structure that includes fields named index and choices. index - is an int that selects a choice. choices is an array of strings - that defines the complete set of choices.
-
other
-
Other structure or array types can also be defined if clients and - support code agree on the meaning. Some examples are: 1) A - structure defining a 2D matrix, 2) A structure defining an image, - 3) A structure that simulates a remote method, ...
-
-
-
timeStamp
-
The timeStamp. The type MUST be a timeStamp structure. Also if the - PVData structure does not have a timeStamp then a search up the parent - tree is made to find a timeStamp.
-
alarm
-
The alarm. The type MUST be an alarm structure.
-
display
-
A display structure as described below. It provides display - characteristics for the value field.
-
control
-
A control structure as described below. It provides control - characteristics for the value field.
-
history
-
Provides a history buffer for the value field. Note that currently - PVData does not define history suppoprt.
-
other
-
Other standard properties can be defined.
-
- -

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:

-
-
input
-
A field with support that changes the value field. This can be - anything. It can be a channel access link. It can obtain a value from - hardware. Etc.
-
valueAlarm
-
A field with support that looks for alarm conditions based on the - value.
-
output
-
A field with support that reads the current value and sends it - somewhere else. This can be anything. It can be a channel access link. It - can write a value to hardware. Etc.
-
- -

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. -

- -

Overview of Property Support

- -

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(String("testMessage"));
-    al.setSeverity(majorAlarm);
-    result = pvAlarm.set(al);
-    assert(result);
-    alarm = pvAlarm.get();
-     ...
-}
- -

timeStamp

- -

A timeStamp is represented by the following structure

-
structure timeStamp
-    long secondsPartEpoch
-    int nanoSeconds
-    int userTag
- -

The Epoch is the posix epoch, i.e. Jan 1, 1970 00:00:00 UTC. Both the -seconds and nanoSeconds are signed integers and thus can be negative. Since the -seconds is kept as a 64 bit integer, it allows for a time much greater than the -present age of the universe. Since the nanoSeconds portion is kept as a 32 bit -integer it is subject to overflow if a value that corresponds to a value that -is greater than a little more than 2 seconds of less that about -2 seconds. The -support code always adjust seconds so that the nanoSecconds part is normlized, -i. e. it has is 0<=nanoSeconds<nanoSecPerSec..

- -

Two header files are provided for manipulating time stamps:

-
-
timeStamp.h
-
Defines a time stamp independent of pvData, i.e. it is a generally - useful class for manipulating timeStamps.
-
pvTimeStamp.h
-
A class that can be attached to a time stamp pvData structure. It - provides get and set methods to get/set a TimeStamp as defined by - timeStamp.h
-
- -

timeStamp.h

- -

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

-
-
TimeStamp()
-
The defauly constuctor. Both seconds and nanoSeconds are set to 0.
-
TimeStamp(int64 secondsPastEpoch,int32 nanoSeconds = 0)
-
A constructor that gives initial values to seconds and nanoseconds.
-
normalize
-
Adjust seconds and nanoSeconds so that - 0<=nanoSeconds<nanoSecPerSec.
-
fromTime_t
-
Set time from standard C time.
-
toTime_t
-
Convert timeStamp to standard C time.
-
getSecondsPastEpoch
-
Get the number of seconds since the epoch.
-
getEpicsSecondsPastEpoch
-
Get the number of EPICS seconds since the epoch. EPICS uses Jan 1, 1990 - 00:00:00 UTC as the epoch.
-
getNanoSeconds
-
Get the number of nanoSeconds. This is always normalized.
-
getUserTag
-
Get the userTag.
-
setUserTag
-
Set the userTag.
-
put(int64 secondsPastEpoch,int32 nanoSeconds = 0)
-
Set the timeStamp value. If necessary it will be normalized.
-
put(int64 milliseconds)
-
Set the timeStamp with a value the is the number of milliSeconds since - the epoch.
-
getCurrent()
-
Set the timeStamp to the current time.
-
toSeconds()
-
Convert the timeStamp to a value that is the number of seconds since - the epocj
-
operator =
-
operator!=
-
operator<=
-
operator<
-
operator>=
-
operator>
-
Standard C++ operators.
-
diff
-
diff = a - b
-
getMilliseconds
-
Get the number of milliseconds since the epoch.
-
- -

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);
- -

pvTimeStamp.h

-
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

-
-
PVTimeStamp
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if a timeStamp - structure is found. It looks first at pvField itself and if is not an - appropriate pvData structure but the field name is value it looks up the - parent structure tree.
-
detach
-
Detach from the pvData structure.
-
isAttached
-
Is there an attachment to a timeStamp structure?
-
get
-
Copies data from the pvData structure to a TimeStamp. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from TimeStamp to the pvData structure. An exception is - thrown if not attached to a pvData structure.
-
- -

alarm

- -

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:

-
-
alarm.h
-
Defines an alarm independent of pvData, i.e. it is a generally useful - class for manipulating alarms.
-
pvAlarm.h
-
A class that can be attached to an alarm pvData structure. It provides - get and set methods to get/set alarm data as defined by alarm.h
-
- -

alarm.h

-
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
-    String getMessage();
-    void setMessage(String const &value);
-    AlarmSeverity getSeverity() const;
-    void setSeverity(AlarmSeverity value);
-    AlarmStatus getStatus() const;
-    void setStatus(AlarmStatus value);
-};
- -

Alarm Severity defines the possible alarm severities:

-
-
getSeverity
-
Get the alarm severity corresponding to the integer value.
-
getSeverityNames
-
Get the array of severity choices.
-
- -

Alarm Status defines the possible choices for alarm status:

-
-
getStatus
-
Get the alarm status corresponding to the integer value.
-
getStatusNames
-
Get the array of status choices.
-
- -

Alarm has the methods:

-
-
Alarm
-
The constructor. It sets the severity to no alarm and the message to - "".
-
getMessage
-
Get the message.
-
setMessage
-
Set the message.
-
getSeverity
-
Get the severity.
-
setSeverity
-
Set the severity.
-
getStatus
-
Get the status.
-
setStatus
-
Set the status.
-
- -

pvAlarm.h

-
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

-
-
PVAlarm
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if it found an - appropriate pvData structure. It looks first a pvField itself and if is - not an appropriate pvData structure but the field name is value it looks - to see if the parent structure has an appropriate sub structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to an alarm structure?
-
get
-
Copies data from the pvData structure to an Alarm. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from Alarm to the pvData structure. An exception is thrown - if not attached to a pvData structure.
-
- -

control

- -

Control information is represented by the following structure

-
structure control
-    double limitLow
-    double limitHigh
-    double minStep
- -

Two header files are provided for manipulating control:

-
-
control.h
-
Defines control independent of pvData, i.e. it is a generally useful - class for manipulating control.
-
pvControl.h
-
A class that can be attached to an control pvData structure. It - provides get and set methods to get/set control data as defined by - control.h
-
- -

control.h

-
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

-
-
Control
-
The default constructure.
-
getLow
-
Get the low limit.
-
getHigh
-
Get the high limit.
-
setLow
-
Set the low limit.
-
setHigh
-
Set the high limit.
-
setMinStep
-
Set the minimum step size.
-
getMinStep
-
Get he minimum step size.
-
- -

pvControl.h

-
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

-
-
PVControl
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if it found an - appropriate pvData structure. It looks first a pvField itself and if is - not an appropriate pvData structure but the field name is value it looks - to see if the parent structure has an appropriate sub structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to a control structure?
-
get
-
Copies data from the pvData structure to a Control. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from Control to the pvData structure. An exception is - thrown if not attached to a pvData structure.
-
- -

display

- -

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:

-
-
display.h
-
Defines display independent of pvData, i.e. it is a generally useful - class for manipulating display.
-
pvDisplay.h
-
A class that can be attached to an display pvData structure. It - provides get and set methods to get/set display data as defined by - display.h
-
- -

display.h

-
class Display {
-public:
-    Display();
-    //default constructors and destructor are OK
-    double getLow() const;
-    double getHigh() const;
-    void setLow(double value);
-    void setHigh(double value);
-    String getDescription() const;
-    void setDescription(String const &value);
-    String getFormat() const;
-    void setFormat(String const &value);
-    String getUnits() const;
-    void setUnits(String const &value);
-};
- -

where

-
-
Control
-
The default constructure.
-
getLow
-
Get the low limit.
-
getHigh
-
Get the high limit.
-
setLow
-
Set the low limit.
-
setHigh
-
Set the high limit.
-
getDescription
-
Get the description.
-
setDescription
-
Set the description.
-
getFormat
-
Get the format.
-
setFormat
-
Set the format.
-
getUnits
-
Get the units.
-
setUnits
-
Set the units.
-
- -

pvDisplay.h

-
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

-
-
PVDisplay
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if it found an - appropriate pvData structure. It looks first a pvField itself and if is - not an appropriate pvData structure but the field name is value it looks - to see if the parent structure has an appropriate sub structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to a display structure?
-
get
-
Copies data from the pvData structure to a Display. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from Display to the pvData structure. An exception is - thrown if not attached to a pvData structure.
-
- -

pvEnumerated.h

- -

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();
-    String getChoice();
-    bool choicesMutable();
-    StringArrayPtr const & getChoices();
-    int32 getNumberChoices();
-    bool setChoices(StringArray &choices,int32 numberChoices);
-};
- -

where

-
-
PVEnumerated
-
The default constructor. Attach must be called before any get or set - method can be called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if pvField (is - not, is) an enumerated structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to an enemerated structure?
-
setIndex
-
Set the index field in the pvData structure. An exception is thrown if - not attached to a pvData structure.
-
getIndex
-
Get the index field in the pvData structure.
-
getChoice
-
Get the String value corresponding to the current index field in the - pvData structure. An exception is thrown if not attached to a pvData - structure.
-
choicesMutable
-
Can the choices be changed? Note that this is often true. An exception - is thrown if not attached to a pvData structure.
-
getChoices
-
Get the array of choices. An exception is thrown if not attached to a - pvData structure.
-
getNumberChoices
-
Get the number of choices. An exception is thrown if not attached to a - pvData structure.
-
setChoices
-
Change the choices. An exception is thrown if not attached to a pvData - structure.
-
- -

Examples

- -

Accessing PVData

- -

Assume that code wants to print two fields from a PVStructure:

-
-
value
-
Must be a PVDouble.
-
timeStamp
-
Just look for field with this name.
-
- -

The following code uses introspection to get the desired information.

-
void getValueAndTimeStamp(PVStructurePtr pvStructure,StringBuilder buf) {
-   PVFieldPtr valuePV = pvStructure->getSubField(String("value"));
-   if(valuePV.get()==NULL) {
-       buf += "value field not found";
-       return;
-   }
-   buf += "value ";
-   valuePV->toString(&buf);
-   PVFieldPtr timeStampPV = pvStructure->getSubField(String("timeStamp"));
-   if(timeStampPV.get()==NULL) {
-       buf += "timeStamp field not found";
-       return;
-   }
-   buf += " timeStamp ";
-   timeStampPV->toString(&buf);
-}
- -

Creating PVData

- -

Example of creating a scalar field.

-
    PVDataCreatePtr pvDataCreate = getPVDataCreate();
-    PVDoublePtr pvValue = static_pointer_cast<PVDouble>(
-        pvDataCreate->createPVScalar(pvDouble));
- -

Create a structure with a value and an alarm the hard way

-
    FieldCreatePtr fieldCreate = getFieldCreate();
-    PVDataCreatePtr pvDataCreate = getPVDataCreate();
-    FieldConstPtrArray fields;
-    StringArray names;
-    fields.resize(3);
-    names.resize(3);
-    fields[0] = fieldCreate->createScalar(pvInt);
-    fields[1] = fieldCreate->createScalar(pvInt);
-    fields[2] = fieldCreate->createScalar(pvString);
-    names[0] = "severity";
-    names[0] = "status";
-    names[0] = "message";
-    StructureConstPtr alarmField =  
-        fieldCreate->createStructure(names,fields);
-    fields.resize(2);
-    names.resize(2);
-    fields[0] = fieldCreate->createScalar(pvDouble);
-    fields[1] = alarmField;
-    names[0] = "value";
-    names[0] = "alarm";
-    StructureConstPtr structure =
-        fieldCreate->createStructure(names,fields);
-    PVStructurePtr pv = pvDataCreate->createPVStructure(structure);
- -

Create an alarm structure the easy way.

-
    StandardPVFieldPtr standardPVField = getStandardPVField();
-    PVStructurePtr pv = standardPVField->scalar(pvDouble,"alarm");
- -

Create a PVStructure with field name example that has a double value field , -timeStamp, alarm, and display. Do it the easy way.

-
    StandardPVFieldPtr standardPVField = getStandardPVField();
-    PVStructurePtr pvStructure = standardPVField->scalar(
-        pvDouble,"timeStamp,alarm.display");
- -

pvDataApp/factory

- -

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.

- -

PVAuxInfoImpl.cpp implements auxInfo.

- -

Convert.cpp automatically creates a single instance of Convert and -implements getConvert.

- -

Other files implement PVData base classes

- -

pvDataAPP/misc

- -

Overview

- -

This package provides utility code:

-
-
bitSet.h
-
An implementation of BitSet that can be serialized.
-
byteBuffer.h
-
Used to serialize objects.
-
destroyable.h
-
Provides method destroy.
-
epicsException.h
-
Exception with stack trace.
-
event.h
-
Signal and wait for an event.
-
executor.h
-
Provides a thread for executing commands.
-
lock.h
-
Support for locking and unlocking.
-
messageQueue.h
-
Support for queuing messages to give to requesters.
-
noDefaultMethods.h
-
When privately extended prevents compiler from implementing default - methods.
-
queue.h
-
A queue implementation that allows the latest queue element to continue - to be used when no free element is available.
-
requester.h
-
Allows messages to be sent to a requester.
-
serialize.h
-
Support for serializing objects.
-
serializeHelper.h
-
More support for serializing objects.
-
sharedPtr.h
-
Defines POINTER_DEFINITIONS.
-
status.h
-
A way to pass status information to a client.
-
thread.h
-
Provides thread support.
-
timeFunction.h
-
Time how long a function call requires.
-
timer.h
-
An implementation of Timer that does not require an object to be - created for each timer request.
-
- -

Note that directory testApp/misc has test code for all the classes in misc. -The test code also can be used as examples.

- -

bitSet.h

- -

This is adapted from the java.util.BitSet. bitSet.h is:

-
class BitSet : public Serializable {
-public:
-    static BitSet::shared_pointer create(uint32 nbits);
-    BitSet();
-    BitSet(uint32 nbits);
-    virtual ~BitSet();
-    void flip(uint32 bitIndex);
-    void set(uint32 bitIndex);
-    void clear(uint32 bitIndex);
-    void set(uint32 bitIndex, bool value);
-    bool get(uint32 bitIndex) const;
-    void clear();
-    int32 nextSetBit(uint32 fromIndex) const;
-    int32 nextClearBit(uint32 fromIndex) const;
-    bool isEmpty() const;
-    uint32 cardinality() const;
-    uint32 size() const;
-    BitSet& operator&=(const BitSet& set);
-    BitSet& operator|=(const BitSet& set);
-    BitSet& operator^=(const BitSet& set);
-    BitSet& operator-=(const BitSet& set);
-    BitSet& operator=(const BitSet &set);
-    void or_and(const BitSet& set1, const BitSet& set2);
-    bool operator==(const BitSet &set) const;
-    bool operator!=(const BitSet &set) const;
-    void toString(StringBuilder buffer);
-    void toString(StringBuilder buffer, int indentLevel) const;
-private:
-};
- -

where

-
-
BitSet()
-
Creates a bitSet of initial size 64 bits. All bits initially false.
-
BitSet(uint32 nbits)
-
Creates a bitSet with the initial of the specified number of bits. All - bits initially false.
-
~BitSet()
-
Destructor.
-
flip(uint32 bitIndex)
-
Flip the specified bit.
-
set(uint32 bitIndex)
-
Set the specified bit true.
-
clear(uint32 bitIndex)
-
Set the specified bit false.
-
set(uint32 bitIndex, bool value)
-
Set the specified bit to value.
-
get(uint32 bitIndex)
-
Return the state of the specified bit.
-
clear()
-
Set all bits to false.
-
nextSetBit(uint32 fromIndex)
-
Get the index of the next true bit beginning with the specified - bit.
-
nextClearBit(uint32 fromIndex)
-
Get the index of the next false bit beginning with the specified - bit.
-
isEmpty()
-
Return (false,true) if (at least one bit true, all bits are false)
-
cardinality()
-
Return the number of true bits.
-
size()
-
Returns the number of bits of space actually in use.
-
operator&=(const BitSet& set)
-
Performs a logical and of this target bit set with the argument bit - set. This bit set is modified so that each bit in it has the value true - if and only if it both initially had the value true and the corresponding - bit in the bit set argument also had the value.
-
operator|=(const BitSet& set)
-
Performs a logical or of this target bit set with the argument bit - set.
-
operator^=(const BitSet& set)
-
Performs a logical exclusive or of this target bit set with the - argument bit set.
-
operator-=(const BitSet& set)
-

Clears all of the bits in this bitSet whose corresponding bit is set - in the specified bitSet.

-
-
operator=(const BitSet &set)
-
Assignment operator.
-
or_and(const BitSet& set1, const BitSet& set2)
-
Perform AND operation on set1 and set2, and then OR this bitSet with - the result.
-
operator==(const BitSet &set)
-
Does this bitSet have the same values as the argument.
-
operator!=(const BitSet &set)
-
Is this bitSet different than the argument.
-
toString(StringBuilder buffer)
-
Show the current values of the bitSet.
-
toString(StringBuilder buffer, int indentLevel)
-
Show the current values of the bitSet.
-
virtual void serialize(ByteBuffer *buffer,SerializableControl *flusher) - const;
-
Serialize the bitSet
-
virtual void deserialize(ByteBuffer *buffer,DeserializableControl - *flusher);
-
Deserialize the bitSet.
-
- -

byteBuffer.h

- -

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();
- ...
-};
- -

destroyable.h

-
class Destroyable  {
-public:
-    POINTER_DEFINITIONS(Destroyable);
-    virtual void destroy() = 0;
-    virtual ~Destroyable() {};
-};
- -

epicsException.h

-
/*
- * 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.
- */
- -

event.h

- -

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 */
-private:
-    epicsEventId id;
-};
- -

where

-
-
Event
-
The constructor. The initial value can be full or empty. The normal - first state is empty.
-
signal
-
The event becomes full. The current or next wait will complete.
-
wait
-
Wait until event is full or until timeout. The return value is - (false,true) if the wait completed because event (was not, was) full. A - false value normally means that that a timeout occured. It is also - returned if an error occurs or because the event is being deleted.
-
tryWait
-
returns (false,true) if the event is (empty,full)
-
- -

executor.h

- -

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(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:

-
-
Executor
-
The constructor. A thread name and priority must be specified.
-
~Executor
-
The destructor. If any commands remain in the execute list they are not - called. All ExecutorNodes that have been created are deleted.
-
execute
-
Request that command be executed. If it is already on the run list - nothing is done.
-
- -

lock.h

-
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 xx(mutex);
-        if(alreadyInitialized) return;
-        // initialization
-    }
- -

messageQueue.h

- -

Definitions

- -

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:
-    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(String message,MessageType messageType,bool replaceLast);
-    bool isEmpty() ;
-    bool isFull() ;
-    int getClearOverrun();
- ...
-};
- -

A messageNode is a class with two public data members:

-
-
getMessage
-
The message.
-
getMessageType
-
The message type.
-
setMessageNull
-
Set the message to be a null string.
-
- -

A messageQueue is an interface with public methods:

-
-
MessageQueue
-
The constructor. The queue size must be specified.
-
~MessageQueue
-
The destructor.
-
put
-
Put a new message into the queue. False is returned if the queue was - full and true otherwise. If replaceLast is true then the last message is - replaced with this message.
-
get
-
Get the oldest queue element. If the queue is empty null is returned. - Before the next get can be issued release must be called.
-
release
-
Release the queue element returned by the last get.
-
isEmpty
-
Is the queue empty?
-
isFull
-
Is the queue full?
-
getClearOverrun
-
Get the number of times put has been called but no free element is - available.
-
- -

Look at miscTest/testMessageQueue.cpp for an example.

- -

noDefaultMethods.h

- -

If a class privately extends this class then the compiler can not create any -of the following: default constructor, default copy constructror, or default -assignment contructor.

-
/* This is based on Item 6 of
- * Effective C++, Third Edition, Scott Meyers
- */
-    class NoDefaultMethods {
-    protected:
-    // allow by derived objects
-    NoDefaultMethods(){};
-    ~NoDefaultMethods(){}
-    private:
-    // do not implment
-    NoDefaultMethods(const NoDefaultMethods&);
-    NoDefaultMethods & operator=(const NoDefaultMethods &);
-    };
- -

queue.h

- -

This provides a queue which has an immutable capacity. When the queue is -full the user code is expected to keep using the current element until a new -free element becomes avalable.

-
template <typename T>
-class Queue
-{   
-public:
-    POINTER_DEFINITIONS(Queue);
-    typedef std::tr1::shared_ptr<T> queueElementPtr;
-    typedef std::vector<queueElementPtr> queueElementPtrArray;
-    Queue(queueElementPtrArray &);
-    virtual ~Queue();
-    void clear();
-    int capacity();
-    int getNumberFree();
-    int getNumberUsed();
-    queueElementPtr & getFree();
-    void setUsed(queueElementPtr const &element);
-    queueElementPtr & getUsed();
-    void releaseUsed(queueElementPtr const &element);
- ...
-};
- -

testApp/misc/testQueue.cpp provides an example of how to define a queue.

- -

The queue methods are:

-
-
clear
-
Make the queue empty.
-
getNumberFree
-
Get the number of free elements in the queue.
-
capacity
-
Get the capacity, i.e. the maximun number of elements the queue can - hold.
-
getNumberFree
-
Get the number of free elements.
-
getNumberUsed
-
Get the number of elements used.
-
getFree
-
Get the next free element. Null is returned if no free elements are - available. If a non null value is returned then the element belongs to - the caller until setUsed is called.
-
setUsed
-
Set a queue element used. This must be the element returned by the last - call to getFree.
-
getUsed
-
Get the next used element of null if no more used elements are - available.
-
releaseUsed
-
Set a queue element free. This must be the element returned by the last - call to getUsed.
-
- -

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.h

- -

A PVField extends Requester. Requester is present so that when database -errors are found there is someplace to send a message.

-
enum MessageType {
-   infoMessage,warningMessage,errorMessage,fatalErrorMessage
-};
-
-extern String getMessageTypeName(MessageType messageType);
-extern const size_t messageTypeCount;
-class Requester {
-public:
-    POINTER_DEFINITIONS(Requester);
-    virtual ~Requester(){}
-    virtual String getRequesterName() = 0;
-    virtual void message(String const & message,MessageType messageType) = 0;
-};
- -

where

-
-
-
MessageType
-
Type of message.
-
messageTypeName
-
An array of strings of the message type names, i.e. - String("info"),String("warning"),String("error"),String("fatalError").
-
getRequesterName
-
Returns the requester name.
-
message
-
Gives a message to the requester.
-
- -

serialize.h

-
    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;
-    };
- -

serializeHelper.h

- -

This is a helper class for serialization, which is required for sending and -receiving pvData over the nerwork.

-
class SerializeHelper : public NoDefaultMethods {
-public:
-    static void writeSize(int s, ByteBuffer* buffer,
-        SerializableControl* flusher);
-    static int readSize(ByteBuffer* buffer,
-        DeserializableControl* control);
-    static void serializeString(const String& value,
-        ByteBuffer* buffer,SerializableControl* flusher);
-    static void serializeSubstring(const String& value, int offset,
-        int count, ByteBuffer* buffer,
-        SerializableControl* flusher);
-    static String deserializeString(ByteBuffer* buffer,
-        DeserializableControl* control);
- ...
-};
- -

where

-
-
writeSize
-
Serialize the size.
-
readSize
-
Deserialize the size.
-
serializeString
-
Serialize a String.
-
serializeSubstring
-
Serialize a substring.
-
deserializeString
-
Deserialize a string.
-
- -

sharedPtr.h

-
#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;
- -

status.h

- -

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, epics::pvData::String const & message);
-    Status(StatusType type, epics::pvData::String const & message, epics::pvData::String stackDump);
-    ~Status()
-    StatusType getType() const;
-    String getMessage() const;
-    String getStackDump() const;
-    bool isOK() const;
-    bool isSuccess() const;
-    String toString() const;
-    void toString(StringBuilder buffer, int indentLevel = 0) const;
-    void serialize(ByteBuffer *buffer, SerializableControl *flusher) const;
-    void serialize(ByteBuffer *buffer, SerializableControl *flusher) const;
-};
- -

The Status methods are:

-
-
StatusType
-
An enum for the status type.
-
getType
-
Get the statusType.
-
getMessage
-
Get a message explaining the error.
-
getStackDump
-
Get a stack dump.
-
- -

The StatusCreate methods are:

-
-
getStatusOK
-
Get a singleton that returns StatusType.OK and a null message and - stackDump.
-
createStatus
-
Create a new Status.
-
deserializeStatus
-
Use this method instead of Status.deserialize(), since this allows OK - status optimization.
-
- -

thread.h

- -

ThreadPriority

-
enum ThreadPriority {
-    lowestPriority,
-    lowerPriority,
-    lowPriority,
-    middlePriority,
-    highPriority,
-    higherPriority,
-    highestPriority
-};
- -

Thread

-
class Runnable {
-public:
-    virtual void run() = 0;
-};
-
-class Thread;
-
-class Thread : public epicsThread, private NoDefaultMethods {
-public:
-    Thread(
-        String name,
-        ThreadPriority priority,
-        Runnable *runnableReady,
-        epicsThreadStackSizeClass stkcls=epicsThreadStackSmall);
-    ~Thread();
- ...
-};
- -

Runnable must be implement by code that wants to be run via a thread. It has -one virtual method: run. Run is the code that is run as a thread. When run -compeletes it can not be restarted. If code wants to delete a thread then it -MUST arrange that the run returns before the thread can be deleted. An -exception is thrown if run remains active when delete is called.

- -

Thread has the methods:

-
-
Thread
-
The constructor. A thread name and priority must be specified. The run - methods of runnable is executed. When the run methods returns the thread - will no longer be active but the client code must still delete the - thread.
-
~Thread
-
The destructor. This is called as the result of: - 
    delete pthread;
-
-
- -

timeFunction.h

- -

TimeFunction is a facility that measures the average number of seconds a -function call requires. When timeCall is called, it calls function in a loop. -It starts with a loop of one iteration. If the total elapsed time is less then -.1 seconds it increases the number of iterrations by a factor of 10. It keeps -repeating until the elapsed time is greater than .1 seconds. It returns the -average number of seconds per call.

-
class TimeFunctionRequester;
-class TimeFunction;
-typedef std::tr1::shared_ptr<TimeFunctionRequester> TimeFunctionRequesterPtr;
-typedef std::tr1::shared_ptr<TimeFunction> TimeFunctionPtr;
-        
-class TimeFunctionRequester {
-public:              
-    POINTER_DEFINITIONS(TimeFunctionRequester);
-    virtual ~TimeFunctionRequester(){}
-    virtual void function() = 0;
-};  
-
-    
-class TimeFunction {
-public:    
-    POINTER_DEFINITIONS(TimeFunction);
-    TimeFunction(TimeFunctionRequesterPtr const & requester);
-    ~TimeFunction(); 
-    double timeCall();
- ...
-};
- -

TimeFunctionRequester must be implemented by code that wants to time how -long a function takes. It has the single method:

-
-
function
-
This is the function.
-
- -

TimeFunction has the methods:

-
-
TimeFunction
-
Constructor.
-
~TimeFunction
-
Destructor.
-
timeCall
-
Time how long it takes to execute the function. It starts by calling - the function one time. If it takes < 1 seconds to doubles the number - of times to call the function. It repeats this until it takes at least - one second to call it ntimes.
-
- -

timer.h

- -

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(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 toString(StringBuilder builder);
- ...
-};
- -

TimerCallback must be implemented by the user. It has the following methods: -

-
-
callback
-
This is called when a timer expires. This is called with no locks held. - When called a delay timer is no longer on the queue but a periodioc timer - is on a queue. Thus the callback for a delay timer can issue a new - schedule request but a periodic timer must not. Note the explaination of - TimerNode.cancel below.
-
timerStopped
-
Timer.stop was called when a timer request was queued. or if the timer - is stopped and a schedule request is made.
-
- -

In order to schedule a callback client code must allocate a TimerNode It can -be used to schedule multiple callbacks. It has the methods:

-
-
TimerNode
-
The constructor. User code must create a TimeNode in order to call a - schedule method.
-
~TimerNode
-
The destructor. This is called as a result of the client calling: - 
    delete timerNode;
-
-
cancel
-
This is called to cancel a timer request. If a callback has been - dequeued but the callback not called when cancel is called then a - callback may still happen. New schedule requests can be made after a - cancel request has been made.
-
isScheduled
-
Is the timerNode scheduled to be called.
-
- -

Timer has the methods:

-
-
Timer
-
The consttructor.
-
~Timer
-
The destructor. The queue is emptied and TimerCallback.timerStopped is - called for each element of the queue.
-
scheduleAfterDelay
-
A request to schedule a callback after a delay specified in - seconds.
-
schedulePeriodic
-
Schedule a periodic callback.
-
- -

pvDataApp/pvMisc

- -

bitSetUtil.h

- -

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:

-
-
compress
-
Compress the bits in a BitSet related to a structure.
- For each structure: -
    -
  1. If the bit for the structure is set then the bit for all subfields - of the structure are cleared.
    2. -
  2. If the bit for the structure is not set but all immediate subfields - have their bit set then the bit for the structure is set and the bits - for all subfields are cleared.
    3. -
- Note that this is a recursive algorithm. That is if every immediate - subfield has it's offset bit set then the bits for ALL fields that reside - in the structure will be cleared.
-
Channel Access can call this before sending data. It can then pass - entire structures if the structure offset bit is set.
-
-
- - diff --git a/documentation/pvDataCPP_20140501.html b/documentation/pvDataCPP_20140501.html deleted file mode 100644 index b94284f..0000000 --- a/documentation/pvDataCPP_20140501.html +++ /dev/null @@ -1,5537 +0,0 @@ - - - - - - EPICS pvDataCPP - - - - - - - - -
-

EPICS pvDataCPP

- - -

EPICS v4 Working Group, Working Draft, 01-May-2014

- -
-
Latest version:
-
pvDataCPP.html -
-
This version:
-
pvDataCPP_20140501.html -
-
Previous version:
-
pvDataCPP_20131023.html -
-
Editors:
-
Marty Kraimer, BNL
-
Michael Davidsaver, BNL
-
Matej Sekoranja, CosyLab
-
- -

This product is made available subject to acceptance of the EPICS open source -license.

-
-
- -

Abstract

- -

EPICS Version 4 provides efficient -storage, access, and communication, of memory resident structured data. -pvData is the storage compoment. -pvDataCPP is the C++ implementation of pvData. -It is one part of the set of related products in the EPICS -V4 control system programming environment:
-relatedDocumentsV4.html -

- - -

Status of this Document

- -

This is the 01-May-2014 version of the C++ implementation of pvData. -

- -

RELEASE_NOTES.md provides changes since the last release. -TODO.md describes things to do before the next release. -

- - -
-

Table of Contents

-
-
- -

Introduction

- -

pvData is one of a set of related projects. It describes and implements -data that the other projects support. Thus it is not useful by itself but -understanding pvData is required in order to understand the other projects. The -reader should also become familar with project pvAccess, which is -located via the same sourceforge site as this project.

- -

The Java and C++ implementation of pvData implement the same data model but -differ in implementation because of the differences between Java and C++.

- -

It is a good idea to read all of pvDataJava.html but read at least the -first two chapters:

-
-
Introduction
-
A brief descripton of pvData.
-
PVData Meta Language
-
A language used to describe data.
-
- -

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:

-
-
pvDataAPP/pv
-
This subdirectory contains all the public interfaces that describe pvData. - The section from Namespace and Memory Management - through Conversion discuss these interfaces. -
-
pvDataApp/property
-
This section has support for managing "standard" fields. -
-
pvDataApp/misc
-
This section has support for facilities required by implementation code.
-
copy and monitor
-
These sections provide pvData support for implementing pvAccess providers.
-
- -

Examples

-

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 just edit configure/RELEASE.local and then execute make. -

-

The examples assume that the following statements have been issued:

-
-std::string builder;
-FieldCreatePtr fieldCreate = getFieldCreate();
-PVDataCreatePtr pvDataCreate = getPVDataCreate();
-StandardFieldPtr standardField = getStandardField();
-StandardPVFieldPtr standardPVField = getStandardPVField();
-StructureConstPtr alarm = getStandardField()->alarm();
-StructureConstPtr timeStamp = getStandardField()->timeStamp();
-
-

These provide access to most of pvData:

-
-
fieldCreate
-
This creates instances of introspection objects. - It also provides fieldBuilder, which provides an easier way to create introspection objects. -
-
pvDataCreate
-
This creates instances of data objects. -
-
standardField
-
This provides support for introspection obects for standard fields, - Standard fields are alarm, timeStamp, display, enumerated structure, and value alarm. -
-
standardPVField
-
This provides support for data obects for standard fields, -
-
- - -

Introspection Examples

-

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.

-

Three ways to create a structure

-

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("secsPastEpoch");
-    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);
-    builder.clear();
-    doubleScalar->toString(&builder);
-    cout << builder << "\n\n";
-
-

Using FieldBuilder the same can be done via:

-
-    StructureConstPtr doubleScalarHard =
-    getFieldCreate()->createFieldBuilder()->
-        add("value",pvDouble) ->
-        addNestedStructure("timeStamp")->
-            setId("time_t")->
-            add("secsPastEpoch", pvLong)->
-            add("nanoseconds", pvInt)->
-            add("userTag", pvInt)->
-            endNested()->
-        createStructure();
-    builder.clear();
-    doubleScalarHard->toString(&builder);
-    cout << builder << endl;
-
-Both produce: -
-structure
-    double value
-    time_t timeStamp
-        long secsPastEpoch
-        int nanoseconds
-
-

An easy way to create a structure with a string array value field and an alarm and time stamp is -via standardField:

-
-    StructureConstPtr stringArrayEasy =
-        getStandardField()->scalarArray(pvString,"alarm,timeStamp");
-    builder.clear();
-    stringArrayEasy->toString(&builder);
-    cout << builder << endl;
-
-It produces : -
-uri:ev4:nt/2012/pwd:NTScalarArray
-    string[] value
-    alarm_t alarm
-        int severity
-        int status
-        string message
-    time_t timeStamp
-        long secondsPastEpoch
-        int nanoSeconds
-        int userTag
-
-

enumerated structure

-

An enumerated structure is a structure with two sub-fields: -index, which is an int, and choices, which is an array of string. -The following examples create a structure which has a field names value, which -is an enumerated structure and additional fields. -A hard way to create an structure with an enumerated value field and a time stamp is:

-
-    StructureConstPtr enum_t =
-    getFieldCreate()->createFieldBuilder()->
-        setId("enum_t")->
-        add("index", pvInt)->
-        addArray("choices", pvString)->
-        createStructure();
-
-    StructureConstPtr ntEnumHard =
-    getFieldCreate()->createFieldBuilder()->
-        setId("uri:ev4:nt/2012/pwd/NTEnum")->
-        add("value", enum_t)->
-        addNestedStructure("timeStamp")->
-            setId("time_t")->
-            add("secsPastEpoch", pvLong)->
-            add("nanoseconds", pvInt)->
-            add("userTag", pvInt)->
-            endNested()->
-        createStructure();
-    builder.clear();
-    ntEnumHard->toString(&builder);
-    cout << builder << endl;
-
-It produces: -
-uri:ev4:nt/2012/pwd/NTEnum
-    enum_t value
-        int index
-        string[] choices
-    time_t timeStamp
-        long secsPastEpoch
-        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");
-    builder.clear();
-    ntEnumEasy->toString(&builder);
-    cout << builder << endl;
-
-It produces: -
-uri:ev4:nt/2012/pwd:NTEnum
-    enum_t value
-        int index
-        string[] choices
-    alarm_t alarm
-        int severity
-        int status
-        string message
-    time_t timeStamp
-        long secondsPastEpoch
-        int nanoSeconds
-        int userTag
-
- -

union example

-

The following creates a union and a structure with a union value field:

- -
-    UnionConstPtr ntunion =
-    getFieldCreate()->createFieldBuilder()->
-        add("doubleValue", pvDouble)->
-        add("intValue", pvInt)->
-        add("timeStamp",timeStamp)->
-        createUnion();
-    builder.clear();
-    ntunion->toString(&builder);
-    cout << builder << endl;
-
-    StructureConstPtr unionValue = getStandardField()->regUnion(punion,"alarm,timeStamp");
-    builder.clear();
-    ntunion->toString(&builder);
-    cout << builder << endl;
-
-It produces: -
-union
-    double doubleValue
-    int intValue
-    time_t timeStamp
-        long secondsPastEpoch
-        int nanoSeconds
-        int userTag
-
-structure with value field being a union
-uri:ev4:nt/2012/pwd:NTUnion
-    union value
-        double doubleValue
-        int intValue
-        time_t timeStamp
-            long secondsPastEpoch
-            int nanoSeconds
-            int userTag
-    alarm_t alarm
-        int severity
-        int status
-        string message
-    time_t timeStamp
-        long secondsPastEpoch
-        int nanoSeconds
-        int userTag
-
-

power supply

-

The following creates a more complex structure:

-
-    StructureConstPtr powerSupply =
-    getFieldCreate()->createFieldBuilder()->
-        add("alarm_t",alarm) ->
-        add("timestamp_t",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();
-    builder.clear();
-    powerSupply->toString(&builder);
-    cout << builder << endl;
-
-It produces: -
-structure
-    alarm_t alarm_t
-        int severity
-        int status
-        string message
-    time_t timestamp_t
-        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
-
-

Data Examples

-

The examples all produce a top level structure.

-

scalar example

-
-    PVStructurePtr doubleValue = getPVDataCreate()->createPVStructure(
-        getStandardField()->scalar(pvDouble,"alarm,timeStamp"));
-    PVDoublePtr pvdouble =
-        doubleValue->getSubField<PVDouble>("value");
-    pvdouble->put(1e5);
-    cout << doubleValue->dumpValue(cout) << endl;
-
-This produces: -
-uri:ev4:nt/2012/pwd:NTScalar 
-    double value 100000
-    alarm_t alarm
-        int severity 0
-        int status 0
-        string message 
-    time_t timeStamp
-        long secondsPastEpoch 0
-        int nanoSeconds 0
-        int userTag 0
-0x607268
-
-

array example

-
-    PVStructurePtr doubleArrayValue = getPVDataCreate()->createPVStructure(
-        getStandardField()->scalarArray(pvDouble,"alarm,timeStamp"));
-    PVDoubleArrayPtr pvDoubleArray =s
-         doubleArrayValue->getSubField<PVDoubleArray>("value");
-    size_t len = 10;
-    shared_vector<double> xxx(len);
-    for(size_t i=0; i< len; ++i) xxx[i] = i;
-    shared_vector<const double> data(freeze(xxx));
-    pvDoubleArray->replace(data);
-    cout << doubleArrayValue->dumpValue(cout) << endl;
-    
-    shared_vector<const double>  getData = pvDoubleArray->view();
-    cout << "via getData";
-    for (size_t i=0; i< len; ++i) cout << " " << getData[i];
-    cout << endl;
-
-This produces: -
-uri:ev4:nt/2012/pwd:NTScalarArray 
-    double[] value [0,1,2,3,4,5,6,7,8,9]
-    alarm_t alarm
-        int severity 0
-        int status 0
-        string message 
-    time_t timeStamp
-        long secondsPastEpoch 0
-        int nanoSeconds 0
-        int userTag 0
-0x607268
-via getData 0 1 2 3 4 5 6 7 8 9
-
-

enumerated example

-
-    PVStructurePtr pvntenum = getPVDataCreate()->createPVStructure(
-         getStandardField()->enumerated("alarm,timeStamp"));
-    cout << pvntenum->dumpValue(cout) << "\n\n";
-
-This produces: -
-uri:ev4:nt/2012/pwd:NTEnum 
-    enum_t value
-        int index 0
-        string[] choices []
-    alarm_t alarm
-        int severity 0
-        int status 0
-        string message 
-    time_t timeStamp
-        long secondsPastEpoch 0
-        int nanoSeconds 0
-        int userTag 0
-0x607268
-
-

power supply example

-
-    StructureConstPtr powerSupply =
-    getFieldCreate()->createFieldBuilder()->
-        add("alarm_t",alarm) ->
-        add("timestamp_t",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 = getPVDataCreate()->createPVStructure(powerSupply);
-    cout << pvpowerSupply->dumpValue(cout) << endl;
-
-This produces: -
-structure 
-    alarm_t alarm_t
-        int severity 0
-        int status 0
-        string message 
-    time_t timestamp_t
-        long secondsPastEpoch 0
-        int nanoSeconds 0
-        int userTag 0
-    structure power
-        double value 0
-        alarm_t alarm
-            int severity 0
-            int status 0
-            string message 
-    structure voltage
-        double value 0
-        alarm_t alarm
-            int severity 0
-            int status 0
-            string message 
-    structure current
-        double value 0
-        alarm_t alarm
-            int severity 0
-            int status 0
-            string message 
-0x607268
-
-

union example

-
-    PVStructurePtr pvStructure = pvDataCreate->createPVStructure(
-        standardField->regUnion(
-            getFieldCreate()->createFieldBuilder()->
-                add("doubleValue", pvDouble)->
-                add("intValue", pvInt)->
-                add("timeStamp",timeStamp)->
-                createUnion(),
-            "alarm,timeStamp"));
-    PVStructurePtr pvTimeStamp =
-        pvStructure->getSubField<PVUnion>("value")->select<PVStructure>(2);
-    pvTimeStamp->getSubField<PVLong>("secondsPastEpoch")->put(1000);
-    cout << pvStructure->dumpValue(cout) << "\n";
-    pvStructure->getSubField<PVUnion>("value")->select<PVDouble>(0)->put(1e5);
-    cout << pvStructure->dumpValue(cout) << "\n\n";
-
-This produces: -
-uri:ev4:nt/2012/pwd:NTUnion
-    union value
-        time_t
-            long secondsPastEpoch 1000
-            int nanoSeconds 0
-            int userTag 0
-    alarm_t alarm
-        int severity 0
-        int status 0
-        string message
-    time_t timeStamp
-        long secondsPastEpoch 0
-        int nanoSeconds 0
-        int userTag 0
-0x60a2c8
-uri:ev4:nt/2012/pwd:NTUnion
-    union value
-        double  100000
-    alarm_t alarm
-        int severity 0
-        int status 0
-        string message
-    time_t timeStamp
-        long secondsPastEpoch 0
-        int nanoSeconds 0
-        int userTag 0
-0x60a2c8
-
- -

varient union example

-
-    PVStructurePtr pvStructure = pvDataCreate->createPVStructure(
-        standardField->variantUnion("alarm,timeStamp"));
-    PVStructurePtr pvTimeStamp =
-        pvDataCreate->createPVStructure(standardField->timeStamp());
-    pvStructure->getSubField<PVUnion>("value")->set(pvTimeStamp);
-    pvTimeStamp->getSubField<PVLong>("secondsPastEpoch")->put(1000);
-    cout << pvStructure->dumpValue(cout) << "\n";
-    pvStructure->getSubField<PVUnion>("value")->set(
-        pvDataCreate->createPVScalar(pvDouble));
-    PVDoublePtr pvValue = static_pointer_cast<PVDouble>(
-        pvStructure->getSubField<PVUnion>("value")->get());
-    pvValue->put(1e5);
-    cout << pvStructure->dumpValue(cout) << "\n\n";
-
-This produces: -
-uri:ev4:nt/2012/pwd:NTUnion
-    any value
-        time_t
-            long secondsPastEpoch 1000
-            int nanoSeconds 0
-            int userTag 0
-    alarm_t alarm
-        int severity 0
-        int status 0
-        string message
-    time_t timeStamp
-        long secondsPastEpoch 0
-        int nanoSeconds 0
-        int userTag 0
-0x60a2c8
-uri:ev4:nt/2012/pwd:NTUnion
-    any value
-        double  100000
-    alarm_t alarm
-        int severity 0
-        int status 0
-        string message
-    time_t timeStamp
-        long secondsPastEpoch 0
-        int nanoSeconds 0
-        int userTag 0
-0x60a2c8
-
- -

big union example

-
-    PVStructurePtr pvStructure = pvDataCreate->createPVStructure(
-        standardField->regUnion(
-            getFieldCreate()->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"));
-    builder.clear();
-    pvStructure->getStructure()->toString(&builder);
-    cout << "introspection\n";
-    cout << builder << endl;
-    cout << "data\n";
-    cout << pvStructure->dumpValue(cout) << "\n";
-    PVUnionPtr pvUnion = pvStructure->getSubField<PVUnion>("value");;
-    pvUnion->select("doubleValue");
-    PVDoublePtr pvDouble = pvUnion->get<PVDouble>();
-    pvDouble->put(1.55);
-    cout << "select valueDouble\n";
-    cout << pvStructure->dumpValue(cout) << "\n";
-    cout << "value = " << pvDouble->get() << "\n";
-    pvUnion->select("structValue");
-    pvDouble = pvUnion->get<PVStructure>()->getSubField<PVDouble>("doubleValue");
-    pvDouble->put(1.65);
-    cout << "select structValue\n";
-    cout << pvStructure->dumpValue(cout) << "\n";
-    cout << "value = " << pvDouble->get() << "\n";
-
-This produces: -
-introspection
-uri:ev4:nt/2012/pwd:NTUnion
-    union value
-        double doubleValue
-        double[] doubleArrayValue
-        union unionValue
-            double doubleValue
-            alarm_t alarm
-                int severity
-                int status
-                string message
-        structure structValue
-            double doubleValue
-            double[] doubleArrayValue
-        union[] unionArrayValue
-            union[]
-                union
-                    double doubleValue
-                    alarm_t alarm
-                        int severity
-                        int status
-                        string message
-        structure[] structArrayValue
-            structure[]
-                structure
-                    double doubleValue
-                    double[] doubleArrayValue
-    alarm_t alarm
-        int severity
-        int status
-        string message
-    time_t timeStamp
-        long secondsPastEpoch
-        int nanoSeconds
-        int userTag
-data
-uri:ev4:nt/2012/pwd:NTUnion
-    union value
-        (none)
-    alarm_t alarm
-        int severity 0
-        int status 0
-        string message
-    time_t timeStamp
-        long secondsPastEpoch 0
-        int nanoSeconds 0
-        int userTag 0
-0x60a2c8
-select valueDouble
-uri:ev4:nt/2012/pwd:NTUnion
-    union value
-        double  1.55
-    alarm_t alarm
-        int severity 0
-        int status 0
-        string message
-    time_t timeStamp
-        long secondsPastEpoch 0
-        int nanoSeconds 0
-        int userTag 0
-0x60a2c8
-value = 1.55
-select structValue
-uri:ev4:nt/2012/pwd:NTUnion
-    union value
-        structure
-            double doubleValue 1.65
-            double[] doubleArrayValue []
-    alarm_t alarm
-        int severity 0
-        int status 0
-        string message
-    time_t timeStamp
-        long secondsPastEpoch 0
-        int nanoSeconds 0
-        int userTag 0
-0x60a2c8
-value = 1.65
-
- -

Namespace and Memory Management

- -

Namespace

- -

All code in project pvDataCPP appears in namespace:

-
namespace epics { namespace pvData {
-     // ...
-}}
- -

Memory Managemment

- -

Many pvDataCPP introspection and data objects are designed to be shared. They are -made availiable via std::tr1::shared_ptr. -The following naming convention is used -in typedefs:

-
-
Ptr
-
When Ptr appears it stands for std::tr1::shared_ptr. -
-
-

For example:

-
-typedef PVScalarValue<boolean> PVBoolean;
-typedef std::tr1::shared_ptr<PVBoolean> PVBooleanPtr;
-
- -

pvDataApp/pv

- -

Directory pvDataApp/pv has header files that completely describe pvData. -The implementation is provided in directory pvDataApp/factory. -Test programs appears in testApp/pv.

- -

NOTES:

-
-
interface
-
The documention uses the word interface. - This is an analogy with how Java defines interface. - C++ does not have interfaces but directory pv defines classes - with public members that are similar to the Java interfaces. Most of the - implementation is in factory.
-
Naming Convertions
-
The naming convertions for variables, methods, and classes follow the - Java convertions, i. e. class name begin with an upper case letter, - variables and methods begin with a lower case letter.
-
- -

A PVStructure is a field that contains an array of subfields. Each field has -code for accessing the field. The interface for each field is an interface that -extends PVField. Each field also has an introspection interface, which an -extension of Field. The next few sections describes the complete set of C++ -introspection and data interfaces for pvData.

- -

Class FieldCreate creates introspection objects. Class PVDataCreate creates -data objects. Class Convert provides a rich set of methods for converting and -copying data between fields.

- -

Directory pvDataApp/pv has the following header files:

-
-
pvType.h
-
C++ definitions for primitive types.
-
pvIntrospect.h
-
A complete description of the introspection interfaces.
-
pvData.h
-
A complete description of the data interfaces.
-
convert.h
-
A facility that converts between data fields.
-
pvSubArrayCopy.h
-
This provides a facility that performs array coping between - arrays that have the same type.
-
standardField.h
-
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.
-
printer.h
-
TBD This is not documented. - In addition toString and dumpValue should be reviewed. -
-
- -

pvType.h

- -

This provides C/C++ definitions for the pvData primitive types: boolean, -byte, short, int, long, ubyte,ushort, uint,u long,float, double, and string. -Because pvData is network data, the C++ implementation must implement the -proper semantics for the primitive types.

- -

pvType.h provides the proper semantics.

- -

It includes the definitions:

-
-typedef /*lots of stuff*/ boolean
-
-typedef int8_t   int8;
-typedef int16_t  int16;
-typedef int32_t  int32;
-typedef int64_t  int64;
-typedef uint8_t   uint8;
-typedef uint16_t  uint16;
-typedef uint32_t uint32;
-typedef uint64_t uint64;
-// float and double are types
-typedef std::string std::string;
-
-typedef std::vector StringArray;
-typedef std::tr1::shared_ptr 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::iterator StringArray_iterator;
-typedef std::vector::const_iterator StringArray_const_iterator;
-
-typedef std::string * StringBuilder;
-
- -

where

-
-
boolean
-
A c++ bool has the semantics required for boolean. Only the name is - different. C++ code can use either bool or boolean.
-
int8,...,uint64
-
Integers present a problem because short, int, and long are C++ - reserved words but do not have a well defined number of bits. Thus for - C++ the definitions above are used in C++ code. The above definitions - have worked on all C++ implementations tested at present. If they break - in a future implementation they should be changes via "#ifdef" - preprocessor statements.
-
std::string
-
pvData requires that a string be an immutable string that is transfered - over the network as a UTF8 encoded string. Since std::string implements - copy on write semantics, it can be used for support for immutable - strings. It can also be serialized/deserialized as a UTF8 encoded string. - Because it is not a C++ primitive the first letter is capitalized. This - is the same convention the Java implementation uses. - Note that string is treated like a primitive type.
-
StringArray definitions
-
typedefs are provided for an array of std::strings, - which is a std::vector<std::string>. - This is used by introspection. -
-
StringBuilder
-
This is used to implement semantics similar to the Java toString - method. It is being replaced by the C++ stream semantics.
-
-

TBD -

-
boolean
-
Question for Michael. Why isn't the definition of boolean just - 
-typedef uint8_t boolean;
-
-
StringBuilder
-
Should this go away? - Note that it is used for both introspection and data. -
-
printer.h
-
Not documented. - How should printer, toString, and dumpValue be related? - Also limit number of elements to show if array is large. -
-
-

- -

pvIntrospect.h

- -

This subsection describes pvIntrospect.h This file is quite big so rather -than showing the entire file, it will be described in parts.

- -

The primary purpose for pvData is to support network access to structured data. -pvAccess transports top level pvStructures. In addition a pvAccess server holds -a set of pvnames, where each name is a unique name in the local network. -This is also refered to as the channel name. -

- -

Given a pvname , it is possible to introspect the types of the associated data -access to data. The reflection and data interfaces are separate because the -data may not be available. For example when a pvAccess client connects to a pvname, -the client library can obtain the reflection information without obtaining any -data. Only when a client issues an I/O request will data be available. This -separation is especially important for arrays and structures so that a client -can discover the type without requiring that a large data array or structure be -transported over the network.

- -

Type Description

- -

Types are defined as:

-
enum Type {
-    scalar,
-    scalarArray,
-    structure,
-    structureArray,
-    union_,
-    unionArray
-};
-
-class TypeFunc {
-public:
-    const char* name(Type);
-    static void toString(StringBuilder buf,const 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);
-    void toString(StringBuilder buf,ScalarType scalarType);
-    size_t elementSize(ScalarType id);
-};
- -

Type is one of the following:

-
-
scalar
-
A scalar of one of the scalar types.
-
scalarArray
-
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 types can be different.
-
structureArray
-
An array where each element is a structure. Each element has the same - structure introspection interface.
-
union_t
-
This is like a structure that has a single subfield. - The type for the subfield can either be any type, which is called a varient union, - of can be one od a specified set of types. - In the data interfaces the type can be changed dynamically. -'
-
unionArray
-
An array where each element is a union. Each element has the same - union introspection interface.
-
- -

ScalarType is one of the following:

-
-
pvBoolean
-
Has the value false or true.
-
pvByte
-
A signed 8 bit integer.
-
pvShort
-
A signed 16 bit integer.
-
pvInt
-
A signed 32 bit integer.
-
pvLong
-
A signed 64 bit integer.
-
pvUByte
-
An unsigned 8 bit integer.
-
pvUShort
-
An unsigned 16 bit integer.
-
pvUInt
-
An unsigned 32 bit integer.
-
pvULong
-
An unsigned 64 bit integer.
-
pvFloat
-
A IEEE float.
-
pvDouble
-
A IEEE double,
-
pvString
-
An immutable string.
-
- -

TypeFunction is a set of convenience methods for Type

-
-
name
-
Returns the name of the type.
-
toString
-
Convert the type to a string.
-
- -

ScalarTypeFunction is a set of convenience methods for ScalarType

-
-
isInteger
-
Is the scalarType an integer type, i.e. one of pvByte,...pvULong.
-
isUInteger
-
Is the scalarType an unsigned integer type, i.e. one of - pvUByte,...pvULong
-
isNumeric
-
Is the scalarType numeric, i.e. pvByte,...,pvDouble.
-
isPrimitive
-
Is the scalarType primitive, i.e. not pvString
-
name
-
Returns the name of the scalarType.
-
getScalarType
-
Given a string of the form std::string("boolean"),...,std::string("string") - return the scalarType.
-
toString
-
Convert the scalar type to a string.
-
elementSize
-
Returns the size in bytes of an instance of the scalarType.
-
- -

Introspection Description

- -

This section describes the reflection interfaces which provide the -following:

-
-
Field
-
A field: -
    -
  • Has a Type.
    • -
  • Can be converted to a string.
    • -
  • Can be shared. A reference count is kept. When it becomes 0 the - instance is automatically deleted.
    • -
-
-
Scalar
-
A scalar has a scalarType
-
ScalarArray
-
The element type is a scalarType
-
Structure
-
Has fields that can be any of the supported types.
-
StructureArray
-
The field holds an array of structures. Each element has the same - Structure interspection interface. A pvAccess client can only get/put - entire PVStructure elements NOT subfields of array elements.
-
Union
-
- This has two flavors: a varient union or a union of a fixed set - of types. A PVUnion will have a single subfield. - If the union introspection interface is a varient union then - the single field can be of any type and has the name any. - If the union is not a varient type then the type can be one of - a fixed set of types and a name associated with the type. - The union introspection interface has a field array and a string - array that has the fixed set of types and associated names. -
-
UnionArray
-
- This is an array of unions. A PVUnionArray is an array - of PVUnions. Each element has the same interspection interface - but the subfield of each element can have a different type. -
-
FieldBuilder
-
This is a convenience interface that makes it easier to create - top introspection interfaces. -
-
FieldCreate
-
This is an interface that provides methods to create introspection - interfaces. A factory is provides to create FieldCreate.
-
getFieldCreate
-
Gets a pointer to the single instance of FieldCreate.
-
-

Field,Scalar,ScalarArray,Structure,StructureArray,Union,UnionArray

-
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 void toString(StringBuilder buf) const{toString(buf,0);}
-    virtual void toString(StringBuilder buf,int indentLevel) const;
- ...
-};
-
-class Scalar : public Field{
-public:
-    POINTER_DEFINITIONS(Scalar);
-    virtual ~Scalar();
-    typedef Scalar& reference;
-    typedef const Scalar& const_reference;
-
-    ScalarType getScalarType() const {return scalarType;}
-    virtual void toString(StringBuilder buf) const{toString(buf,0);}
-    virtual void toString(StringBuilder buf,int indentLevel) const;
-    virtual std::string getID() const;
-    virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
-    virtual void deserialize(ByteBuffer *buffer, DeserializableContol *control);
- ...
-};
-
-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 void toString(StringBuilder buf) const{toString(buf,0);}
-    virtual void toString(StringBuilder buf,int indentLevel) const;
-    virtual std::string getID() const;
-    virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
-    virtual void deserialize(ByteBuffer *buffer, DeserializableControl *control);
- ...
-};
-
-class StructureArray : public Field{
-public:
-    POINTER_DEFINITIONS(StructureArray);
-    typedef StructureArray& reference;
-    typedef const StructureArray& const_reference;
-
-    StructureConstPtr  getStructure() const {return pstructure;}
-    virtual void toString(StringBuilder buf,int indentLevel=0) const;
-    virtual std::string getID() 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 void toString(StringBuilder buf,int indentLevel) const;
-   virtual std::string getID() 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 void toString(StringBuilder buf) const;
-    virtual void toString(StringBuilder buf,int indentLevel) const;
-    virtual std::string getID() 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 void toString(StringBuilder buf,int indentLevel=0) const;
-    
-    virtual std::string getID() const;
-
-    virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
-    virtual void deserialize(ByteBuffer *buffer, DeserializableControl *control);
-};
-
-
-
Constructors
-
Note that all constructors are protected or private. The only way to - create instances is via fieldBuilder or fieldCreate. The implementation manages all - storage via shared pointers.
-
toString
-
Many classes provide this (actually two methods). This method is called - to get a string that uses the metadata syntax described in a previous - section.
-
- -

Field

-
-
getType
-
Get the field type.
-
getID
-
Get an ID for this introspection interface
-
- -

Scalar

-
-
getScalarType
-
Get that scalar type.
-
getID
-
For each scalarType there is one instance of Scalar. The ID for each is - the metadata name for the type, i. e. one of "boolean" , ... , "string". -
-
- -

ScalarArray

-
-
getElementType
-
Get the element type.
-
getID
-
For each elemnetType there is one instance of ScalarArray. The ID for - each is the metadata name for the type, i. e. one of "boolean[]" , ... , - "string[]".
-
- -

StructureArray

-
-
getStructure
-
Get the introspection interface that each element shares,
-
getID
-
This returns the ID[] where ID is the value returned by - structure->getID().
-
- -

Structure

-
-
getNumberFields
-
Get the number of immediate subfields.
-
getField
-
Given a name or an index get the introspection interface for the - field.
-
getFieldIndex
-
Given a name get the index, within the array returned by the next - method, of the field.
-
getFields
-
Get the array of introspection interfaces for the field,
-
getFieldNames
-
Get the array of field names for the subfields.
-
getFieldName
-
Get the field name for the specified index.
-
-

Union

-
-
getNumberFields
-
Get the number of possible field types. - Both getFields and getFieldNames will return an array with getNumberFields elements. - A value of 0 is returned for invarient arrays. -
-
getField
-
Given a name ot an index the type is returned. - NULL is returned if not found. -
-
getFieldIndex
-
Get the index for name. -1 is returned if not found. -
getFields
-
Get the array of types.
-
getFieldNames
-
Get the array of names.
-
getFieldName
-
Get the name for the specified index.
-
isVariant
-
returns true if this is varient array and false otherwise. -
-

UnionArray

-
-
getUnion
-
Get the union interface for each element.
-
-

fieldBuilder and createField

-
-class epicsShareClass FieldBuilder :
-    public std::tr1::enable_shared_from_this<FieldBuilder>
-{
-public:
-    FieldBuilderPtr setId(std::string const & id);
-    FieldBuilderPtr add(std::string const & name, ScalarType scalarType);
-    FieldBuilderPtr add(std::string const & name, FieldConstPtr const & field);
-    FieldBuilderPtr addArray(std::string const & name, ScalarType scalarType);
-    FieldBuilderPtr addArray(std::string const & name, FieldConstPtr const & element);
-    StructureConstPtr createStructure();
-    UnionConstPtr createUnion();
-    FieldBuilderPtr addNestedStructure(std::string const & name); 
-    FieldBuilderPtr addNestedUnion(std::string const & name);
-    FieldBuilderPtr addNestedStructureArray(std::string const & name); 
-    FieldBuilderPtr addNestedUnionArray(std::string const & name);
-    FieldBuilderPtr endNested();
-};
-
-class epicsShareClass FieldCreate {
-public:
-    static FieldCreatePtr getFieldCreate();
-    FieldBuilderPtr createFieldBuilder() const;
-    ScalarConstPtr createScalar(ScalarType scalarType) const;
-    ScalarArrayConstPtr createScalarArray(ScalarType elementType) const;
-    StructureArrayConstPtr createStructureArray(StructureConstPtr const & structure) const;
-    StructureConstPtr createStructure () const;
-    StructureConstPtr createStructure (
-        StringArray const & fieldNames,
-        FieldConstPtrArray const & fields) const;
-    StructureConstPtr createStructure (
-    	std::string const & id,
-        StringArray const & fieldNames,
-        FieldConstPtrArray const & fields) const;
-    UnionConstPtr createUnion (
-        StringArray const & fieldNames,
-        FieldConstPtrArray const & fields) const;
-    UnionConstPtr createUnion (
-    	std::string const & id,
-        StringArray const & fieldNames,
-        FieldConstPtrArray const & fields) const;
-    UnionConstPtr createVariantUnion() const;
-    UnionArrayConstPtr createVariantUnionArray() const;
-    UnionArrayConstPtr createUnionArray(UnionConstPtr const & punion) const;
-    StructureConstPtr appendField(
-        StructureConstPtr const & structure,
-        std::string const & fieldName, FieldConstPtr const & field) const;
-    StructureConstPtr appendFields(
-        StructureConstPtr const & structure,
-        StringArray const & fieldNames,
-        FieldConstPtrArray const & fields) const;
-    FieldConstPtr deserialize(ByteBuffer* buffer, DeserializableControl* control) const;
-        
-};
-
-epicsShareExtern FieldCreatePtr getFieldCreate();
-
- -

FieldBuilder

-

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. -

-
-
setID
-
This sets an ID for the field, which is the name for the field when it is a subfield. -
-
add
-
- Add a scalar field. -
-
addArray
-
- Add a scalarArray field. -
-
createStructure
-
- Create a structure from the fields that are currently present. -
-
createUnion
-
- Create a union from the fields that are currently present. -
-
addNestedStructure
-
- Add a nested structure. This is followed by an arbitrary number of adds - followed by a an endNested. -
-
addNestedUnion
-
- Add a nested union. This is followed by an arbitrary number of adds - followed by a an endNested. -
-
addNestedStructureArray
-
- Add a nested structure array. This is followed by an arbitrary number of adds - followed by a an endNested. -
-
addNestedUnionArray
-
- Add a nested union array. This is followed by an arbitrary number of adds - followed by a an endNested. -
-
endNested
-
- End current nested structure or union. -
-
-

A simple example is:

-
-StructureConstPtr structure =
-      getFieldCreate()->createFieldBuilder()->
-      setId("enum_t")->
-      add("index", pvDouble)->
-      addArray("choices", pvString)->
-      createStructure();
-std::string builder;
-structure->toString(&builder);
-cout << builder << endl;
-
-This produces: -
-enum_t
-    double index
-    string[] choices
-
-

Another example is:

-
-StructureConstPtr enum_t =
-getFieldCreate()->createFieldBuilder()->
-    setId("enum_t")->
-    add("index", pvInt)->
-    addArray("choices", pvString)->
-    createStructure();
-
-StructureConstPtr ntEnum =
-getFieldCreate()->createFieldBuilder()->
-    setId("uri:ev4:nt/2012/pwd/NTEnum")->
-    add("value", enum_t)->
-    addNestedStructure("timeStamp")->
-        setId("time_t")->
-        add("secsPastEpoch", pvLong)->
-        add("nanoseconds", pvInt)->
-        add("userTag", pvInt)->
-        endNested()->
-    createStructure();
-builder.clear();
-ntEnum->toString(&builder);
-cout << builder << endl;
-
-This produces: -
-uri:ev4:nt/2012/pwd/NTEnum
-    enum_t value
-        int index
-        string[] choices
-    time_t timeStamp
-        long secsPastEpoch
-        int nanoseconds
-        int userTag
-
-

The following example:

-
-    UnionConstPtr ntunion =
-    getFieldCreate()->createFieldBuilder()->
-        add("doubleValue", pvDouble)->
-        add("intValue", pvInt)->
-        addNestedStructure("timeStamp")->
-            setId("time_t")->
-            add("secsPastEpoch", pvLong)->
-            add("nanoseconds", pvInt)->
-            add("userTag", pvInt)->
-            endNested()->
-        createUnion();
-    builder.clear();
-    ntunion->toString(&builder);
-    cout << builder << endl;
-
-produces: -
-union
-    double doubleValue
-    int intValue
-    time_t timeStamp
-        long secsPastEpoch
-        int nanoseconds
-        int userTag
-
-

A powerSupply structure can be created as follows:

-
-StructureConstPtr alarm = getStandardField()->alarm();
-StructureConstPtr timeStamp = getStandardField()->timeStamp();
-
-StructureConstPtr powerSupply =
-getFieldCreate()->createFieldBuilder()->
-    add("alarm_t",alarm) ->
-    add("timestamp_t",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();
-builder.clear();
-powerSupply->toString(&builder);
-cout << builder << endl;
-
-produces: -
-structure
-    alarm_t alarm_t
-        int severity
-        int status
-        string message
-    time_t timestamp_t
-        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
-
-

FieldCreate

-
-
getFieldCreate
-
Get the single instance of FieldCreate.
-
createFieldBuilder
-
Create an instance of a FieldBuilder.
-
createScalar
-
Create a scalar introspection instance.
-
createScalarArray
-
Create a scalar array introspection instance.
-
createStructure
-
Create a structure introspection instance. Three methods are provided. - The first creates an empty structure, i. e. a structure with no fields. - The other two are similar. - The only difference is that one provides an ID and the other does - not. The one without will result in ID structure.
-
createUnion
-
Create a union. There are two methods. - Each has arguments for an array of types and an array of names. - One method has an id. The other results in id = union. -
-
createVariantUnion
-
- Create a varient union. The id will be any. -
-
createUnionArray
-
Create a union array. punion is the introspection interface - for each element.
-
createVariantUnionArray
-
Create a union array where each element is a varient union.
-
createStructureArray
-
Create a structure array introspection instance.
-
appendField
-
Create a new structure that is like an existing structure but has - an extra field appended to it. -
-
appendFields
-
Create a new structure that is like an existing structure but has - extra fields appended to it. -
-
deserialize
-
Deserialize from given byte buffer.
-
-

TBD -

-
toString
-
Should support for steams exist.
-
ScalarTypeTraits and ScalarTypeID
-
These seem to only be used by shared_vector. Do they need to be documented?
-
-

- -

standardField.h

- -

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();
- ...
-};
-
-
scalar
-
Create a scalar with the specified scalar type and name. A structure - will be created with the first element being a scalar with the specified - scalar type and name value. The other fields in the structure will be the - corresponding property structures.
-
regUnion
-
A structure - will be created with the first element being a union with the specified - scalar type and name value. The other fields in the structure will be the - corresponding property structures.
-
varient`Union
-
Create a varient union. A structure - will be created with the first element being a union with the specified - scalar type and name value. The other fields in the structure will be the - corresponding property structures.
-
scalarArray
-
Create a scalarArray with each element having the specified scalar type - and name. A structure will be created with the first element being a - scalarArray with name value. The other fields in the structure will be - the corresponding property structures.
-
structureArray
-
Create a structureArray with the specified structure interface and - name. A structure will be created with the first element being a - structureArray with the specified structure interface and name value. The - other fields in the structure will be the corresponding property - structures.
-
unionArray
-
Create a unionArray with the specified union interface and - name. A structure will be created with the first element being a - unionArray with the specified structure interface and name value. The - other fields in the structure will be the corresponding property - structures.
-
structure
-
Create a structure with the specified name and fields specified by - numFields and fields. A structure will be created with the first element - being a structure with the name value and fields specified by numFields - and fields. The other fields in the structure will be the corresponding - property structures.
-
enumerated
-
Create a structure with the specified name and fields for an enumerated - structure. If properties are specified then a structure will be created - with the first element being a structure with the name value and fields - for an enumerated structure. The other fields in the structure will be - the corresponding property structures.
-
alarm
-
timeStamp
-
display
-
control
-
booleanAlarm
-
byteAlarm
-
shortAlarm
-
intAlarm
-
longAlarm
-
floatAlarm
-
doubleAlarm
-
enumeratedAlarm
-
The above provide introspection interfaces for standard properties. See - the section on Properties for a description of how these are defined.
-
-

pvData.h

- -

This section describes pvData.h This file is quite big so rather than -showing the entire file, it will be described in parts.

- -

typedefs

- -

These are typedefs for Array and Ptr for the various pvData class -definitions, i.e. typdefs for "std::vector" and "std::tr1::shared_ptr".

-
-class PVField;
-class PVScalar;
-class PVScalarArray;
-class PVStructure;
-class PVStructureArray;
-
-
-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

- -

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);
-   virtual void toString(StringBuilder buf) ;
-   virtual void toString(StringBuilder buf,int indentLevel);
-   std::ostream& dumpValue(std::ostream& o) const;
- ...
-}
-std::ostream& operator<<(std::ostream& o, const PVField& f);
-
- -

The public methods for PVField are:

-
-
~PVField
-
Destructor. Since shared pointers are used it should never be called by - user code.
-
getFieldName
-
Get the field name. If the field is a top level structure the field - name will be an empty string.
-
getFullName
-
Fully expand the name of this field using the - names of its parent fields with a dot '.' seperating - each name. -
-
getFieldOffset
-
Get offset of the PVField field within top level structure. Every field - within the PVStructure has a unique offset. The top level structure has - an offset of 0. The first field within the structure has offset equal to - 1. The other offsets are determined by recursively traversing each - structure of the tree.
-
getNextFieldOffset
-
Get the next offset. If the field is a scalar or array field then this - is just offset + 1. If the field is a structure it is the offset of the - next field after this structure. Thus (nextOffset - offset) is always - equal to the total number of fields within the field.
-
getNumberFields
-
Get the total number of fields in this field. This is nextFieldOffset - - fieldOffset.
-
isImmutable
-
Is the field immutable?
-
setImmutable
-
Make the field immutable. Once a field is immutable it can never be - changed since there is no method to again make it mutable. This is an - important design decision since it allows immutable array fields to share - the internal primitive data array.
-
getField
-
Get the reflection interface for the data.
-
getParent
-
Get the interface for the parent or null if this is the top level - PVStructure.
-
postPut
-
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. - PostHandler is a class that must be implemented by any code that calls setPostHandler. - It's single virtual method. postPut is called whenever PVField::postPut is called. -
-
equals
-
Compare this field with another field. The result will be true only if - the fields have exactly the same field types and if the data values are - equal.
-
toString
-
Converts the field data to a string. This is mostly for debugging - purposes.
-
dumpValue
-
Method for streams I/O.
-
-

TBD - -

-
toString and dumpValue
-
toString is broken
- Should toString go away or be changed? -
-
-

- -

PVScalar

- -

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

-
-
getScalar
-
Get the introspection interface for the PVScalar.
-
getAs
-
Convert and return the scalar value in the requested type. - Result type is determined from the function template argument - which must be one of the ScalarType enums. - For example: -
-uint32 val = pv->getAs();
-
-
- -
- -

PVScalarValue

- -

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

-
-
get
-
Get the value stored in the object.
-
put
-
Change the value stored in the object.
-
dumpValue
-
ostream method.
-
operator>>=
-
get operator. For example: -
-double value;
-PVDoublePtr pvDouble;
-...
-pvDouble>>=value;
-
-
-
operator<<=
-
put operator. For example: -
-double value;
-PVDoublePtr pvDouble;
-...
-pvDouble<<=value;
-
-
-
getAs
-
Convert and return the scalar value in the requested type. - Result type is determined from the function template argument - which must be one of the ScalarType enums. - For example: -
-int32 val = pv->getAs<pvInt>>();
-
-
-
putFrom
-
Convert the scalar value in the requested type - and put the value into this PVScalarValue. - The source type is determined from the function template argument - which must be one of the ScalarType enums. - For example: -
-int32 val;
-pv->putFrom<pvInt>(val);
-
-
-
-

TBD -

-
dumpvalue
-
replace this with ostream operator<<
-
-

- -

PVUnion

-

A PVUnion has a single subfield. -The Union introspection interface determines the possible -field types for the subfield. -If it is a varient union then any type is allowed and the -subfield name is normally any. -If it is not a varient union that the Union interface determines -the possible field types and names.

-
-class PVUnion : public PVField
-{
-public:
-    POINTER_DEFINITIONS(PVUnion);
-    virtual ~PVUnion();
-    UnionConstPtr getUnion() const;
-    PVFieldPtr get() const;
-    
-    template<typename PVT>
-    std::tr1::shared_ptr<PVT> get() const {
-        return std::tr1::dynamic_pointer_cast<PVT>(get());
-    }
-
-   PVFieldPtr select(int32 index);
-
-    template<typename PVT>
-    std::tr1::shared_ptr<PVT> select(int32 index) {
-        return std::tr1::dynamic_pointer_cast<PVT>(select(index));
-    }
-
-    PVFieldPtr select(std::string const & fieldName);
-
-    template<typename PVT>
-    std::tr1::shared_ptr<PVT> select(std::string const & fieldName) {
-        return std::tr1::dynamic_pointer_cast<PVT>(select(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);
-};
-
-
-
getUnion
-
Get the introspection interface.
-
get
-
Get the curent field. A template version does the conversion. - NULL is returned if no field is selected or if the caller -' asks for the wrong type. -
-
select
-
Select and get the field by index or name. - A templated version does the conversion. - If the index is out of bounds or the name is not valid this methods throws an exception. - The method set should be used for variant unions rather than select. -
-
getSelectedIndex
-
Get the index of the currently selected field.
-
getSelectedFieldName
-
Get the name of the currently selected field.
-
set
-
Set the field to the argument. If invalid type an exception is thrown. - This should always work for a variant union. -
-
- -

PVArray

- -

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 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;
- ...
-};
-
-
setImmutable
-
Set the data immutable. Note that this is permanent since there is no - methods to make it mutable.
-
getLength
-
Get the current length. This is less than or equal to the capacity.
-
setLength
-
Set the length. If the PVField is not mutable then an exception is - thrown. If this is greater than the capacity setCapacity is called.
-
getCapacity
-
Get the capacity, i.e. this is the size of the underlying data - array.
-
setCapacity
-
Set the capacity. The semantics are implementation dependent but - typical semantics are as follows: If the capacity is not mutable an - exception is thrown. A new data array is created and data is copied from - the old array to the new array.
-
isCapacityMutable
-
Is the capacity mutable
-
setCapacityMutable
-
Specify if the capacity can be changed.
-
setCapacity
-
Set the capaciity.
-
dumpValue
-
ostream method
-
-

- - -

PVScalarArray

- -

PVScalarArray is the base class for scalar array data. PVValueArray is a -templete for the various scalar array data classes. There is a class for each -possible scalar type, i. e. PVBooleanArray, ..., PVStringArray.

-
-class PVScalarArray : public PVArray {
-public:
-    POINTER_DEFINITIONS(PVScalarArray);
-    virtual ~PVScalarArray();
-    typedef PVScalarArray &reference;
-    typedef const PVScalarArray& const_reference;
-
-    const ScalarArrayConstPtr getScalarArray() const ;
-
-    template<typename T>
-    void getAs(shared_vector<const T>& out) const
-
-    template<typename T>
-    void putFrom(const shared_vector<const T>& inp)
-
-    void assign(PVScalarArray& pv);
- ...
-}
-
- -

where

-
-
getScalarArray
-
Get the introspection interface.
-
getAs
-
Fetch the current value and convert to the requested type. - A copy is made if the requested type does not match the element type. - If the types do match then no copy is made. -
-
putFrom
-
Assign the given value after conversion. - A copy and element-wise conversion is performed unless the element type - of the PVScalarArray matches the type of the provided data. - If the types do match then a new refernce to the provided data is kept. -
-
assign
-
Assign the given PVScalarArray's value. - A copy and element-wise conversion is performed unless the element type - of the PVScalarArray matches the type of the provided data. - If the types do match then a new refernce to the provided data is kept. -
-
- -

PVStructure

- -

The interface for a structure is:

-
class PVStructure : public PVField,public BitSetSerializable {
-public:
-    POINTER_DEFINITIONS(PVStructure);
-    virtual ~PVStructure();
-    typedef PVStructure & reference;
-    typedef const PVStructure & const_reference;
-
-    virtual void setImmutable();
-    StructureConstPtr getStructure() const;
-    const PVFieldPtrArray & getPVFields() const;
-    PVFieldPtr getSubField(std::string const &fieldName) const;
-
-    template<typename PVT>
-    std::tr1::shared_ptr<PVT> getSubField(std::string const &fieldName) const
-
-    PVFieldPtr getSubField(std::size_t fieldOffset) const;
-
-    template<typename PVT>
-    std::tr1::shared_ptr<PVT> getSubField(std::size_t fieldOffset) const
-
-    virtual void serialize(
-        ByteBuffer *pbuffer,SerializableControl *pflusher) const ;
-    virtual void deserialize(
-        ByteBuffer *pbuffer,DeserializableControl *pflusher);
-    virtual void serialize(ByteBuffer *pbuffer,
-        SerializableControl *pflusher,BitSet *pbitSet) const;
-    virtual void deserialize(ByteBuffer *pbuffer,
-        DeserializableControl*pflusher,BitSet *pbitSet);
-    PVStructure(StructureConstPtr const & structure);
-    PVStructure(StructureConstPtr const & structure,PVFieldPtrArray const & pvFields);
-    virtual std::ostream& dumpValue(std::ostream& o) const;
-};
- -

where

-
-
getStructure
-
Get the introspection interface for the structure.
-
getPVFields
-
Returns the array of subfields. The set of subfields must all have - different field names.
-
getSubField(std::string fieldName)
-
- Get a subField of a field.d - A non-null result is - returned if fieldName is a field of the PVStructure. The fieldName can be - of the form name.name... - If the field does not exist the a Ptr to a NULL value is returned - without any error message being generated. -
- Note that the template version replaces getBooleanField, etc.
-
-
getSubField(int fieldOffset)
-
Get the field located a fieldOffset, where fieldOffset is relative to - the top level structure. This returns null if the specified field is not - located within this PVStructure. -
-
dumpValue
-
Method for streams I/O.
-
-

TBD -

-
dumpvalue
-
replace this with ostream operator<<
-
-

- - -

PVValueArray

- -

This is a template class plus instances for PVBooleanArray, ..., -PVStringArray.

-
template<typename T>
-class PVValueArray : public detail::PVVectorStorage<T,PVScalarArray> 
-{
-public:
-    POINTER_DEFINITIONS(PVValueArray);
-    typedef T  value_type;
-    typedef T* pointer;
-    typedef const T* const_pointer;
-    typedef ::epics::pvData::shared_vector<T> svector;
-    typedef ::epics::pvData::shared_vector<const T> const_svector;
-    static const ScalarType typeCode;
-
-    virtual ~PVValueArray() {}
-    std::ostream& dumpValue(std::ostream& o) const;
-    std::ostream& dumpValue(std::ostream& o, size_t index) const;
-    // inherited from PVVectorStorage
-    const_svector view();
-    void swap(const_svector& other);
-    void replace(const const_svector& next);
-    svector reuse();
-    ...
-};
-
- -

where

-
-
dumpValue
-
Method for streams I/O.
-
view
-
Fetch a read-only view of the current array data.
-
swap
-
- Callers must ensure that postPut() is called after the last swap() operation. - Before you call this directly, consider using the reuse(), or replace() methods. -
-
replace
-
Discard current contents and replaced with the provided.
-
reuse
-
Remove and return the current array data or an unique copy if shared.
-
-

TBD -

-
dumpvalue
-
replace this with ostream operator<<
-
Check for completeness
-
Michael should check that PVScalarArray and PVValueArray - have the correct set of methods and that the descriptions are correct.
-
-

- -

PVStructureArray

- -

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 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 void serialize(ByteBuffer *pbuffer,
-    virtual const_svector view() const;
-    virtual void swap(const_svector &other);
-    virtual void replace(const const_svector &other);
-        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;
-    // inherited from PVVectorStorage
-    const_svector view();
-    void swap(const_svector& other);
-    void replace(const const_svector& next);
-    svector reuse();
- ...
-}
- -

where

-
-
getStructureArray
-
Get the introspection interface shared by each element.
-
append
-
Create new elements and append them to the end of the array. It returns - the index of the first new element.
-
remove
-
Remove the specfied set of elements. It returns (false,true) if the - elements (were not, were) removed. It will not removed any elements - unless all requested elements exist or are null. Note that this deletes - the element and sets the array element to null. It does not change the - array capacity.
-
compress
-
This moves all null elements and then changes the array capacity. When - done there are no null elements.
-
- -

The other methods are similar to the methods for other array types. - See PVArray above for details.

- -

PVUnionArray

-

The interface for an array of unions is:

-
-template&ly;&gt;
-class epicsShareClass PVValueArray&ly;PVUnionPtr&gt; : public detail::PVVectorStorage&ly;PVUnionPtr,PVArray&gt;
-{
-    typedef detail::PVVectorStorage&ly;PVUnionPtr,PVArray&gt; base_t;
-public:
-    POINTER_DEFINITIONS(PVUnionArray);
-    typedef PVUnionPtr  value_type;
-    typedef PVUnionPtr* pointer;
-    typedef const PVUnionPtr* const_pointer;
-    typedef PVUnionArray &reference;
-    typedef const PVUnionArray& const_reference;
-
-    //TODO: full namespace can be removed along with local typedef 'shared_vector'
-    typedef ::epics::pvData::shared_vector&ly;PVUnionPtr&gt; svector;
-    typedef ::epics::pvData::shared_vector&ly;const PVUnionPtr&gt; const_svector;
-    
-    virtual ~PVValueArray() {}
-
-    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

-
-
getUnionArray
-
Get the introspection interface shared by each element.
-
append
-
Create new elements and append them to the end of the array. It returns - the index of the first new element.
-
remove
-
Remove the specfied set of elements. It returns (false,true) if the - elements (were not, were) removed. It will not removed any elements - unless all requested elements exist or are null. Note that this deletes - the element and sets the array element to null. It does not change the - array capacity.
-
compress
-
This moves all null elements and then changes the array capacity. When - done there are no null elements.
-
- -

The other methods are similar to the methods for other array types. - See PVArray above for details.

- -

PVDataCreate

- -

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

-
-
getPVDataCreate
-
The returns the PVDataCreate implementation, which is a singleton.
-
createPVField
-
The PVField is created reusing the Field interface. Two methods are - provided. Each calls the corresponding createPVScalar, createPVArray, or - createPVStructure depending in the type of the last argument.
-
createPVScalar
-
Creates an instance of a PVScalar. Four versions are supplied. The - first is passed an introspection interface. - The second provides the scalarType. - The third provides a PVScalar to clone. - The last is a template version. PVAT must be a valid type. - For example: -
-PVDoublePtr pvDouble = getPVDataCreate()->createPVScalar<PVDouble>();
-
-
-
createPVStructure
-
Create an instance of a PVStructure. - Three methods are provided. - The first uses an array of field names and an array of PVFields to initialize the sub-fields. - The second initializes the subfields by cloning the fields contained in - structToClone. The newly created sub-fields will have the same values as the original. - If structToClone is null then the new structure is initialized to have 0 sub-fields. - The third method uses a previously created structure introspection interface. -
-
createPVUnion
-
Create an instance of a PVUnion. Two methods are provided. - The first uses a previously created union introspection interface. - The second clones an existing PVUnion. -
-
createPVVariantUnion
-
Creates an instance of a varient PVUnion. - This is a union which has a single field which can be any pvData supported type, -
-
createPVScalarArray
-
Create an instance of a PVArray. Four versions are supplied. - The first is passed an introspection interface. - The second provides the elementType. - The third provides a PVScalarArray to clone. - The last is a template version. PVAT must be a valid type. - For example: -
-PVDoubleArrayPtr pvDoubleArray = getPVDataCreate()->createPVScalarArray<PVDoubleArray>();
-
-
-
createPVStructureArray
-
Create a PVStructureArray. - Two versions are provided. - The first is passed a StructureArrayConstPtr. - The second is passed a StructureConstPtr which is used to create a StructureArrayConstPtr. - The argument provides the Structure interface for ALL elements of the PVStructureArray. -
-
createPVUnionArray
-
Create a PVUnionArray. - Two versions are provided. - The first is passed a UnionArrayConstPtr. - The second is passed a UnionConstPtr which is used to create a UnionArrayConstPtr. - The argument provides the Union interface for ALL elements of the PVUnionArray. -
-
createPVVariantUnionArray
-
Create a PVUnionArray. - No arguments are needed. -
-
- -

standardPVField.h

- -

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();
-
- -

Conversion

-

There are two facilities for converting between two different PVData -objects:

-
-
Convert
-
This preforms all conversions except for coping subarrays.
-
PVSubArray
-
This copies a subarray from one PVArray to another. - The two arrays must have the same element type.
-
-

convert.h

- -

NOTE about copying immutable array fields. If an entire immutable array -field is copied to another array that has the same elementType, both offsets -are 0, and the length is the length of the source array, then the shareData -method of the target array is called and the target array is set immutable. -Thus the source and target share the same primitive array.

- -

This section describes the supported conversions between data types.

- -
-bool operator==(PVField&, PVField&);
-
-static bool operator!=(PVField& a, PVField& b);
-
-bool operator==(const Field&, const Field&);
-bool operator==(const Scalar&, const Scalar&);
-bool operator==(const ScalarArray&, const ScalarArray&);
-bool operator==(const Structure&, const Structure&);
-bool operator==(const StructureArray&, const StructureArray&);
-bool operator==(const Union&, const Union&);
-bool operator==(const UnionArray&, const UnionArray&);
-
-static inline bool operator!=(const Field& a, const Field& b);
-static inline bool operator!=(const Scalar& a, const Scalar& b);
-static inline bool operator!=(const ScalarArray& a, const ScalarArray& b);
-static inline bool operator!=(const Structure& a, const Structure& b);
-static inline bool operator!=(const StructureArray& a, const StructureArray& b);
-static inline bool operator!=(const Union& a, const Union& b);
-static inline bool operator!=(const UnionArray& a, const UnionArray& b);
-
-class Convert;
-typedef std::tr1::shared_ptr<Convert> ConvertPtr;
-
-class Convert {
-public:
-    static ConvertPtr getConvert();
-    ~Convert();
-    void getFullName(StringBuilder buf,PVFieldPtr const & pvField);
-    bool equals(PVFieldPtr const &a,PVFieldPtr const &b);
-    bool equals(PVField &a,PVField &b);
-    void getString(StringBuilder buf,PVFieldPtr const & pvField,int indentLevel);
-    void getString(StringBuilder buf,PVFieldPtr const & pvField);
-    void getString(StringBuilder buf,PVField const * pvField,int indentLevel);
-    void getString(StringBuilder 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(StringBuilder 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.

- -

pvSubArrayCopy.h

-
-template<typename T>
-void copy(
-    PVValueArray<T> & pvFrom,
-    size_t fromOffset,
-    PVValueArray<T> & pvTo,
-    size_t toOffset,
-    size_t len);
-
-void copy(
-    PVScalarArray & from,
-    size_t fromOffset,
-    PVScalarArray & to,
-    size_t toOffset,
-    size_t len);
-
-void copy(
-    PVStructureArray & from,
-    size_t fromOffset,
-    PVStructureArray & to,
-    size_t toOffset,
-    size_t len);
-
-void copy(
-    PVArray & from,
-    size_t fromOffset,
-    PVArray & to,
-    size_t toOffset,
-    size_t len);
-
-

The last copy is the only one most client need to call. -It either throws an error of the element types do not match or calls the -other copy functions. The arguments are:

-
-
from
-
The source array.
-
fromOffset
-
The offset into the source array.
-
to
-
The destination array. The element type must be the same - as for the source array. If the element type is structure then - the introspection interface for the element types must be the same. -
-
toOffset
-
The offset into the destination array.
-
len
-
The number of elements to copy.
-
-

An exception is thrown if:

-
-
type mismatch
-
The element types for the source and destination differ.
-
immutable
-
The destination array is immutable. -
capacity immutable
-
The destination array needs to have it's capacity extentended - but the capacity is immutable.
-
- -

pvDataApp/property

- -

Definition of Property

- -

Only fields named "value" have properties. A record can have multiple value -fields, which can appear in the top level structure of a record or in a -substructure. All other fields in the structure containing a value field are -considered properties of the value field. The fieldname is also the property -name. The value field can have any type, i.e. scalar, scalarArray, or -structure. Typical property fields are timeStamp, alarm, display, control, and -history. The timeStamp is a special case. If it appears anywhere in the -structure hieraracy above a value field it is a property of the value field.

- -

For example the following top level structure has a single value field. The -value field has properties alarm, timeStamp, and display.

-
structure counterOutput
-    double value
-    alarm_t
-        int severity 0
-        int status 0
-        string message
-    timeStamp_t
-        long secondsPastEpoch
-        int nanoSeconds
-        int userTag
-    display_t
-        double limitLow 0.0
-        double limitHigh 10.0
-        string description "Sample Description"
-        string format "%f"
-        string units volts
- -

The following example has three value fields each with properties alarm and -timeStamp. Voltage, Current, and Power each have a different alarms but all -share the timeStamp.

-
structure powerSupplyValue
-    double value
-    alarm_t
-        int severity 0
-        int status 0
-        string message
-
-structure powerSupplySimple
-    alarm_t
-        int severity 0
-        int status 0
-        string message
-    timeStamp_t
-        long secondsPastEpoch
-        int nanoSeconds
-        int userTag
-    powerSupplyValue_t voltage
-        double value
-        alarm_t
-            int severity 0
-            int status 0
-            string message
-    powerSupplyValue_t power
-        double value
-        alarm_t
-            int severity 0
-            int status 0
-            string message
-    powerSupplyValue_t current
-        double value
-        alarm_t
-            int severity 0
-            int status 0
-            string message
- -

Standard Properties

- -

The following field names have special meaning, i.e. support properties for -general purpose clients.

-
-
value
-
This is normally defined since most general purpose clients access this - field. All other fields in the structure support or describe the value - field. The type can any supported type but is usually one of the - following: -
-
scalar
-
Any of the scalar types.
-
scalarArray
-
An array with the elementType being a scalar type
-
enumerated structure
-
A structure that includes fields named index and choices. index - is an int that selects a choice. choices is an array of strings - that defines the complete set of choices.
-
other
-
Other structure or array types can also be defined if clients and - support code agree on the meaning. Some examples are: 1) A - structure defining a 2D matrix, 2) A structure defining an image, - 3) A structure that simulates a remote method, ...
-
-
-
timeStamp
-
The timeStamp. The type MUST be a timeStamp structure. Also if the - PVData structure does not have a timeStamp then a search up the parent - tree is made to find a timeStamp.
-
alarm
-
The alarm. The type MUST be an alarm structure.
-
display
-
A display structure as described below. It provides display - characteristics for the value field.
-
control
-
A control structure as described below. It provides control - characteristics for the value field.
-
history
-
Provides a history buffer for the value field. Note that currently - PVData does not define history suppoprt.
-
other
-
Other standard properties can be defined.
-
- -

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:

-
-
input
-
A field with support that changes the value field. This can be - anything. It can be a channel access link. It can obtain a value from - hardware. Etc.
-
valueAlarm
-
A field with support that looks for alarm conditions based on the - value.
-
output
-
A field with support that reads the current value and sends it - somewhere else. This can be anything. It can be a channel access link. It - can write a value to hardware. Etc.
-
- -

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. -

- -

Overview of Property Support

- -

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();
-     ...
-}
- -

timeStamp

- -

A timeStamp is represented by the following structure

-
structure timeStamp
-    long secondsPartEpoch
-    int nanoSeconds
-    int userTag
- -

The Epoch is the posix epoch, i.e. Jan 1, 1970 00:00:00 UTC. Both the -seconds and nanoSeconds are signed integers and thus can be negative. Since the -seconds is kept as a 64 bit integer, it allows for a time much greater than the -present age of the universe. Since the nanoSeconds portion is kept as a 32 bit -integer it is subject to overflow if a value that corresponds to a value that -is greater than a little more than 2 seconds of less that about -2 seconds. The -support code always adjust seconds so that the nanoSecconds part is normlized, -i. e. it has is 0<=nanoSeconds<nanoSecPerSec..

- -

Two header files are provided for manipulating time stamps:

-
-
timeStamp.h
-
Defines a time stamp independent of pvData, i.e. it is a generally - useful class for manipulating timeStamps.
-
pvTimeStamp.h
-
A class that can be attached to a time stamp pvData structure. It - provides get and set methods to get/set a TimeStamp as defined by - timeStamp.h
-
- -

timeStamp.h

- -

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

-
-
TimeStamp()
-
The defauly constuctor. Both seconds and nanoSeconds are set to 0.
-
TimeStamp(int64 secondsPastEpoch,int32 nanoSeconds = 0)
-
A constructor that gives initial values to seconds and nanoseconds.
-
normalize
-
Adjust seconds and nanoSeconds so that - 0<=nanoSeconds<nanoSecPerSec.
-
fromTime_t
-
Set time from standard C time.
-
toTime_t
-
Convert timeStamp to standard C time.
-
getSecondsPastEpoch
-
Get the number of seconds since the epoch.
-
getEpicsSecondsPastEpoch
-
Get the number of EPICS seconds since the epoch. EPICS uses Jan 1, 1990 - 00:00:00 UTC as the epoch.
-
getNanoSeconds
-
Get the number of nanoSeconds. This is always normalized.
-
getUserTag
-
Get the userTag.
-
setUserTag
-
Set the userTag.
-
put(int64 secondsPastEpoch,int32 nanoSeconds = 0)
-
Set the timeStamp value. If necessary it will be normalized.
-
put(int64 milliseconds)
-
Set the timeStamp with a value the is the number of milliSeconds since - the epoch.
-
getCurrent()
-
Set the timeStamp to the current time.
-
toSeconds()
-
Convert the timeStamp to a value that is the number of seconds since - the epocj
-
operator =
-
operator!=
-
operator<=
-
operator<
-
operator>=
-
operator>
-
Standard C++ operators.
-
diff
-
diff = a - b
-
getMilliseconds
-
Get the number of milliseconds since the epoch.
-
- -

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);
- -

pvTimeStamp.h

-
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

-
-
PVTimeStamp
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if a timeStamp - structure is found. It looks first at pvField itself and if is not an - appropriate pvData structure but the field name is value it looks up the - parent structure tree.
-
detach
-
Detach from the pvData structure.
-
isAttached
-
Is there an attachment to a timeStamp structure?
-
get
-
Copies data from the pvData structure to a TimeStamp. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from TimeStamp to the pvData structure. An exception is - thrown if not attached to a pvData structure.
-
- -

alarm

- -

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:

-
-
alarm.h
-
Defines an alarm independent of pvData, i.e. it is a generally useful - class for manipulating alarms.
-
pvAlarm.h
-
A class that can be attached to an alarm pvData structure. It provides - get and set methods to get/set alarm data as defined by alarm.h
-
- -

alarm.h

-
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:

-
-
getSeverity
-
Get the alarm severity corresponding to the integer value.
-
getSeverityNames
-
Get the array of severity choices.
-
- -

Alarm Status defines the possible choices for alarm status:

-
-
getStatus
-
Get the alarm status corresponding to the integer value.
-
getStatusNames
-
Get the array of status choices.
-
- -

Alarm has the methods:

-
-
Alarm
-
The constructor. It sets the severity to no alarm and the message to - "".
-
getMessage
-
Get the message.
-
setMessage
-
Set the message.
-
getSeverity
-
Get the severity.
-
setSeverity
-
Set the severity.
-
getStatus
-
Get the status.
-
setStatus
-
Set the status.
-
- -

pvAlarm.h

-
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

-
-
PVAlarm
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if it found an - appropriate pvData structure. It looks first a pvField itself and if is - not an appropriate pvData structure but the field name is value it looks - to see if the parent structure has an appropriate sub structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to an alarm structure?
-
get
-
Copies data from the pvData structure to an Alarm. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from Alarm to the pvData structure. An exception is thrown - if not attached to a pvData structure.
-
- -

control

- -

Control information is represented by the following structure

-
structure control
-    double limitLow
-    double limitHigh
-    double minStep
- -

Two header files are provided for manipulating control:

-
-
control.h
-
Defines control independent of pvData, i.e. it is a generally useful - class for manipulating control.
-
pvControl.h
-
A class that can be attached to an control pvData structure. It - provides get and set methods to get/set control data as defined by - control.h
-
- -

control.h

-
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

-
-
Control
-
The default constructure.
-
getLow
-
Get the low limit.
-
getHigh
-
Get the high limit.
-
setLow
-
Set the low limit.
-
setHigh
-
Set the high limit.
-
setMinStep
-
Set the minimum step size.
-
getMinStep
-
Get he minimum step size.
-
- -

pvControl.h

-
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

-
-
PVControl
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if it found an - appropriate pvData structure. It looks first a pvField itself and if is - not an appropriate pvData structure but the field name is value it looks - to see if the parent structure has an appropriate sub structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to a control structure?
-
get
-
Copies data from the pvData structure to a Control. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from Control to the pvData structure. An exception is - thrown if not attached to a pvData structure.
-
- -

display

- -

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:

-
-
display.h
-
Defines display independent of pvData, i.e. it is a generally useful - class for manipulating display.
-
pvDisplay.h
-
A class that can be attached to an display pvData structure. It - provides get and set methods to get/set display data as defined by - display.h
-
- -

display.h

-
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

-
-
Control
-
The default constructure.
-
getLow
-
Get the low limit.
-
getHigh
-
Get the high limit.
-
setLow
-
Set the low limit.
-
setHigh
-
Set the high limit.
-
getDescription
-
Get the description.
-
setDescription
-
Set the description.
-
getFormat
-
Get the format.
-
setFormat
-
Set the format.
-
getUnits
-
Get the units.
-
setUnits
-
Set the units.
-
- -

pvDisplay.h

-
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

-
-
PVDisplay
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if it found an - appropriate pvData structure. It looks first a pvField itself and if is - not an appropriate pvData structure but the field name is value it looks - to see if the parent structure has an appropriate sub structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to a display structure?
-
get
-
Copies data from the pvData structure to a Display. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from Display to the pvData structure. An exception is - thrown if not attached to a pvData structure.
-
- -

pvEnumerated.h

- -

An enumerated structure is a structure that has fields:

-
structure
-    int index
-    string[] choices
- -

For enumerated structures a single header file pvEnumerted.h is available

-
class PVEnumerated {
-public:
-    PVEnumerated();
-    //default constructors and destructor are OK
-    //This class should not be extended
-    //returns (false,true) if pvField(isNot, is valid enumerated structure
-    //An automatic detach is issued if already attached.
-    bool attach(PVFieldPtr const &pvField);
-    void detach();
-    bool isAttached();
-    // each of the following throws logic_error is not attached to PVField
-    // a set returns false if field is immutable
-    bool setIndex(int32 index);
-    int32 getIndex();
-    std::string getChoice();
-    bool choicesMutable();
-    StringArrayPtr const & getChoices();
-    int32 getNumberChoices();
-    bool setChoices(StringArray &choices,int32 numberChoices);
-};
- -

where

-
-
PVEnumerated
-
The default constructor. Attach must be called before any get or set - method can be called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if pvField (is - not, is) an enumerated structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to an enemerated structure?
-
setIndex
-
Set the index field in the pvData structure. An exception is thrown if - not attached to a pvData structure.
-
getIndex
-
Get the index field in the pvData structure.
-
getChoice
-
Get the std::string value corresponding to the current index field in the - pvData structure. An exception is thrown if not attached to a pvData - structure.
-
choicesMutable
-
Can the choices be changed? Note that this is often true. An exception - is thrown if not attached to a pvData structure.
-
getChoices
-
Get the array of choices. An exception is thrown if not attached to a - pvData structure.
-
getNumberChoices
-
Get the number of choices. An exception is thrown if not attached to a - pvData structure.
-
setChoices
-
Change the choices. An exception is thrown if not attached to a pvData - structure.
-
- - -

pvDataApp/factory

- -

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

- -

pvDataAPP/misc

- -

Overview

- -

This package provides utility code:

-
-
bitSet.h
-
An implementation of BitSet that can be serialized.
-
byteBuffer.h
-
Used to serialize objects.
-
destroyable.h
-
Provides method destroy.
-
epicsException.h
-
Exception with stack trace.
-
event.h
-
Signal and wait for an event.
-
executor.h
-
Provides a thread for executing commands.
-
localStaticLock.h
-
TBD Matej can You explain what this does?
-
lock.h
-
Support for locking and unlocking.
-
messageQueue.h
-
Support for queuing messages to give to requesters.
-
noDefaultMethods.h
-
When privately extended prevents compiler from implementing default - methods.
-
queue.h
-
A queue implementation that allows the latest queue element to continue - to be used when no free element is available.
-
requester.h
-
Allows messages to be sent to a requester.
-
serialize.h
-
Support for serializing objects.
-
serializeHelper.h
-
More support for serializing objects.
-
sharedPtr.h
-
Defines POINTER_DEFINITIONS.
-
sharedVector.h -
Like std::vector except that std::shared_ptr is used for - the data array.
-
status.h
-
A way to pass status information to a client.
-
templateMeta.h
-
TBD Michael can You provide an explaination?
-
thread.h
-
Provides thread support.
-
timeFunction.h
-
Time how long a function call requires.
-
timer.h
-
An implementation of Timer that does not require an object to be - created for each timer request.
-
typeCast.h
-
TBD Michael can You provide an explaination?
-
- -

Note that directory testApp/misc has test code for all the classes in misc. -The test code also can be used as examples.

- -

bitSet.h

- -

This is adapted from the java.util.BitSet. bitSet.h is:

-
-class BitSet;
-typedef std::tr1::shared_ptr<BitSet> BitSetPtr;
-
-class BitSet : public Serializable {
-public:
-    static BitSetPtr create(uint32 nbits);
-    BitSet();
-    BitSet(uint32 nbits);
-    virtual ~BitSet();
-    void flip(uint32 bitIndex);
-    void set(uint32 bitIndex);
-    void clear(uint32 bitIndex);
-    void set(uint32 bitIndex, bool value);
-    bool get(uint32 bitIndex) const;
-    void clear();
-    int32 nextSetBit(uint32 fromIndex) const;
-    int32 nextClearBit(uint32 fromIndex) const;
-    bool isEmpty() const;
-    uint32 cardinality() const;
-    uint32 size() const;
-    BitSet& operator&=(const BitSet& set);
-    BitSet& operator|=(const BitSet& set);
-    BitSet& operator^=(const BitSet& set);
-    BitSet& operator-=(const BitSet& set);
-    BitSet& operator=(const BitSet &set);
-    void or_and(const BitSet& set1, const BitSet& set2);
-    bool operator==(const BitSet &set) const;
-    bool operator!=(const BitSet &set) const;
-    void toString(StringBuilder buffer, int indentLevel = 0) const;
-    virtual void serialize(
-        ByteBuffer *buffer,SerializableControl *flusher) const;
-    virtual void deserialize(
-        ByteBuffer *buffer,DeserializableControl *flusher);
-
-private:
-};
- -

where

-
-
BitSet()
-
Creates a bitSet of initial size 64 bits. All bits initially false.
-
BitSet(uint32 nbits)
-
Creates a bitSet with the initial of the specified number of bits. All - bits initially false.
-
~BitSet()
-
Destructor.
-
flip(uint32 bitIndex)
-
Flip the specified bit.
-
set(uint32 bitIndex)
-
Set the specified bit true.
-
clear(uint32 bitIndex)
-
Set the specified bit false.
-
set(uint32 bitIndex, bool value)
-
Set the specified bit to value.
-
get(uint32 bitIndex)
-
Return the state of the specified bit.
-
clear()
-
Set all bits to false.
-
nextSetBit(uint32 fromIndex)
-
Get the index of the next true bit beginning with the specified - bit.
-
nextClearBit(uint32 fromIndex)
-
Get the index of the next false bit beginning with the specified - bit.
-
isEmpty()
-
Return (false,true) if (at least one bit true, all bits are false)
-
cardinality()
-
Return the number of true bits.
-
size()
-
Returns the number of bits of space actually in use.
-
operator&=(const BitSet& set)
-
Performs a logical and of this target bit set with the argument bit - set. This bit set is modified so that each bit in it has the value true - if and only if it both initially had the value true and the corresponding - bit in the bit set argument also had the value.
-
operator|=(const BitSet& set)
-
Performs a logical or of this target bit set with the argument bit - set.
-
operator^=(const BitSet& set)
-
Performs a logical exclusive or of this target bit set with the - argument bit set.
-
operator-=(const BitSet& set)
-

Clears all of the bits in this bitSet whose corresponding bit is set - in the specified bitSet.

-
-
operator=(const BitSet &set)
-
Assignment operator.
-
or_and(const BitSet& set1, const BitSet& set2)
-
Perform AND operation on set1 and set2, and then OR this bitSet with - the result.
-
operator==(const BitSet &set)
-
Does this bitSet have the same values as the argument.
-
operator!=(const BitSet &set)
-
Is this bitSet different than the argument.
-
toString(StringBuilder buffer, int indentLevel)
-
Show the current values of the bitSet.
-
virtual void serialize(ByteBuffer *buffer,SerializableControl *flusher) - const;
-
Serialize the bitSet
-
virtual void deserialize(ByteBuffer *buffer,DeserializableControl - *flusher);
-
Deserialize the bitSet.
-
-

TBD -

-
toString
-
Should this change and also implement ostream operator?
-
-

- -

byteBuffer.h

- -

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();
- ...
-};
- -

destroyable.h

-
class Destroyable  {
-public:
-    POINTER_DEFINITIONS(Destroyable);
-    virtual void destroy() = 0;
-    virtual ~Destroyable() {};
-};
- -

epicsException.h

-
/*
- * 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.
- */
- -

event.h

- -

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

-
-
Event
-
The constructor. The initial value can be full or empty. The normal - first state is empty.
-
signal
-
The event becomes full. The current or next wait will complete.
-
wait
-
Wait until event is full or until timeout. The return value is - (false,true) if the wait completed because event (was not, was) full. A - false value normally means that that a timeout occured. It is also - returned if an error occurs or because the event is being deleted.
-
tryWait
-
returns (false,true) if the event is (empty,full)
-
- -

executor.h

- -

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:

-
-
Executor
-
The constructor. A thread name and priority must be specified.
-
~Executor
-
The destructor. If any commands remain in the execute list they are not - called. All ExecutorNodes that have been created are deleted.
-
execute
-
Request that command be executed. If it is already on the run list - nothing is done.
-
- -

localStaticLock.h

-
-extern epics::pvData::Mutex& getLocalStaticInitMutex();
-
-static class MutexInitializer {
-  public:
-    MutexInitializer ();
-    ~MutexInitializer ();
-} localStaticMutexInitializer; // Note object here in the header.
-
-

TBD Matej will explain.

- -

lock.h

-
-typedef epicsMutex Mutex;
-
-class Lock : private NoDefaultMethods {
-public:
-    explicit Lock(Mutex &pm);
-    ~Lock();
-    void lock();
-    void unlock();
-    bool tryLock();
-    bool ownsLock() ;
- ...
-};
- -

Lock is as easy to use as Java synchronize. To protect some object just -create a Mutex for the object and then in any method to be synchronized just -have code like:

-
class SomeClass {
-private
-    Mutex mutex;
- ...
-public
-    SomeClass() : mutex(Mutex()) {}
- ...
-    void method()
-    {
-        Lock xx(mutex);
-        ...
-    }
-
- -

The method will take the lock when xx is created and release the lock when -the current code block completes.

- -

Another example of Lock is initialization code that must initialize only -once. This can be implemented as follows:

-
    static void init(void) {
-        static Mutex mutex;
-        Lock guard(mutex);
-        if(alreadyInitialized) return;
-        // initialization
-    }
-

-

Lock has a private variable: -

-bool locked;
-
-and improves efficency by checking the local variable before calling the -mutex methods. This is not thread safe if any methods are called by a thread other than -the thread that created the Lock. -

-

It is thread safe if used as follows:

-
-{
-    Lock guard(mutex);
-    ...
-    /* the following can optionally be called
-    guard.unlock();
-    guard.lock();
-    */
-}
-
-

It is not thread safe if used as follows:

-
-class SomeClass
-{
-private:
-    Mutex mutex;
-    Lock lock;
-public:
-    SomeClass: lock(mutex) {}
-    ...
-    void someMethod() {
-        lock.unlock();
-        ...
-    }
-    ...
-};
-
-

It is only safe if all methods of Lock, including ~Lock(), -are called by the same thread. -

- -

messageQueue.h

- -

Definitions

- -

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:

-
-
getMessage
-
The message.
-
getMessageType
-
The message type.
-
setMessageNull
-
Set the message to be a null string.
-
- -

A messageQueue is an interface with public methods:

-
-
MessageQueue
-
The constructor. The queue size must be specified.
-
~MessageQueue
-
The destructor.
-
put
-
Put a new message into the queue. False is returned if the queue was - full and true otherwise. If replaceLast is true then the last message is - replaced with this message.
-
get
-
Get the oldest queue element. If the queue is empty null is returned. - Before the next get can be issued release must be called.
-
release
-
Release the queue element returned by the last get.
-
isEmpty
-
Is the queue empty?
-
isFull
-
Is the queue full?
-
getClearOverrun
-
Get the number of times put has been called but no free element is - available.
-
- -

Look at miscTest/testMessageQueue.cpp for an example.

- -

noDefaultMethods.h

- -

If a class privately extends this class then the compiler can not create any -of the following: default constructor, default copy constructror, or default -assignment contructor.

-
/* This is based on Item 6 of
- * Effective C++, Third Edition, Scott Meyers
- */
-    class NoDefaultMethods {
-    protected:
-    // allow by derived objects
-    NoDefaultMethods(){};
-    ~NoDefaultMethods(){}
-    private:
-    // do not implment
-    NoDefaultMethods(const NoDefaultMethods&);
-    NoDefaultMethods & operator=(const NoDefaultMethods &);
-    };
- -

queue.h

- -

This provides a bounded queue. When the queue is -full the user code is expected to keep using the current element until a new -free element becomes avalable.

-
-template <typename T>
-class Queue
-{   
-public:
-    POINTER_DEFINITIONS(Queue);
-    typedef std::tr1::shared_ptr<T> queueElementPtr;
-    typedef std::vector<queueElementPtr> queueElementPtrArray;
-    Queue(queueElementPtrArray &);
-    virtual ~Queue();
-    void clear();
-    int capacity();
-    int getNumberFree();
-    int getNumberUsed();
-    queueElementPtr & getFree();
-    void setUsed(queueElementPtr const &element);
-    queueElementPtr & getUsed();
-    void releaseUsed(queueElementPtr const &element);
- ...
-};
- -

testApp/misc/testQueue.cpp provides an example of how to define a queue.

- -

The queue methods are:

-
-
clear
-
Make the queue empty.
-
getNumberFree
-
Get the number of free elements in the queue.
-
capacity
-
Get the capacity, i.e. the maximun number of elements the queue can - hold.
-
getNumberFree
-
Get the number of free elements.
-
getNumberUsed
-
Get the number of elements used.
-
getFree
-
Get the next free element. Null is returned if no free elements are - available. If a non null value is returned then the element belongs to - the caller until setUsed is called.
-
setUsed
-
Set a queue element used. This must be the element returned by the last - call to getFree.
-
getUsed
-
Get the next used element of null if no more used elements are - available.
-
releaseUsed
-
Set a queue element free. This must be the element returned by the last - call to getUsed.
-
- -

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.h

- -

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

-
-
-
MessageType
-
Type of message.
-
messageTypeName
-
An array of strings of the message type names, i.e. - std::string("info"),std::string("warning"),std::string("error"),std::string("fatalError").
-
getRequesterName
-
Returns the requester name.
-
message
-
Gives a message to the requester.
-
- -

serialize.h

-
-    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;
-    };
- -

serializeHelper.h

- -

This is a helper class for serialization, which is required for sending and -receiving pvData over the nerwork.

-
class SerializeHelper : public NoDefaultMethods {
-public:
-    static void writeSize(int s, ByteBuffer* buffer,
-        SerializableControl* flusher);
-    static int readSize(ByteBuffer* buffer,
-        DeserializableControl* control);
-    static void serializeString(const std::string& value,
-        ByteBuffer* buffer,SerializableControl* flusher);
-    static void serializeSubstring(const std::string& value, int offset,
-        int count, ByteBuffer* buffer,
-        SerializableControl* flusher);
-    static std::string deserializeString(ByteBuffer* buffer,
-        DeserializableControl* control);
- ...
-};
- -

where

-
-
writeSize
-
Serialize the size.
-
readSize
-
Deserialize the size.
-
serializeString
-
Serialize a std::string.
-
serializeSubstring
-
Serialize a substring.
-
deserializeString
-
Deserialize a string.
-
- -

sharedPtr.h

-
-#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;
- -

sharedVector.h

-

-shared_vector is a holder for a contigious piece of memory. -Data is shared, but offset and length are not. -This allows one vector to have access to only a subset of a piece of memory. -

-

-shared_vector differs from std::vector as follows:

-
-
Differences in behavior
-
- shared_vector models const-ness like shared_ptr. - An equivalent of 'const std::vector<E>' is - 'const shared_vector<const E>'. - However, it is also possible to have 'const shared_vector<E>' - analogous to 'E* const' and 'shared_vector<const E>>' - which is analogous to 'const E*'.i -
- Copying a shared_vector, by construction or assignment, does not copy - its contents. - Modifications to one such "copy" effect all - associated shared_vector instances. -
- std::vector::reserve(N) has no effect if N<=std::vector::capacity(). - However, like resize(), shared_vector<E>::reserve() has the side effect - of always calling make_unique(). -
-
Parts of std::vector interface not implemented
-
- Mutating methods insert(), erase(), shrink_to_fit(), emplace(), and emplace_back() are not implemented. -
- shared_vector does not model an allocator which is bound to the object. Therefore the get_allocator() method and the allocator_type typedef are not provided. -
- The assign() method and the related constructor are not implemented at this time. -
- The comparison operators are not implemented at this time. -
-
Parts not found in std::vector
-
- shared_vector has additional constructors from raw pointers and shared_ptr s. - The copy constructor and assignment operator allow implicit castings - from type 'shared_vector<T>' to 'shared_vector<const T>>'. - To faciliate safe modification the methods unique() and make_unique() are provided - The slice() method selects a sub-set of the shared_vector. - The low level accessors dataPtr(), dataOffset(), dataCount(), and dataTotal(). -
-
- - -
-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
-
Several flavors of constructor are provided. The most commingly used is: - 
-shared_vector(size_t c);
-
- This creates a shared_vector of the specified size/ -
-
max_size
-
The maximum size the C++ implementation allows, i.e., - the maximum possible capacity. - Note that units are number of elements not number of bytes. -
-
capacity
-
The current capacity.
-
reserve
-
Set array capacity.
-
resize
-
Grow or shrink array. - It the second argument is given it is the value to assign to - and new elements. -
-
make_unique
-
Ensure (by copying) that this shared_vector - is the sole owner of the data array. -
-
begin,...,rend
-
Standard interators.
-
front
-
Return a reference to the first element.
-
back
-
Return a reference to the last element.
-
push_back
-
Add an element to the end of the array.
-
pop_back
-
Remove an element from the end of the array.
-
data
-
Return a pointer to the raw array.
-
operator[](size_t i)
-
Return a reference to the specified element.
-
at
-
Like the previous except that it throws a range-error if - the specified element is out of range.
-
operator=
-
Copy an existing shared_vector.
-
swap
-
Swap the contents of this vector with another.
-
clear
-
Clear contents.
-
unique
-
returns (true,false) if data (is not, is) shared.
-
size
-
Number of elements visible through this vector.
-
empty
-
Is the number of elements zero?
-
slice
-
Reduce the view of this shared_vector.
-
dataPtr
-
A readonly shared_ptr to the array.
-
dataOffset
-
Offset in the data array of first visible element.
-
dataCount
-
Number of visible elements between dataOffset and end of data.
-
dataTotal
-
The total number of elements between dataOffset and the end of data
-
-

TBD -Michael should decide if this is the correct set of methods to describe. -Also he should check for correct descriptions. -

- - -

status.h

- -

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;
-    std::string toString() const;
-    void toString(StringBuilder buffer, int indentLevel = 0) const;
-    void serialize(ByteBuffer *buffer, SerializableControl *flusher) const;
-    void serialize(ByteBuffer *buffer, SerializableControl *flusher) const;
-};
- -

The Status methods are:

-
-
StatusType
-
An enum for the status type.
-
getType
-
Get the statusType.
-
getMessage
-
Get a message explaining the error.
-
getStackDump
-
Get a stack dump.
-
- -

The StatusCreate methods are:

-
-
getStatusOK
-
Get a singleton that returns StatusType.OK and a null message and - stackDump.
-
createStatus
-
Create a new Status.
-
deserializeStatus
-
Use this method instead of Status.deserialize(), since this allows OK - status optimization.
-
-

templateMeta.h

-

TBD Michael will explain.

- -

thread.h

- -

ThreadPriority

-
enum ThreadPriority {
-    lowestPriority,
-    lowerPriority,
-    lowPriority,
-    middlePriority,
-    highPriority,
-    higherPriority,
-    highestPriority
-};
- -

Thread

-
-class Thread;
-typedef std::tr1::shared_ptr<Thread> ThreadPtr;
-typedef std::tr1::shared_ptr<epicsThread> EpicsThreadPtr;
-
-class Runnable {
-public:
-    virtual void run() = 0;
-};
-
-class Thread;
-
-class Thread : public epicsThread, private NoDefaultMethods {
-public:
-    Thread(
-        std::string name,
-        ThreadPriority priority,
-        Runnable *runnableReady,
-        epicsThreadStackSizeClass stkcls=epicsThreadStackSmall);
-    ~Thread();
- ...
-};
- -

Runnable must be implement by code that wants to be run via a thread. It has -one virtual method: run. Run is the code that is run as a thread. When run -compeletes it can not be restarted. If code wants to delete a thread then it -MUST arrange that the run returns before the thread can be deleted. An -exception is thrown if run remains active when delete is called.

- -

Thread has the methods:

-
-
Thread
-
The constructor. A thread name and priority must be specified. The run - methods of runnable is executed. When the run methods returns the thread - will no longer be active but the client code must still delete the - thread.
-
~Thread
-
The destructor. This is called as the result of: - 
    delete pthread;
-
-
- -

timeFunction.h

- -

TimeFunction is a facility that measures the average number of seconds a -function call requires. When timeCall is called, it calls function in a loop. -It starts with a loop of one iteration. If the total elapsed time is less then -.1 seconds it increases the number of iterrations by a factor of 10. It keeps -repeating until the elapsed time is greater than .1 seconds. It returns the -average number of seconds per call.

-
class TimeFunctionRequester;
-class TimeFunction;
-typedef std::tr1::shared_ptr<TimeFunctionRequester> TimeFunctionRequesterPtr;
-typedef std::tr1::shared_ptr<TimeFunction> TimeFunctionPtr;
-        
-class TimeFunctionRequester {
-public:              
-    POINTER_DEFINITIONS(TimeFunctionRequester);
-    virtual ~TimeFunctionRequester(){}
-    virtual void function() = 0;
-};  
-
-    
-class TimeFunction {
-public:    
-    POINTER_DEFINITIONS(TimeFunction);
-    TimeFunction(TimeFunctionRequesterPtr const & requester);
-    ~TimeFunction(); 
-    double timeCall();
- ...
-};
- -

TimeFunctionRequester must be implemented by code that wants to time how -long a function takes. It has the single method:

-
-
function
-
This is the function.
-
- -

TimeFunction has the methods:

-
-
TimeFunction
-
Constructor.
-
~TimeFunction
-
Destructor.
-
timeCall
-
Time how long it takes to execute the function. It starts by calling - the function one time. If it takes < 1 seconds to doubles the number - of times to call the function. It repeats this until it takes at least - one second to call it ntimes.
-
- -

timer.h

- -

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 toString(StringBuilder builder);
- ...
-};
- -

TimerCallback must be implemented by the user. It has the following methods: -

-
-
callback
-
This is called when a timer expires. This is called with no locks held. - When called a delay timer is no longer on the queue but a periodioc timer - is on a queue. Thus the callback for a delay timer can issue a new - schedule request but a periodic timer must not. Note the explaination of - TimerNode.cancel below.
-
timerStopped
-
Timer.stop was called when a timer request was queued. or if the timer - is stopped and a schedule request is made.
-
- -

In order to schedule a callback client code must allocate a TimerNode It can -be used to schedule multiple callbacks. It has the methods:

-
-
TimerNode
-
The constructor. User code must create a TimeNode in order to call a - schedule method.
-
~TimerNode
-
The destructor. This is called as a result of the client calling: - 
    delete timerNode;
-
-
cancel
-
This is called to cancel a timer request. If a callback has been - dequeued but the callback not called when cancel is called then a - callback may still happen. New schedule requests can be made after a - cancel request has been made.
-
isScheduled
-
Is the timerNode scheduled to be called.
-
- -

Timer has the methods:

-
-
Timer
-
The consttructor.
-
~Timer
-
The destructor. The queue is emptied and TimerCallback.timerStopped is - called for each element of the queue.
-
scheduleAfterDelay
-
A request to schedule a callback after a delay specified in - seconds.
-
schedulePeriodic
-
Schedule a periodic callback.
-
-

typeCast.h

-

TBD Michael will explain.

- -

pvDataApp/pvMisc

- -

bitSetUtil.h

- -

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:

-
-
compress
-
Compress the bits in a BitSet related to a structure.
- For each structure: -
    -
  1. If the bit for the structure is set then the bit for all subfields - of the structure are cleared.
    2. -
  2. If the bit for the structure is not set but all immediate subfields - have their bit set then the bit for the structure is set and the bits - for all subfields are cleared.
    3. -
- Note that this is a recursive algorithm. That is if every immediate - subfield has it's offset bit set then the bits for ALL fields that reside - in the structure will be cleared.
-
Channel Access can call this before sending data. It can then pass - entire structures if the structure offset bit is set.
-
- -

support for copy and monitor

-

copy and monitor are not used in this project. -They are intended for use by pvAccess and by pvAccess servers. -They are provided with this project because the code depends only on -pvData itself. -

-

This document describes C++ specific code. - -pvRequest.html -provides a language independent overview of copy and monitor. -

-

-NOTE:pvRequest.html must be updated since it is based on an earlier version of pvCopy that -had knowlege of PVRecord. The C++ version was implemented in pvDatabaseCPP -and the Java version on pvIOCJava. -At present only the C++ version of the new API for pvCopy is implemented. -

-

Copy provides: -

-
createRequest
-
- The Channel create methods in pvAccess all have an argument - PVStructure pvRequest.
- Given an ascii string createRequest creates a PVStructure that provides - a pvData representation of the information from the ascii string. - It is this structure that can be passed to the channel create methods.
- The information in a pvRequest selects an arbitrarary subset of the - fields in a top level structure that resides in the server. - In addition options can be specified. Both global and field specific - options can be specified. -
-
pvCopy
-
This is a faculity used by channel providers. - It provides client specific code that manages a copy of an arbitrary - subset of the fields in a top level structure that resides in the - provider. It also allows provider access to options specified - by the client. -
-
-Monitor provides: -
-
monitor
-
This is support code for channel providers that implement channel - monitor. It, together with the queue facility, provides support for - monitor queues. -
-
monitorPlugin
-
This is support for implementing monitor plugins. - A monitor plugin can be developed that has no knowledge - of pvAccess but only pvData. -
-
-

- -

support for copy

-

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. -

- -

createRequest

-

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
-}
-
-

pvCopy

-

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  &copyPVStructure,
-        BitSetPtr const  &bitSet);
-     void updateCopySetBitSet(
-        PVStructurePtr const  &copyPVStructure,
-        BitSetPtr const  &bitSet);
-    void updateCopyFromBitSet(
-        PVStructurePtr const  &copyPVStructure,
-        BitSetPtr const  &bitSet);
-    void updateMaster(
-        PVStructurePtr const  &copyPVStructure,
-        BitSetPtr const  &bitSet);
-    PVStructurePtr getOptions(std::size_t fieldOffset);
-...
-};
-
-where -
-
PVCopyTraverseMasterCallback::nextMasterPVField
-
- PVCopyTraverseMasterCallback is a callback which must - be implemented by the code that uses pvCopy, normally - the channel provider. It has the single method nextMasterPVField -
- nextMasterPVField is called for each field in the master - as a result of a call to traverseMaster. -
-
create
-
- This is the method for creating a PVCopy instance.
-
-
pvMaster
-
the top level sructure managed by the server.
-
pvRequest
-
selects the set of subfields desired - and options for each field.
-
structureName
-
the name for the top level of any PVStructure created. -
-
-
-
getPVMaster
-
- Gets the top level structure from pvMaster. -
-
traverseMaster
-
- Traverse all fields of the top level structure of pvMaster. - For each field the callback is called. -
-
getStructure
-
- Get the introspection interface for a PVStructure for e copy. -
-
createPVStructure
-
Create a copy instance. - Monitors keep a queue of monitor elements. - Since each element needs a PVStructure, multiple top level structures - will be created. -
-
getCopyOffset
-
Given a field in pvMaster. - return the offset in copy for the same field. - A value of std::string::npos means that the copy does not have this field. - Two overloaded methods are provided. The first is called if - the field of master is not a structure. The second is for - subfields of a structure. -
-
getMasterPVField
-
- Given a offset in the copy get the corresponding field in pvMaster. -
-
initCopy
-
- Initialize the fields in copyPVStructure - by giving each field the value from the corresponding field in pvMaster. - bitSet will be set to show that all fields are changed. - This means that bit set will have the value {0}. -
-
updateCopySetBitSet
-
- Set all fields in copyPVStructure to the value of the corresponding field - in pvMaster. Each field that is changed has it's corresponding - bit set in bitSet. -
-
updateCopyFromBitSet
-
- For each set bit in bitSet set the field in copyPVStructure to the value - of the corrseponding field in pvMaster. -
-
updateMaster
-
- For each set bit in bitSet set the field in pvMaster to the value - of the corrseponding field in copyPVStructure. - -
-
getOptions
-
- Get the options for the field at the specified offset. - A NULL is returned if no options were specified for the field. - If options were specified,PVStructurePtr is - a structure with a set of PVString subfields that specify name,value - pairs. name is the subField name and value is the subField value. -
-
- - - - -

support for monitor

-

This consists of two components: -

-
monitor
-
Used by code that implements pvAccess montors.
-
monitorPlugin
-
Code that provides special semantics for monitors.
-
-

-

monitor

-
-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

-

MonitorElement holds the data for one element of a monitor queue. -It has the fields: -

-
pvStructurePtr
-
A top level structure with data values at the time the monitors occurs.
-
changedBitSet
-
Shows which fields have changed since the previous monitor.
-
overrunBitSet
-
Shows which fields have changed more han once since the previous monitor.
-
-

-

monitorElement queue

-

-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

-

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:

-
-
start
-
- Start monitoring. - This will result in a an inital monitor that has the current value - of all fields. -
-
stop
-
- Stop monitoring. -
-
poll
-
- Called to get a monitor element. - If no new elemants are available then a null pointer is returned. -
-
release
-
- Release the monotor element. - The caller owns the monitor element between the calls to poll and release. -
-
-
-

MonitorRequester

-

This must be implemented by a pvAccess client. -It has the methods:

-
-
monitorConnect
-
- A monitor has either connected of disconnected. -
-
monitorEvent
-
- A new monitor element is available. -
-
unlisten
-
- The channel is going away. The client cam no longer access the monitor. -
-
- -

monitorPlugin

-
-class MonitorPlugin
-{
-    virtual std::string const & getName() = 0;
-    virtual bool causeMonitor(
-        PVFieldPtr const &pvField,
-        PVStructurePtr const &pvTop,
-        MonitorElementPtr const &monitorElement) = 0;
-    virtual void monitorDone(
-        MonitorElementPtr const &monitorElement);
-    virtual void startMonitoring();
-    virtual void stopMonitoring();
-    virtual void beginGroupPut();
-    virtual void endGroupPut();
-};
-
-class MonitorPluginCreator
-{
-    virtual MonitorPluginPtr create(
-        FieldConstPtr const &field,
-        StructureConstPtr const &top,
-        PVStructurePtr const &pvFieldOptions) = 0;
-     virtual std::string const & getName() = 0;
-}
-
-class MonitorPluginManager
-{
-    static MonitorPluginManagerPtr get();
-    bool addPlugin(
-         std::string const &pluginName,
-         MonitorPluginCreatorPtr const &creator);
-    MonitorPluginCreatorPtr findPlugin(std::string const &pluginName);
-    void showNames();
-};
-
-
-

MonitorPlugin

-

MonitorPlugin must be implemented by the plugin implementation. -It has methods:

-
-
getName
-
Get the name of the plugin.
-
causeMonitor
-
- Should the value of pvField cause a monitor to be raised. - pvField and pvTop are fields in the top level structure - being monitored. monitorElement has the top level structure - for the copy. - The implementation should not modify the fields in the structure - being monitored. - Called with pvTop locked. -
-
monitorDone
-
- Called just before monitorElement will be given to client. - The plugin can change the data values and bitSets in monitorElement. - Called with pvTop unlocked. -
-
startMonitoring
-
- Monitoring is starting. -
-
stopMonitoring
-
- Monitoring is being stopped. -
-
beginGroupPut
-
- A set of puts is starting. - Called with pvTop locked. -
-
endGroupPut
-
- The set of puts is complete. - Called with pvTop locked. -
-
-

MonitorPluginCreator

-

MonitorPluginCreator must also be implemented by the plugin implementation. -It is called for each field instance that has options of the from -[plugin=name...] where name is the name of the plugin. -Note that a plugin instance will belong to a single client. -It has methods:

-
-
getName
-
Get the name of the plugin.
-
create
-
- Create a new plugin instance. - If the arguments are not compatible with the plugin a NULL shared pointer is - returned.
- pvFieldOptions is - a structure with a set of PVString subfields that specify name,value - pairs. name is the subField name and value is the subField value.
- Note that a plugin will below to a single client. -
-
-

MonitorPluginManager

-

MonitorPluginManager has the methods:

-
-
get
-
- MonitorPluginManager is a singleton. - The first call to get will create the single instance. - Further calls will rerurn the single instance. -
-
addPlugin
-
- Add a new plugin. -
-
findPlugin
-
- Find a plugin. A NULL shared pointer is reurned if it has not been added. -
-
showNames
-
- Show the names of all puugins that have been added. -
-
-

NOTE: -Should the method causeMonitor -have arguments pvField and pvTop -be defined so that they can not be modfied. -This would be posssible if the following was defined: -

-typedef std::tr1::shared_ptr<const PVField> PVFieldConstPtr;
-typedef std::tr1::shared_ptr<const PVStructure> PVStructureConstPtr;
-
-then the definition for causeMonitor could be: -
-virtual bool causeMonitor(
-        PVFieldConstPtr const &pvField,
-        PVStructureConstPtr const &pvTop,
-        MonitorElementPtr const &monitorElement) = 0;
-
-But just adding these definitions is not sufficent. -In addition all methods defined in pvDataCPP must be checked. -In particular many of the methods in Convert must have -their arguments modified. -Big job. -

-

monitorPlugin example

-

Example Plugin Overview

-

This section describes an example plugin that:

-
    -
  • Only raises monitors when a field changes value.
    - If no plugin is provided - the default is to raise a monitor when a put is issued to a field.
    • -
  • Optionally a change will not raise a monitor.
    - The change will, however, - appear if a put to another field raise a monitor.
    • -
-

As an example assume that a channel provided by pvAccess has a top level structure -that represents a power supply.

-
-structure powerSupply
-    structure alarm
-    structure timeStamp
-    structure power
-       double value
-       structure alarm
-       struvture display
-    structure voltage
-       double value
-       structure alarm
-       struvture display
-    structure current
-       double value
-       structure alarm
-       struvture display
-
-

A pvAccess client wants to create a monitor on the powerSupply as follows: -The client wants a top level structure that looks like: -

-structure powerSupply
-    structure alarm
-    structure timeStamp
-    structure power
-       double value
-    structure voltage
-       double value
-    structure current
-       double value
-
-In addition the client wants monitors to occur only when one of the monitored -fields changes value but not just because a put occured. -Also if only the timeStamp changes value then that should not cause a monitor. -

-

The example monitor plugin implements the semantics the -client wants. It can be attached to any field via the following options: -

-[plugin=onChange,raiseMonitor=value]
-
-This plugin will trigger a monitor for the field only if the field changes -value. In addition value equals false means do not raise a monotor -for changes to this field. -But if a change to another field does cause a monitor the change to this field -will be passed to the client. -

-

-Assume that the client has already connected to the channel. -The client can then issue the commands:

-
-std::string request("field(alarm[plugin=onChange]");
-request += ",timeStamp[plugin=onChange,raiseMonitor=false]";
-request += ",power.value[plugin=onChange";
-request += ",voltage.value[plugin=onChange";
-request += ",current.value[plugin=onChange";
-
-PVStructurePtr pvRequest = createRequest->createRequest(request);
-
-MonitorPtr monitor = channel->createMonitor(monitorRequester,pvRequest);
-
-

Example Plugin Code

-

The header file to create the example has the definition:

-
-class ExampleMonitorPlugin{
-public:
-    static void create();
-};
-
-

The implementation is:

-
-class OnChangePlugin : public MonitorPlugin
-{
-public:
-    virtual ~OnChangePlugin(){}
-    OnChangePlugin() {}
-    bool init(
-        FieldConstPtr const &field,
-        StructureConstPtr const &top,
-        PVStructurePtr const &pvFieldOptions)
-   {
-        pvField = getPVDataCreate()->createPVField(field);
-        raiseMonitor = true;
-        if(pvFieldOptions!=NULL) {
-            PVStringPtr pvString =
-                pvFieldOptions->getSubField<PVString>("raiseMonitor");
-                if(pvString!=NULL) {
-                    std::string value = pvString->get();
-                    if(value.compare("false")==0) raiseMonitor = false;
-                }
-        }
-        return true;
-   }
-   virtual std::string &getName(){return pluginName;}
-   virtual bool causeMonitor(
-        PVFieldPtr const &pvNew,
-        PVStructurePtr const &pvTop,
-        MonitorElementPtr const &monitorElement)
-   {
-       bool isSame = convert->equals(pvNew,pvField);
-       if(isSame) return false;
-       convert->copy(pvNew,pvField);
-       return raiseMonitor;
-   }
-private:
-   PVFieldPtr pvField;
-   bool raiseMonitor;
-};
-class OnChangePluginCreator : public MonitorPluginCreator
-{
-public:
-    virtual std::string &getName(){return pluginName;}
-    virtual MonitorPluginPtr create(
-        FieldConstPtr const &field,
-        StructureConstPtr const &top,
-        PVStructurePtr const &pvFieldOptions)
-   {
-       OnChangePluginPtr plugin(new OnChangePlugin());
-       bool result = plugin->init(field,top,pvFieldOptions);
-       if(!result) return MonitorPluginPtr();
-       return plugin;
-   }
-
-};
-
-void ExampleMonitorPlugin::create()
-{
-    static OnChangePluginCreatorPtr plugin;
-    static Mutex mutex;
-    Lock xx(mutex);
-    if(plugin==NULL) {
-        plugin = OnChangePluginCreatorPtr(new OnChangePluginCreator());
-        MonitorPluginManager::get()->addPlugin(pluginName,plugin);
-    }
-}
-
- - -
- - diff --git a/documentation/pvDataCPP_20140708.html b/documentation/pvDataCPP_20140708.html deleted file mode 100644 index 1823fa4..0000000 --- a/documentation/pvDataCPP_20140708.html +++ /dev/null @@ -1,5380 +0,0 @@ - - - - - - EPICS pvDataCPP - - - - - - - - -
-

EPICS pvDataCPP

- - -

EPICS v4 Working Group, Working Draft, 08-July-2014

- -
-
Latest version:
-
pvDataCPP.html -
-
This version:
-
pvDataCPP_20140708.html -
-
Previous version:
-
pvDataCPP_20140501.html -
-
Editors:
-
Marty Kraimer, BNL
-
Michael Davidsaver, BNL
-
Matej Sekoranja, CosyLab
-
- -

This product is made available subject to acceptance of the EPICS open source -license.

-
-
- -

Abstract

- -

EPICS Version 4 provides efficient -storage, access, and communication, of memory resident structured data. -pvData is the storage compoment. -pvDataCPP is the C++ implementation of pvData. -It is one part of the set of related products in the EPICS -V4 control system programming environment:
-relatedDocumentsV4.html -

- - -

Status of this Document

- -

This is the 08-July-2014 version of the C++ implementation of pvData. -

- -

RELEASE_NOTES.md provides changes since the last release. -TODO.md describes things to do before the next release. -

- - -
-

Table of Contents

-
-
- -

Introduction

- -

pvData is one of a set of related projects. It describes and implements -data that the other projects support. Thus it is not useful by itself but -understanding pvData is required in order to understand the other projects. The -reader should also become familar with project pvAccess, which is -located via the same sourceforge site as this project.

- -

The Java and C++ implementation of pvData implement the same data model but -differ in implementation because of the differences between Java and C++.

- -

It is a good idea to read all of pvDataJava.html but read at least the -first two chapters:

-
-
Introduction
-
A brief descripton of pvData.
-
PVData Meta Language
-
A language used to describe data.
-
- -

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:

-
-
pvDataAPP/pv
-
This subdirectory contains all the public interfaces that describe pvData. - The section from Namespace and Memory Management - through Conversion discuss these interfaces. -
-
pvDataApp/property
-
This section has support for managing "standard" fields. -
-
pvDataApp/misc
-
This section has support for facilities required by implementation code.
-
copy and monitor
-
These sections provide pvData support for implementing pvAccess providers.
-
- -

Examples

-

This section provides some examples of creating and accessing both introspection and -data interfaces. The first time reader may not understand them but hopefully will get an -idea of how pvData works. After reading the rest of this document the examples will -be much easier to understand. -

-

The documentation directory for this project has a file examples.zip. -It has the code for the examples. -After it is unzipped:

-
-cd examples/configure
-cp ExampleRELEASE.local RELEASE.local
-#edit RELEASE.local
-cd ..
-make
-bin/linux-x86_64/introspectMain 
-bin/linux-x86_64/dataMain
-
-

-

The examples assume that the following statements have been issued:

-
-using std::cout;
-using std::endl;
-FieldCreatePtr fieldCreate = getFieldCreate();
-PVDataCreatePtr pvDataCreate = getPVDataCreate();
-StandardFieldPtr standardField = getStandardField();
-StandardPVFieldPtr standardPVField = getStandardPVField();
-
-

These provide access to most of pvData:

-
-
fieldCreate
-
This creates instances of introspection objects. - It also provides fieldBuilder, which provides an easier way to create introspection objects. -
-
pvDataCreate
-
This creates instances of data objects. -
-
standardField
-
This provides support for introspection obects for standard fields, - Standard fields are alarm, timeStamp, display, enumerated structure, and value alarm. -
-
standardPVField
-
This provides support for data obects for standard fields, -
-
- - -

Introspection Examples

-

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.

-

Three ways to create a structure

-

The following is the hardest way to create structure that has a double value field and a time stamp field: -It uses only createField. -

-
-    size_t n = 3;
-    StringArray names;
-    names.reserve(n);
-    FieldConstPtrArray fields;
-    fields.reserve(n);
-    names.push_back("secondsPastEpoch");
-    fields.push_back(fieldCreate->createScalar(pvLong));
-    names.push_back("nanoSeconds");
-    fields.push_back(fieldCreate->createScalar(pvInt));
-    names.push_back("userTag");
-    fields.push_back(fieldCreate->createScalar(pvInt));
-    StructureConstPtr timeStamp = fieldCreate->createStructure(names,fields);
-    size_t ntop = 2;
-    StringArray topnames;
-    topnames.reserve(ntop);
-    FieldConstPtrArray topfields;
-    topfields.reserve(ntop);
-    topnames.push_back("value");
-    topfields.push_back(fieldCreate->createScalar(pvDouble));
-    topnames.push_back("timeStamp");
-    topfields.push_back(timeStamp);
-    StructureConstPtr doubleScalar =
-        fieldCreate->createStructure(topnames,topfields);
-    cout << doubleScalar->dump(cout) << endl;
-
-

Using FieldBuilder the same can be done via:

-
-    StructureConstPtr doubleScalarHard =
-    getFieldCreate()->createFieldBuilder()->
-        add("value",pvDouble) ->
-        addNestedStructure("timeStamp")->
-            setId("time_t")->
-            add("secondsPastEpoch", pvLong)->
-            add("nanoSeconds", pvInt)->
-            add("userTag", pvInt)->
-            endNested()->
-        createStructure();
-    cout << doubleScalarHard->dump(cout) << endl;
-
-

The easiest way to produce the structure is:

-
-    StructureConstPtr stringArrayEasy =
-         getStandardField()->scalarArray(pvString,"alarm,timeStamp");
-    cout << stringArrayEasy->dump(cout) << "\n\n";
-
-These three ways produce: -
-hardest way
-structure
-    double value
-    structure timeStamp
-        long secsPastEpoch
-        int nanoseconds
-        int userTag
-
-hardway
-structure
-    double value
-    time_t timeStamp
-        long secsPastEpoch
-        int nanoseconds
-        int userTag
-
-easy way
-uri:ev4:nt/2012/pwd:NTScalarArray
-    string[] value
-    alarm_t alarm
-        int severity
-        int status
-        string message
-    time_t timeStamp
-        long secondsPastEpoch
-        int nanoSeconds
-        int userTag
-
-

An easy way to create a structure with a string array value field and an alarm and time stamp is -via standardField:

-
-    StructureConstPtr stringArrayEasy =
-        standardField->scalarArray(pvString,"alarm,timeStamp");
-    cout <<stringArrayEasy->dump(cout) << endl;
-
-It produces : -
-uri:ev4:nt/2012/pwd:NTScalarArray
-    string[] value
-    alarm_t alarm
-        int severity
-        int status
-        string message
-    time_t timeStamp
-        long secondsPastEpoch
-        int nanoSeconds
-        int userTag
-0x607188
-
-

enumerated structure

-

An enumerated structure is a structure with two sub-fields: -index, which is an int, and choices, which is an array of string. -The following examples create a structure which has a field names value, which -is an enumerated structure and additional fields. -A hard way to create an structure with an enumerated value field and a time stamp is:

-
-    StructureConstPtr enum_t =
-    fieldCreate->createFieldBuilder()->
-        setId("enum_t")->
-        add("index", pvInt)->
-        addArray("choices", pvString)->
-        createStructure();
-
-    StructureConstPtr ntEnumHard =
-    fieldCreate->createFieldBuilder()->
-        setId("uri:ev4:nt/2012/pwd/NTEnum")->
-        add("value", enum_t)->
-        addNestedStructure("timeStamp")->
-            setId("time_t")->
-            add("secondsPastEpoch", pvLong)->
-            add("nanoSeconds", pvInt)->
-            add("userTag", pvInt)->
-            endNested()->
-        createStructure();
-    cout <<ntEnumHard->dump(cout) << endl;
-
-It produces: -
-uri:ev4:nt/2012/pwd/NTEnum
-    enum_t value
-        int index
-        string[] choices
-    time_t timeStamp
-        long secondsPastEpoch
-        int nanoSeconds
-        int userTag
-
-

The following is an easy way. Note that it has two additional -fields: alarm and timeStamp:

-
-    StructureConstPtr ntEnumEasy = getStandardField()->enumerated("alarm,timeStamp");
-    cout <<ntEnumEsay->dump(cout) << endl;
-
-It produces: -
-uri:ev4:nt/2012/pwd:NTEnum
-    enum_t value
-        int index
-        string[] choices
-    alarm_t alarm
-        int severity
-        int status
-        string message
-    time_t timeStamp
-        long secondsPastEpoch
-        int nanoSeconds
-        int userTag
-
- -

union example

-

The following creates a union and a structure with a union value field:

- -
-    UnionConstPtr ntunion =
-    fieldCreate->createFieldBuilder()->
-        add("doubleValue", pvDouble)->
-        add("intValue", pvInt)->
-        add("timeStamp",standardField->timeStamp())->
-        createUnion();
-    cout <<ntunion->dump(cout) << endl;
-
-    StructureConstPtr unionValue = standardField->regUnion(punion,"alarm,timeStamp");
-    cout <<unionValue->dump(cout) << endl;
-
-It produces: -
-union
-    double doubleValue
-    int intValue
-    time_t timeStamp
-        long secondsPastEpoch
-        int nanoSeconds
-        int userTag
-
-structure with value field being a union
-uri:ev4:nt/2012/pwd:NTUnion
-    union value
-        double doubleValue
-        int intValue
-        time_t timeStamp
-            long secondsPastEpoch
-            int nanoSeconds
-            int userTag
-    alarm_t alarm
-        int severity
-        int status
-        string message
-    time_t timeStamp
-        long secondsPastEpoch
-        int nanoSeconds
-        int userTag
-
- -

union array example

-

The following:

-
-    UnionArrayConstPtr unionArray = fieldCreate->createUnionArray(
-        fieldCreate->createVariantUnion());
-    cout << unionArray->dump(cout) << "\n\n";
-
-

Produces

-
-any[]
-any
-0x607188
-
-

power supply

-

The following creates a more complex structure:

-
-    StructureConstPtr powerSupply =
-    fieldCreate->createFieldBuilder()->
-        add("alarm",standardField->alarm()) ->
-        add("timestamp",standardField->timeStamp()) ->
-        addNestedStructure("power") ->
-           add("value",pvDouble) ->
-           add("alarm",standardField->alarm()) ->
-           endNested()->
-        addNestedStructure("voltage") ->
-           add("value",pvDouble) ->
-           add("alarm",standardField->alarm()) ->
-           endNested()->
-        addNestedStructure("current") ->
-           add("value",pvDouble) ->
-           add("alarm",standardField->alarm()) ->
-           endNested()->
-        createStructure();
-    std::cout << powerSupply->dumpValue(cout) <<std::endl;
-
-It produces: -
-structure
-    alarm_t alarm
-        int severity
-        int status
-        string message
-    time_t timestamp
-        long secondsPastEpoch
-        int nanoSeconds
-        int userTag
-    structure power
-        double value
-        alarm_t alarm
-            int severity
-            int status
-            string message
-    structure voltage
-        double value
-        alarm_t alarm
-            int severity
-            int status
-            string message
-    structure current
-        double value
-        alarm_t alarm
-            int severity
-            int status
-            string message
-
-

Data Examples

-

The examples all produce a top level structure.

-

scalar example

-
-    PVStructurePtr doubleValue = getPVDataCreate()->createPVStructure(
-        getStandardField()->scalar(pvDouble,"alarm,timeStamp"));
-    PVDoublePtr pvdouble =
-        doubleValue->getSubField<PVDouble>("value");
-    pvdouble->put(1e5);
-    cout << doubleValue->dumpValue(cout) << endl;
-    double value = doubleValue->getSubField<PVDouble>("value")->get();
-    cout << "from get " << value << "\n\n";
-
-This produces: -
-uri:ev4:nt/2012/pwd:NTScalar 
-    double value 100000
-    alarm_t alarm
-        int severity 0
-        int status 0
-        string message 
-    time_t timeStamp
-        long secondsPastEpoch 0
-        int nanoSeconds 0
-        int userTag 0
-0x607268
-from get 100000
-
-

array example

-
-    PVStructurePtr doubleArrayValue = pvDataCreate->createPVStructure(
-        standardField->scalarArray(pvDouble,"alarm,timeStamp"));
-    PVDoubleArrayPtr pvDoubleArray =
-         doubleArrayValue->getSubField<PVDoubleArray>("value");
-    size_t len = 10;
-    shared_vector<double> xxx(len);
-    for(size_t i=0; i< len; ++i) xxx[i] = i;
-    shared_vector<const double> data(freeze(xxx));
-    pvDoubleArray->replace(data);
-    cout << doubleArrayValue->dumpValue(cout) << endl;
-    
-    shared_vector<const double>  getData = pvDoubleArray->view();
-    cout << "via getData";
-    for (size_t i=0; i< len; ++i) cout << " " << getData[i];
-    cout << endl;
-
-This produces: -
-uri:ev4:nt/2012/pwd:NTScalarArray 
-    double[] value [0,1,2,3,4,5,6,7,8,9]
-    alarm_t alarm
-        int severity 0
-        int status 0
-        string message 
-    time_t timeStamp
-        long secondsPastEpoch 0
-        int nanoSeconds 0
-        int userTag 0
-0x607268
-via getData 0 1 2 3 4 5 6 7 8 9
-
-

enumerated example

-
-    PVStructurePtr pvntenum = pvDataCreate->createPVStructure(
-         standardField->enumerated("alarm,timeStamp"));
-    cout << pvntenum->dumpValue(cout) << "\n\n";
-
-This produces: -
-uri:ev4:nt/2012/pwd:NTEnum 
-    enum_t value
-        int index 0
-        string[] choices []
-    alarm_t alarm
-        int severity 0
-        int status 0
-        string message 
-    time_t timeStamp
-        long secondsPastEpoch 0
-        int nanoSeconds 0
-        int userTag 0
-0x607268
-
-

power supply example

-
-    StructureConstPtr powerSupply =
-    fieldCreate->createFieldBuilder()->
-        add("alarm",alarm) ->
-        add("timestamp",timeStamp) ->
-        addNestedStructure("power") ->
-           add("value",pvDouble) ->
-           add("alarm",alarm) ->
-           endNested()->
-        addNestedStructure("voltage") ->
-           add("value",pvDouble) ->
-           add("alarm",alarm) ->
-           endNested()->
-        addNestedStructure("current") ->
-           add("value",pvDouble) ->
-           add("alarm",alarm) ->
-           endNested()->
-        createStructure();
-    PVStructurePtr pvpowerSupply = pvDataCreate->createPVStructure(powerSupply);
-    cout << pvpowerSupply->dumpValue(cout) << endl;
-
-This produces: -
-structure 
-    alarm_t alarm_t
-        int severity 0
-        int status 0
-        string message 
-    time_t timestamp_t
-        long secondsPastEpoch 0
-        int nanoSeconds 0
-        int userTag 0
-    structure power
-        double value 0
-        alarm_t alarm
-            int severity 0
-            int status 0
-            string message 
-    structure voltage
-        double value 0
-        alarm_t alarm
-            int severity 0
-            int status 0
-            string message 
-    structure current
-        double value 0
-        alarm_t alarm
-            int severity 0
-            int status 0
-            string message 
-0x607268
-
-

union example

-
-    PVStructurePtr pvStructure = pvDataCreate->createPVStructure(
-        standardField->regUnion(
-            fieldCreate->createFieldBuilder()->
-                add("doubleValue", pvDouble)->
-                add("intValue", pvInt)->
-                add("timeStamp",standardField->timeStamp())->
-                createUnion(),
-            "alarm,timeStamp"));
-    PVStructurePtr pvTimeStamp =
-        pvStructure->getSubField<PVUnion>("value")->select<PVStructure>(2);
-    pvTimeStamp->getSubField<PVLong>("secondsPastEpoch")->put(1000);
-    cout << pvStructure->dumpValue(cout) << "\n";
-    pvStructure->getSubField<PVUnion>("value")->select<PVDouble>(0)->put(1e5);
-    cout << pvStructure->dumpValue(cout) << "\n\n";
-
-This produces: -
-uri:ev4:nt/2012/pwd:NTUnion
-    union value
-        time_t
-            long secondsPastEpoch 1000
-            int nanoSeconds 0
-            int userTag 0
-    alarm_t alarm
-        int severity 0
-        int status 0
-        string message
-    time_t timeStamp
-        long secondsPastEpoch 0
-        int nanoSeconds 0
-        int userTag 0
-0x60a2c8
-uri:ev4:nt/2012/pwd:NTUnion
-    union value
-        double  100000
-    alarm_t alarm
-        int severity 0
-        int status 0
-        string message
-    time_t timeStamp
-        long secondsPastEpoch 0
-        int nanoSeconds 0
-        int userTag 0
-0x60a2c8
-
- -

varient union example

-
-    PVStructurePtr pvStructure = pvDataCreate->createPVStructure(
-        standardField->variantUnion("alarm,timeStamp"));
-    PVStructurePtr pvTimeStamp =
-        pvDataCreate->createPVStructure(standardField->timeStamp());
-    pvStructure->getSubField<PVUnion>("value")->set(pvTimeStamp);
-    pvTimeStamp->getSubField<PVLong>("secondsPastEpoch")->put(1000);
-    cout << pvStructure->dumpValue(cout) << "\n";
-    pvStructure->getSubField<PVUnion>("value")->set(
-        pvDataCreate->createPVScalar(pvDouble));
-    PVDoublePtr pvValue = static_pointer_cast<PVDouble>(
-        pvStructure->getSubField<PVUnion>("value")->get());
-    pvValue->put(1e5);
-    cout << pvStructure->dumpValue(cout) << "\n\n";
-
-This produces: -
-uri:ev4:nt/2012/pwd:NTUnion
-    any value
-        time_t
-            long secondsPastEpoch 1000
-            int nanoSeconds 0
-            int userTag 0
-    alarm_t alarm
-        int severity 0
-        int status 0
-        string message
-    time_t timeStamp
-        long secondsPastEpoch 0
-        int nanoSeconds 0
-        int userTag 0
-0x60a2c8
-uri:ev4:nt/2012/pwd:NTUnion
-    any value
-        double  100000
-    alarm_t alarm
-        int severity 0
-        int status 0
-        string message
-    time_t timeStamp
-        long secondsPastEpoch 0
-        int nanoSeconds 0
-        int userTag 0
-0x60a2c8
-
- -

big union example

-
-    PVStructurePtr pvStructure = pvDataCreate->createPVStructure(
-        standardField->regUnion(
-            fieldCreate->createFieldBuilder()->
-                add("doubleValue", pvDouble)->
-                addArray("doubleArrayValue",pvDouble)->
-                addNestedUnion("unionValue") ->
-                    add("doubleValue", pvDouble)->
-                    add("alarm",standardField->alarm()) ->
-                    endNested() ->
-                addNestedStructure("structValue") ->
-                    add("doubleValue", pvDouble)->
-                    addArray("doubleArrayValue",pvDouble)->
-                    endNested() ->
-                addNestedUnionArray("unionArrayValue") ->
-                    add("doubleValue", pvDouble)->
-                    add("alarm",standardField->alarm()) ->
-                    endNested() ->
-                addNestedStructureArray("structArrayValue") ->
-                    add("doubleValue", pvDouble)->
-                    addArray("doubleArrayValue",pvDouble)->
-                    endNested() ->
-                createUnion(),
-            "alarm,timeStamp"));
-    cout << "introspection\n";
-    cout <<pvStructure->getStructure()->dump(cout) << endl;
-    cout << "data\n";
-    cout << pvStructure->dumpValue(cout) << "\n";
-    PVUnionPtr pvUnion = pvStructure->getSubField<PVUnion>("value");;
-    pvUnion->select("doubleValue");
-    PVDoublePtr pvDouble = pvUnion->get<PVDouble>();
-    pvDouble->put(1.55);
-    cout << "select valueDouble\n";
-    cout << pvStructure->dumpValue(cout) << "\n";
-    cout << "value = " << pvDouble->get() << "\n";
-    pvUnion->select("structValue");
-    pvDouble = pvUnion->get<PVStructure>()->getSubField<PVDouble>("doubleValue");
-    pvDouble->put(1.65);
-    cout << "select structValue\n";
-    cout << pvStructure->dumpValue(cout) << "\n";
-    cout << "value = " << pvDouble->get() << "\n";
-
-This produces: -
-introspection
-uri:ev4:nt/2012/pwd:NTUnion
-    union value
-        double doubleValue
-        double[] doubleArrayValue
-        union unionValue
-            double doubleValue
-            alarm_t alarm
-                int severity
-                int status
-                string message
-        structure structValue
-            double doubleValue
-            double[] doubleArrayValue
-        union[] unionArrayValue
-            union[]
-                union
-                    double doubleValue
-                    alarm_t alarm
-                        int severity
-                        int status
-                        string message
-        structure[] structArrayValue
-            structure[]
-                structure
-                    double doubleValue
-                    double[] doubleArrayValue
-    alarm_t alarm
-        int severity
-        int status
-        string message
-    time_t timeStamp
-        long secondsPastEpoch
-        int nanoSeconds
-        int userTag
-0x60a2c8
-data
-uri:ev4:nt/2012/pwd:NTUnion
-    union value
-        (none)
-    alarm_t alarm
-        int severity 0
-        int status 0
-        string message
-    time_t timeStamp
-        long secondsPastEpoch 0
-        int nanoSeconds 0
-        int userTag 0
-0x60a2c8
-select valueDouble
-uri:ev4:nt/2012/pwd:NTUnion
-    union value
-        double  1.55
-    alarm_t alarm
-        int severity 0
-        int status 0
-        string message
-    time_t timeStamp
-        long secondsPastEpoch 0
-        int nanoSeconds 0
-        int userTag 0
-0x60a2c8
-value = 1.55
-select structValue
-uri:ev4:nt/2012/pwd:NTUnion
-    union value
-        structure
-            double doubleValue 1.65
-            double[] doubleArrayValue []
-    alarm_t alarm
-        int severity 0
-        int status 0
-        string message
-    time_t timeStamp
-        long secondsPastEpoch 0
-        int nanoSeconds 0
-        int userTag 0
-0x60a2c8
-value = 1.65
-
- -

Namespace and Memory Management

- -

Namespace

- -

All code in project pvDataCPP appears in namespace:

-
namespace epics { namespace pvData {
-     // ...
-}}
- -

Memory Managemment

- -

Many pvDataCPP introspection and data objects are designed to be shared. They are -made availiable via std::tr1::shared_ptr. -The following naming convention is used -in typedefs:

-
-
Ptr
-
When Ptr appears it stands for std::tr1::shared_ptr. -
-
-

For example:

-
-typedef PVScalarValue<boolean> PVBoolean;
-typedef std::tr1::shared_ptr<PVBoolean> PVBooleanPtr;
-
- -

pvDataApp/pv

- -

Directory pvDataApp/pv has header files that completely describe pvData. -The implementation is provided in directory pvDataApp/factory. -Test programs appears in testApp/pv.

- -

NOTES:

-
-
interface
-
The documention uses the word interface. - This is an analogy with how Java defines interface. - C++ does not have interfaces but directory pv defines classes - with public members that are similar to the Java interfaces. Most of the - implementation is in factory.
-
Naming Convertions
-
The naming convertions for variables, methods, and classes follow the - Java convertions, i. e. class name begin with an upper case letter, - variables and methods begin with a lower case letter.
-
- -

A PVStructure is a field that contains an array of subfields. Each field has -code for accessing the field. The interface for each field is an interface that -extends PVField. Each field also has an introspection interface, which an -extension of Field. The next few sections describes the complete set of C++ -introspection and data interfaces for pvData.

- -

Class FieldCreate creates introspection objects. Class PVDataCreate creates -data objects. Class Convert provides a rich set of methods for converting and -copying data between fields.

- -

Directory pvDataApp/pv has the following header files:

-
-
pvType.h
-
C++ definitions for primitive types.
-
pvIntrospect.h
-
A complete description of the introspection interfaces.
-
pvData.h
-
A complete description of the data interfaces.
-
convert.h
-
A facility that converts between data fields.
-
pvSubArrayCopy.h
-
This provides a facility that performs array coping between - arrays that have the same type.
-
standardField.h
-
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.
-
- -

pvType.h

- -

This provides C/C++ definitions for the pvData primitive types: boolean, -byte, short, int, long, ubyte,ushort, uint,u long,float, double, and string. -Because pvData is network data, the C++ implementation must implement the -proper semantics for the primitive types.

- -

pvType.h provides the proper semantics.

- -

It includes the definitions:

-
-typedef /*lots of stuff*/ boolean
-
-typedef int8_t   int8;
-typedef int16_t  int16;
-typedef int32_t  int32;
-typedef int64_t  int64;
-typedef uint8_t   uint8;
-typedef uint16_t  uint16;
-typedef uint32_t uint32;
-typedef uint64_t uint64;
-// float and double are types
-
-typedef std::vector<std::string> StringArray;
-typedef std::tr1::shared_ptr<StringArray> StringArrayPtr;
-inline std::string * get(StringArray &value);
-inline std::string const * get(StringArray const &value);
-inline std::string * get(StringArrayPtr &value);
-inline std::string const * get(StringArrayPtr const &value);
-}
-inline StringArray & getVector(StringArrayPtr &value);
-inline StringArray const & getVector(StringArrayPtr const &value);
-typedef std::vector<std::string>::iterator StringArray_iterator;
-typedef std::vector<std::string>::const_iterator StringArray_const_iterator;
-
- -

where

-
-
boolean
-
A c++ bool has the semantics required for boolean. Only the name is - different. C++ code can use either bool or boolean.
-
int8,...,uint64
-
Integers present a problem because short, int, and long are C++ - reserved words but do not have a well defined number of bits. Thus for - C++ the definitions above are used in C++ code. The above definitions - have worked on all C++ implementations tested at present. If they break - in a future implementation they should be changes via "#ifdef" - preprocessor statements.
-
std::string
-
pvData requires that a string be an immutable string that is transfered - over the network as a UTF8 encoded string. Since std::string implements - copy on write semantics, it can be used for support for immutable - strings. It can also be serialized/deserialized as a UTF8 encoded string. - Because it is not a C++ primitive the first letter is capitalized. This - is the same convention the Java implementation uses. - Note that string is treated like a primitive type.
-
StringArray definitions
-
typedefs are provided for an array of std::strings, - which is a std::vector<std::string>. - This is used by introspection. -
-
-

TBD -

-
boolean
-
Question for Michael. Why isn't the definition of boolean just - 
-typedef uint8_t boolean;
-
-
printer.h
-
Not documented. Is this needed? Nothing currently uses it.
-
-

- -

pvIntrospect.h

- -

This subsection describes pvIntrospect.h This file is quite big so rather -than showing the entire file, it will be described in parts.

- -

The primary purpose for pvData is to support network access to structured data. -pvAccess transports top level pvStructures. In addition a pvAccess server holds -a set of pvnames, where each name is a unique name in the local network. -This is also refered to as the channel name. -

- -

Given a pvname , it is possible to introspect the types of the associated data -access to data. The reflection and data interfaces are separate because the -data may not be available. For example when a pvAccess client connects to a pvname, -the client library can obtain the reflection information without obtaining any -data. Only when a client issues an I/O request will data be available. This -separation is especially important for arrays and structures so that a client -can discover the type without requiring that a large data array or structure be -transported over the network.

- -

Type Description

- -

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:

-
-
scalar
-
A scalar of one of the scalar types.
-
scalarArray
-
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 types can be different.
-
structureArray
-
An array where each element is a structure. Each element has the same - structure introspection interface.
-
union_t
-
This is like a structure that has a single subfield. - The type for the subfield can either be any type, which is called a varient union, - of can be one od a specified set of types. - In the data interfaces the type can be changed dynamically. -'
-
unionArray
-
An array where each element is a union. Each element has the same - union introspection interface.
-
- -

ScalarType is one of the following:

-
-
pvBoolean
-
Has the value false or true.
-
pvByte
-
A signed 8 bit integer.
-
pvShort
-
A signed 16 bit integer.
-
pvInt
-
A signed 32 bit integer.
-
pvLong
-
A signed 64 bit integer.
-
pvUByte
-
An unsigned 8 bit integer.
-
pvUShort
-
An unsigned 16 bit integer.
-
pvUInt
-
An unsigned 32 bit integer.
-
pvULong
-
An unsigned 64 bit integer.
-
pvFloat
-
A IEEE float.
-
pvDouble
-
A IEEE double,
-
pvString
-
An immutable string.
-
- -

TypeFunction is a set of convenience methods for Type

-
-
name
-
Returns the name of the type.
-
- -

ScalarTypeFunction is a set of convenience methods for ScalarType

-
-
isInteger
-
Is the scalarType an integer type, i.e. one of pvByte,...pvULong.
-
isUInteger
-
Is the scalarType an unsigned integer type, i.e. one of - pvUByte,...pvULong
-
isNumeric
-
Is the scalarType numeric, i.e. pvByte,...,pvDouble.
-
isPrimitive
-
Is the scalarType primitive, i.e. not pvString
-
name
-
Returns the name of the scalarType.
-
getScalarType
-
Given a string of the form std::string("boolean"),...,std::string("string") - return the scalarType.
-
elementSize
-
Returns the size in bytes of an instance of the scalarType.
-
- -

Introspection Description

- -

This section describes the reflection interfaces which provide the -following:

-
-
Field
-
A field: -
    -
  • Has a Type.
    • -
  • Can be converted to a string.
    • -
  • Can be shared. A reference count is kept. When it becomes 0 the - instance is automatically deleted.
    • -
-
-
Scalar
-
A scalar has a scalarType
-
ScalarArray
-
The element type is a scalarType
-
Structure
-
Has fields that can be any of the supported types.
-
StructureArray
-
The field holds an array of structures. Each element has the same - Structure interspection interface. A pvAccess client can only get/put - entire PVStructure elements NOT subfields of array elements.
-
Union
-
- This has two flavors: a varient union or a union of a fixed set - of types. A PVUnion will have a single subfield. - If the union introspection interface is a varient union then - the single field can be of any type and has the name any. - If the union is not a varient type then the type can be one of - a fixed set of types and a name associated with the type. - The union introspection interface has a field array and a string - array that has the fixed set of types and associated names. -
-
UnionArray
-
- This is an array of unions. A PVUnionArray is an array - of PVUnions. Each element has the same interspection interface - but the subfield of each element can have a different type. -
-
FieldBuilder
-
This is a convenience interface that makes it easier to create - top introspection interfaces. -
-
FieldCreate
-
This is an interface that provides methods to create introspection - interfaces. A factory is provides to create FieldCreate.
-
getFieldCreate
-
Gets a pointer to the single instance of FieldCreate.
-
-

Field,Scalar,ScalarArray,Structure,StructureArray,Union,UnionArray

-
class Field;
-class Scalar;
-class ScalarArray;
-class Structure;
-class StructureArray;
-class Union;
-class UnionArray;
-
-typedef std::tr1::shared_ptr<const Field> FieldConstPtr;
-typedef std::vector<FieldConstPtr> FieldConstPtrArray;
-typedef std::tr1::shared_ptr<const Scalar> ScalarConstPtr;
-typedef std::tr1::shared_ptr<const ScalarArray> ScalarArrayConstPtr;
-typedef std::tr1::shared_ptr<const Structure> StructureConstPtr;
-typedef std::tr1::shared_ptr<const StructureArray> StructureArrayConstPtr;
-typedef std::tr1::shared_ptr<const Union> UnionConstPtr;
-typedef std::tr1::shared_ptr<const UnionArray> UnionArrayConstPtr;
-
-
-class Field :
-    virtual public Serializable,
-    public std::tr1::enable_shared_from_this<Field>
-{
-public:
-    POINTER_DEFINITIONS(Field);
-    virtual ~Field();
-    Type getType() const{return m_type;}
-    virtual std::string getID() const = 0;
-    virtual std::ostream& dump(std::ostream& o) const = 0;
- ...
-};
-std::ostream& operator<<(std::ostream& o, const Field& field);
-
-class Scalar : public Field{
-public:
-    POINTER_DEFINITIONS(Scalar);
-    virtual ~Scalar();
-    typedef Scalar& reference;
-    typedef const Scalar& const_reference;
-
-    ScalarType getScalarType() const {return scalarType;}
-    virtual std::string getID() const;
-    virtual std::ostream& dump(std::ostream& o) const;
-    virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
-    virtual void deserialize(ByteBuffer *buffer, DeserializableContol *control);
- ...
-};
-
-class epicsShareClass Array : public Field{
-public:
-    POINTER_DEFINITIONS(Array);
-    virtual ~Array();
-    typedef Array& reference;
-    typedef const Array& const_reference;
- ...
-};
-
-
-class ScalarArray : public Field{
-public:
-    POINTER_DEFINITIONS(ScalarArray);
-    typedef ScalarArray& reference;
-    typedef const ScalarArray& const_reference;
-
-    ScalarArray(ScalarType scalarType);
-    ScalarType  getElementType() const {return elementType;}
-    virtual std::string getID() const;
-    virtual std::ostream& dump(std::ostream& o) const;
-    virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
-    virtual void deserialize(ByteBuffer *buffer, DeserializableControl *control);
- ...
-};
-
-class StructureArray : public Field{
-public:
-    POINTER_DEFINITIONS(StructureArray);
-    typedef StructureArray& reference;
-    typedef const StructureArray& const_reference;
-
-    StructureConstPtr  getStructure() const {return pstructure;}
-    virtual std::string getID() const;
-    virtual std::ostream& dump(std::ostream& o) const;
-    virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
-    virtual void deserialize(ByteBuffer *buffer, DeserializableControl *control);
- ...
-};
-
-class epicsShareClass UnionArray : public Field{
-public:
-    POINTER_DEFINITIONS(UnionArray);
-    typedef UnionArray& reference;
-    typedef const UnionArray& const_reference;
-    UnionConstPtr  getUnion() const {return punion;}
-    virtual std::string getID() const;
-    virtual std::ostream& dump(std::ostream& o) const;
-    virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
-    virtual void deserialize(ByteBuffer *buffer, DeserializableControl *control);
-};
-
-class Structure : public Field {
-public:
-    POINTER_DEFINITIONS(Structure);
-    typedef Structure& reference;
-    typedef const Structure& const_reference;
-
-    std::size_t getNumberFields() const {return numberFields;}
-    FieldConstPtr getField(std::string const & fieldName) const;
-    FieldConstPtr getField(std::size_t index) const;
-    std::size_t getFieldIndex(std::string const &fieldName) const;
-    FieldConstPtrArray const & getFields() const {return fields;}
-    StringArray const & getFieldNames() const;
-    std::string getFieldName(std::size_t fieldIndex) const;
-    virtual std::string getID() const;
-    virtual std::ostream& dump(std::ostream& o) const;
-    virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
-    virtual void deserialize(ByteBuffer *buffer, DeserializableControl *control);
- ...
-};
-
-class epicsShareClass Union : public Field {
-public:
-    POINTER_DEFINITIONS(Union);
-    static std::string DEFAULT_ID;
-    static std::string ANY_ID;
-    virtual ~Union();
-    typedef Union& reference;
-    typedef const Union& const_reference;
-
-    std::size_t getNumberFields() const;
-    FieldConstPtr getField(std::string const &fieldName) const;
-    FieldConstPtr getField(std::size_t index);
-    std::size_t getFieldIndex(std::string const &fieldName) const;
-    FieldConstPtrArray const & getFields() const;
-    StringArray const & getFieldNames() const;
-    std::string getFieldName(std::size_t fieldIndex) const;
-    bool isVariant() const;
-    virtual std::string getID() const;
-    virtual std::ostream& dump(std::ostream& o) const;
-    virtual void serialize(
-        ByteBuffer *buffer, SerializableControl *control) const;
-    virtual void deserialize(
-        ByteBuffer *buffer, DeserializableControl *control);
-    
-};
-
-
-
Constructors
-
Note that all constructors are protected or private. The only way to - create instances is via fieldBuilder or fieldCreate. The implementation manages all - storage via shared pointers.
-
dump
-
Many classes provide this. This is a stream method that prints using - the metadata syntax described in pvDataJava.html.
-
- -

Field

-
-
getType
-
Get the field type.
-
getID
-
Get an ID for this introspection interface
-
- -

Scalar

-
-
getScalarType
-
Get that scalar type.
-
getID
-
For each scalarType there is one instance of Scalar. The ID for each is - the metadata name for the type, i. e. one of "boolean" , ... , "string". -
-
- -

ScalarArray

-
-
getElementType
-
Get the element type.
-
getID
-
For each elemnetType there is one instance of ScalarArray. The ID for - each is the metadata name for the type, i. e. one of "boolean[]" , ... , - "string[]".
-
- -

StructureArray

-
-
getStructure
-
Get the introspection interface that each element shares,
-
getID
-
This returns the ID[] where ID is the value returned by - structure->getID().
-
-` -

UnionArray

-
-
getUnion
-
Get the union interface for each element.
-
- -

Structure

-
-
getNumberFields
-
Get the number of immediate subfields.
-
getField
-
Given a name or an index get the introspection interface for the - field.
-
getFieldIndex
-
Given a name get the index, within the array returned by the next - method, of the field.
-
getFields
-
Get the array of introspection interfaces for the field,
-
getFieldNames
-
Get the array of field names for the subfields.
-
getFieldName
-
Get the field name for the specified index.
-
-

Union

-
-
getNumberFields
-
Get the number of possible field types. - Both getFields and getFieldNames will return an array with getNumberFields elements. - A value of 0 is returned for invarient arrays. -
-
getField
-
Given a name ot an index the type is returned. - NULL is returned if not found. -
-
getFieldIndex
-
Get the index for name. -1 is returned if not found. -
getFields
-
Get the array of types.
-
getFieldNames
-
Get the array of names.
-
getFieldName
-
Get the name for the specified index.
-
isVariant
-
returns true if this is varient array and false otherwise. -
-

fieldBuilder and createField

-
-class epicsShareClass FieldBuilder :
-    public std::tr1::enable_shared_from_this<FieldBuilder>
-{
-public:
-    FieldBuilderPtr setId(std::string const & id);
-    FieldBuilderPtr add(std::string const & name, ScalarType scalarType);
-    FieldBuilderPtr add(std::string const & name, FieldConstPtr const & field);
-    FieldBuilderPtr addArray(std::string const & name, ScalarType scalarType);
-    FieldBuilderPtr addArray(std::string const & name, FieldConstPtr const & element);
-    StructureConstPtr createStructure();
-    UnionConstPtr createUnion();
-    FieldBuilderPtr addNestedStructure(std::string const & name); 
-    FieldBuilderPtr addNestedUnion(std::string const & name);
-    FieldBuilderPtr addNestedStructureArray(std::string const & name); 
-    FieldBuilderPtr addNestedUnionArray(std::string const & name);
-    FieldBuilderPtr endNested();
-};
-
-class epicsShareClass FieldCreate {
-public:
-    static FieldCreatePtr getFieldCreate();
-    FieldBuilderPtr createFieldBuilder() const;
-    ScalarConstPtr createScalar(ScalarType scalarType) const;
-    ScalarArrayConstPtr createScalarArray(ScalarType elementType) const;
-    StructureArrayConstPtr createStructureArray(StructureConstPtr const & structure) const;
-    StructureConstPtr createStructure () const;
-    StructureConstPtr createStructure (
-        StringArray const & fieldNames,
-        FieldConstPtrArray const & fields) const;
-    StructureConstPtr createStructure (
-    	std::string const & id,
-        StringArray const & fieldNames,
-        FieldConstPtrArray const & fields) const;
-    UnionConstPtr createUnion (
-        StringArray const & fieldNames,
-        FieldConstPtrArray const & fields) const;
-    UnionConstPtr createUnion (
-    	std::string const & id,
-        StringArray const & fieldNames,
-        FieldConstPtrArray const & fields) const;
-    UnionConstPtr createVariantUnion() const;
-    UnionArrayConstPtr createVariantUnionArray() const;
-    UnionArrayConstPtr createUnionArray(UnionConstPtr const & punion) const;
-    StructureConstPtr appendField(
-        StructureConstPtr const & structure,
-        std::string const & fieldName, FieldConstPtr const & field) const;
-    StructureConstPtr appendFields(
-        StructureConstPtr const & structure,
-        StringArray const & fieldNames,
-        FieldConstPtrArray const & fields) const;
-    FieldConstPtr deserialize(ByteBuffer* buffer, DeserializableControl* control) const;
-        
-};
-
-epicsShareExtern FieldCreatePtr getFieldCreate();
-
- -

FieldBuilder

-

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. -

-
-
setID
-
This sets an ID for the field, which is the name for the field when it is a subfield. -
-
add
-
- Add a scalar field. -
-
addArray
-
- Add a scalarArray field. -
-
createStructure
-
- Create a structure from the fields that are currently present. -
-
createUnion
-
- Create a union from the fields that are currently present. -
-
addNestedStructure
-
- Add a nested structure. This is followed by an arbitrary number of adds - followed by a an endNested. -
-
addNestedUnion
-
- Add a nested union. This is followed by an arbitrary number of adds - followed by a an endNested. -
-
addNestedStructureArray
-
- Add a nested structure array. This is followed by an arbitrary number of adds - followed by a an endNested. -
-
addNestedUnionArray
-
- Add a nested union array. This is followed by an arbitrary number of adds - followed by a an endNested. -
-
endNested
-
- End current nested structure or union. -
-
-

Examples of using fieldBuilder were given earlier in this manual.

-

FieldCreate

-
-
getFieldCreate
-
Get the single instance of FieldCreate.
-
createFieldBuilder
-
Create an instance of a FieldBuilder.
-
createScalar
-
Create a scalar introspection instance.
-
createScalarArray
-
Create a scalar array introspection instance.
-
createStructure
-
Create a structure introspection instance. Three methods are provided. - The first creates an empty structure, i. e. a structure with no fields. - The other two are similar. - The only difference is that one provides an ID and the other does - not. The one without will result in ID structure.
-
createUnion
-
Create a union. There are two methods. - Each has arguments for an array of types and an array of names. - One method has an id. The other results in id = union. -
-
createVariantUnion
-
- Create a varient union. The id will be any. -
-
createUnionArray
-
Create a union array. punion is the introspection interface - for each element.
-
createVariantUnionArray
-
Create a union array where each element is a varient union.
-
createStructureArray
-
Create a structure array introspection instance.
-
appendField
-
Create a new structure that is like an existing structure but has - an extra field appended to it. -
-
appendFields
-
Create a new structure that is like an existing structure but has - extra fields appended to it. -
-
deserialize
-
Deserialize from given byte buffer.
-
- -

standardField.h

- -

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();
- ...
-};
-
-
scalar
-
Create a scalar with the specified scalar type and name. A structure - will be created with the first element being a scalar with the specified - scalar type and name value. The other fields in the structure will be the - corresponding property structures.
-
regUnion
-
A structure - will be created with the first element being a union with the specified - scalar type and name value. The other fields in the structure will be the - corresponding property structures.
-
varient`Union
-
Create a varient union. A structure - will be created with the first element being a union with the specified - scalar type and name value. The other fields in the structure will be the - corresponding property structures.
-
scalarArray
-
Create a scalarArray with each element having the specified scalar type - and name. A structure will be created with the first element being a - scalarArray with name value. The other fields in the structure will be - the corresponding property structures.
-
structureArray
-
Create a structureArray with the specified structure interface and - name. A structure will be created with the first element being a - structureArray with the specified structure interface and name value. The - other fields in the structure will be the corresponding property - structures.
-
unionArray
-
Create a unionArray with the specified union interface and - name. A structure will be created with the first element being a - unionArray with the specified structure interface and name value. The - other fields in the structure will be the corresponding property - structures.
-
structure
-
Create a structure with the specified name and fields specified by - numFields and fields. A structure will be created with the first element - being a structure with the name value and fields specified by numFields - and fields. The other fields in the structure will be the corresponding - property structures.
-
enumerated
-
Create a structure with the specified name and fields for an enumerated - structure. If properties are specified then a structure will be created - with the first element being a structure with the name value and fields - for an enumerated structure. The other fields in the structure will be - the corresponding property structures.
-
alarm
-
timeStamp
-
display
-
control
-
booleanAlarm
-
byteAlarm
-
shortAlarm
-
intAlarm
-
longAlarm
-
floatAlarm
-
doubleAlarm
-
enumeratedAlarm
-
The above provide introspection interfaces for standard properties. See - the section on Properties for a description of how these are defined.
-
-

pvData.h

- -

This section describes pvData.h This file is quite big so rather than -showing the entire file, it will be described in parts.

- -

typedefs

- -

These are typedefs for Array and Ptr for the various pvData class -definitions, i.e. typdefs for "std::vector" and "std::tr1::shared_ptr".

-
-class PVField;
-class PVScalar;
-class PVScalarArray;
-class PVStructure;
-class PVStructureArray;
-
-
-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

- -

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:

-
-
~PVField
-
Destructor. Since shared pointers are used it should never be called by - user code.
-
getFieldName
-
Get the field name. If the field is a top level structure the field - name will be an empty string.
-
getFullName
-
Fully expand the name of this field using the - names of its parent fields with a dot '.' seperating - each name. -
-
getFieldOffset
-
Get offset of the PVField field within top level structure. Every field - within the PVStructure has a unique offset. The top level structure has - an offset of 0. The first field within the structure has offset equal to - 1. The other offsets are determined by recursively traversing each - structure of the tree.
-
getNextFieldOffset
-
Get the next offset. If the field is a scalar or array field then this - is just offset + 1. If the field is a structure it is the offset of the - next field after this structure. Thus (nextOffset - offset) is always - equal to the total number of fields within the field.
-
getNumberFields
-
Get the total number of fields in this field. This is nextFieldOffset - - fieldOffset.
-
isImmutable
-
Is the field immutable?
-
setImmutable
-
Make the field immutable. Once a field is immutable it can never be - changed since there is no method to again make it mutable. This is an - important design decision since it allows immutable array fields to share - the internal primitive data array.
-
getField
-
Get the reflection interface for the data.
-
getParent
-
Get the interface for the parent or null if this is the top level - PVStructure.
-
postPut
-
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. - PostHandler is a class that must be implemented by any code that calls setPostHandler. - It's single virtual method. postPut is called whenever PVField::postPut is called. -
-
equals
-
Compare this field with another field. The result will be true only if - the fields have exactly the same field types and if the data values are - equal.
-
dumpValue
-
Method for streams I/O.
-
- -

PVScalar

- -

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

-
-
getScalar
-
Get the introspection interface for the PVScalar.
-
getAs
-
Convert and return the scalar value in the requested type. - Result type is determined from the function template argument - which must be one of the ScalarType enums. - For example: -
-uint32 val = pv->getAs();
-
-
- -
- -

PVScalarValue

- -

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

-
-
get
-
Get the value stored in the object.
-
put
-
Change the value stored in the object.
-
dumpValue
-
ostream method.
-
operator>>=
-
get operator. For example: -
-double value;
-PVDoublePtr pvDouble;
-...
-pvDouble>>=value;
-
-
-
operator<<=
-
put operator. For example: -
-double value;
-PVDoublePtr pvDouble;
-...
-pvDouble<<=value;
-
-
-
getAs
-
Convert and return the scalar value in the requested type. - Result type is determined from the function template argument - which must be one of the ScalarType enums. - For example: -
-int32 val = pv->getAs<pvInt>>();
-
-
-
putFrom
-
Convert the scalar value in the requested type - and put the value into this PVScalarValue. - The source type is determined from the function template argument - which must be one of the ScalarType enums. - For example: -
-int32 val;
-pv->putFrom<pvInt>(val);
-
- -
-
-

PVUnion

-

A PVUnion has a single subfield. -The Union introspection interface determines the possible -field types for the subfield. -If it is a varient union then any type is allowed and the -subfield name is normally any. -If it is not a varient union that the Union interface determines -the possible field types and names.

-
-class PVUnion : public PVField
-{
-public:
-    POINTER_DEFINITIONS(PVUnion);
-    virtual ~PVUnion();
-    typedef PVUnion & reference;
-    typedef const PVUnion & const_reference;
-
-    UnionConstPtr getUnion() const;
-    PVFieldPtr get() const;
-    
-    template<typename PVT>
-    std::tr1::shared_ptr<PVT> get() const;
-
-   PVFieldPtr select(int32 index);
-
-    template<typename PVT>
-    std::tr1::shared_ptr<PVT> select(int32 index);
-
-    PVFieldPtr select(std::string const & fieldName);
-
-    template<typename PVT>
-    std::tr1::shared_ptr<PVT> select(std::string const & fieldName);
-
-    int32 getSelectedIndex() const;
-    std::string getSelectedFieldName() const;
-    void set(PVFieldPtr const & value);
-    void set(int32 index, PVFieldPtr const & value);
-    void set(std::string const & fieldName, PVFieldPtr const & value);
-    virtual void serialize(
-        ByteBuffer *pbuffer,SerializableControl *pflusher) const ;
-    PVUnion(UnionConstPtr const & punion);
-};
-
-
-
getUnion
-
Get the introspection interface.
-
get
-
Get the curent field. A template version does the conversion. - NULL is returned if no field is selected or if the caller -' asks for the wrong type. -
-
select
-
Select and get the field by index or name. - A templated version does the conversion. - If the index is out of bounds or the name is not valid this methods throws an exception. - The method set should be used for variant unions rather than select. -
-
getSelectedIndex
-
Get the index of the currently selected field.
-
getSelectedFieldName
-
Get the name of the currently selected field.
-
set
-
Set the field to the argument. If invalid type an exception is thrown. - This should always work for a variant union. -
-
- -

PVArray

- -

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;
- ...
-};
-
-
getArray
-
Get the introspection interface.
-
setImmutable
-
Set the data immutable. Note that this is permanent since there is no - methods to make it mutable.
-
getLength
-
Get the current length. This is less than or equal to the capacity.
-
setLength
-
Set the length. If the PVField is not mutable then an exception is - thrown. If this is greater than the capacity setCapacity is called.
-
getCapacity
-
Get the capacity, i.e. this is the size of the underlying data - array.
-
setCapacity
-
Set the capacity. The semantics are implementation dependent but - typical semantics are as follows: If the capacity is not mutable an - exception is thrown. A new data array is created and data is copied from - the old array to the new array.
-
isCapacityMutable
-
Is the capacity mutable
-
setCapacityMutable
-
Specify if the capacity can be changed.
-
setCapacity
-
Set the capaciity.
-
dumpValue
-
ostream method
-
-

- - -

PVScalarArray

- -

PVScalarArray is the base class for scalar array data. PVValueArray is a -templete for the various scalar array data classes. There is a class for each -possible scalar type, i. e. PVBooleanArray, ..., PVStringArray.

-
-class PVScalarArray : public PVArray {
-public:
-    POINTER_DEFINITIONS(PVScalarArray);
-    virtual ~PVScalarArray();
-    typedef PVScalarArray &reference;
-    typedef const PVScalarArray& const_reference;
-
-    const ScalarArrayConstPtr getScalarArray() const ;
-
-    template<typename T>
-    void getAs(shared_vector<const T>& out) const
-
-    template<typename T>
-    void putFrom(const shared_vector<const T>& inp)
-
-    void assign(PVScalarArray& pv);
- ...
-}
-
- -

where

-
-
getScalarArray
-
Get the introspection interface.
-
getAs
-
Fetch the current value and convert to the requested type. - A copy is made if the requested type does not match the element type. - If the types do match then no copy is made. -
-
putFrom
-
Assign the given value after conversion. - A copy and element-wise conversion is performed unless the element type - of the PVScalarArray matches the type of the provided data. - If the types do match then a new refernce to the provided data is kept. -
-
assign
-
Assign the given PVScalarArray's value. - A copy and element-wise conversion is performed unless the element type - of the PVScalarArray matches the type of the provided data. - If the types do match then a new refernce to the provided data is kept. -
-
- -

PVStructure

- -

The interface for a structure is:

-
class PVStructure : public PVField,public BitSetSerializable {
-public:
-    POINTER_DEFINITIONS(PVStructure);
-    virtual ~PVStructure();
-    typedef PVStructure & reference;
-    typedef const PVStructure & const_reference;
-
-    virtual void setImmutable();
-    StructureConstPtr getStructure() const;
-    const PVFieldPtrArray & getPVFields() const;
-    PVFieldPtr getSubField(std::string const &fieldName) const;
-
-    template<typename PVT>
-    std::tr1::shared_ptr<PVT> getSubField(std::string const &fieldName) const
-
-    PVFieldPtr getSubField(std::size_t fieldOffset) const;
-
-    template<typename PVT>
-    std::tr1::shared_ptr<PVT> getSubField(std::size_t fieldOffset) const
-
-    virtual void serialize(
-        ByteBuffer *pbuffer,SerializableControl *pflusher) const ;
-    virtual void deserialize(
-        ByteBuffer *pbuffer,DeserializableControl *pflusher);
-    virtual void serialize(ByteBuffer *pbuffer,
-        SerializableControl *pflusher,BitSet *pbitSet) const;
-    virtual void deserialize(ByteBuffer *pbuffer,
-        DeserializableControl*pflusher,BitSet *pbitSet);
-    PVStructure(StructureConstPtr const & structure);
-    PVStructure(StructureConstPtr const & structure,PVFieldPtrArray const & pvFields);
-    virtual std::ostream& dumpValue(std::ostream& o) const;
-};
- -

where

-
-
getStructure
-
Get the introspection interface for the structure.
-
getPVFields
-
Returns the array of subfields. The set of subfields must all have - different field names.
-
getSubField(std::string fieldName)
-
- Get a subField of a field.d - A non-null result is - returned if fieldName is a field of the PVStructure. The fieldName can be - of the form name.name... - If the field does not exist the a Ptr to a NULL value is returned - without any error message being generated. -
- Note that the template version replaces getBooleanField, etc.
-
-
getSubField(int fieldOffset)
-
Get the field located a fieldOffset, where fieldOffset is relative to - the top level structure. This returns null if the specified field is not - located within this PVStructure. -
-
dumpValue
-
Method for streams I/O.
-
- - -

PVValueArray

- -

This is a template class plus instances for PVBooleanArray, ..., -PVStringArray.

-
template<typename T>
-class PVValueArray : public detail::PVVectorStorage<T,PVScalarArray> 
-{
-public:
-    POINTER_DEFINITIONS(PVValueArray);
-    typedef T  value_type;
-    typedef T* pointer;
-    typedef const T* const_pointer;
-    typedef ::epics::pvData::shared_vector<T> svector;
-    typedef ::epics::pvData::shared_vector<const T> const_svector;
-    static const ScalarType typeCode;
-
-    virtual ~PVValueArray() {}
-    std::ostream& dumpValue(std::ostream& o) const;
-    std::ostream& dumpValue(std::ostream& o, size_t index) const;
-    // inherited from PVVectorStorage
-    const_svector view();
-    void swap(const_svector& other);
-    void replace(const const_svector& next);
-    svector reuse();
-    ...
-};
-
- -

where

-
-
dumpValue
-
Method for streams I/O.
-
view
-
Fetch a read-only view of the current array data.
-
swap
-
- Callers must ensure that postPut() is called after the last swap() operation. - Before you call this directly, consider using the reuse(), or replace() methods. -
-
replace
-
Discard current contents and replaced with the provided.
-
reuse
-
Remove and return the current array data or an unique copy if shared.
-
-

TBD -

-
Check for completeness
-
Michael should check that PVScalarArray and PVValueArray - have the correct set of methods and that the descriptions are correct.
-
-

- -

PVStructureArray

- -

The interface for an array of structures is:

-
-template<>
-class PVValueArray<PVStructurePtr> : public detail::PVVectorStorage<PVStructurePtr,PVArray>
-{
-public:
-    POINTER_DEFINITIONS(PVStructureArray);
-    typedef PVStructurePtr  value_type;
-    typedef PVStructurePtr* pointer;
-    typedef const PVStructurePtr* const_pointer;
-    typedef PVStructureArray &reference;
-    typedef const PVStructureArray& const_reference;
-    typedef ::epics::pvData::shared_vector<PVStructurePtr> svector;
-    typedef ::epics::pvData::shared_vector<const PVStructurePtr> const_svector;
-
-    virtual ~PVStructureArray() {}
-    virtual ArrayConstPtr getArray() const;
-    virtual size_t getLength();
-    virtual size_t getCapacity();
-    virtual void setCapacity(size_t capacity);
-    virtual void setLength(std::size_t length);
-    virtual StructureArrayConstPtr getStructureArray() const ;
-    virtual std::size_t append(std::size_t number);
-    virtual bool remove(std::size_t offset,std::size_t number);
-    virtual void compress();
-    virtual const_svector view() const;
-    virtual void swap(const_svector &other);
-    virtual void replace(const const_svector &other);
-    virtual void serialize(ByteBuffer *pbuffer,
-        SerializableControl *pflusher) const;
-    virtual void serialize(ByteBuffer *pbuffer,
-        SerializableControl *pflusher, std::size_t offset, std::size_t count) const ;
-    virtual void deserialize(ByteBuffer *buffer,
-        DeserializableControl *pflusher);
-    virtual std::ostream& dumpValue(std::ostream& o) const;
-    virtual std::ostream& dumpValue(std::ostream& o, std::size_t index) const;
-    // inherited from PVVectorStorage
-    const_svector view();
-    void swap(const_svector& other);
-    void replace(const const_svector& next);
-    svector reuse();
- ...
-}
-

where

-
-
getStructureArray
-
Get the introspection interface shared by each element.
-
compress
-
This moves all null elements and then changes the array capacity. When - done there are no null elements.
-
- -

The other methods are similar to the methods for other array types. - See PVArray above for details.

- -

PVUnionArray

-

The interface for an array of unions is:

-
-template&ly;&gt;
-class epicsShareClass PVValueArray&ly;PVUnionPtr&gt; : public detail::PVVectorStorage&ly;PVUnionPtr,PVArray&gt;
-{
-    typedef detail::PVVectorStorage&ly;PVUnionPtr,PVArray&gt; base_t;
-public:
-    POINTER_DEFINITIONS(PVUnionArray);
-    typedef PVUnionPtr  value_type;
-    typedef PVUnionPtr* pointer;
-    typedef const PVUnionPtr* const_pointer;
-    typedef PVUnionArray &reference;
-    typedef const PVUnionArray& const_reference;
-
-    //TODO: full namespace can be removed along with local typedef 'shared_vector'
-    typedef ::epics::pvData::shared_vector&ly;PVUnionPtr&gt; svector;
-    typedef ::epics::pvData::shared_vector&ly;const PVUnionPtr&gt; 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

-
-
getUnionArray
-
Get the introspection interface shared by each element.
-
compress
-
This moves all null elements and then changes the array capacity. When - done there are no null elements.
-
- -

The other methods are similar to the methods for other array types. - See PVArray above for details.

- -

PVDataCreate

- -

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

-
-
getPVDataCreate
-
The returns the PVDataCreate implementation, which is a singleton.
-
createPVField
-
The PVField is created reusing the Field interface. Two methods are - provided. Each calls the corresponding createPVScalar, createPVArray, or - createPVStructure depending in the type of the last argument.
-
createPVScalar
-
Creates an instance of a PVScalar. Four versions are supplied. The - first is passed an introspection interface. - The second provides the scalarType. - The third provides a PVScalar to clone. - The last is a template version. PVAT must be a valid type. - For example: -
-PVDoublePtr pvDouble = getPVDataCreate()->createPVScalar<PVDouble>();
-
-
-
createPVStructure
-
Create an instance of a PVStructure. - Three methods are provided. - The first uses an array of field names and an array of PVFields to initialize the sub-fields. - The second initializes the subfields by cloning the fields contained in - structToClone. The newly created sub-fields will have the same values as the original. - If structToClone is null then the new structure is initialized to have 0 sub-fields. - The third method uses a previously created structure introspection interface. -
-
createPVUnion
-
Create an instance of a PVUnion. Two methods are provided. - The first uses a previously created union introspection interface. - The second clones an existing PVUnion. -
-
createPVVariantUnion
-
Creates an instance of a varient PVUnion. - This is a union which has a single field which can be any pvData supported type, -
-
createPVScalarArray
-
Create an instance of a PVArray. Four versions are supplied. - The first is passed an introspection interface. - The second provides the elementType. - The third provides a PVScalarArray to clone. - The last is a template version. PVAT must be a valid type. - For example: -
-PVDoubleArrayPtr pvDoubleArray = getPVDataCreate()->createPVScalarArray<PVDoubleArray>();
-
-
-
createPVStructureArray
-
Create a PVStructureArray. - Two versions are provided. - The first is passed a StructureArrayConstPtr. - The second is passed a StructureConstPtr which is used to create a StructureArrayConstPtr. - The argument provides the Structure interface for ALL elements of the PVStructureArray. -
-
createPVUnionArray
-
Create a PVUnionArray. - Two versions are provided. - The first is passed a UnionArrayConstPtr. - The second is passed a UnionConstPtr which is used to create a UnionArrayConstPtr. - The argument provides the Union interface for ALL elements of the PVUnionArray. -
-
createPVVariantUnionArray
-
Create a PVUnionArray. - No arguments are needed. -
-
- -

standardPVField.h

- -

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();
-
- -

Conversion

-

There are two facilities for converting between two different PVData -objects:

-
-
Convert
-
This preforms all conversions except for coping subarrays.
-
PVSubArray
-
This copies a subarray from one PVArray to another. - The two arrays must have the same element type.
-
-

convert.h

- -

NOTE about copying immutable array fields. If an entire immutable array -field is copied to another array that has the same elementType, both offsets -are 0, and the length is the length of the source array, then the shareData -method of the target array is called and the target array is set immutable. -Thus the source and target share the same primitive array.

- -

This section describes the supported conversions between data types.

- -
-bool operator==(PVField&, PVField&);
-
-static bool operator!=(PVField& a, PVField& b);
-
-bool operator==(const Field&, const Field&);
-bool operator==(const Scalar&, const Scalar&);
-bool operator==(const ScalarArray&, const ScalarArray&);
-bool operator==(const Structure&, const Structure&);
-bool operator==(const StructureArray&, const StructureArray&);
-bool operator==(const Union&, const Union&);
-bool operator==(const UnionArray&, const UnionArray&);
-
-static inline bool operator!=(const Field& a, const Field& b);
-static inline bool operator!=(const Scalar& a, const Scalar& b);
-static inline bool operator!=(const ScalarArray& a, const ScalarArray& b);
-static inline bool operator!=(const Structure& a, const Structure& b);
-static inline bool operator!=(const StructureArray& a, const StructureArray& b);
-static inline bool operator!=(const Union& a, const Union& b);
-static inline bool operator!=(const UnionArray& a, const UnionArray& b);
-
-class Convert;
-typedef std::tr1::shared_ptr<Convert> ConvertPtr;
-
-class Convert {
-public:
-    static ConvertPtr getConvert();
-    ~Convert();
-    void getFullName(std::string * buf,PVFieldPtr const & pvField);
-    bool equals(PVFieldPtr const &a,PVFieldPtr const &b);
-    bool equals(PVField &a,PVField &b);
-    void getString(std::string * buf,PVFieldPtr const & pvField,int indentLevel);
-    void getString(std::string * buf,PVFieldPtr const & pvField);
-    void getString(std::string * buf,PVField const * pvField,int indentLevel);
-    void getString(std::string * buf,PVField const * pvField);
-    std::size_t fromString(
-        PVStructurePtr const &pv,
-        StringArray const & from,
-        std::size_t fromStartIndex = 0);
-    void fromString(PVScalarPtr const & pv, std::string const & from);
-    std::size_t fromString(PVScalarArrayPtr const & pv, std::string const &from);
-    std::size_t fromStringArray(
-        PVScalarArrayPtr const & pv,
-        std::size_t offset, std::size_t length,
-        StringArray const & from,
-        std::size_t fromOffset);
-    std::size_t toStringArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        StringArray & to,
-        std::size_t toOffset);
-    bool isCopyCompatible(FieldConstPtr const & from, FieldConstPtr const & to);
-    void copy(PVFieldPtr const & from, PVFieldPtr const & to);
-    bool isCopyScalarCompatible(
-        ScalarConstPtr const & from,
-        ScalarConstPtr const & to);
-    void copyScalar(PVScalarPtr const & from, PVScalarPtr const & to);
-    bool isCopyScalarArrayCompatible(
-        ScalarArrayConstPtr const & from,
-        ScalarArrayConstPtr const & to);
-    bool isCopyStructureCompatible(
-        StructureConstPtr const & from, StructureConstPtr const & to);
-    void copyStructure(PVStructurePtr const & from, PVStructurePtr const & to);
-    bool isCopyStructureArrayCompatible(
-        StructureArrayConstPtr const & from, StructureArrayConstPtr const & to);
-    void copyStructureArray(
-        PVStructureArrayPtr const & from, PVStructureArrayPtr const & to);
-    bool isCopyUnionCompatible(
-        UnionConstPtr const & from, UnionConstPtr const & to);
-    void copyUnion(
-        PVUnionPtr const & from, PVUnionPtr const & to);
-    bool isCopyUnionArrayCompatible(
-        UnionArrayConstPtr const & from, UnionArrayConstPtr const & to);
-    void copyUnionArray(
-        PVUnionArrayPtr const & from, PVUnionArrayPtr const & to);
-    int8 toByte(PVScalarPtr const & pv);
-    int16 toShort(PVScalarPtr const & pv);
-    int32 toInt(PVScalarPtr const & pv);
-    int64 toLong(PVScalarPtr const & pv);
-    uint8 toUByte(PVScalarPtr const & pv);
-    uint16 toUShort(PVScalarPtr const & pv);
-    uint32 toUInt(PVScalarPtr const & pv);
-    uint64 toULong(PVScalarPtr const & pv);
-    float toFloat(PVScalarPtr const & pv);
-    double toDouble(PVScalarPtr const & pv);
-    std::string toString(PVScalarPtr const & pv);
-    void fromByte(PVScalarPtr const & pv,int8 from);
-    void fromShort(PVScalarPtr const & pv,int16 from);
-    void fromInt(PVScalarPtr const & pv, int32 from);
-    void fromLong(PVScalarPtr const & pv, int64 from);
-    void fromUByte(PVScalarPtr const & pv,uint8 from);
-    void fromUShort(PVScalarPtr const & pv,uint16 from);
-    void fromUInt(PVScalarPtr const & pv, uint32 from);
-    void fromULong(PVScalarPtr const & pv, uint64 from);
-    void fromFloat(PVScalarPtr const & pv, float from);
-    void fromDouble(PVScalarPtr const & pv, double from);
-    void newLine(std::string * buf, int indentLevel);
- ...
-}
-
-extern ConvertPtr getConvert();
-
-

newLine is a convenience method for code that implements toString It -generates a newline and inserts blanks at the beginning of the newline.

- -

pvSubArrayCopy.h

-
-template<typename T>
-void copy(
-    PVValueArray<T> & pvFrom,
-    size_t fromOffset,
-    size_t fromStride,
-    PVValueArray<T> & pvTo,
-    size_t toOffset,
-    size_t toStride,
-    size_t count);
-
-void copy(
-    PVScalarArray & from,
-    size_t fromOffset,
-    size_t fromStride,
-    PVScalarArray & to,
-    size_t toOffset,
-    size_t toStride,
-    size_t count);
-
-void copy(
-    PVStructureArray & from,
-    size_t fromOffset,
-    size_t fromStride,
-    PVStructureArray & to,
-    size_t toOffset,
-    size_t toStride,
-    size_t count);
-
-void copy(
-    PVArray & from,
-    size_t fromOffset,
-    size_t fromStride,
-    PVArray & to,
-    size_t toOffset,
-    size_t toStride,
-    size_t count);
-
-

The last copy is the only one most client need to call. -It either throws an error of the element types do not match or calls the -other copy functions. The arguments are:

-
-
from
-
The source array.
-
fromOffset
-
The offset into the source array.
-
fromStride
-
The interval between source elements.
-
to
-
The destination array. The element type must be the same - as for the source array. If the element type is structure then - the introspection interface for the element types must be the same. -
-
toOffset
-
The offset into the destination array.
-
toStride
-
The interval between destination elements.
-
count
-
The number of elements to copy.
-
-

An exception is thrown if:

-
-
type mismatch
-
The element types for the source and destination differ.
-
immutable
-
The destination array is immutable. -
capacity immutable
-
The destination array needs to have it's capacity extentended - but the capacity is immutable.
-
- -

pvDataApp/property

- -

Definition of Property

- -

Only fields named "value" have properties. A record can have multiple value -fields, which can appear in the top level structure of a record or in a -substructure. All other fields in the structure containing a value field are -considered properties of the value field. The fieldname is also the property -name. The value field can have any type, i.e. scalar, scalarArray, or -structure. Typical property fields are timeStamp, alarm, display, control, and -history. The timeStamp is a special case. If it appears anywhere in the -structure hieraracy above a value field it is a property of the value field.

- -

For example the following top level structure has a single value field. The -value field has properties alarm, timeStamp, and display.

-
structure counterOutput
-    double value
-    alarm_t
-        int severity 0
-        int status 0
-        string message
-    timeStamp_t
-        long secondsPastEpoch
-        int nanoSeconds
-        int userTag
-    display_t
-        double limitLow 0.0
-        double limitHigh 10.0
-        string description "Sample Description"
-        string format "%f"
-        string units volts
- -

The following example has three value fields each with properties alarm and -timeStamp. Voltage, Current, and Power each have a different alarms but all -share the timeStamp.

-
structure powerSupplyValue
-    double value
-    alarm_t
-        int severity 0
-        int status 0
-        string message
-
-structure powerSupplySimple
-    alarm_t
-        int severity 0
-        int status 0
-        string message
-    timeStamp_t
-        long secondsPastEpoch
-        int nanoSeconds
-        int userTag
-    powerSupplyValue_t voltage
-        double value
-        alarm_t
-            int severity 0
-            int status 0
-            string message
-    powerSupplyValue_t power
-        double value
-        alarm_t
-            int severity 0
-            int status 0
-            string message
-    powerSupplyValue_t current
-        double value
-        alarm_t
-            int severity 0
-            int status 0
-            string message
- -

Standard Properties

- -

The following field names have special meaning, i.e. support properties for -general purpose clients.

-
-
value
-
This is normally defined since most general purpose clients access this - field. All other fields in the structure support or describe the value - field. The type can any supported type but is usually one of the - following: -
-
scalar
-
Any of the scalar types.
-
scalarArray
-
An array with the elementType being a scalar type
-
enumerated structure
-
A structure that includes fields named index and choices. index - is an int that selects a choice. choices is an array of strings - that defines the complete set of choices.
-
other
-
Other structure or array types can also be defined if clients and - support code agree on the meaning. Some examples are: 1) A - structure defining a 2D matrix, 2) A structure defining an image, - 3) A structure that simulates a remote method, ...
-
-
-
timeStamp
-
The timeStamp. The type MUST be a timeStamp structure. Also if the - PVData structure does not have a timeStamp then a search up the parent - tree is made to find a timeStamp.
-
alarm
-
The alarm. The type MUST be an alarm structure.
-
display
-
A display structure as described below. It provides display - characteristics for the value field.
-
control
-
A control structure as described below. It provides control - characteristics for the value field.
-
history
-
Provides a history buffer for the value field. Note that currently - PVData does not define history suppoprt.
-
other
-
Other standard properties can be defined.
-
- -

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:

-
-
input
-
A field with support that changes the value field. This can be - anything. It can be a channel access link. It can obtain a value from - hardware. Etc.
-
valueAlarm
-
A field with support that looks for alarm conditions based on the - value.
-
output
-
A field with support that reads the current value and sends it - somewhere else. This can be anything. It can be a channel access link. It - can write a value to hardware. Etc.
-
- -

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. -

- -

Overview of Property Support

- -

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();
-     ...
-}
- -

timeStamp

- -

A timeStamp is represented by the following structure

-
structure timeStamp
-    long secondsPastEpoch
-    int nanoSeconds
-    int userTag
- -

The Epoch is the posix epoch, i.e. Jan 1, 1970 00:00:00 UTC. Both the -seconds and nanoSeconds are signed integers and thus can be negative. Since the -seconds is kept as a 64 bit integer, it allows for a time much greater than the -present age of the universe. Since the nanoSeconds portion is kept as a 32 bit -integer it is subject to overflow if a value that corresponds to a value that -is greater than a little more than 2 seconds of less that about -2 seconds. The -support code always adjust seconds so that the nanoSecconds part is normlized, -i. e. it has is 0<=nanoSeconds<nanoSecPerSec..

- -

Two header files are provided for manipulating time stamps:

-
-
timeStamp.h
-
Defines a time stamp independent of pvData, i.e. it is a generally - useful class for manipulating timeStamps.
-
pvTimeStamp.h
-
A class that can be attached to a time stamp pvData structure. It - provides get and set methods to get/set a TimeStamp as defined by - timeStamp.h
-
- -

timeStamp.h

- -

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

-
-
TimeStamp()
-
The defauly constuctor. Both seconds and nanoSeconds are set to 0.
-
TimeStamp(int64 secondsPastEpoch,int32 nanoSeconds = 0)
-
A constructor that gives initial values to seconds and nanoseconds.
-
normalize
-
Adjust seconds and nanoSeconds so that - 0<=nanoSeconds<nanoSecPerSec.
-
fromTime_t
-
Set time from standard C time.
-
toTime_t
-
Convert timeStamp to standard C time.
-
getSecondsPastEpoch
-
Get the number of seconds since the epoch.
-
getEpicsSecondsPastEpoch
-
Get the number of EPICS seconds since the epoch. EPICS uses Jan 1, 1990 - 00:00:00 UTC as the epoch.
-
getNanoSeconds
-
Get the number of nanoSeconds. This is always normalized.
-
getUserTag
-
Get the userTag.
-
setUserTag
-
Set the userTag.
-
put(int64 secondsPastEpoch,int32 nanoSeconds = 0)
-
Set the timeStamp value. If necessary it will be normalized.
-
put(int64 milliseconds)
-
Set the timeStamp with a value the is the number of milliSeconds since - the epoch.
-
getCurrent()
-
Set the timeStamp to the current time.
-
toSeconds()
-
Convert the timeStamp to a value that is the number of seconds since - the epocj
-
operator =
-
operator!=
-
operator<=
-
operator<
-
operator>=
-
operator>
-
Standard C++ operators.
-
diff
-
diff = a - b
-
getMilliseconds
-
Get the number of milliseconds since the epoch.
-
- -

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);
- -

pvTimeStamp.h

-
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

-
-
PVTimeStamp
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if a timeStamp - structure is found. It looks first at pvField itself and if is not an - appropriate pvData structure but the field name is value it looks up the - parent structure tree.
-
detach
-
Detach from the pvData structure.
-
isAttached
-
Is there an attachment to a timeStamp structure?
-
get
-
Copies data from the pvData structure to a TimeStamp. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from TimeStamp to the pvData structure. An exception is - thrown if not attached to a pvData structure.
-
- -

alarm

- -

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:

-
-
alarm.h
-
Defines an alarm independent of pvData, i.e. it is a generally useful - class for manipulating alarms.
-
pvAlarm.h
-
A class that can be attached to an alarm pvData structure. It provides - get and set methods to get/set alarm data as defined by alarm.h
-
- -

alarm.h

-
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:

-
-
getSeverity
-
Get the alarm severity corresponding to the integer value.
-
getSeverityNames
-
Get the array of severity choices.
-
- -

Alarm Status defines the possible choices for alarm status:

-
-
getStatus
-
Get the alarm status corresponding to the integer value.
-
getStatusNames
-
Get the array of status choices.
-
- -

Alarm has the methods:

-
-
Alarm
-
The constructor. It sets the severity to no alarm and the message to - "".
-
getMessage
-
Get the message.
-
setMessage
-
Set the message.
-
getSeverity
-
Get the severity.
-
setSeverity
-
Set the severity.
-
getStatus
-
Get the status.
-
setStatus
-
Set the status.
-
- -

pvAlarm.h

-
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

-
-
PVAlarm
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if it found an - appropriate pvData structure. It looks first a pvField itself and if is - not an appropriate pvData structure but the field name is value it looks - to see if the parent structure has an appropriate sub structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to an alarm structure?
-
get
-
Copies data from the pvData structure to an Alarm. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from Alarm to the pvData structure. An exception is thrown - if not attached to a pvData structure.
-
- -

control

- -

Control information is represented by the following structure

-
structure control
-    double limitLow
-    double limitHigh
-    double minStep
- -

Two header files are provided for manipulating control:

-
-
control.h
-
Defines control independent of pvData, i.e. it is a generally useful - class for manipulating control.
-
pvControl.h
-
A class that can be attached to an control pvData structure. It - provides get and set methods to get/set control data as defined by - control.h
-
- -

control.h

-
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

-
-
Control
-
The default constructure.
-
getLow
-
Get the low limit.
-
getHigh
-
Get the high limit.
-
setLow
-
Set the low limit.
-
setHigh
-
Set the high limit.
-
setMinStep
-
Set the minimum step size.
-
getMinStep
-
Get he minimum step size.
-
- -

pvControl.h

-
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

-
-
PVControl
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if it found an - appropriate pvData structure. It looks first a pvField itself and if is - not an appropriate pvData structure but the field name is value it looks - to see if the parent structure has an appropriate sub structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to a control structure?
-
get
-
Copies data from the pvData structure to a Control. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from Control to the pvData structure. An exception is - thrown if not attached to a pvData structure.
-
- -

display

- -

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:

-
-
display.h
-
Defines display independent of pvData, i.e. it is a generally useful - class for manipulating display.
-
pvDisplay.h
-
A class that can be attached to an display pvData structure. It - provides get and set methods to get/set display data as defined by - display.h
-
- -

display.h

-
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

-
-
Control
-
The default constructure.
-
getLow
-
Get the low limit.
-
getHigh
-
Get the high limit.
-
setLow
-
Set the low limit.
-
setHigh
-
Set the high limit.
-
getDescription
-
Get the description.
-
setDescription
-
Set the description.
-
getFormat
-
Get the format.
-
setFormat
-
Set the format.
-
getUnits
-
Get the units.
-
setUnits
-
Set the units.
-
- -

pvDisplay.h

-
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

-
-
PVDisplay
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if it found an - appropriate pvData structure. It looks first a pvField itself and if is - not an appropriate pvData structure but the field name is value it looks - to see if the parent structure has an appropriate sub structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to a display structure?
-
get
-
Copies data from the pvData structure to a Display. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from Display to the pvData structure. An exception is - thrown if not attached to a pvData structure.
-
- -

pvEnumerated.h

- -

An enumerated structure is a structure that has fields:

-
structure
-    int index
-    string[] choices
- -

For enumerated structures a single header file pvEnumerted.h is available

-
class PVEnumerated {
-public:
-    PVEnumerated();
-    //default constructors and destructor are OK
-    //This class should not be extended
-    //returns (false,true) if pvField(isNot, is valid enumerated structure
-    //An automatic detach is issued if already attached.
-    bool attach(PVFieldPtr const &pvField);
-    void detach();
-    bool isAttached();
-    // each of the following throws logic_error is not attached to PVField
-    // a set returns false if field is immutable
-    bool setIndex(int32 index);
-    int32 getIndex();
-    std::string getChoice();
-    bool choicesMutable();
-    StringArrayPtr const & getChoices();
-    int32 getNumberChoices();
-    bool setChoices(StringArray &choices,int32 numberChoices);
-};
- -

where

-
-
PVEnumerated
-
The default constructor. Attach must be called before any get or set - method can be called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if pvField (is - not, is) an enumerated structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to an enemerated structure?
-
setIndex
-
Set the index field in the pvData structure. An exception is thrown if - not attached to a pvData structure.
-
getIndex
-
Get the index field in the pvData structure.
-
getChoice
-
Get the std::string value corresponding to the current index field in the - pvData structure. An exception is thrown if not attached to a pvData - structure.
-
choicesMutable
-
Can the choices be changed? Note that this is often true. An exception - is thrown if not attached to a pvData structure.
-
getChoices
-
Get the array of choices. An exception is thrown if not attached to a - pvData structure.
-
getNumberChoices
-
Get the number of choices. An exception is thrown if not attached to a - pvData structure.
-
setChoices
-
Change the choices. An exception is thrown if not attached to a pvData - structure.
-
- - -

pvDataApp/factory

- -

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

- -

pvDataAPP/misc

- -

Overview

- -

This package provides utility code:

-
-
bitSet.h
-
An implementation of BitSet that can be serialized.
-
byteBuffer.h
-
Used to serialize objects.
-
destroyable.h
-
Provides method destroy.
-
epicsException.h
-
Exception with stack trace.
-
event.h
-
Signal and wait for an event.
-
executor.h
-
Provides a thread for executing commands.
-
localStaticLock.h
-
TBD Matej can You explain what this does?
-
lock.h
-
Support for locking and unlocking.
-
messageQueue.h
-
Support for queuing messages to give to requesters.
-
noDefaultMethods.h
-
When privately extended prevents compiler from implementing default - methods.
-
queue.h
-
A queue implementation that allows the latest queue element to continue - to be used when no free element is available.
-
requester.h
-
Allows messages to be sent to a requester.
-
serialize.h
-
Support for serializing objects.
-
serializeHelper.h
-
More support for serializing objects.
-
sharedPtr.h
-
Defines POINTER_DEFINITIONS.
-
sharedVector.h -
Like std::vector except that std::shared_ptr is used for - the data array.
-
status.h
-
A way to pass status information to a client.
-
templateMeta.h
-
TBD Michael can You provide an explaination?
-
thread.h
-
Provides thread support.
-
timeFunction.h
-
Time how long a function call requires.
-
timer.h
-
An implementation of Timer that does not require an object to be - created for each timer request.
-
typeCast.h
-
TBD Michael can You provide an explaination?
-
- -

Note that directory testApp/misc has test code for all the classes in misc. -The test code also can be used as examples.

- -

bitSet.h

- -

This is adapted from the java.util.BitSet. bitSet.h is:

-
-class BitSet;
-typedef std::tr1::shared_ptr<BitSet> BitSetPtr;
-
-class BitSet : public Serializable {
-public:
-    static BitSetPtr create(uint32 nbits);
-    BitSet();
-    BitSet(uint32 nbits);
-    virtual ~BitSet();
-    void flip(uint32 bitIndex);
-    void set(uint32 bitIndex);
-    void clear(uint32 bitIndex);
-    void set(uint32 bitIndex, bool value);
-    bool get(uint32 bitIndex) const;
-    void clear();
-    int32 nextSetBit(uint32 fromIndex) const;
-    int32 nextClearBit(uint32 fromIndex) const;
-    bool isEmpty() const;
-    uint32 cardinality() const;
-    uint32 size() const;
-    BitSet& operator&=(const BitSet& set);
-    BitSet& operator|=(const BitSet& set);
-    BitSet& operator^=(const BitSet& set);
-    BitSet& operator-=(const BitSet& set);
-    BitSet& operator=(const BitSet &set);
-    void or_and(const BitSet& set1, const BitSet& set2);
-    bool operator==(const BitSet &set) const;
-    bool operator!=(const BitSet &set) const;
-    virtual void serialize(
-        ByteBuffer *buffer,SerializableControl *flusher) const;
-    virtual void deserialize(
-        ByteBuffer *buffer,DeserializableControl *flusher);
-private:
-};
-
-std::ostream& operator<<(std::ostream& o, const BitSet& b);
-
- -

where

-
-
BitSet()
-
Creates a bitSet of initial size 64 bits. All bits initially false.
-
BitSet(uint32 nbits)
-
Creates a bitSet with the initial of the specified number of bits. All - bits initially false.
-
~BitSet()
-
Destructor.
-
flip(uint32 bitIndex)
-
Flip the specified bit.
-
set(uint32 bitIndex)
-
Set the specified bit true.
-
clear(uint32 bitIndex)
-
Set the specified bit false.
-
set(uint32 bitIndex, bool value)
-
Set the specified bit to value.
-
get(uint32 bitIndex)
-
Return the state of the specified bit.
-
clear()
-
Set all bits to false.
-
nextSetBit(uint32 fromIndex)
-
Get the index of the next true bit beginning with the specified - bit.
-
nextClearBit(uint32 fromIndex)
-
Get the index of the next false bit beginning with the specified - bit.
-
isEmpty()
-
Return (false,true) if (at least one bit true, all bits are false)
-
cardinality()
-
Return the number of true bits.
-
size()
-
Returns the number of bits of space actually in use.
-
operator&=(const BitSet& set)
-
Performs a logical and of this target bit set with the argument bit - set. This bit set is modified so that each bit in it has the value true - if and only if it both initially had the value true and the corresponding - bit in the bit set argument also had the value.
-
operator|=(const BitSet& set)
-
Performs a logical or of this target bit set with the argument bit - set.
-
operator^=(const BitSet& set)
-
Performs a logical exclusive or of this target bit set with the - argument bit set.
-
operator-=(const BitSet& set)
-

Clears all of the bits in this bitSet whose corresponding bit is set - in the specified bitSet.

-
-
operator=(const BitSet &set)
-
Assignment operator.
-
or_and(const BitSet& set1, const BitSet& set2)
-
Perform AND operation on set1 and set2, and then OR this bitSet with - the result.
-
operator==(const BitSet &set)
-
Does this bitSet have the same values as the argument.
-
operator!=(const BitSet &set)
-
Is this bitSet different than the argument.
-
virtual void serialize(ByteBuffer *buffer,SerializableControl *flusher) - const;
-
Serialize the bitSet
-
virtual void deserialize(ByteBuffer *buffer,DeserializableControl - *flusher);
-
Deserialize the bitSet.
-
-

- -

byteBuffer.h

- -

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();
- ...
-};
- -

destroyable.h

-
class Destroyable  {
-public:
-    POINTER_DEFINITIONS(Destroyable);
-    virtual void destroy() = 0;
-    virtual ~Destroyable() {};
-};
- -

epicsException.h

-
/*
- * 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.
- */
- -

event.h

- -

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

-
-
Event
-
The constructor. The initial value can be full or empty. The normal - first state is empty.
-
signal
-
The event becomes full. The current or next wait will complete.
-
wait
-
Wait until event is full or until timeout. The return value is - (false,true) if the wait completed because event (was not, was) full. A - false value normally means that that a timeout occured. It is also - returned if an error occurs or because the event is being deleted.
-
tryWait
-
returns (false,true) if the event is (empty,full)
-
- -

executor.h

- -

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:

-
-
Executor
-
The constructor. A thread name and priority must be specified.
-
~Executor
-
The destructor. If any commands remain in the execute list they are not - called. All ExecutorNodes that have been created are deleted.
-
execute
-
Request that command be executed. If it is already on the run list - nothing is done.
-
- -

localStaticLock.h

-
-extern epics::pvData::Mutex& getLocalStaticInitMutex();
-
-static class MutexInitializer {
-  public:
-    MutexInitializer ();
-    ~MutexInitializer ();
-} localStaticMutexInitializer; // Note object here in the header.
-
-

TBD Matej will explain.

- -

lock.h

-
-typedef epicsMutex Mutex;
-
-class Lock : private NoDefaultMethods {
-public:
-    explicit Lock(Mutex &pm);
-    ~Lock();
-    void lock();
-    void unlock();
-    bool tryLock();
-    bool ownsLock() ;
- ...
-};
- -

Lock is as easy to use as Java synchronize. To protect some object just -create a Mutex for the object and then in any method to be synchronized just -have code like:

-
class SomeClass {
-private
-    Mutex mutex;
- ...
-public
-    SomeClass() : mutex(Mutex()) {}
- ...
-    void method()
-    {
-        Lock xx(mutex);
-        ...
-    }
-
- -

The method will take the lock when xx is created and release the lock when -the current code block completes.

- -

Another example of Lock is initialization code that must initialize only -once. This can be implemented as follows:

-
    static void init(void) {
-        static Mutex mutex;
-        Lock guard(mutex);
-        if(alreadyInitialized) return;
-        // initialization
-    }
-

-

Lock has a private variable: -

-bool locked;
-
-and improves efficency by checking the local variable before calling the -mutex methods. This is not thread safe if any methods are called by a thread other than -the thread that created the Lock. -

-

It is thread safe if used as follows:

-
-{
-    Lock guard(mutex);
-    ...
-    /* the following can optionally be called
-    guard.unlock();
-    guard.lock();
-    */
-}
-
-

It is not thread safe if used as follows:

-
-class SomeClass
-{
-private:
-    Mutex mutex;
-    Lock lock;
-public:
-    SomeClass: lock(mutex) {}
-    ...
-    void someMethod() {
-        lock.unlock();
-        ...
-    }
-    ...
-};
-
-

It is only safe if all methods of Lock, including ~Lock(), -are called by the same thread. -

- -

messageQueue.h

- -

Definitions

- -

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:

-
-
getMessage
-
The message.
-
getMessageType
-
The message type.
-
setMessageNull
-
Set the message to be a null string.
-
- -

A messageQueue is an interface with public methods:

-
-
MessageQueue
-
The constructor. The queue size must be specified.
-
~MessageQueue
-
The destructor.
-
put
-
Put a new message into the queue. False is returned if the queue was - full and true otherwise. If replaceLast is true then the last message is - replaced with this message.
-
get
-
Get the oldest queue element. If the queue is empty null is returned. - Before the next get can be issued release must be called.
-
release
-
Release the queue element returned by the last get.
-
isEmpty
-
Is the queue empty?
-
isFull
-
Is the queue full?
-
getClearOverrun
-
Get the number of times put has been called but no free element is - available.
-
- -

Look at miscTest/testMessageQueue.cpp for an example.

- -

noDefaultMethods.h

- -

If a class privately extends this class then the compiler can not create any -of the following: default constructor, default copy constructror, or default -assignment contructor.

-
/* This is based on Item 6 of
- * Effective C++, Third Edition, Scott Meyers
- */
-    class NoDefaultMethods {
-    protected:
-    // allow by derived objects
-    NoDefaultMethods(){};
-    ~NoDefaultMethods(){}
-    private:
-    // do not implment
-    NoDefaultMethods(const NoDefaultMethods&);
-    NoDefaultMethods & operator=(const NoDefaultMethods &);
-    };
- -

queue.h

- -

This provides a bounded queue. When the queue is -full the user code is expected to keep using the current element until a new -free element becomes avalable.

-
-template <typename T>
-class Queue
-{   
-public:
-    POINTER_DEFINITIONS(Queue);
-    typedef std::tr1::shared_ptr<T> queueElementPtr;
-    typedef std::vector<queueElementPtr> queueElementPtrArray;
-    Queue(queueElementPtrArray &);
-    virtual ~Queue();
-    void clear();
-    int capacity();
-    int getNumberFree();
-    int getNumberUsed();
-    queueElementPtr & getFree();
-    void setUsed(queueElementPtr const &element);
-    queueElementPtr & getUsed();
-    void releaseUsed(queueElementPtr const &element);
- ...
-};
- -

testApp/misc/testQueue.cpp provides an example of how to define a queue.

- -

The queue methods are:

-
-
clear
-
Make the queue empty.
-
getNumberFree
-
Get the number of free elements in the queue.
-
capacity
-
Get the capacity, i.e. the maximun number of elements the queue can - hold.
-
getNumberFree
-
Get the number of free elements.
-
getNumberUsed
-
Get the number of elements used.
-
getFree
-
Get the next free element. Null is returned if no free elements are - available. If a non null value is returned then the element belongs to - the caller until setUsed is called.
-
setUsed
-
Set a queue element used. This must be the element returned by the last - call to getFree.
-
getUsed
-
Get the next used element of null if no more used elements are - available.
-
releaseUsed
-
Set a queue element free. This must be the element returned by the last - call to getUsed.
-
- -

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.h

- -

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

-
-
-
MessageType
-
Type of message.
-
messageTypeName
-
An array of strings of the message type names, i.e. - std::string("info"),std::string("warning"),std::string("error"),std::string("fatalError").
-
getRequesterName
-
Returns the requester name.
-
message
-
Gives a message to the requester.
-
- -

serialize.h

-
-    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;
-    };
- -

serializeHelper.h

- -

This is a helper class for serialization, which is required for sending and -receiving pvData over the nerwork.

-
class SerializeHelper : public NoDefaultMethods {
-public:
-    static void writeSize(int s, ByteBuffer* buffer,
-        SerializableControl* flusher);
-    static int readSize(ByteBuffer* buffer,
-        DeserializableControl* control);
-    static void serializeString(const std::string& value,
-        ByteBuffer* buffer,SerializableControl* flusher);
-    static void serializeSubstring(const std::string& value, int offset,
-        int count, ByteBuffer* buffer,
-        SerializableControl* flusher);
-    static std::string deserializeString(ByteBuffer* buffer,
-        DeserializableControl* control);
- ...
-};
- -

where

-
-
writeSize
-
Serialize the size.
-
readSize
-
Deserialize the size.
-
serializeString
-
Serialize a std::string.
-
serializeSubstring
-
Serialize a substring.
-
deserializeString
-
Deserialize a string.
-
- -

sharedPtr.h

-
-#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;
- -

sharedVector.h

-

-shared_vector is a holder for a contigious piece of memory. -Data is shared, but offset and length are not. -This allows one vector to have access to only a subset of a piece of memory. -

-

-shared_vector differs from std::vector as follows:

-
-
Differences in behavior
-
- shared_vector models const-ness like shared_ptr. - An equivalent of 'const std::vector<E>' is - 'const shared_vector<const E>'. - However, it is also possible to have 'const shared_vector<E>' - analogous to 'E* const' and 'shared_vector<const E>>' - which is analogous to 'const E*'.i -
- Copying a shared_vector, by construction or assignment, does not copy - its contents. - Modifications to one such "copy" effect all - associated shared_vector instances. -
- std::vector::reserve(N) has no effect if N<=std::vector::capacity(). - However, like resize(), shared_vector<E>::reserve() has the side effect - of always calling make_unique(). -
-
Parts of std::vector interface not implemented
-
- Mutating methods insert(), erase(), shrink_to_fit(), emplace(), and emplace_back() are not implemented. -
- shared_vector does not model an allocator which is bound to the object. Therefore the get_allocator() method and the allocator_type typedef are not provided. -
- The assign() method and the related constructor are not implemented at this time. -
- The comparison operators are not implemented at this time. -
-
Parts not found in std::vector
-
- shared_vector has additional constructors from raw pointers and shared_ptr s. - The copy constructor and assignment operator allow implicit castings - from type 'shared_vector<T>' to 'shared_vector<const T>>'. - To faciliate safe modification the methods unique() and make_unique() are provided - The slice() method selects a sub-set of the shared_vector. - The low level accessors dataPtr(), dataOffset(), dataCount(), and dataTotal(). -
-
- - -
-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
-
Several flavors of constructor are provided. The most commingly used is: - 
-shared_vector(size_t c);
-
- This creates a shared_vector of the specified size/ -
-
max_size
-
The maximum size the C++ implementation allows, i.e., - the maximum possible capacity. - Note that units are number of elements not number of bytes. -
-
capacity
-
The current capacity.
-
reserve
-
Set array capacity.
-
resize
-
Grow or shrink array. - It the second argument is given it is the value to assign to - and new elements. -
-
make_unique
-
Ensure (by copying) that this shared_vector - is the sole owner of the data array. -
-
begin,...,rend
-
Standard interators.
-
front
-
Return a reference to the first element.
-
back
-
Return a reference to the last element.
-
push_back
-
Add an element to the end of the array.
-
pop_back
-
Remove an element from the end of the array.
-
data
-
Return a pointer to the raw array.
-
operator[](size_t i)
-
Return a reference to the specified element.
-
at
-
Like the previous except that it throws a range-error if - the specified element is out of range.
-
operator=
-
Copy an existing shared_vector.
-
swap
-
Swap the contents of this vector with another.
-
clear
-
Clear contents.
-
unique
-
returns (true,false) if data (is not, is) shared.
-
size
-
Number of elements visible through this vector.
-
empty
-
Is the number of elements zero?
-
slice
-
Reduce the view of this shared_vector.
-
dataPtr
-
A readonly shared_ptr to the array.
-
dataOffset
-
Offset in the data array of first visible element.
-
dataCount
-
Number of visible elements between dataOffset and end of data.
-
dataTotal
-
The total number of elements between dataOffset and the end of data
-
-

TBD -Michael should decide if this is the correct set of methods to describe. -Also he should check for correct descriptions. -

- - -

status.h

- -

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:

-
-
StatusType
-
An enum for the status type.
-
getType
-
Get the statusType.
-
getMessage
-
Get a message explaining the error.
-
getStackDump
-
Get a stack dump.
-
- -

The StatusCreate methods are:

-
-
getStatusOK
-
Get a singleton that returns StatusType.OK and a null message and - stackDump.
-
createStatus
-
Create a new Status.
-
deserializeStatus
-
Use this method instead of Status.deserialize(), since this allows OK - status optimization.
-
-

templateMeta.h

-

TBD Michael will explain.

- -

thread.h

- -

ThreadPriority

-
enum ThreadPriority {
-    lowestPriority,
-    lowerPriority,
-    lowPriority,
-    middlePriority,
-    highPriority,
-    higherPriority,
-    highestPriority
-};
- -

Thread

-
-class Thread;
-typedef std::tr1::shared_ptr<Thread> ThreadPtr;
-typedef std::tr1::shared_ptr<epicsThread> EpicsThreadPtr;
-
-class Runnable {
-public:
-    virtual void run() = 0;
-};
-
-class Thread;
-
-class Thread : public epicsThread, private NoDefaultMethods {
-public:
-    Thread(
-        std::string name,
-        ThreadPriority priority,
-        Runnable *runnableReady,
-        epicsThreadStackSizeClass stkcls=epicsThreadStackSmall);
-    ~Thread();
- ...
-};
- -

Runnable must be implement by code that wants to be run via a thread. It has -one virtual method: run. Run is the code that is run as a thread. When run -compeletes it can not be restarted. If code wants to delete a thread then it -MUST arrange that the run returns before the thread can be deleted. An -exception is thrown if run remains active when delete is called.

- -

Thread has the methods:

-
-
Thread
-
The constructor. A thread name and priority must be specified. The run - methods of runnable is executed. When the run methods returns the thread - will no longer be active but the client code must still delete the - thread.
-
~Thread
-
The destructor. This is called as the result of: - 
    delete pthread;
-
-
- -

timeFunction.h

- -

TimeFunction is a facility that measures the average number of seconds a -function call requires. When timeCall is called, it calls function in a loop. -It starts with a loop of one iteration. If the total elapsed time is less then -.1 seconds it increases the number of iterrations by a factor of 10. It keeps -repeating until the elapsed time is greater than .1 seconds. It returns the -average number of seconds per call.

-
class TimeFunctionRequester;
-class TimeFunction;
-typedef std::tr1::shared_ptr<TimeFunctionRequester> TimeFunctionRequesterPtr;
-typedef std::tr1::shared_ptr<TimeFunction> TimeFunctionPtr;
-        
-class TimeFunctionRequester {
-public:              
-    POINTER_DEFINITIONS(TimeFunctionRequester);
-    virtual ~TimeFunctionRequester(){}
-    virtual void function() = 0;
-};  
-
-    
-class TimeFunction {
-public:    
-    POINTER_DEFINITIONS(TimeFunction);
-    TimeFunction(TimeFunctionRequesterPtr const & requester);
-    ~TimeFunction(); 
-    double timeCall();
- ...
-};
- -

TimeFunctionRequester must be implemented by code that wants to time how -long a function takes. It has the single method:

-
-
function
-
This is the function.
-
- -

TimeFunction has the methods:

-
-
TimeFunction
-
Constructor.
-
~TimeFunction
-
Destructor.
-
timeCall
-
Time how long it takes to execute the function. It starts by calling - the function one time. If it takes < 1 seconds to doubles the number - of times to call the function. It repeats this until it takes at least - one second to call it ntimes.
-
- -

timer.h

- -

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: -

-
-
callback
-
This is called when a timer expires. This is called with no locks held. - When called a delay timer is no longer on the queue but a periodioc timer - is on a queue. Thus the callback for a delay timer can issue a new - schedule request but a periodic timer must not. Note the explaination of - TimerNode.cancel below.
-
timerStopped
-
Timer.stop was called when a timer request was queued. or if the timer - is stopped and a schedule request is made.
-
- -

In order to schedule a callback client code must allocate a TimerNode It can -be used to schedule multiple callbacks. It has the methods:

-
-
TimerNode
-
The constructor. User code must create a TimeNode in order to call a - schedule method.
-
~TimerNode
-
The destructor. This is called as a result of the client calling: - 
    delete timerNode;
-
-
cancel
-
This is called to cancel a timer request. If a callback has been - dequeued but the callback not called when cancel is called then a - callback may still happen. New schedule requests can be made after a - cancel request has been made.
-
isScheduled
-
Is the timerNode scheduled to be called.
-
- -

Timer has the methods:

-
-
Timer
-
The consttructor.
-
~Timer
-
The destructor. The queue is emptied and TimerCallback.timerStopped is - called for each element of the queue.
-
scheduleAfterDelay
-
A request to schedule a callback after a delay specified in - seconds.
-
schedulePeriodic
-
Schedule a periodic callback.
-
-

typeCast.h

-

TBD Michael will explain.

- -

pvDataApp/pvMisc

- -

bitSetUtil.h

- -

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:

-
-
compress
-
Compress the bits in a BitSet related to a structure.
- For each structure: -
    -
  1. If the bit for the structure is set then the bit for all subfields - of the structure are cleared.
    2. -
  2. If the bit for the structure is not set but all immediate subfields - have their bit set then the bit for the structure is set and the bits - for all subfields are cleared.
    3. -
- Note that this is a recursive algorithm. That is if every immediate - subfield has it's offset bit set then the bits for ALL fields that reside - in the structure will be cleared.
-
Channel Access can call this before sending data. It can then pass - entire structures if the structure offset bit is set.
-
- -

support for copy and monitor

-

copy and monitor are not used in this project. -They are intended for use by pvAccess and by pvAccess servers. -They are provided with this project because the code depends only on -pvData itself. -

-

This document describes C++ specific code. - -pvRequest.html -provides a language independent overview of copy and monitor. -

-

-NOTE:pvRequest.html must be updated since it is based on an earlier version of pvCopy that -had knowlege of PVRecord. The C++ version was implemented in pvDatabaseCPP -and the Java version on pvIOCJava. -At present only the C++ version of the new API for pvCopy is implemented. -

-

Copy provides: -

-
createRequest
-
- The Channel create methods in pvAccess all have an argument - PVStructure pvRequest.
- Given an ascii string createRequest creates a PVStructure that provides - a pvData representation of the information from the ascii string. - It is this structure that can be passed to the channel create methods.
- The information in a pvRequest selects an arbitrarary subset of the - fields in a top level structure that resides in the server. - In addition options can be specified. Both global and field specific - options can be specified. -
-
pvCopy
-
This is a faculity used by channel providers. - It provides client specific code that manages a copy of an arbitrary - subset of the fields in a top level structure that resides in the - provider. It also allows provider access to options specified - by the client. -
-
-Monitor provides: -
-
monitor
-
This is support code for channel providers that implement channel - monitor. It, together with the queue facility, provides support for - monitor queues. -
-
monitorPlugin
-
This is support for implementing monitor plugins. - A monitor plugin can be developed that has no knowledge - of pvAccess but only pvData. -
-
-

- -

support for copy

-

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. -

- -

createRequest

-

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
-}
-
-

pvCopy

-

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  &copyPVStructure,
-        BitSetPtr const  &bitSet);
-     void updateCopySetBitSet(
-        PVStructurePtr const  &copyPVStructure,
-        BitSetPtr const  &bitSet);
-    void updateCopyFromBitSet(
-        PVStructurePtr const  &copyPVStructure,
-        BitSetPtr const  &bitSet);
-    void updateMaster(
-        PVStructurePtr const  &copyPVStructure,
-        BitSetPtr const  &bitSet);
-    PVStructurePtr getOptions(std::size_t fieldOffset);
-    std::string dump();
-...
-};
-
-where -
-
PVCopyTraverseMasterCallback::nextMasterPVField
-
- PVCopyTraverseMasterCallback is a callback which must - be implemented by the code that uses pvCopy, normally - the channel provider. It has the single method nextMasterPVField -
- nextMasterPVField is called for each field in the master - as a result of a call to traverseMaster. -
-
create
-
- This is the method for creating a PVCopy instance.
-
-
pvMaster
-
the top level sructure managed by the server.
-
pvRequest
-
selects the set of subfields desired - and options for each field.
-
structureName
-
the name for the top level of any PVStructure created. -
-
-
-
getPVMaster
-
- Gets the top level structure from pvMaster. -
-
traverseMaster
-
- Traverse all fields of the top level structure of pvMaster. - For each field the callback is called. -
-
getStructure
-
- Get the introspection interface for a PVStructure for e copy. -
-
createPVStructure
-
Create a copy instance. - Monitors keep a queue of monitor elements. - Since each element needs a PVStructure, multiple top level structures - will be created. -
-
getCopyOffset
-
Given a field in pvMaster. - return the offset in copy for the same field. - A value of std::string::npos means that the copy does not have this field. - Two overloaded methods are provided. The first is called if - the field of master is not a structure. The second is for - subfields of a structure. -
-
getMasterPVField
-
- Given a offset in the copy get the corresponding field in pvMaster. -
-
initCopy
-
- Initialize the fields in copyPVStructure - by giving each field the value from the corresponding field in pvMaster. - bitSet will be set to show that all fields are changed. - This means that bit set will have the value {0}. -
-
updateCopySetBitSet
-
- Set all fields in copyPVStructure to the value of the corresponding field - in pvMaster. Each field that is changed has it's corresponding - bit set in bitSet. -
-
updateCopyFromBitSet
-
- For each set bit in bitSet set the field in copyPVStructure to the value - of the corrseponding field in pvMaster. -
-
updateMaster
-
- For each set bit in bitSet set the field in pvMaster to the value - of the corrseponding field in copyPVStructure. - -
-
getOptions
-
- Get the options for the field at the specified offset. - A NULL is returned if no options were specified for the field. - If options were specified,PVStructurePtr is - a structure with a set of PVString subfields that specify name,value - pairs. name is the subField name and value is the subField value. -
-
- - - - -

support for monitor

-

This consists of two components: -

-
monitor
-
Used by code that implements pvAccess montors.
-
monitorPlugin
-
Code that provides special semantics for monitors.
-
-

-

monitor

-
-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

-

MonitorElement holds the data for one element of a monitor queue. -It has the fields: -

-
pvStructurePtr
-
A top level structure with data values at the time the monitors occurs.
-
changedBitSet
-
Shows which fields have changed since the previous monitor.
-
overrunBitSet
-
Shows which fields have changed more han once since the previous monitor.
-
-

-

monitorElement queue

-

-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

-

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:

-
-
start
-
- Start monitoring. - This will result in a an inital monitor that has the current value - of all fields. -
-
stop
-
- Stop monitoring. -
-
poll
-
- Called to get a monitor element. - If no new elemants are available then a null pointer is returned. -
-
release
-
- Release the monotor element. - The caller owns the monitor element between the calls to poll and release. -
-
-
-

MonitorRequester

-

This must be implemented by a pvAccess client. -It has the methods:

-
-
monitorConnect
-
- A monitor has either connected of disconnected. -
-
monitorEvent
-
- A new monitor element is available. -
-
unlisten
-
- The channel is going away. The client cam no longer access the monitor. -
-
- -

monitorPlugin

-
-class MonitorPlugin
-{
-    virtual std::string const & getName() = 0;
-    virtual bool causeMonitor(
-        PVFieldPtr const &pvField,
-        PVStructurePtr const &pvTop,
-        MonitorElementPtr const &monitorElement) = 0;
-    virtual void monitorDone(
-        MonitorElementPtr const &monitorElement);
-    virtual void startMonitoring();
-    virtual void stopMonitoring();
-    virtual void beginGroupPut();
-    virtual void endGroupPut();
-};
-
-class MonitorPluginCreator
-{
-    virtual MonitorPluginPtr create(
-        FieldConstPtr const &field,
-        StructureConstPtr const &top,
-        PVStructurePtr const &pvFieldOptions) = 0;
-     virtual std::string const & getName() = 0;
-}
-
-class MonitorPluginManager
-{
-    static MonitorPluginManagerPtr get();
-    bool addPlugin(
-         std::string const &pluginName,
-         MonitorPluginCreatorPtr const &creator);
-    MonitorPluginCreatorPtr findPlugin(std::string const &pluginName);
-    void showNames();
-};
-
-
-

MonitorPlugin

-

MonitorPlugin must be implemented by the plugin implementation. -It has methods:

-
-
getName
-
Get the name of the plugin.
-
causeMonitor
-
- Should the value of pvField cause a monitor to be raised. - pvField and pvTop are fields in the top level structure - being monitored. monitorElement has the top level structure - for the copy. - The implementation should not modify the fields in the structure - being monitored. - Called with pvTop locked. -
-
monitorDone
-
- Called just before monitorElement will be given to client. - The plugin can change the data values and bitSets in monitorElement. - Called with pvTop unlocked. -
-
startMonitoring
-
- Monitoring is starting. -
-
stopMonitoring
-
- Monitoring is being stopped. -
-
beginGroupPut
-
- A set of puts is starting. - Called with pvTop locked. -
-
endGroupPut
-
- The set of puts is complete. - Called with pvTop locked. -
-
-

MonitorPluginCreator

-

MonitorPluginCreator must also be implemented by the plugin implementation. -It is called for each field instance that has options of the from -[plugin=name...] where name is the name of the plugin. -Note that a plugin instance will belong to a single client. -It has methods:

-
-
getName
-
Get the name of the plugin.
-
create
-
- Create a new plugin instance. - If the arguments are not compatible with the plugin a NULL shared pointer is - returned.
- pvFieldOptions is - a structure with a set of PVString subfields that specify name,value - pairs. name is the subField name and value is the subField value.
- Note that a plugin will below to a single client. -
-
-

MonitorPluginManager

-

MonitorPluginManager has the methods:

-
-
get
-
- MonitorPluginManager is a singleton. - The first call to get will create the single instance. - Further calls will rerurn the single instance. -
-
addPlugin
-
- Add a new plugin. -
-
findPlugin
-
- Find a plugin. A NULL shared pointer is reurned if it has not been added. -
-
showNames
-
- Show the names of all puugins that have been added. -
-
-

NOTE: -Should the method causeMonitor -have arguments pvField and pvTop -be defined so that they can not be modfied. -This would be posssible if the following was defined: -

-typedef std::tr1::shared_ptr<const PVField> PVFieldConstPtr;
-typedef std::tr1::shared_ptr<const PVStructure> PVStructureConstPtr;
-
-then the definition for causeMonitor could be: -
-virtual bool causeMonitor(
-        PVFieldConstPtr const &pvField,
-        PVStructureConstPtr const &pvTop,
-        MonitorElementPtr const &monitorElement) = 0;
-
-But just adding these definitions is not sufficent. -In addition all methods defined in pvDataCPP must be checked. -In particular many of the methods in Convert must have -their arguments modified. -Big job. -

-

monitorPlugin example

-

Example Plugin Overview

-

This section describes an example plugin that:

-
    -
  • Only raises monitors when a field changes value.
    - If no plugin is provided - the default is to raise a monitor when a put is issued to a field.
    • -
  • Optionally a change will not raise a monitor.
    - The change will, however, - appear if a put to another field raise a monitor.
    • -
-

As an example assume that a channel provided by pvAccess has a top level structure -that represents a power supply.

-
-structure powerSupply
-    structure alarm
-    structure timeStamp
-    structure power
-       double value
-       structure alarm
-       struvture display
-    structure voltage
-       double value
-       structure alarm
-       struvture display
-    structure current
-       double value
-       structure alarm
-       struvture display
-
-

A pvAccess client wants to create a monitor on the powerSupply as follows: -The client wants a top level structure that looks like: -

-structure powerSupply
-    structure alarm
-    structure timeStamp
-    structure power
-       double value
-    structure voltage
-       double value
-    structure current
-       double value
-
-In addition the client wants monitors to occur only when one of the monitored -fields changes value but not just because a put occured. -Also if only the timeStamp changes value then that should not cause a monitor. -

-

The example monitor plugin implements the semantics the -client wants. It can be attached to any field via the following options: -

-[plugin=onChange,raiseMonitor=value]
-
-This plugin will trigger a monitor for the field only if the field changes -value. In addition value equals false means do not raise a monotor -for changes to this field. -But if a change to another field does cause a monitor the change to this field -will be passed to the client. -

-

-Assume that the client has already connected to the channel. -The client can then issue the commands:

-
-std::string request("field(alarm[plugin=onChange]");
-request += ",timeStamp[plugin=onChange,raiseMonitor=false]";
-request += ",power.value[plugin=onChange";
-request += ",voltage.value[plugin=onChange";
-request += ",current.value[plugin=onChange";
-
-PVStructurePtr pvRequest = createRequest->createRequest(request);
-
-MonitorPtr monitor = channel->createMonitor(monitorRequester,pvRequest);
-
-

Example Plugin Code

-

The header file to create the example has the definition:

-
-class ExampleMonitorPlugin{
-public:
-    static void create();
-};
-
-

The implementation is:

-
-class OnChangePlugin : public MonitorPlugin
-{
-public:
-    virtual ~OnChangePlugin(){}
-    OnChangePlugin() {}
-    bool init(
-        FieldConstPtr const &field,
-        StructureConstPtr const &top,
-        PVStructurePtr const &pvFieldOptions)
-   {
-        pvField = getPVDataCreate()->createPVField(field);
-        raiseMonitor = true;
-        if(pvFieldOptions!=NULL) {
-            PVStringPtr pvString =
-                pvFieldOptions->getSubField<PVString>("raiseMonitor");
-                if(pvString!=NULL) {
-                    std::string value = pvString->get();
-                    if(value.compare("false")==0) raiseMonitor = false;
-                }
-        }
-        return true;
-   }
-   virtual std::string &getName(){return pluginName;}
-   virtual bool causeMonitor(
-        PVFieldPtr const &pvNew,
-        PVStructurePtr const &pvTop,
-        MonitorElementPtr const &monitorElement)
-   {
-       bool isSame = convert->equals(pvNew,pvField);
-       if(isSame) return false;
-       convert->copy(pvNew,pvField);
-       return raiseMonitor;
-   }
-private:
-   PVFieldPtr pvField;
-   bool raiseMonitor;
-};
-class OnChangePluginCreator : public MonitorPluginCreator
-{
-public:
-    virtual std::string &getName(){return pluginName;}
-    virtual MonitorPluginPtr create(
-        FieldConstPtr const &field,
-        StructureConstPtr const &top,
-        PVStructurePtr const &pvFieldOptions)
-   {
-       OnChangePluginPtr plugin(new OnChangePlugin());
-       bool result = plugin->init(field,top,pvFieldOptions);
-       if(!result) return MonitorPluginPtr();
-       return plugin;
-   }
-
-};
-
-void ExampleMonitorPlugin::create()
-{
-    static OnChangePluginCreatorPtr plugin;
-    static Mutex mutex;
-    Lock xx(mutex);
-    if(plugin==NULL) {
-        plugin = OnChangePluginCreatorPtr(new OnChangePluginCreator());
-        MonitorPluginManager::get()->addPlugin(pluginName,plugin);
-    }
-}
-
- - -
- - diff --git a/documentation/pvDataCPP_20140723.html b/documentation/pvDataCPP_20140723.html deleted file mode 100644 index 8caf403..0000000 --- a/documentation/pvDataCPP_20140723.html +++ /dev/null @@ -1,5392 +0,0 @@ - - - - - - EPICS pvDataCPP - - - - - - - - -
-

EPICS pvDataCPP

- - -

EPICS v4 Working Group, Working Draft, 23-July-2014

- -
-
Latest version:
-
pvDataCPP.html -
-
This version:
-
pvDataCPP_20140723.html -
-
Previous version:
-
pvDataCPP_20140708.html -
-
Editors:
-
Marty Kraimer, BNL
-
Michael Davidsaver, BNL
-
Matej Sekoranja, CosyLab
-
- -

This product is made available subject to acceptance of the EPICS open source -license.

-
-
- -

Abstract

- -

EPICS Version 4 provides efficient -storage, access, and communication, of memory resident structured data. -pvData is the storage compoment. -pvDataCPP is the C++ implementation of pvData. -It is one part of the set of related products in the EPICS -V4 control system programming environment:
-relatedDocumentsV4.html -

- - -

Status of this Document

- -

This is the 23-July-2014 version of the C++ implementation of pvData. -

- -

RELEASE_NOTES.md provides changes since the last release. -TODO.md describes things to do before the next release. -

- - - -
-

Table of Contents

-
-
- -

Introduction

- -

pvData is one of a set of related projects. It describes and implements -data that the other projects support. Thus it is not useful by itself but -understanding pvData is required in order to understand the other projects. The -reader should also become familar with project pvAccess, which is -located via the same sourceforge site as this project.

- -

The Java and C++ implementation of pvData implement the same data model but -differ in implementation because of the differences between Java and C++.

- -

It is a good idea to read all of pvDataJava.html but read at least the -first two chapters:

-
-
Introduction
-
A brief descripton of pvData.
-
PVData Meta Language
-
A language used to describe data.
-
- -

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:

-
-
pvDataAPP/pv
-
This subdirectory contains all the public interfaces that describe pvData. - The section from Namespace and Memory Management - through Conversion discuss these interfaces. -
-
pvDataApp/property
-
This section has support for managing "standard" fields. -
-
pvDataApp/misc
-
This section has support for facilities required by implementation code.
-
copy and monitor
-
These sections provide pvData support for implementing pvAccess providers.
-
- -

Examples

-

This section provides some examples of creating and accessing both introspection and -data interfaces. The first time reader may not understand them but hopefully will get an -idea of how pvData works. After reading the rest of this document the examples will -be much easier to understand. -

-

The documentation directory for this project has a file examples.zip. -It has the code for the examples. -After it is unzipped:

-
-cd examples/configure
-cp ExampleRELEASE.local RELEASE.local
-#edit RELEASE.local
-cd ..
-make
-bin/linux-x86_64/introspectMain 
-bin/linux-x86_64/dataMain
-
-

-

The examples assume that the following statements have been issued:

-
-using std::cout;
-using std::endl;
-FieldCreatePtr fieldCreate = getFieldCreate();
-PVDataCreatePtr pvDataCreate = getPVDataCreate();
-StandardFieldPtr standardField = getStandardField();
-StandardPVFieldPtr standardPVField = getStandardPVField();
-
-

These provide access to most of pvData:

-
-
fieldCreate
-
This creates instances of introspection objects. - It also provides fieldBuilder, which provides an easier way to create introspection objects. -
-
pvDataCreate
-
This creates instances of data objects. -
-
standardField
-
This provides support for introspection obects for standard fields, - Standard fields are alarm, timeStamp, display, enumerated structure, and value alarm. -
-
standardPVField
-
This provides support for data obects for standard fields, -
-
- - -

Introspection Examples

-

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.

-

Three ways to create a structure

-

The following is the hardest way to create structure that has a double value field and a time stamp field: -It uses only createField. -

-
-    size_t n = 3;
-    StringArray names;
-    names.reserve(n);
-    FieldConstPtrArray fields;
-    fields.reserve(n);
-    names.push_back("secondsPastEpoch");
-    fields.push_back(fieldCreate->createScalar(pvLong));
-    names.push_back("nanoseconds");
-    fields.push_back(fieldCreate->createScalar(pvInt));
-    names.push_back("userTag");
-    fields.push_back(fieldCreate->createScalar(pvInt));
-    StructureConstPtr timeStamp = fieldCreate->createStructure(names,fields);
-    size_t ntop = 2;
-    StringArray topnames;
-    topnames.reserve(ntop);
-    FieldConstPtrArray topfields;
-    topfields.reserve(ntop);
-    topnames.push_back("value");
-    topfields.push_back(fieldCreate->createScalar(pvDouble));
-    topnames.push_back("timeStamp");
-    topfields.push_back(timeStamp);
-    StructureConstPtr doubleScalar =
-        fieldCreate->createStructure(topnames,topfields);
-    cout << doubleScalar->dump(cout) << endl;
-
-

Using FieldBuilder the same can be done via:

-
-    StructureConstPtr doubleScalarHard =
-    getFieldCreate()->createFieldBuilder()->
-        add("value",pvDouble) ->
-        addNestedStructure("timeStamp")->
-            setId("time_t")->
-            add("secondsPastEpoch", pvLong)->
-            add("nanoseconds", pvInt)->
-            add("userTag", pvInt)->
-            endNested()->
-        createStructure();
-    cout << doubleScalarHard->dump(cout) << endl;
-
-

The easiest way to produce the structure is:

-
-    StructureConstPtr stringArrayEasy =
-         getStandardField()->scalarArray(pvString,"alarm,timeStamp");
-    cout << stringArrayEasy->dump(cout) << "\n\n";
-
-These three ways produce: -
-hardest way
-structure
-    double value
-    structure timeStamp
-        long secsPastEpoch
-        int nanoseconds
-        int userTag
-
-hardway
-structure
-    double value
-    time_t timeStamp
-        long secsPastEpoch
-        int nanoseconds
-        int userTag
-
-easy way
-uri:ev4:nt/2012/pwd:NTScalarArray
-    string[] value
-    alarm_t alarm
-        int severity
-        int status
-        string message
-    time_t timeStamp
-        long secondsPastEpoch
-        int nanoseconds
-        int userTag
-
-

An easy way to create a structure with a string array value field and an alarm and time stamp is -via standardField:

-
-    StructureConstPtr stringArrayEasy =
-        standardField->scalarArray(pvString,"alarm,timeStamp");
-    cout <<stringArrayEasy->dump(cout) << endl;
-
-It produces : -
-uri:ev4:nt/2012/pwd:NTScalarArray
-    string[] value
-    alarm_t alarm
-        int severity
-        int status
-        string message
-    time_t timeStamp
-        long secondsPastEpoch
-        int nanoseconds
-        int userTag
-0x607188
-
-

enumerated structure

-

An enumerated structure is a structure with two sub-fields: -index, which is an int, and choices, which is an array of string. -The following examples create a structure which has a field names value, which -is an enumerated structure and additional fields. -A hard way to create an structure with an enumerated value field and a time stamp is:

-
-    StructureConstPtr enum_t =
-    fieldCreate->createFieldBuilder()->
-        setId("enum_t")->
-        add("index", pvInt)->
-        addArray("choices", pvString)->
-        createStructure();
-
-    StructureConstPtr ntEnumHard =
-    fieldCreate->createFieldBuilder()->
-        setId("uri:ev4:nt/2012/pwd/NTEnum")->
-        add("value", enum_t)->
-        addNestedStructure("timeStamp")->
-            setId("time_t")->
-            add("secondsPastEpoch", pvLong)->
-            add("nanoseconds", pvInt)->
-            add("userTag", pvInt)->
-            endNested()->
-        createStructure();
-    cout <<ntEnumHard->dump(cout) << endl;
-
-It produces: -
-uri:ev4:nt/2012/pwd/NTEnum
-    enum_t value
-        int index
-        string[] choices
-    time_t timeStamp
-        long secondsPastEpoch
-        int nanoseconds
-        int userTag
-
-

The following is an easy way. Note that it has two additional -fields: alarm and timeStamp:

-
-    StructureConstPtr ntEnumEasy = getStandardField()->enumerated("alarm,timeStamp");
-    cout <<ntEnumEsay->dump(cout) << endl;
-
-It produces: -
-uri:ev4:nt/2012/pwd:NTEnum
-    enum_t value
-        int index
-        string[] choices
-    alarm_t alarm
-        int severity
-        int status
-        string message
-    time_t timeStamp
-        long secondsPastEpoch
-        int nanoseconds
-        int userTag
-
- -

union example

-

The following creates a union and a structure with a union value field:

- -
-    UnionConstPtr ntunion =
-    fieldCreate->createFieldBuilder()->
-        add("doubleValue", pvDouble)->
-        add("intValue", pvInt)->
-        add("timeStamp",standardField->timeStamp())->
-        createUnion();
-    cout <<ntunion->dump(cout) << endl;
-
-    StructureConstPtr unionValue = standardField->regUnion(punion,"alarm,timeStamp");
-    cout <<unionValue->dump(cout) << endl;
-
-It produces: -
-union
-    double doubleValue
-    int intValue
-    time_t timeStamp
-        long secondsPastEpoch
-        int nanoseconds
-        int userTag
-
-structure with value field being a union
-uri:ev4:nt/2012/pwd:NTUnion
-    union value
-        double doubleValue
-        int intValue
-        time_t timeStamp
-            long secondsPastEpoch
-            int nanoseconds
-            int userTag
-    alarm_t alarm
-        int severity
-        int status
-        string message
-    time_t timeStamp
-        long secondsPastEpoch
-        int nanoseconds
-        int userTag
-
- -

union array example

-

The following:

-
-    UnionArrayConstPtr unionArray = fieldCreate->createUnionArray(
-        fieldCreate->createVariantUnion());
-    cout << unionArray->dump(cout) << "\n\n";
-
-

Produces

-
-any[]
-any
-0x607188
-
-

power supply

-

The following creates a more complex structure:

-
-    StructureConstPtr powerSupply =
-    fieldCreate->createFieldBuilder()->
-        add("alarm",standardField->alarm()) ->
-        add("timestamp",standardField->timeStamp()) ->
-        addNestedStructure("power") ->
-           add("value",pvDouble) ->
-           add("alarm",standardField->alarm()) ->
-           endNested()->
-        addNestedStructure("voltage") ->
-           add("value",pvDouble) ->
-           add("alarm",standardField->alarm()) ->
-           endNested()->
-        addNestedStructure("current") ->
-           add("value",pvDouble) ->
-           add("alarm",standardField->alarm()) ->
-           endNested()->
-        createStructure();
-    std::cout << powerSupply->dumpValue(cout) <<std::endl;
-
-It produces: -
-structure
-    alarm_t alarm
-        int severity
-        int status
-        string message
-    time_t timestamp
-        long secondsPastEpoch
-        int nanoseconds
-        int userTag
-    structure power
-        double value
-        alarm_t alarm
-            int severity
-            int status
-            string message
-    structure voltage
-        double value
-        alarm_t alarm
-            int severity
-            int status
-            string message
-    structure current
-        double value
-        alarm_t alarm
-            int severity
-            int status
-            string message
-
-

Data Examples

-

The examples all produce a top level structure.

-

scalar example

-
-    PVStructurePtr doubleValue = getPVDataCreate()->createPVStructure(
-        getStandardField()->scalar(pvDouble,"alarm,timeStamp"));
-    PVDoublePtr pvdouble =
-        doubleValue->getSubField<PVDouble>("value");
-    pvdouble->put(1e5);
-    cout << doubleValue->dumpValue(cout) << endl;
-    double value = doubleValue->getSubField<PVDouble>("value")->get();
-    cout << "from get " << value << "\n\n";
-
-This produces: -
-uri:ev4:nt/2012/pwd:NTScalar 
-    double value 100000
-    alarm_t alarm
-        int severity 0
-        int status 0
-        string message 
-    time_t timeStamp
-        long secondsPastEpoch 0
-        int nanoseconds 0
-        int userTag 0
-0x607268
-from get 100000
-
-

array example

-
-    PVStructurePtr doubleArrayValue = pvDataCreate->createPVStructure(
-        standardField->scalarArray(pvDouble,"alarm,timeStamp"));
-    PVDoubleArrayPtr pvDoubleArray =
-         doubleArrayValue->getSubField<PVDoubleArray>("value");
-    size_t len = 10;
-    shared_vector<double> xxx(len);
-    for(size_t i=0; i< len; ++i) xxx[i] = i;
-    shared_vector<const double> data(freeze(xxx));
-    pvDoubleArray->replace(data);
-    cout << doubleArrayValue->dumpValue(cout) << endl;
-    
-    shared_vector<const double>  getData = pvDoubleArray->view();
-    cout << "via getData";
-    for (size_t i=0; i< len; ++i) cout << " " << getData[i];
-    cout << endl;
-
-This produces: -
-uri:ev4:nt/2012/pwd:NTScalarArray 
-    double[] value [0,1,2,3,4,5,6,7,8,9]
-    alarm_t alarm
-        int severity 0
-        int status 0
-        string message 
-    time_t timeStamp
-        long secondsPastEpoch 0
-        int nanoseconds 0
-        int userTag 0
-0x607268
-via getData 0 1 2 3 4 5 6 7 8 9
-
-

enumerated example

-
-    PVStructurePtr pvntenum = pvDataCreate->createPVStructure(
-         standardField->enumerated("alarm,timeStamp"));
-    cout << pvntenum->dumpValue(cout) << "\n\n";
-
-This produces: -
-uri:ev4:nt/2012/pwd:NTEnum 
-    enum_t value
-        int index 0
-        string[] choices []
-    alarm_t alarm
-        int severity 0
-        int status 0
-        string message 
-    time_t timeStamp
-        long secondsPastEpoch 0
-        int nanoseconds 0
-        int userTag 0
-0x607268
-
-

power supply example

-
-    StructureConstPtr powerSupply =
-    fieldCreate->createFieldBuilder()->
-        add("alarm",alarm) ->
-        add("timestamp",timeStamp) ->
-        addNestedStructure("power") ->
-           add("value",pvDouble) ->
-           add("alarm",alarm) ->
-           endNested()->
-        addNestedStructure("voltage") ->
-           add("value",pvDouble) ->
-           add("alarm",alarm) ->
-           endNested()->
-        addNestedStructure("current") ->
-           add("value",pvDouble) ->
-           add("alarm",alarm) ->
-           endNested()->
-        createStructure();
-    PVStructurePtr pvpowerSupply = pvDataCreate->createPVStructure(powerSupply);
-    cout << pvpowerSupply->dumpValue(cout) << endl;
-
-This produces: -
-structure 
-    alarm_t alarm_t
-        int severity 0
-        int status 0
-        string message 
-    time_t timestamp_t
-        long secondsPastEpoch 0
-        int nanoseconds 0
-        int userTag 0
-    structure power
-        double value 0
-        alarm_t alarm
-            int severity 0
-            int status 0
-            string message 
-    structure voltage
-        double value 0
-        alarm_t alarm
-            int severity 0
-            int status 0
-            string message 
-    structure current
-        double value 0
-        alarm_t alarm
-            int severity 0
-            int status 0
-            string message 
-0x607268
-
-

union example

-
-    PVStructurePtr pvStructure = pvDataCreate->createPVStructure(
-        standardField->regUnion(
-            fieldCreate->createFieldBuilder()->
-                add("doubleValue", pvDouble)->
-                add("intValue", pvInt)->
-                add("timeStamp",standardField->timeStamp())->
-                createUnion(),
-            "alarm,timeStamp"));
-    PVStructurePtr pvTimeStamp =
-        pvStructure->getSubField<PVUnion>("value")->select<PVStructure>(2);
-    pvTimeStamp->getSubField<PVLong>("secondsPastEpoch")->put(1000);
-    cout << pvStructure->dumpValue(cout) << "\n";
-    pvStructure->getSubField<PVUnion>("value")->select<PVDouble>(0)->put(1e5);
-    cout << pvStructure->dumpValue(cout) << "\n\n";
-
-This produces: -
-uri:ev4:nt/2012/pwd:NTUnion
-    union value
-        time_t
-            long secondsPastEpoch 1000
-            int nanoseconds 0
-            int userTag 0
-    alarm_t alarm
-        int severity 0
-        int status 0
-        string message
-    time_t timeStamp
-        long secondsPastEpoch 0
-        int nanoseconds 0
-        int userTag 0
-0x60a2c8
-uri:ev4:nt/2012/pwd:NTUnion
-    union value
-        double  100000
-    alarm_t alarm
-        int severity 0
-        int status 0
-        string message
-    time_t timeStamp
-        long secondsPastEpoch 0
-        int nanoseconds 0
-        int userTag 0
-0x60a2c8
-
- -

varient union example

-
-    PVStructurePtr pvStructure = pvDataCreate->createPVStructure(
-        standardField->variantUnion("alarm,timeStamp"));
-    PVStructurePtr pvTimeStamp =
-        pvDataCreate->createPVStructure(standardField->timeStamp());
-    pvStructure->getSubField<PVUnion>("value")->set(pvTimeStamp);
-    pvTimeStamp->getSubField<PVLong>("secondsPastEpoch")->put(1000);
-    cout << pvStructure->dumpValue(cout) << "\n";
-    pvStructure->getSubField<PVUnion>("value")->set(
-        pvDataCreate->createPVScalar(pvDouble));
-    PVDoublePtr pvValue = static_pointer_cast<PVDouble>(
-        pvStructure->getSubField<PVUnion>("value")->get());
-    pvValue->put(1e5);
-    cout << pvStructure->dumpValue(cout) << "\n\n";
-
-This produces: -
-uri:ev4:nt/2012/pwd:NTUnion
-    any value
-        time_t
-            long secondsPastEpoch 1000
-            int nanoseconds 0
-            int userTag 0
-    alarm_t alarm
-        int severity 0
-        int status 0
-        string message
-    time_t timeStamp
-        long secondsPastEpoch 0
-        int nanoseconds 0
-        int userTag 0
-0x60a2c8
-uri:ev4:nt/2012/pwd:NTUnion
-    any value
-        double  100000
-    alarm_t alarm
-        int severity 0
-        int status 0
-        string message
-    time_t timeStamp
-        long secondsPastEpoch 0
-        int nanoseconds 0
-        int userTag 0
-0x60a2c8
-
- -

big union example

-
-    PVStructurePtr pvStructure = pvDataCreate->createPVStructure(
-        standardField->regUnion(
-            fieldCreate->createFieldBuilder()->
-                add("doubleValue", pvDouble)->
-                addArray("doubleArrayValue",pvDouble)->
-                addNestedUnion("unionValue") ->
-                    add("doubleValue", pvDouble)->
-                    add("alarm",standardField->alarm()) ->
-                    endNested() ->
-                addNestedStructure("structValue") ->
-                    add("doubleValue", pvDouble)->
-                    addArray("doubleArrayValue",pvDouble)->
-                    endNested() ->
-                addNestedUnionArray("unionArrayValue") ->
-                    add("doubleValue", pvDouble)->
-                    add("alarm",standardField->alarm()) ->
-                    endNested() ->
-                addNestedStructureArray("structArrayValue") ->
-                    add("doubleValue", pvDouble)->
-                    addArray("doubleArrayValue",pvDouble)->
-                    endNested() ->
-                createUnion(),
-            "alarm,timeStamp"));
-    cout << "introspection\n";
-    cout <<pvStructure->getStructure()->dump(cout) << endl;
-    cout << "data\n";
-    cout << pvStructure->dumpValue(cout) << "\n";
-    PVUnionPtr pvUnion = pvStructure->getSubField<PVUnion>("value");;
-    pvUnion->select("doubleValue");
-    PVDoublePtr pvDouble = pvUnion->get<PVDouble>();
-    pvDouble->put(1.55);
-    cout << "select valueDouble\n";
-    cout << pvStructure->dumpValue(cout) << "\n";
-    cout << "value = " << pvDouble->get() << "\n";
-    pvUnion->select("structValue");
-    pvDouble = pvUnion->get<PVStructure>()->getSubField<PVDouble>("doubleValue");
-    pvDouble->put(1.65);
-    cout << "select structValue\n";
-    cout << pvStructure->dumpValue(cout) << "\n";
-    cout << "value = " << pvDouble->get() << "\n";
-
-This produces: -
-introspection
-uri:ev4:nt/2012/pwd:NTUnion
-    union value
-        double doubleValue
-        double[] doubleArrayValue
-        union unionValue
-            double doubleValue
-            alarm_t alarm
-                int severity
-                int status
-                string message
-        structure structValue
-            double doubleValue
-            double[] doubleArrayValue
-        union[] unionArrayValue
-            union[]
-                union
-                    double doubleValue
-                    alarm_t alarm
-                        int severity
-                        int status
-                        string message
-        structure[] structArrayValue
-            structure[]
-                structure
-                    double doubleValue
-                    double[] doubleArrayValue
-    alarm_t alarm
-        int severity
-        int status
-        string message
-    time_t timeStamp
-        long secondsPastEpoch
-        int nanoseconds
-        int userTag
-0x60a2c8
-data
-uri:ev4:nt/2012/pwd:NTUnion
-    union value
-        (none)
-    alarm_t alarm
-        int severity 0
-        int status 0
-        string message
-    time_t timeStamp
-        long secondsPastEpoch 0
-        int nanoseconds 0
-        int userTag 0
-0x60a2c8
-select valueDouble
-uri:ev4:nt/2012/pwd:NTUnion
-    union value
-        double  1.55
-    alarm_t alarm
-        int severity 0
-        int status 0
-        string message
-    time_t timeStamp
-        long secondsPastEpoch 0
-        int nanoseconds 0
-        int userTag 0
-0x60a2c8
-value = 1.55
-select structValue
-uri:ev4:nt/2012/pwd:NTUnion
-    union value
-        structure
-            double doubleValue 1.65
-            double[] doubleArrayValue []
-    alarm_t alarm
-        int severity 0
-        int status 0
-        string message
-    time_t timeStamp
-        long secondsPastEpoch 0
-        int nanoseconds 0
-        int userTag 0
-0x60a2c8
-value = 1.65
-
- -

Namespace and Memory Management

- -

Namespace

- -

All code in project pvDataCPP appears in namespace:

-
namespace epics { namespace pvData {
-     // ...
-}}
- -

Memory Managemment

- -

Many pvDataCPP introspection and data objects are designed to be shared. They are -made availiable via std::tr1::shared_ptr. -The following naming convention is used -in typedefs:

-
-
Ptr
-
When Ptr appears it stands for std::tr1::shared_ptr. -
-
-

For example:

-
-typedef PVScalarValue<boolean> PVBoolean;
-typedef std::tr1::shared_ptr<PVBoolean> PVBooleanPtr;
-
- -

pvDataApp/pv

- -

Directory pvDataApp/pv has header files that completely describe pvData. -The implementation is provided in directory pvDataApp/factory. -Test programs appears in testApp/pv.

- -

NOTES:

-
-
interface
-
The documention uses the word interface. - This is an analogy with how Java defines interface. - C++ does not have interfaces but directory pv defines classes - with public members that are similar to the Java interfaces. Most of the - implementation is in factory.
-
Naming Convertions
-
The naming convertions for variables, methods, and classes follow the - Java convertions, i. e. class name begin with an upper case letter, - variables and methods begin with a lower case letter.
-
- -

A PVStructure is a field that contains an array of subfields. Each field has -code for accessing the field. The interface for each field is an interface that -extends PVField. Each field also has an introspection interface, which an -extension of Field. The next few sections describes the complete set of C++ -introspection and data interfaces for pvData.

- -

Class FieldCreate creates introspection objects. Class PVDataCreate creates -data objects. Class Convert provides a rich set of methods for converting and -copying data between fields.

- -

Directory pvDataApp/pv has the following header files:

-
-
pvType.h
-
C++ definitions for primitive types.
-
pvIntrospect.h
-
A complete description of the introspection interfaces.
-
pvData.h
-
A complete description of the data interfaces.
-
convert.h
-
A facility that converts between data fields.
-
pvSubArrayCopy.h
-
This provides a facility that performs array coping between - arrays that have the same type.
-
standardField.h
-
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.
-
- -

pvType.h

- -

This provides C/C++ definitions for the pvData primitive types: boolean, -byte, short, int, long, ubyte,ushort, uint,u long,float, double, and string. -Because pvData is network data, the C++ implementation must implement the -proper semantics for the primitive types.

- -

pvType.h provides the proper semantics.

- -

It includes the definitions:

-
-typedef /*lots of stuff*/ boolean
-
-typedef int8_t   int8;
-typedef int16_t  int16;
-typedef int32_t  int32;
-typedef int64_t  int64;
-typedef uint8_t   uint8;
-typedef uint16_t  uint16;
-typedef uint32_t uint32;
-typedef uint64_t uint64;
-// float and double are types
-
-typedef std::vector<std::string> StringArray;
-typedef std::tr1::shared_ptr<StringArray> StringArrayPtr;
-inline std::string * get(StringArray &value);
-inline std::string const * get(StringArray const &value);
-inline std::string * get(StringArrayPtr &value);
-inline std::string const * get(StringArrayPtr const &value);
-}
-inline StringArray & getVector(StringArrayPtr &value);
-inline StringArray const & getVector(StringArrayPtr const &value);
-typedef std::vector<std::string>::iterator StringArray_iterator;
-typedef std::vector<std::string>::const_iterator StringArray_const_iterator;
-
- -

where

-
-
boolean
-
A c++ bool has the semantics required for boolean. Only the name is - different. C++ code can use either bool or boolean.
-
int8,...,uint64
-
Integers present a problem because short, int, and long are C++ - reserved words but do not have a well defined number of bits. Thus for - C++ the definitions above are used in C++ code. The above definitions - have worked on all C++ implementations tested at present. If they break - in a future implementation they should be changes via "#ifdef" - preprocessor statements.
-
std::string
-
pvData requires that a string be an immutable string that is transfered - over the network as a UTF8 encoded string. Since std::string implements - copy on write semantics, it can be used for support for immutable - strings. It can also be serialized/deserialized as a UTF8 encoded string. - Because it is not a C++ primitive the first letter is capitalized. This - is the same convention the Java implementation uses. - Note that string is treated like a primitive type.
-
StringArray definitions
-
typedefs are provided for an array of std::strings, - which is a std::vector<std::string>. - This is used by introspection. -
-
-

TBD -

-
boolean
-
Question for Michael. Why isn't the definition of boolean just - 
-typedef uint8_t boolean;
-
-
printer.h
-
Not documented. Is this needed? Nothing currently uses it.
-
-

- -

pvIntrospect.h

- -

This subsection describes pvIntrospect.h This file is quite big so rather -than showing the entire file, it will be described in parts.

- -

The primary purpose for pvData is to support network access to structured data. -pvAccess transports top level pvStructures. In addition a pvAccess server holds -a set of pvnames, where each name is a unique name in the local network. -This is also refered to as the channel name. -

- -

Given a pvname , it is possible to introspect the types of the associated data -access to data. The reflection and data interfaces are separate because the -data may not be available. For example when a pvAccess client connects to a pvname, -the client library can obtain the reflection information without obtaining any -data. Only when a client issues an I/O request will data be available. This -separation is especially important for arrays and structures so that a client -can discover the type without requiring that a large data array or structure be -transported over the network.

- -

Type Description

- -

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:

-
-
scalar
-
A scalar of one of the scalar types.
-
scalarArray
-
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 types can be different.
-
structureArray
-
An array where each element is a structure. Each element has the same - structure introspection interface.
-
union_t
-
This is like a structure that has a single subfield. - The type for the subfield can either be any type, which is called a varient union, - of can be one od a specified set of types. - In the data interfaces the type can be changed dynamically. -'
-
unionArray
-
An array where each element is a union. Each element has the same - union introspection interface.
-
- -

ScalarType is one of the following:

-
-
pvBoolean
-
Has the value false or true.
-
pvByte
-
A signed 8 bit integer.
-
pvShort
-
A signed 16 bit integer.
-
pvInt
-
A signed 32 bit integer.
-
pvLong
-
A signed 64 bit integer.
-
pvUByte
-
An unsigned 8 bit integer.
-
pvUShort
-
An unsigned 16 bit integer.
-
pvUInt
-
An unsigned 32 bit integer.
-
pvULong
-
An unsigned 64 bit integer.
-
pvFloat
-
A IEEE float.
-
pvDouble
-
A IEEE double,
-
pvString
-
An immutable string.
-
- -

TypeFunction is a set of convenience methods for Type

-
-
name
-
Returns the name of the type.
-
- -

ScalarTypeFunction is a set of convenience methods for ScalarType

-
-
isInteger
-
Is the scalarType an integer type, i.e. one of pvByte,...pvULong.
-
isUInteger
-
Is the scalarType an unsigned integer type, i.e. one of - pvUByte,...pvULong
-
isNumeric
-
Is the scalarType numeric, i.e. pvByte,...,pvDouble.
-
isPrimitive
-
Is the scalarType primitive, i.e. not pvString
-
name
-
Returns the name of the scalarType.
-
getScalarType
-
Given a string of the form std::string("boolean"),...,std::string("string") - return the scalarType.
-
elementSize
-
Returns the size in bytes of an instance of the scalarType.
-
- -

Introspection Description

- -

This section describes the reflection interfaces which provide the -following:

-
-
Field
-
A field: -
    -
  • Has a Type.
    • -
  • Can be converted to a string.
    • -
  • Can be shared. A reference count is kept. When it becomes 0 the - instance is automatically deleted.
    • -
-
-
Scalar
-
A scalar has a scalarType
-
ScalarArray
-
The element type is a scalarType
-
Structure
-
Has fields that can be any of the supported types.
-
StructureArray
-
The field holds an array of structures. Each element has the same - Structure interspection interface. A pvAccess client can only get/put - entire PVStructure elements NOT subfields of array elements.
-
Union
-
- This has two flavors: a varient union or a union of a fixed set - of types. A PVUnion will have a single subfield. - If the union introspection interface is a varient union then - the single field can be of any type and has the name any. - If the union is not a varient type then the type can be one of - a fixed set of types and a name associated with the type. - The union introspection interface has a field array and a string - array that has the fixed set of types and associated names. -
-
UnionArray
-
- This is an array of unions. A PVUnionArray is an array - of PVUnions. Each element has the same interspection interface - but the subfield of each element can have a different type. -
-
FieldBuilder
-
This is a convenience interface that makes it easier to create - top introspection interfaces. -
-
FieldCreate
-
This is an interface that provides methods to create introspection - interfaces. A factory is provides to create FieldCreate.
-
getFieldCreate
-
Gets a pointer to the single instance of FieldCreate.
-
-

Field,Scalar,ScalarArray,Structure,StructureArray,Union,UnionArray

-
class Field;
-class Scalar;
-class ScalarArray;
-class Structure;
-class StructureArray;
-class Union;
-class UnionArray;
-
-typedef std::tr1::shared_ptr<const Field> FieldConstPtr;
-typedef std::vector<FieldConstPtr> FieldConstPtrArray;
-typedef std::tr1::shared_ptr<const Scalar> ScalarConstPtr;
-typedef std::tr1::shared_ptr<const ScalarArray> ScalarArrayConstPtr;
-typedef std::tr1::shared_ptr<const Structure> StructureConstPtr;
-typedef std::tr1::shared_ptr<const StructureArray> StructureArrayConstPtr;
-typedef std::tr1::shared_ptr<const Union> UnionConstPtr;
-typedef std::tr1::shared_ptr<const UnionArray> UnionArrayConstPtr;
-
-
-class Field :
-    virtual public Serializable,
-    public std::tr1::enable_shared_from_this<Field>
-{
-public:
-    POINTER_DEFINITIONS(Field);
-    virtual ~Field();
-    Type getType() const{return m_type;}
-    virtual std::string getID() const = 0;
-    virtual std::ostream& dump(std::ostream& o) const = 0;
- ...
-};
-std::ostream& operator<<(std::ostream& o, const Field& field);
-
-class Scalar : public Field{
-public:
-    POINTER_DEFINITIONS(Scalar);
-    virtual ~Scalar();
-    typedef Scalar& reference;
-    typedef const Scalar& const_reference;
-
-    ScalarType getScalarType() const {return scalarType;}
-    virtual std::string getID() const;
-    virtual std::ostream& dump(std::ostream& o) const;
-    virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
-    virtual void deserialize(ByteBuffer *buffer, DeserializableContol *control);
- ...
-};
-
-class epicsShareClass Array : public Field{
-public:
-    POINTER_DEFINITIONS(Array);
-    virtual ~Array();
-    typedef Array& reference;
-    typedef const Array& const_reference;
- ...
-};
-
-
-class ScalarArray : public Field{
-public:
-    POINTER_DEFINITIONS(ScalarArray);
-    typedef ScalarArray& reference;
-    typedef const ScalarArray& const_reference;
-
-    ScalarArray(ScalarType scalarType);
-    ScalarType  getElementType() const {return elementType;}
-    virtual std::string getID() const;
-    virtual std::ostream& dump(std::ostream& o) const;
-    virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
-    virtual void deserialize(ByteBuffer *buffer, DeserializableControl *control);
- ...
-};
-
-class StructureArray : public Field{
-public:
-    POINTER_DEFINITIONS(StructureArray);
-    typedef StructureArray& reference;
-    typedef const StructureArray& const_reference;
-
-    StructureConstPtr  getStructure() const {return pstructure;}
-    virtual std::string getID() const;
-    virtual std::ostream& dump(std::ostream& o) const;
-    virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
-    virtual void deserialize(ByteBuffer *buffer, DeserializableControl *control);
- ...
-};
-
-class epicsShareClass UnionArray : public Field{
-public:
-    POINTER_DEFINITIONS(UnionArray);
-    typedef UnionArray& reference;
-    typedef const UnionArray& const_reference;
-    UnionConstPtr  getUnion() const {return punion;}
-    virtual std::string getID() const;
-    virtual std::ostream& dump(std::ostream& o) const;
-    virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
-    virtual void deserialize(ByteBuffer *buffer, DeserializableControl *control);
-};
-
-class Structure : public Field {
-public:
-    POINTER_DEFINITIONS(Structure);
-    typedef Structure& reference;
-    typedef const Structure& const_reference;
-
-    std::size_t getNumberFields() const {return numberFields;}
-    FieldConstPtr getField(std::string const & fieldName) const;
-    FieldConstPtr getField(std::size_t index) const;
-    std::size_t getFieldIndex(std::string const &fieldName) const;
-    FieldConstPtrArray const & getFields() const {return fields;}
-    StringArray const & getFieldNames() const;
-    std::string getFieldName(std::size_t fieldIndex) const;
-    virtual std::string getID() const;
-    virtual std::ostream& dump(std::ostream& o) const;
-    virtual void serialize(ByteBuffer *buffer, SerializableControl *control) const;
-    virtual void deserialize(ByteBuffer *buffer, DeserializableControl *control);
- ...
-};
-
-class epicsShareClass Union : public Field {
-public:
-    POINTER_DEFINITIONS(Union);
-    static std::string DEFAULT_ID;
-    static std::string ANY_ID;
-    virtual ~Union();
-    typedef Union& reference;
-    typedef const Union& const_reference;
-
-    std::size_t getNumberFields() const;
-    FieldConstPtr getField(std::string const &fieldName) const;
-    FieldConstPtr getField(std::size_t index);
-    std::size_t getFieldIndex(std::string const &fieldName) const;
-    FieldConstPtrArray const & getFields() const;
-    StringArray const & getFieldNames() const;
-    std::string getFieldName(std::size_t fieldIndex) const;
-    bool isVariant() const;
-    virtual std::string getID() const;
-    virtual std::ostream& dump(std::ostream& o) const;
-    virtual void serialize(
-        ByteBuffer *buffer, SerializableControl *control) const;
-    virtual void deserialize(
-        ByteBuffer *buffer, DeserializableControl *control);
-    
-};
-
-
-
Constructors
-
Note that all constructors are protected or private. The only way to - create instances is via fieldBuilder or fieldCreate. The implementation manages all - storage via shared pointers.
-
dump
-
Many classes provide this. This is a stream method that prints using - the metadata syntax described in pvDataJava.html.
-
- -

Field

-
-
getType
-
Get the field type.
-
getID
-
Get an ID for this introspection interface
-
- -

Scalar

-
-
getScalarType
-
Get that scalar type.
-
getID
-
For each scalarType there is one instance of Scalar. The ID for each is - the metadata name for the type, i. e. one of "boolean" , ... , "string". -
-
- -

ScalarArray

-
-
getElementType
-
Get the element type.
-
getID
-
For each elemnetType there is one instance of ScalarArray. The ID for - each is the metadata name for the type, i. e. one of "boolean[]" , ... , - "string[]".
-
- -

StructureArray

-
-
getStructure
-
Get the introspection interface that each element shares,
-
getID
-
This returns the ID[] where ID is the value returned by - structure->getID().
-
-` -

UnionArray

-
-
getUnion
-
Get the union interface for each element.
-
- -

Structure

-
-
getNumberFields
-
Get the number of immediate subfields.
-
getField
-
Given a name or an index get the introspection interface for the - field.
-
getFieldIndex
-
Given a name get the index, within the array returned by the next - method, of the field.
-
getFields
-
Get the array of introspection interfaces for the field,
-
getFieldNames
-
Get the array of field names for the subfields.
-
getFieldName
-
Get the field name for the specified index.
-
-

Union

-
-
getNumberFields
-
Get the number of possible field types. - Both getFields and getFieldNames will return an array with getNumberFields elements. - A value of 0 is returned for invarient arrays. -
-
getField
-
Given a name ot an index the type is returned. - NULL is returned if not found. -
-
getFieldIndex
-
Get the index for name. -1 is returned if not found. -
getFields
-
Get the array of types.
-
getFieldNames
-
Get the array of names.
-
getFieldName
-
Get the name for the specified index.
-
isVariant
-
returns true if this is varient array and false otherwise. -
-

fieldBuilder and createField

-
-class epicsShareClass FieldBuilder :
-    public std::tr1::enable_shared_from_this<FieldBuilder>
-{
-public:
-    FieldBuilderPtr setId(std::string const & id);
-    FieldBuilderPtr add(std::string const & name, ScalarType scalarType);
-    FieldBuilderPtr add(std::string const & name, FieldConstPtr const & field);
-    FieldBuilderPtr addArray(std::string const & name, ScalarType scalarType);
-    FieldBuilderPtr addArray(std::string const & name, FieldConstPtr const & element);
-    StructureConstPtr createStructure();
-    UnionConstPtr createUnion();
-    FieldBuilderPtr addNestedStructure(std::string const & name); 
-    FieldBuilderPtr addNestedUnion(std::string const & name);
-    FieldBuilderPtr addNestedStructureArray(std::string const & name); 
-    FieldBuilderPtr addNestedUnionArray(std::string const & name);
-    FieldBuilderPtr endNested();
-};
-
-class epicsShareClass FieldCreate {
-public:
-    static FieldCreatePtr getFieldCreate();
-    FieldBuilderPtr createFieldBuilder() const;
-    ScalarConstPtr createScalar(ScalarType scalarType) const;
-    ScalarArrayConstPtr createScalarArray(ScalarType elementType) const;
-    StructureArrayConstPtr createStructureArray(StructureConstPtr const & structure) const;
-    StructureConstPtr createStructure () const;
-    StructureConstPtr createStructure (
-        StringArray const & fieldNames,
-        FieldConstPtrArray const & fields) const;
-    StructureConstPtr createStructure (
-    	std::string const & id,
-        StringArray const & fieldNames,
-        FieldConstPtrArray const & fields) const;
-    UnionConstPtr createUnion (
-        StringArray const & fieldNames,
-        FieldConstPtrArray const & fields) const;
-    UnionConstPtr createUnion (
-    	std::string const & id,
-        StringArray const & fieldNames,
-        FieldConstPtrArray const & fields) const;
-    UnionConstPtr createVariantUnion() const;
-    UnionArrayConstPtr createVariantUnionArray() const;
-    UnionArrayConstPtr createUnionArray(UnionConstPtr const & punion) const;
-    StructureConstPtr appendField(
-        StructureConstPtr const & structure,
-        std::string const & fieldName, FieldConstPtr const & field) const;
-    StructureConstPtr appendFields(
-        StructureConstPtr const & structure,
-        StringArray const & fieldNames,
-        FieldConstPtrArray const & fields) const;
-    FieldConstPtr deserialize(ByteBuffer* buffer, DeserializableControl* control) const;
-        
-};
-
-epicsShareExtern FieldCreatePtr getFieldCreate();
-
- -

FieldBuilder

-

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. -

-
-
setID
-
This sets an ID for the field, which is the name for the field when it is a subfield. -
-
add
-
- Add a scalar field. -
-
addArray
-
- Add a scalarArray field. -
-
createStructure
-
- Create a structure from the fields that are currently present. -
-
createUnion
-
- Create a union from the fields that are currently present. -
-
addNestedStructure
-
- Add a nested structure. This is followed by an arbitrary number of adds - followed by a an endNested. -
-
addNestedUnion
-
- Add a nested union. This is followed by an arbitrary number of adds - followed by a an endNested. -
-
addNestedStructureArray
-
- Add a nested structure array. This is followed by an arbitrary number of adds - followed by a an endNested. -
-
addNestedUnionArray
-
- Add a nested union array. This is followed by an arbitrary number of adds - followed by a an endNested. -
-
endNested
-
- End current nested structure or union. -
-
-

Examples of using fieldBuilder were given earlier in this manual.

-

FieldCreate

-
-
getFieldCreate
-
Get the single instance of FieldCreate.
-
createFieldBuilder
-
Create an instance of a FieldBuilder.
-
createScalar
-
Create a scalar introspection instance.
-
createScalarArray
-
Create a scalar array introspection instance.
-
createStructure
-
Create a structure introspection instance. Three methods are provided. - The first creates an empty structure, i. e. a structure with no fields. - The other two are similar. - The only difference is that one provides an ID and the other does - not. The one without will result in ID structure.
-
createUnion
-
Create a union. There are two methods. - Each has arguments for an array of types and an array of names. - One method has an id. The other results in id = union. -
-
createVariantUnion
-
- Create a varient union. The id will be any. -
-
createUnionArray
-
Create a union array. punion is the introspection interface - for each element.
-
createVariantUnionArray
-
Create a union array where each element is a varient union.
-
createStructureArray
-
Create a structure array introspection instance.
-
appendField
-
Create a new structure that is like an existing structure but has - an extra field appended to it. -
-
appendFields
-
Create a new structure that is like an existing structure but has - extra fields appended to it. -
-
deserialize
-
Deserialize from given byte buffer.
-
- -

standardField.h

- -

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();
- ...
-};
-
-
scalar
-
Create a scalar with the specified scalar type and name. A structure - will be created with the first element being a scalar with the specified - scalar type and name value. The other fields in the structure will be the - corresponding property structures.
-
regUnion
-
A structure - will be created with the first element being a union with the specified - scalar type and name value. The other fields in the structure will be the - corresponding property structures.
-
varient`Union
-
Create a varient union. A structure - will be created with the first element being a union with the specified - scalar type and name value. The other fields in the structure will be the - corresponding property structures.
-
scalarArray
-
Create a scalarArray with each element having the specified scalar type - and name. A structure will be created with the first element being a - scalarArray with name value. The other fields in the structure will be - the corresponding property structures.
-
structureArray
-
Create a structureArray with the specified structure interface and - name. A structure will be created with the first element being a - structureArray with the specified structure interface and name value. The - other fields in the structure will be the corresponding property - structures.
-
unionArray
-
Create a unionArray with the specified union interface and - name. A structure will be created with the first element being a - unionArray with the specified structure interface and name value. The - other fields in the structure will be the corresponding property - structures.
-
structure
-
Create a structure with the specified name and fields specified by - numFields and fields. A structure will be created with the first element - being a structure with the name value and fields specified by numFields - and fields. The other fields in the structure will be the corresponding - property structures.
-
enumerated
-
Create a structure with the specified name and fields for an enumerated - structure. If properties are specified then a structure will be created - with the first element being a structure with the name value and fields - for an enumerated structure. The other fields in the structure will be - the corresponding property structures.
-
alarm
-
timeStamp
-
display
-
control
-
booleanAlarm
-
byteAlarm
-
shortAlarm
-
intAlarm
-
longAlarm
-
floatAlarm
-
doubleAlarm
-
enumeratedAlarm
-
The above provide introspection interfaces for standard properties. See - the section on Properties for a description of how these are defined.
-
-

pvData.h

- -

This section describes pvData.h This file is quite big so rather than -showing the entire file, it will be described in parts.

- -

typedefs

- -

These are typedefs for Array and Ptr for the various pvData class -definitions, i.e. typdefs for "std::vector" and "std::tr1::shared_ptr".

-
-class PVField;
-class PVScalar;
-class PVScalarArray;
-class PVStructure;
-class PVStructureArray;
-class PVUnion;
-class PVUnionArray;
-
-typedef std::tr1::shared_ptr<PostHandler> PostHandlerPtr;
-
-typedef std::tr1::shared_ptr<PVField> PVFieldPtr;
-typedef std::vector<PVFieldPtr> PVFieldPtrArray;
-typedef std::vector<PVFieldPtr>::iterator PVFieldPtrArray_iterator;
-typedef std::vector<PVFieldPtr>::const_iterator PVFieldPtrArray_const__iterator;
-
-typedef std::tr1::shared_ptr<PVScalar> PVScalarPtr;
-typedef std::tr1::shared_ptr<PVScalarArray> PVScalarArrayPtr;
-
-typedef std::tr1::shared_ptr<PVStructure> PVStructurePtr;
-typedef std::vector<PVStructurePtr> PVStructurePtrArray;
-typedef std::vector<PVStructurePtr>::iterator PVStructurePtrArray_iterator;
-typedef std::vector<PVStructurePtr>::const_iterator PVStructurePtrArray_const__iterator;
-
-typedef PVValueArray<PVStructurePtr> PVStructureArray;
-typedef std::tr1::shared_ptr<PVStructureArray> PVStructureArrayPtr;
-typedef std::vector<PVStructureArrayPtr> PVStructureArrayPtrArray;
-typedef std::tr1::shared_ptr<PVStructureArrayPtrArray> PVStructureArrayPtrArrayPtr;
-
-typedef std::tr1::shared_ptr<PVUnion> PVUnionPtr;
-typedef std::vector<PVUnionPtr> PVUnionPtrArray;
-typedef std::vector<PVUnionPtr>::iterator PVUnionPtrArray_iterator;
-typedef std::vector<PVUnionPtr>::const_iterator PVUnionPtrArray_const__iterator;
-
-typedef PVValueArray<PVUnionPtr> PVUnionArray;
-typedef std::tr1::shared_ptr<PVUnionArray> PVUnionArrayPtr;
-typedef std::vector<PVUnionArrayPtr> PVUnionArrayPtrArray;
-typedef std::tr1::shared_ptr<PVUnionArrayPtrArray> PVUnionArrayPtrArrayPtr;
-
-class PVDataCreate;
-typedef std::tr1::shared_ptr<PVDataCreate> PVDataCreatePtr;
-
-
-/**
- * typedefs for the various possible scalar types.
- */
-typedef PVScalarValue<boolean> PVBoolean;
-typedef PVScalarValue<int8> PVByte;
-typedef PVScalarValue<int16> PVShort;
-typedef PVScalarValue<int32> PVInt;
-typedef PVScalarValue<int64> PVLong;
-typedef PVScalarValue<uint8> PVUByte;
-typedef PVScalarValue<uint16> PVUShort;
-typedef PVScalarValue<uint32> PVUInt;
-typedef PVScalarValue<uint64> PVULong;
-typedef PVScalarValue<float> PVFloat;
-typedef PVScalarValue<double> PVDouble;
-class PVString;
-typedef std::tr1::shared_ptr<PVBoolean> PVBooleanPtr;
-typedef std::tr1::shared_ptr<PVByte> PVBytePtr;
-typedef std::tr1::shared_ptr<PVShort> PVShortPtr;
-typedef std::tr1::shared_ptr<PVInt> PVIntPtr;
-typedef std::tr1::shared_ptr<PVLong> PVLongPtr;
-typedef std::tr1::shared_ptr<PVUByte> PVUBytePtr;
-typedef std::tr1::shared_ptr<PVUShort> PVUShortPtr;
-typedef std::tr1::shared_ptr<PVUInt> PVUIntPtr;
-typedef std::tr1::shared_ptr<PVULong> PVULongPtr;
-typedef std::tr1::shared_ptr<PVFloat> PVFloatPtr;
-typedef std::tr1::shared_ptr<PVDouble> PVDoublePtr;
-typedef std::tr1::shared_ptr<PVString> PVStringPtr;
-
-/**
- * Definitions for the various scalarArray types.
- */
-typedef PVValueArray<boolean> PVBooleanArray;
-typedef PVValueArray<int8> PVByteArray;
-typedef PVValueArray<int16> PVShortArray;
-typedef PVValueArray<int32> PVIntArray;
-typedef PVValueArray<int64> PVLongArray;
-typedef PVValueArray<uint8> PVUByteArray;
-typedef PVValueArray<uint16> PVUShortArray;
-typedef PVValueArray<uint32> PVUIntArray;
-typedef PVValueArray<uint64> PVULongArray;
-typedef PVValueArray<float> PVFloatArray;
-typedef PVValueArray<double> PVDoubleArray;
-typedef PVValueArray<std::string> PVStringArray;
-
-typedef std::tr1::shared_ptr<PVBooleanArray> PVBooleanArrayPtr;
-typedef std::tr1::shared_ptr<PVByteArray> PVByteArrayPtr;
-typedef std::tr1::shared_ptr<PVShortArray> PVShortArrayPtr;
-typedef std::tr1::shared_ptr<PVIntArray> PVIntArrayPtr;
-typedef std::tr1::shared_ptr<PVLongArray> PVLongArrayPtr;
-typedef std::tr1::shared_ptr<PVUByteArray> PVUByteArrayPtr;
-typedef std::tr1::shared_ptr<PVUShortArray> PVUShortArrayPtr;
-typedef std::tr1::shared_ptr<PVUIntArray> PVUIntArrayPtr;
-typedef std::tr1::shared_ptr<PVULongArray> PVULongArrayPtr;
-typedef std::tr1::shared_ptr<PVFloatArray> PVFloatArrayPtr;
-typedef std::tr1::shared_ptr<PVDoubleArray> PVDoubleArrayPtr;
-typedef std::tr1::shared_ptr<PVStringArray> PVStringArrayPtr;
-
- -

PVField

- -

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:

-
-
~PVField
-
Destructor. Since shared pointers are used it should never be called by - user code.
-
getFieldName
-
Get the field name. If the field is a top level structure the field - name will be an empty string.
-
getFullName
-
Fully expand the name of this field using the - names of its parent fields with a dot '.' seperating - each name. -
-
getFieldOffset
-
Get offset of the PVField field within top level structure. Every field - within the PVStructure has a unique offset. The top level structure has - an offset of 0. The first field within the structure has offset equal to - 1. The other offsets are determined by recursively traversing each - structure of the tree.
-
getNextFieldOffset
-
Get the next offset. If the field is a scalar or array field then this - is just offset + 1. If the field is a structure it is the offset of the - next field after this structure. Thus (nextOffset - offset) is always - equal to the total number of fields within the field.
-
getNumberFields
-
Get the total number of fields in this field. This is nextFieldOffset - - fieldOffset.
-
isImmutable
-
Is the field immutable?
-
setImmutable
-
Make the field immutable. Once a field is immutable it can never be - changed since there is no method to again make it mutable. This is an - important design decision since it allows immutable array fields to share - the internal primitive data array.
-
getField
-
Get the reflection interface for the data.
-
getParent
-
Get the interface for the parent or null if this is the top level - PVStructure.
-
postPut
-
If a postHandler is registered it is called otherwise no action is - taken.
- NOTE: The implementation of the various data interfaces automatically - call postPut when a field is changed. However this is not true - for a subField of a PVUnion, PVUnionArray, or PVStructureArray. - If a subField of any of these is changed then the code that is making - the modification must call postPut for the PVUnion, PVUnionArray, or PVStructureArray - field. Note also that it is not a good idea to modify a subfield of a PVUnionArray - or a PVStructureArray since it violates the idea of Copy On Write for arrays. -
-
setPostHandler
-
Set the postHandler for the record. Only a single handler can be - registered. - PostHandler is a class that must be implemented by any code that calls setPostHandler. - It's single virtual method. postPut is called whenever PVField::postPut is called. -
-
equals
-
Compare this field with another field. The result will be true only if - the fields have exactly the same field types and if the data values are - equal.
-
dumpValue
-
Method for streams I/O.
-
- -

PVScalar

- -

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

-
-
getScalar
-
Get the introspection interface for the PVScalar.
-
getAs
-
Convert and return the scalar value in the requested type. - Result type is determined from the function template argument - which must be one of the ScalarType enums. - For example: -
-uint32 val = pv->getAs();
-
-
- -
- -

PVScalarValue

- -

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

-
-
get
-
Get the value stored in the object.
-
put
-
Change the value stored in the object.
-
dumpValue
-
ostream method.
-
operator>>=
-
get operator. For example: -
-double value;
-PVDoublePtr pvDouble;
-...
-pvDouble>>=value;
-
-
-
operator<<=
-
put operator. For example: -
-double value;
-PVDoublePtr pvDouble;
-...
-pvDouble<<=value;
-
-
-
getAs
-
Convert and return the scalar value in the requested type. - Result type is determined from the function template argument - which must be one of the ScalarType enums. - For example: -
-int32 val = pv->getAs<pvInt>>();
-
-
-
putFrom
-
Convert the scalar value in the requested type - and put the value into this PVScalarValue. - The source type is determined from the function template argument - which must be one of the ScalarType enums. - For example: -
-int32 val;
-pv->putFrom<pvInt>(val);
-
- -
-
-

PVUnion

-

A PVUnion has a single subfield. -The Union introspection interface determines the possible -field types for the subfield. -If it is a varient union then any type is allowed and the -subfield name is normally any. -If it is not a varient union that the Union interface determines -the possible field types and names.

-
-class PVUnion : public PVField
-{
-public:
-    POINTER_DEFINITIONS(PVUnion);
-    virtual ~PVUnion();
-    typedef PVUnion & reference;
-    typedef const PVUnion & const_reference;
-
-    UnionConstPtr getUnion() const;
-    PVFieldPtr get() const;
-    
-    template<typename PVT>
-    std::tr1::shared_ptr<PVT> get() const;
-
-   PVFieldPtr select(int32 index);
-
-    template<typename PVT>
-    std::tr1::shared_ptr<PVT> select(int32 index);
-
-    PVFieldPtr select(std::string const & fieldName);
-
-    template<typename PVT>
-    std::tr1::shared_ptr<PVT> select(std::string const & fieldName);
-
-    int32 getSelectedIndex() const;
-    std::string getSelectedFieldName() const;
-    void set(PVFieldPtr const & value);
-    void set(int32 index, PVFieldPtr const & value);
-    void set(std::string const & fieldName, PVFieldPtr const & value);
-    virtual void serialize(
-        ByteBuffer *pbuffer,SerializableControl *pflusher) const ;
-    PVUnion(UnionConstPtr const & punion);
-};
-
-
-
getUnion
-
Get the introspection interface.
-
get
-
Get the curent field. A template version does the conversion. - NULL is returned if no field is selected or if the caller -' asks for the wrong type. -
-
select
-
Select and get the field by index or name. - A templated version does the conversion. - If the index is out of bounds or the name is not valid this methods throws an exception. - The method set should be used for variant unions rather than select. -
-
getSelectedIndex
-
Get the index of the currently selected field.
-
getSelectedFieldName
-
Get the name of the currently selected field.
-
set
-
Set the field to the argument. If invalid type an exception is thrown. - This should always work for a variant union. -
-
- -

PVArray

- -

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;
- ...
-};
-
-
getArray
-
Get the introspection interface.
-
setImmutable
-
Set the data immutable. Note that this is permanent since there is no - methods to make it mutable.
-
getLength
-
Get the current length. This is less than or equal to the capacity.
-
setLength
-
Set the length. If the PVField is not mutable then an exception is - thrown. If this is greater than the capacity setCapacity is called.
-
getCapacity
-
Get the capacity, i.e. this is the size of the underlying data - array.
-
setCapacity
-
Set the capacity. The semantics are implementation dependent but - typical semantics are as follows: If the capacity is not mutable an - exception is thrown. A new data array is created and data is copied from - the old array to the new array.
-
isCapacityMutable
-
Is the capacity mutable
-
setCapacityMutable
-
Specify if the capacity can be changed.
-
setCapacity
-
Set the capaciity.
-
dumpValue
-
ostream method
-
-

- - -

PVScalarArray

- -

PVScalarArray is the base class for scalar array data. PVValueArray is a -templete for the various scalar array data classes. There is a class for each -possible scalar type, i. e. PVBooleanArray, ..., PVStringArray.

-
-class PVScalarArray : public PVArray {
-public:
-    POINTER_DEFINITIONS(PVScalarArray);
-    virtual ~PVScalarArray();
-    typedef PVScalarArray &reference;
-    typedef const PVScalarArray& const_reference;
-
-    const ScalarArrayConstPtr getScalarArray() const ;
-
-    template<typename T>
-    void getAs(shared_vector<const T>& out) const
-
-    template<typename T>
-    void putFrom(const shared_vector<const T>& inp)
-
-    void assign(PVScalarArray& pv);
- ...
-}
-
- -

where

-
-
getScalarArray
-
Get the introspection interface.
-
getAs
-
Fetch the current value and convert to the requested type. - A copy is made if the requested type does not match the element type. - If the types do match then no copy is made. -
-
putFrom
-
Assign the given value after conversion. - A copy and element-wise conversion is performed unless the element type - of the PVScalarArray matches the type of the provided data. - If the types do match then a new refernce to the provided data is kept. -
-
assign
-
Assign the given PVScalarArray's value. - A copy and element-wise conversion is performed unless the element type - of the PVScalarArray matches the type of the provided data. - If the types do match then a new refernce to the provided data is kept. -
-
- -

PVStructure

- -

The interface for a structure is:

-
class PVStructure : public PVField,public BitSetSerializable {
-public:
-    POINTER_DEFINITIONS(PVStructure);
-    virtual ~PVStructure();
-    typedef PVStructure & reference;
-    typedef const PVStructure & const_reference;
-
-    virtual void setImmutable();
-    StructureConstPtr getStructure() const;
-    const PVFieldPtrArray & getPVFields() const;
-    PVFieldPtr getSubField(std::string const &fieldName) const;
-
-    template<typename PVT>
-    std::tr1::shared_ptr<PVT> getSubField(std::string const &fieldName) const
-
-    PVFieldPtr getSubField(std::size_t fieldOffset) const;
-
-    template<typename PVT>
-    std::tr1::shared_ptr<PVT> getSubField(std::size_t fieldOffset) const
-
-    virtual void serialize(
-        ByteBuffer *pbuffer,SerializableControl *pflusher) const ;
-    virtual void deserialize(
-        ByteBuffer *pbuffer,DeserializableControl *pflusher);
-    virtual void serialize(ByteBuffer *pbuffer,
-        SerializableControl *pflusher,BitSet *pbitSet) const;
-    virtual void deserialize(ByteBuffer *pbuffer,
-        DeserializableControl*pflusher,BitSet *pbitSet);
-    PVStructure(StructureConstPtr const & structure);
-    PVStructure(StructureConstPtr const & structure,PVFieldPtrArray const & pvFields);
-    virtual std::ostream& dumpValue(std::ostream& o) const;
-};
- -

where

-
-
getStructure
-
Get the introspection interface for the structure.
-
getPVFields
-
Returns the array of subfields. The set of subfields must all have - different field names.
-
getSubField(std::string fieldName)
-
- Get a subField of a field.d - A non-null result is - returned if fieldName is a field of the PVStructure. The fieldName can be - of the form name.name... - If the field does not exist the a Ptr to a NULL value is returned - without any error message being generated. -
- Note that the template version replaces getBooleanField, etc.
-
-
getSubField(int fieldOffset)
-
Get the field located a fieldOffset, where fieldOffset is relative to - the top level structure. This returns null if the specified field is not - located within this PVStructure. -
-
dumpValue
-
Method for streams I/O.
-
- - -

PVValueArray

- -

This is a template class plus instances for PVBooleanArray, ..., -PVStringArray.

-
template<typename T>
-class PVValueArray : public detail::PVVectorStorage<T,PVScalarArray> 
-{
-public:
-    POINTER_DEFINITIONS(PVValueArray);
-    typedef T  value_type;
-    typedef T* pointer;
-    typedef const T* const_pointer;
-    typedef ::epics::pvData::shared_vector<T> svector;
-    typedef ::epics::pvData::shared_vector<const T> const_svector;
-    static const ScalarType typeCode;
-
-    virtual ~PVValueArray() {}
-    std::ostream& dumpValue(std::ostream& o) const;
-    std::ostream& dumpValue(std::ostream& o, size_t index) const;
-    // inherited from PVVectorStorage
-    const_svector view();
-    void swap(const_svector& other);
-    void replace(const const_svector& next);
-    svector reuse();
-    ...
-};
-
- -

where

-
-
dumpValue
-
Method for streams I/O.
-
view
-
Fetch a read-only view of the current array data.
-
swap
-
- Callers must ensure that postPut() is called after the last swap() operation. - Before you call this directly, consider using the reuse(), or replace() methods. -
-
replace
-
Discard current contents and replaced with the provided.
-
reuse
-
Remove and return the current array data or an unique copy if shared.
-
-

TBD -

-
Check for completeness
-
Michael should check that PVScalarArray and PVValueArray - have the correct set of methods and that the descriptions are correct.
-
-

- -

PVStructureArray

- -

The interface for an array of structures is:

-
-template<>
-class PVValueArray<PVStructurePtr> : public detail::PVVectorStorage<PVStructurePtr,PVArray>
-{
-public:
-    POINTER_DEFINITIONS(PVStructureArray);
-    typedef PVStructurePtr  value_type;
-    typedef PVStructurePtr* pointer;
-    typedef const PVStructurePtr* const_pointer;
-    typedef PVStructureArray &reference;
-    typedef const PVStructureArray& const_reference;
-    typedef ::epics::pvData::shared_vector<PVStructurePtr> svector;
-    typedef ::epics::pvData::shared_vector<const PVStructurePtr> const_svector;
-
-    virtual ~PVStructureArray() {}
-    virtual ArrayConstPtr getArray() const;
-    virtual size_t getLength();
-    virtual size_t getCapacity();
-    virtual void setCapacity(size_t capacity);
-    virtual void setLength(std::size_t length);
-    virtual StructureArrayConstPtr getStructureArray() const ;
-    virtual std::size_t append(std::size_t number);
-    virtual bool remove(std::size_t offset,std::size_t number);
-    virtual void compress();
-    virtual const_svector view() const;
-    virtual void swap(const_svector &other);
-    virtual void replace(const const_svector &other);
-    virtual void serialize(ByteBuffer *pbuffer,
-        SerializableControl *pflusher) const;
-    virtual void serialize(ByteBuffer *pbuffer,
-        SerializableControl *pflusher, std::size_t offset, std::size_t count) const ;
-    virtual void deserialize(ByteBuffer *buffer,
-        DeserializableControl *pflusher);
-    virtual std::ostream& dumpValue(std::ostream& o) const;
-    virtual std::ostream& dumpValue(std::ostream& o, std::size_t index) const;
-    // inherited from PVVectorStorage
-    const_svector view();
-    void swap(const_svector& other);
-    void replace(const const_svector& next);
-    svector reuse();
- ...
-}
-

where

-
-
getStructureArray
-
Get the introspection interface shared by each element.
-
compress
-
This moves all null elements and then changes the array capacity. When - done there are no null elements.
-
- -

The other methods are similar to the methods for other array types. - See PVArray above for details.

- -

PVUnionArray

-

The interface for an array of unions is:

-
-template&ly;&gt;
-class epicsShareClass PVValueArray&ly;PVUnionPtr&gt; : public detail::PVVectorStorage&ly;PVUnionPtr,PVArray&gt;
-{
-    typedef detail::PVVectorStorage&ly;PVUnionPtr,PVArray&gt; base_t;
-public:
-    POINTER_DEFINITIONS(PVUnionArray);
-    typedef PVUnionPtr  value_type;
-    typedef PVUnionPtr* pointer;
-    typedef const PVUnionPtr* const_pointer;
-    typedef PVUnionArray &reference;
-    typedef const PVUnionArray& const_reference;
-
-    //TODO: full namespace can be removed along with local typedef 'shared_vector'
-    typedef ::epics::pvData::shared_vector&ly;PVUnionPtr&gt; svector;
-    typedef ::epics::pvData::shared_vector&ly;const PVUnionPtr&gt; 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

-
-
getUnionArray
-
Get the introspection interface shared by each element.
-
compress
-
This moves all null elements and then changes the array capacity. When - done there are no null elements.
-
- -

The other methods are similar to the methods for other array types. - See PVArray above for details.

- -

PVDataCreate

- -

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

-
-
getPVDataCreate
-
The returns the PVDataCreate implementation, which is a singleton.
-
createPVField
-
The PVField is created reusing the Field interface. Two methods are - provided. Each calls the corresponding createPVScalar, createPVArray, or - createPVStructure depending in the type of the last argument.
-
createPVScalar
-
Creates an instance of a PVScalar. Four versions are supplied. The - first is passed an introspection interface. - The second provides the scalarType. - The third provides a PVScalar to clone. - The last is a template version. PVAT must be a valid type. - For example: -
-PVDoublePtr pvDouble = getPVDataCreate()->createPVScalar<PVDouble>();
-
-
-
createPVStructure
-
Create an instance of a PVStructure. - Three methods are provided. - The first uses an array of field names and an array of PVFields to initialize the sub-fields. - The second initializes the subfields by cloning the fields contained in - structToClone. The newly created sub-fields will have the same values as the original. - If structToClone is null then the new structure is initialized to have 0 sub-fields. - The third method uses a previously created structure introspection interface. -
-
createPVUnion
-
Create an instance of a PVUnion. Two methods are provided. - The first uses a previously created union introspection interface. - The second clones an existing PVUnion. -
-
createPVVariantUnion
-
Creates an instance of a varient PVUnion. - This is a union which has a single field which can be any pvData supported type, -
-
createPVScalarArray
-
Create an instance of a PVArray. Four versions are supplied. - The first is passed an introspection interface. - The second provides the elementType. - The third provides a PVScalarArray to clone. - The last is a template version. PVAT must be a valid type. - For example: -
-PVDoubleArrayPtr pvDoubleArray = getPVDataCreate()->createPVScalarArray<PVDoubleArray>();
-
-
-
createPVStructureArray
-
Create a PVStructureArray. - Two versions are provided. - The first is passed a StructureArrayConstPtr. - The second is passed a StructureConstPtr which is used to create a StructureArrayConstPtr. - The argument provides the Structure interface for ALL elements of the PVStructureArray. -
-
createPVUnionArray
-
Create a PVUnionArray. - Two versions are provided. - The first is passed a UnionArrayConstPtr. - The second is passed a UnionConstPtr which is used to create a UnionArrayConstPtr. - The argument provides the Union interface for ALL elements of the PVUnionArray. -
-
createPVVariantUnionArray
-
Create a PVUnionArray. - No arguments are needed. -
-
- -

standardPVField.h

- -

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();
-
- -

Conversion

-

There are two facilities for converting between two different PVData -objects:

-
-
Convert
-
This preforms all conversions except for coping subarrays.
-
PVSubArray
-
This copies a subarray from one PVArray to another. - The two arrays must have the same element type.
-
-

convert.h

- -

NOTE about copying immutable array fields. If an entire immutable array -field is copied to another array that has the same elementType, both offsets -are 0, and the length is the length of the source array, then the shareData -method of the target array is called and the target array is set immutable. -Thus the source and target share the same primitive array.

- -

This section describes the supported conversions between data types.

- -
-bool operator==(PVField&, PVField&);
-
-static bool operator!=(PVField& a, PVField& b);
-
-bool operator==(const Field&, const Field&);
-bool operator==(const Scalar&, const Scalar&);
-bool operator==(const ScalarArray&, const ScalarArray&);
-bool operator==(const Structure&, const Structure&);
-bool operator==(const StructureArray&, const StructureArray&);
-bool operator==(const Union&, const Union&);
-bool operator==(const UnionArray&, const UnionArray&);
-
-static inline bool operator!=(const Field& a, const Field& b);
-static inline bool operator!=(const Scalar& a, const Scalar& b);
-static inline bool operator!=(const ScalarArray& a, const ScalarArray& b);
-static inline bool operator!=(const Structure& a, const Structure& b);
-static inline bool operator!=(const StructureArray& a, const StructureArray& b);
-static inline bool operator!=(const Union& a, const Union& b);
-static inline bool operator!=(const UnionArray& a, const UnionArray& b);
-
-class Convert;
-typedef std::tr1::shared_ptr<Convert> ConvertPtr;
-
-class Convert {
-public:
-    static ConvertPtr getConvert();
-    ~Convert();
-    void getFullName(std::string * buf,PVFieldPtr const & pvField);
-    bool equals(PVFieldPtr const &a,PVFieldPtr const &b);
-    bool equals(PVField &a,PVField &b);
-    void getString(std::string * buf,PVFieldPtr const & pvField,int indentLevel);
-    void getString(std::string * buf,PVFieldPtr const & pvField);
-    void getString(std::string * buf,PVField const * pvField,int indentLevel);
-    void getString(std::string * buf,PVField const * pvField);
-    std::size_t fromString(
-        PVStructurePtr const &pv,
-        StringArray const & from,
-        std::size_t fromStartIndex = 0);
-    void fromString(PVScalarPtr const & pv, std::string const & from);
-    std::size_t fromString(PVScalarArrayPtr const & pv, std::string const &from);
-    std::size_t fromStringArray(
-        PVScalarArrayPtr const & pv,
-        std::size_t offset, std::size_t length,
-        StringArray const & from,
-        std::size_t fromOffset);
-    std::size_t toStringArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        StringArray & to,
-        std::size_t toOffset);
-    bool isCopyCompatible(FieldConstPtr const & from, FieldConstPtr const & to);
-    void copy(PVFieldPtr const & from, PVFieldPtr const & to);
-    bool isCopyScalarCompatible(
-        ScalarConstPtr const & from,
-        ScalarConstPtr const & to);
-    void copyScalar(PVScalarPtr const & from, PVScalarPtr const & to);
-    bool isCopyScalarArrayCompatible(
-        ScalarArrayConstPtr const & from,
-        ScalarArrayConstPtr const & to);
-    bool isCopyStructureCompatible(
-        StructureConstPtr const & from, StructureConstPtr const & to);
-    void copyStructure(PVStructurePtr const & from, PVStructurePtr const & to);
-    bool isCopyStructureArrayCompatible(
-        StructureArrayConstPtr const & from, StructureArrayConstPtr const & to);
-    void copyStructureArray(
-        PVStructureArrayPtr const & from, PVStructureArrayPtr const & to);
-    bool isCopyUnionCompatible(
-        UnionConstPtr const & from, UnionConstPtr const & to);
-    void copyUnion(
-        PVUnionPtr const & from, PVUnionPtr const & to);
-    bool isCopyUnionArrayCompatible(
-        UnionArrayConstPtr const & from, UnionArrayConstPtr const & to);
-    void copyUnionArray(
-        PVUnionArrayPtr const & from, PVUnionArrayPtr const & to);
-    int8 toByte(PVScalarPtr const & pv);
-    int16 toShort(PVScalarPtr const & pv);
-    int32 toInt(PVScalarPtr const & pv);
-    int64 toLong(PVScalarPtr const & pv);
-    uint8 toUByte(PVScalarPtr const & pv);
-    uint16 toUShort(PVScalarPtr const & pv);
-    uint32 toUInt(PVScalarPtr const & pv);
-    uint64 toULong(PVScalarPtr const & pv);
-    float toFloat(PVScalarPtr const & pv);
-    double toDouble(PVScalarPtr const & pv);
-    std::string toString(PVScalarPtr const & pv);
-    void fromByte(PVScalarPtr const & pv,int8 from);
-    void fromShort(PVScalarPtr const & pv,int16 from);
-    void fromInt(PVScalarPtr const & pv, int32 from);
-    void fromLong(PVScalarPtr const & pv, int64 from);
-    void fromUByte(PVScalarPtr const & pv,uint8 from);
-    void fromUShort(PVScalarPtr const & pv,uint16 from);
-    void fromUInt(PVScalarPtr const & pv, uint32 from);
-    void fromULong(PVScalarPtr const & pv, uint64 from);
-    void fromFloat(PVScalarPtr const & pv, float from);
-    void fromDouble(PVScalarPtr const & pv, double from);
-    void newLine(std::string * buf, int indentLevel);
- ...
-}
-
-extern ConvertPtr getConvert();
-
-

newLine is a convenience method for code that implements toString It -generates a newline and inserts blanks at the beginning of the newline.

- -

pvSubArrayCopy.h

-
-template<typename T>
-void copy(
-    PVValueArray<T> & pvFrom,
-    size_t fromOffset,
-    size_t fromStride,
-    PVValueArray<T> & pvTo,
-    size_t toOffset,
-    size_t toStride,
-    size_t count);
-
-void copy(
-    PVScalarArray & from,
-    size_t fromOffset,
-    size_t fromStride,
-    PVScalarArray & to,
-    size_t toOffset,
-    size_t toStride,
-    size_t count);
-
-void copy(
-    PVStructureArray & from,
-    size_t fromOffset,
-    size_t fromStride,
-    PVStructureArray & to,
-    size_t toOffset,
-    size_t toStride,
-    size_t count);
-
-void copy(
-    PVArray & from,
-    size_t fromOffset,
-    size_t fromStride,
-    PVArray & to,
-    size_t toOffset,
-    size_t toStride,
-    size_t count);
-
-

The last copy is the only one most client need to call. -It either throws an error of the element types do not match or calls the -other copy functions. The arguments are:

-
-
from
-
The source array.
-
fromOffset
-
The offset into the source array.
-
fromStride
-
The interval between source elements.
-
to
-
The destination array. The element type must be the same - as for the source array. If the element type is structure then - the introspection interface for the element types must be the same. -
-
toOffset
-
The offset into the destination array.
-
toStride
-
The interval between destination elements.
-
count
-
The number of elements to copy.
-
-

An exception is thrown if:

-
-
type mismatch
-
The element types for the source and destination differ.
-
immutable
-
The destination array is immutable. -
capacity immutable
-
The destination array needs to have it's capacity extentended - but the capacity is immutable.
-
- -

pvDataApp/property

- -

Definition of Property

- -

Only fields named "value" have properties. A record can have multiple value -fields, which can appear in the top level structure of a record or in a -substructure. All other fields in the structure containing a value field are -considered properties of the value field. The fieldname is also the property -name. The value field can have any type, i.e. scalar, scalarArray, or -structure. Typical property fields are timeStamp, alarm, display, control, and -history. The timeStamp is a special case. If it appears anywhere in the -structure hieraracy above a value field it is a property of the value field.

- -

For example the following top level structure has a single value field. The -value field has properties alarm, timeStamp, and display.

-
structure counterOutput
-    double value
-    alarm_t
-        int severity 0
-        int status 0
-        string message
-    timeStamp_t
-        long secondsPastEpoch
-        int nanoseconds
-        int userTag
-    display_t
-        double limitLow 0.0
-        double limitHigh 10.0
-        string description "Sample Description"
-        string format "%f"
-        string units volts
- -

The following example has three value fields each with properties alarm and -timeStamp. Voltage, Current, and Power each have a different alarms but all -share the timeStamp.

-
structure powerSupplyValue
-    double value
-    alarm_t
-        int severity 0
-        int status 0
-        string message
-
-structure powerSupplySimple
-    alarm_t
-        int severity 0
-        int status 0
-        string message
-    timeStamp_t
-        long secondsPastEpoch
-        int nanoseconds
-        int userTag
-    powerSupplyValue_t voltage
-        double value
-        alarm_t
-            int severity 0
-            int status 0
-            string message
-    powerSupplyValue_t power
-        double value
-        alarm_t
-            int severity 0
-            int status 0
-            string message
-    powerSupplyValue_t current
-        double value
-        alarm_t
-            int severity 0
-            int status 0
-            string message
- -

Standard Properties

- -

The following field names have special meaning, i.e. support properties for -general purpose clients.

-
-
value
-
This is normally defined since most general purpose clients access this - field. All other fields in the structure support or describe the value - field. The type can any supported type but is usually one of the - following: -
-
scalar
-
Any of the scalar types.
-
scalarArray
-
An array with the elementType being a scalar type
-
enumerated structure
-
A structure that includes fields named index and choices. index - is an int that selects a choice. choices is an array of strings - that defines the complete set of choices.
-
other
-
Other structure or array types can also be defined if clients and - support code agree on the meaning. Some examples are: 1) A - structure defining a 2D matrix, 2) A structure defining an image, - 3) A structure that simulates a remote method, ...
-
-
-
timeStamp
-
The timeStamp. The type MUST be a timeStamp structure. Also if the - PVData structure does not have a timeStamp then a search up the parent - tree is made to find a timeStamp.
-
alarm
-
The alarm. The type MUST be an alarm structure.
-
display
-
A display structure as described below. It provides display - characteristics for the value field.
-
control
-
A control structure as described below. It provides control - characteristics for the value field.
-
history
-
Provides a history buffer for the value field. Note that currently - PVData does not define history suppoprt.
-
other
-
Other standard properties can be defined.
-
- -

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:

-
-
input
-
A field with support that changes the value field. This can be - anything. It can be a channel access link. It can obtain a value from - hardware. Etc.
-
valueAlarm
-
A field with support that looks for alarm conditions based on the - value.
-
output
-
A field with support that reads the current value and sends it - somewhere else. This can be anything. It can be a channel access link. It - can write a value to hardware. Etc.
-
- -

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. -

- -

Overview of Property Support

- -

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();
-     ...
-}
- -

timeStamp

- -

A timeStamp is represented by the following structure

-
structure timeStamp
-    long secondsPastEpoch
-    int nanoseconds
-    int userTag
- -

The Epoch is the posix epoch, i.e. Jan 1, 1970 00:00:00 UTC. Both the -seconds and nanoseconds are signed integers and thus can be negative. Since the -seconds is kept as a 64 bit integer, it allows for a time much greater than the -present age of the universe. Since the nanoseconds portion is kept as a 32 bit -integer it is subject to overflow if a value that corresponds to a value that -is greater than a little more than 2 seconds of less that about -2 seconds. The -support code always adjust seconds so that the nanoSecconds part is normlized, -i. e. it has is 0<=nanoseconds<nanoSecPerSec..

- -

Two header files are provided for manipulating time stamps:

-
-
timeStamp.h
-
Defines a time stamp independent of pvData, i.e. it is a generally - useful class for manipulating timeStamps.
-
pvTimeStamp.h
-
A class that can be attached to a time stamp pvData structure. It - provides get and set methods to get/set a TimeStamp as defined by - timeStamp.h
-
- -

timeStamp.h

- -

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

-
-
TimeStamp()
-
The defauly constuctor. Both seconds and nanoseconds are set to 0.
-
TimeStamp(int64 secondsPastEpoch,int32 nanoseconds = 0)
-
A constructor that gives initial values to seconds and nanoseconds.
-
normalize
-
Adjust seconds and nanoseconds so that - 0<=nanoseconds<nanoSecPerSec.
-
fromTime_t
-
Set time from standard C time.
-
toTime_t
-
Convert timeStamp to standard C time.
-
getSecondsPastEpoch
-
Get the number of seconds since the epoch.
-
getEpicsSecondsPastEpoch
-
Get the number of EPICS seconds since the epoch. EPICS uses Jan 1, 1990 - 00:00:00 UTC as the epoch.
-
getNanoseconds
-
Get the number of nanoseconds. This is always normalized.
-
getUserTag
-
Get the userTag.
-
setUserTag
-
Set the userTag.
-
put(int64 secondsPastEpoch,int32 nanoseconds = 0)
-
Set the timeStamp value. If necessary it will be normalized.
-
put(int64 milliseconds)
-
Set the timeStamp with a value the is the number of milliSeconds since - the epoch.
-
getCurrent()
-
Set the timeStamp to the current time.
-
toSeconds()
-
Convert the timeStamp to a value that is the number of seconds since - the epocj
-
operator =
-
operator!=
-
operator<=
-
operator<
-
operator>=
-
operator>
-
Standard C++ operators.
-
diff
-
diff = a - b
-
getMilliseconds
-
Get the number of milliseconds since the epoch.
-
- -

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);
- -

pvTimeStamp.h

-
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

-
-
PVTimeStamp
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if a timeStamp - structure is found. It looks first at pvField itself and if is not an - appropriate pvData structure but the field name is value it looks up the - parent structure tree.
-
detach
-
Detach from the pvData structure.
-
isAttached
-
Is there an attachment to a timeStamp structure?
-
get
-
Copies data from the pvData structure to a TimeStamp. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from TimeStamp to the pvData structure. An exception is - thrown if not attached to a pvData structure.
-
- -

alarm

- -

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:

-
-
alarm.h
-
Defines an alarm independent of pvData, i.e. it is a generally useful - class for manipulating alarms.
-
pvAlarm.h
-
A class that can be attached to an alarm pvData structure. It provides - get and set methods to get/set alarm data as defined by alarm.h
-
- -

alarm.h

-
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:

-
-
getSeverity
-
Get the alarm severity corresponding to the integer value.
-
getSeverityNames
-
Get the array of severity choices.
-
- -

Alarm Status defines the possible choices for alarm status:

-
-
getStatus
-
Get the alarm status corresponding to the integer value.
-
getStatusNames
-
Get the array of status choices.
-
- -

Alarm has the methods:

-
-
Alarm
-
The constructor. It sets the severity to no alarm and the message to - "".
-
getMessage
-
Get the message.
-
setMessage
-
Set the message.
-
getSeverity
-
Get the severity.
-
setSeverity
-
Set the severity.
-
getStatus
-
Get the status.
-
setStatus
-
Set the status.
-
- -

pvAlarm.h

-
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

-
-
PVAlarm
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if it found an - appropriate pvData structure. It looks first a pvField itself and if is - not an appropriate pvData structure but the field name is value it looks - to see if the parent structure has an appropriate sub structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to an alarm structure?
-
get
-
Copies data from the pvData structure to an Alarm. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from Alarm to the pvData structure. An exception is thrown - if not attached to a pvData structure.
-
- -

control

- -

Control information is represented by the following structure

-
structure control
-    double limitLow
-    double limitHigh
-    double minStep
- -

Two header files are provided for manipulating control:

-
-
control.h
-
Defines control independent of pvData, i.e. it is a generally useful - class for manipulating control.
-
pvControl.h
-
A class that can be attached to an control pvData structure. It - provides get and set methods to get/set control data as defined by - control.h
-
- -

control.h

-
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

-
-
Control
-
The default constructure.
-
getLow
-
Get the low limit.
-
getHigh
-
Get the high limit.
-
setLow
-
Set the low limit.
-
setHigh
-
Set the high limit.
-
setMinStep
-
Set the minimum step size.
-
getMinStep
-
Get he minimum step size.
-
- -

pvControl.h

-
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

-
-
PVControl
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if it found an - appropriate pvData structure. It looks first a pvField itself and if is - not an appropriate pvData structure but the field name is value it looks - to see if the parent structure has an appropriate sub structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to a control structure?
-
get
-
Copies data from the pvData structure to a Control. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from Control to the pvData structure. An exception is - thrown if not attached to a pvData structure.
-
- -

display

- -

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:

-
-
display.h
-
Defines display independent of pvData, i.e. it is a generally useful - class for manipulating display.
-
pvDisplay.h
-
A class that can be attached to an display pvData structure. It - provides get and set methods to get/set display data as defined by - display.h
-
- -

display.h

-
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

-
-
Control
-
The default constructure.
-
getLow
-
Get the low limit.
-
getHigh
-
Get the high limit.
-
setLow
-
Set the low limit.
-
setHigh
-
Set the high limit.
-
getDescription
-
Get the description.
-
setDescription
-
Set the description.
-
getFormat
-
Get the format.
-
setFormat
-
Set the format.
-
getUnits
-
Get the units.
-
setUnits
-
Set the units.
-
- -

pvDisplay.h

-
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

-
-
PVDisplay
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if it found an - appropriate pvData structure. It looks first a pvField itself and if is - not an appropriate pvData structure but the field name is value it looks - to see if the parent structure has an appropriate sub structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to a display structure?
-
get
-
Copies data from the pvData structure to a Display. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from Display to the pvData structure. An exception is - thrown if not attached to a pvData structure.
-
- -

pvEnumerated.h

- -

An enumerated structure is a structure that has fields:

-
structure
-    int index
-    string[] choices
- -

For enumerated structures a single header file pvEnumerted.h is available

-
class PVEnumerated {
-public:
-    PVEnumerated();
-    //default constructors and destructor are OK
-    //This class should not be extended
-    //returns (false,true) if pvField(isNot, is valid enumerated structure
-    //An automatic detach is issued if already attached.
-    bool attach(PVFieldPtr const &pvField);
-    void detach();
-    bool isAttached();
-    // each of the following throws logic_error is not attached to PVField
-    // a set returns false if field is immutable
-    bool setIndex(int32 index);
-    int32 getIndex();
-    std::string getChoice();
-    bool choicesMutable();
-    StringArrayPtr const & getChoices();
-    int32 getNumberChoices();
-    bool setChoices(StringArray &choices,int32 numberChoices);
-};
- -

where

-
-
PVEnumerated
-
The default constructor. Attach must be called before any get or set - method can be called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if pvField (is - not, is) an enumerated structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to an enemerated structure?
-
setIndex
-
Set the index field in the pvData structure. An exception is thrown if - not attached to a pvData structure.
-
getIndex
-
Get the index field in the pvData structure.
-
getChoice
-
Get the std::string value corresponding to the current index field in the - pvData structure. An exception is thrown if not attached to a pvData - structure.
-
choicesMutable
-
Can the choices be changed? Note that this is often true. An exception - is thrown if not attached to a pvData structure.
-
getChoices
-
Get the array of choices. An exception is thrown if not attached to a - pvData structure.
-
getNumberChoices
-
Get the number of choices. An exception is thrown if not attached to a - pvData structure.
-
setChoices
-
Change the choices. An exception is thrown if not attached to a pvData - structure.
-
- - -

pvDataApp/factory

- -

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

- -

pvDataAPP/misc

- -

Overview

- -

This package provides utility code:

-
-
bitSet.h
-
An implementation of BitSet that can be serialized.
-
byteBuffer.h
-
Used to serialize objects.
-
destroyable.h
-
Provides method destroy.
-
epicsException.h
-
Exception with stack trace.
-
event.h
-
Signal and wait for an event.
-
executor.h
-
Provides a thread for executing commands.
-
localStaticLock.h
-
TBD Matej can You explain what this does?
-
lock.h
-
Support for locking and unlocking.
-
messageQueue.h
-
Support for queuing messages to give to requesters.
-
noDefaultMethods.h
-
When privately extended prevents compiler from implementing default - methods.
-
queue.h
-
A queue implementation that allows the latest queue element to continue - to be used when no free element is available.
-
requester.h
-
Allows messages to be sent to a requester.
-
serialize.h
-
Support for serializing objects.
-
serializeHelper.h
-
More support for serializing objects.
-
sharedPtr.h
-
Defines POINTER_DEFINITIONS.
-
sharedVector.h -
Like std::vector except that std::shared_ptr is used for - the data array.
-
status.h
-
A way to pass status information to a client.
-
templateMeta.h
-
TBD Michael can You provide an explaination?
-
thread.h
-
Provides thread support.
-
timeFunction.h
-
Time how long a function call requires.
-
timer.h
-
An implementation of Timer that does not require an object to be - created for each timer request.
-
typeCast.h
-
TBD Michael can You provide an explaination?
-
- -

Note that directory testApp/misc has test code for all the classes in misc. -The test code also can be used as examples.

- -

bitSet.h

- -

This is adapted from the java.util.BitSet. bitSet.h is:

-
-class BitSet;
-typedef std::tr1::shared_ptr<BitSet> BitSetPtr;
-
-class BitSet : public Serializable {
-public:
-    static BitSetPtr create(uint32 nbits);
-    BitSet();
-    BitSet(uint32 nbits);
-    virtual ~BitSet();
-    void flip(uint32 bitIndex);
-    void set(uint32 bitIndex);
-    void clear(uint32 bitIndex);
-    void set(uint32 bitIndex, bool value);
-    bool get(uint32 bitIndex) const;
-    void clear();
-    int32 nextSetBit(uint32 fromIndex) const;
-    int32 nextClearBit(uint32 fromIndex) const;
-    bool isEmpty() const;
-    uint32 cardinality() const;
-    uint32 size() const;
-    BitSet& operator&=(const BitSet& set);
-    BitSet& operator|=(const BitSet& set);
-    BitSet& operator^=(const BitSet& set);
-    BitSet& operator-=(const BitSet& set);
-    BitSet& operator=(const BitSet &set);
-    void or_and(const BitSet& set1, const BitSet& set2);
-    bool operator==(const BitSet &set) const;
-    bool operator!=(const BitSet &set) const;
-    virtual void serialize(
-        ByteBuffer *buffer,SerializableControl *flusher) const;
-    virtual void deserialize(
-        ByteBuffer *buffer,DeserializableControl *flusher);
-private:
-};
-
-std::ostream& operator<<(std::ostream& o, const BitSet& b);
-
- -

where

-
-
BitSet()
-
Creates a bitSet of initial size 64 bits. All bits initially false.
-
BitSet(uint32 nbits)
-
Creates a bitSet with the initial of the specified number of bits. All - bits initially false.
-
~BitSet()
-
Destructor.
-
flip(uint32 bitIndex)
-
Flip the specified bit.
-
set(uint32 bitIndex)
-
Set the specified bit true.
-
clear(uint32 bitIndex)
-
Set the specified bit false.
-
set(uint32 bitIndex, bool value)
-
Set the specified bit to value.
-
get(uint32 bitIndex)
-
Return the state of the specified bit.
-
clear()
-
Set all bits to false.
-
nextSetBit(uint32 fromIndex)
-
Get the index of the next true bit beginning with the specified - bit.
-
nextClearBit(uint32 fromIndex)
-
Get the index of the next false bit beginning with the specified - bit.
-
isEmpty()
-
Return (false,true) if (at least one bit true, all bits are false)
-
cardinality()
-
Return the number of true bits.
-
size()
-
Returns the number of bits of space actually in use.
-
operator&=(const BitSet& set)
-
Performs a logical and of this target bit set with the argument bit - set. This bit set is modified so that each bit in it has the value true - if and only if it both initially had the value true and the corresponding - bit in the bit set argument also had the value.
-
operator|=(const BitSet& set)
-
Performs a logical or of this target bit set with the argument bit - set.
-
operator^=(const BitSet& set)
-
Performs a logical exclusive or of this target bit set with the - argument bit set.
-
operator-=(const BitSet& set)
-

Clears all of the bits in this bitSet whose corresponding bit is set - in the specified bitSet.

-
-
operator=(const BitSet &set)
-
Assignment operator.
-
or_and(const BitSet& set1, const BitSet& set2)
-
Perform AND operation on set1 and set2, and then OR this bitSet with - the result.
-
operator==(const BitSet &set)
-
Does this bitSet have the same values as the argument.
-
operator!=(const BitSet &set)
-
Is this bitSet different than the argument.
-
virtual void serialize(ByteBuffer *buffer,SerializableControl *flusher) - const;
-
Serialize the bitSet
-
virtual void deserialize(ByteBuffer *buffer,DeserializableControl - *flusher);
-
Deserialize the bitSet.
-
-

- -

byteBuffer.h

- -

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();
- ...
-};
- -

destroyable.h

-
class Destroyable  {
-public:
-    POINTER_DEFINITIONS(Destroyable);
-    virtual void destroy() = 0;
-    virtual ~Destroyable() {};
-};
- -

epicsException.h

-
/*
- * 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.
- */
- -

event.h

- -

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

-
-
Event
-
The constructor. The initial value can be full or empty. The normal - first state is empty.
-
signal
-
The event becomes full. The current or next wait will complete.
-
wait
-
Wait until event is full or until timeout. The return value is - (false,true) if the wait completed because event (was not, was) full. A - false value normally means that that a timeout occured. It is also - returned if an error occurs or because the event is being deleted.
-
tryWait
-
returns (false,true) if the event is (empty,full)
-
- -

executor.h

- -

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:

-
-
Executor
-
The constructor. A thread name and priority must be specified.
-
~Executor
-
The destructor. If any commands remain in the execute list they are not - called. All ExecutorNodes that have been created are deleted.
-
execute
-
Request that command be executed. If it is already on the run list - nothing is done.
-
- -

localStaticLock.h

-
-extern epics::pvData::Mutex& getLocalStaticInitMutex();
-
-static class MutexInitializer {
-  public:
-    MutexInitializer ();
-    ~MutexInitializer ();
-} localStaticMutexInitializer; // Note object here in the header.
-
-

TBD Matej will explain.

- -

lock.h

-
-typedef epicsMutex Mutex;
-
-class Lock : private NoDefaultMethods {
-public:
-    explicit Lock(Mutex &pm);
-    ~Lock();
-    void lock();
-    void unlock();
-    bool tryLock();
-    bool ownsLock() ;
- ...
-};
- -

Lock is as easy to use as Java synchronize. To protect some object just -create a Mutex for the object and then in any method to be synchronized just -have code like:

-
class SomeClass {
-private
-    Mutex mutex;
- ...
-public
-    SomeClass() : mutex(Mutex()) {}
- ...
-    void method()
-    {
-        Lock xx(mutex);
-        ...
-    }
-
- -

The method will take the lock when xx is created and release the lock when -the current code block completes.

- -

Another example of Lock is initialization code that must initialize only -once. This can be implemented as follows:

-
    static void init(void) {
-        static Mutex mutex;
-        Lock guard(mutex);
-        if(alreadyInitialized) return;
-        // initialization
-    }
-

-

Lock has a private variable: -

-bool locked;
-
-and improves efficency by checking the local variable before calling the -mutex methods. This is not thread safe if any methods are called by a thread other than -the thread that created the Lock. -

-

It is thread safe if used as follows:

-
-{
-    Lock guard(mutex);
-    ...
-    /* the following can optionally be called
-    guard.unlock();
-    guard.lock();
-    */
-}
-
-

It is not thread safe if used as follows:

-
-class SomeClass
-{
-private:
-    Mutex mutex;
-    Lock lock;
-public:
-    SomeClass: lock(mutex) {}
-    ...
-    void someMethod() {
-        lock.unlock();
-        ...
-    }
-    ...
-};
-
-

It is only safe if all methods of Lock, including ~Lock(), -are called by the same thread. -

- -

messageQueue.h

- -

Definitions

- -

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:

-
-
getMessage
-
The message.
-
getMessageType
-
The message type.
-
setMessageNull
-
Set the message to be a null string.
-
- -

A messageQueue is an interface with public methods:

-
-
MessageQueue
-
The constructor. The queue size must be specified.
-
~MessageQueue
-
The destructor.
-
put
-
Put a new message into the queue. False is returned if the queue was - full and true otherwise. If replaceLast is true then the last message is - replaced with this message.
-
get
-
Get the oldest queue element. If the queue is empty null is returned. - Before the next get can be issued release must be called.
-
release
-
Release the queue element returned by the last get.
-
isEmpty
-
Is the queue empty?
-
isFull
-
Is the queue full?
-
getClearOverrun
-
Get the number of times put has been called but no free element is - available.
-
- -

Look at miscTest/testMessageQueue.cpp for an example.

- -

noDefaultMethods.h

- -

If a class privately extends this class then the compiler can not create any -of the following: default constructor, default copy constructror, or default -assignment contructor.

-
/* This is based on Item 6 of
- * Effective C++, Third Edition, Scott Meyers
- */
-    class NoDefaultMethods {
-    protected:
-    // allow by derived objects
-    NoDefaultMethods(){};
-    ~NoDefaultMethods(){}
-    private:
-    // do not implment
-    NoDefaultMethods(const NoDefaultMethods&);
-    NoDefaultMethods & operator=(const NoDefaultMethods &);
-    };
- -

queue.h

- -

This provides a bounded queue. When the queue is -full the user code is expected to keep using the current element until a new -free element becomes avalable.

-
-template <typename T>
-class Queue
-{   
-public:
-    POINTER_DEFINITIONS(Queue);
-    typedef std::tr1::shared_ptr<T> queueElementPtr;
-    typedef std::vector<queueElementPtr> queueElementPtrArray;
-    Queue(queueElementPtrArray &);
-    virtual ~Queue();
-    void clear();
-    int capacity();
-    int getNumberFree();
-    int getNumberUsed();
-    queueElementPtr & getFree();
-    void setUsed(queueElementPtr const &element);
-    queueElementPtr & getUsed();
-    void releaseUsed(queueElementPtr const &element);
- ...
-};
- -

testApp/misc/testQueue.cpp provides an example of how to define a queue.

- -

The queue methods are:

-
-
clear
-
Make the queue empty.
-
getNumberFree
-
Get the number of free elements in the queue.
-
capacity
-
Get the capacity, i.e. the maximun number of elements the queue can - hold.
-
getNumberFree
-
Get the number of free elements.
-
getNumberUsed
-
Get the number of elements used.
-
getFree
-
Get the next free element. Null is returned if no free elements are - available. If a non null value is returned then the element belongs to - the caller until setUsed is called.
-
setUsed
-
Set a queue element used. This must be the element returned by the last - call to getFree.
-
getUsed
-
Get the next used element of null if no more used elements are - available.
-
releaseUsed
-
Set a queue element free. This must be the element returned by the last - call to getUsed.
-
- -

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.h

- -

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

-
-
-
MessageType
-
Type of message.
-
messageTypeName
-
An array of strings of the message type names, i.e. - std::string("info"),std::string("warning"),std::string("error"),std::string("fatalError").
-
getRequesterName
-
Returns the requester name.
-
message
-
Gives a message to the requester.
-
- -

serialize.h

-
-    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;
-    };
- -

serializeHelper.h

- -

This is a helper class for serialization, which is required for sending and -receiving pvData over the nerwork.

-
class SerializeHelper : public NoDefaultMethods {
-public:
-    static void writeSize(int s, ByteBuffer* buffer,
-        SerializableControl* flusher);
-    static int readSize(ByteBuffer* buffer,
-        DeserializableControl* control);
-    static void serializeString(const std::string& value,
-        ByteBuffer* buffer,SerializableControl* flusher);
-    static void serializeSubstring(const std::string& value, int offset,
-        int count, ByteBuffer* buffer,
-        SerializableControl* flusher);
-    static std::string deserializeString(ByteBuffer* buffer,
-        DeserializableControl* control);
- ...
-};
- -

where

-
-
writeSize
-
Serialize the size.
-
readSize
-
Deserialize the size.
-
serializeString
-
Serialize a std::string.
-
serializeSubstring
-
Serialize a substring.
-
deserializeString
-
Deserialize a string.
-
- -

sharedPtr.h

-
-#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;
- -

sharedVector.h

-

-shared_vector is a holder for a contigious piece of memory. -Data is shared, but offset and length are not. -This allows one vector to have access to only a subset of a piece of memory. -

-

-shared_vector differs from std::vector as follows:

-
-
Differences in behavior
-
- shared_vector models const-ness like shared_ptr. - An equivalent of 'const std::vector<E>' is - 'const shared_vector<const E>'. - However, it is also possible to have 'const shared_vector<E>' - analogous to 'E* const' and 'shared_vector<const E>>' - which is analogous to 'const E*'.i -
- Copying a shared_vector, by construction or assignment, does not copy - its contents. - Modifications to one such "copy" effect all - associated shared_vector instances. -
- std::vector::reserve(N) has no effect if N<=std::vector::capacity(). - However, like resize(), shared_vector<E>::reserve() has the side effect - of always calling make_unique(). -
-
Parts of std::vector interface not implemented
-
- Mutating methods insert(), erase(), shrink_to_fit(), emplace(), and emplace_back() are not implemented. -
- shared_vector does not model an allocator which is bound to the object. Therefore the get_allocator() method and the allocator_type typedef are not provided. -
- The assign() method and the related constructor are not implemented at this time. -
- The comparison operators are not implemented at this time. -
-
Parts not found in std::vector
-
- shared_vector has additional constructors from raw pointers and shared_ptr s. - The copy constructor and assignment operator allow implicit castings - from type 'shared_vector<T>' to 'shared_vector<const T>>'. - To faciliate safe modification the methods unique() and make_unique() are provided - The slice() method selects a sub-set of the shared_vector. - The low level accessors dataPtr(), dataOffset(), dataCount(), and dataTotal(). -
-
- - -
-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
-
Several flavors of constructor are provided. The most commingly used is: - 
-shared_vector(size_t c);
-
- This creates a shared_vector of the specified size/ -
-
max_size
-
The maximum size the C++ implementation allows, i.e., - the maximum possible capacity. - Note that units are number of elements not number of bytes. -
-
capacity
-
The current capacity.
-
reserve
-
Set array capacity.
-
resize
-
Grow or shrink array. - It the second argument is given it is the value to assign to - and new elements. -
-
make_unique
-
Ensure (by copying) that this shared_vector - is the sole owner of the data array. -
-
begin,...,rend
-
Standard interators.
-
front
-
Return a reference to the first element.
-
back
-
Return a reference to the last element.
-
push_back
-
Add an element to the end of the array.
-
pop_back
-
Remove an element from the end of the array.
-
data
-
Return a pointer to the raw array.
-
operator[](size_t i)
-
Return a reference to the specified element.
-
at
-
Like the previous except that it throws a range-error if - the specified element is out of range.
-
operator=
-
Copy an existing shared_vector.
-
swap
-
Swap the contents of this vector with another.
-
clear
-
Clear contents.
-
unique
-
returns (true,false) if data (is not, is) shared.
-
size
-
Number of elements visible through this vector.
-
empty
-
Is the number of elements zero?
-
slice
-
Reduce the view of this shared_vector.
-
dataPtr
-
A readonly shared_ptr to the array.
-
dataOffset
-
Offset in the data array of first visible element.
-
dataCount
-
Number of visible elements between dataOffset and end of data.
-
dataTotal
-
The total number of elements between dataOffset and the end of data
-
-

TBD -Michael should decide if this is the correct set of methods to describe. -Also he should check for correct descriptions. -

- - -

status.h

- -

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:

-
-
StatusType
-
An enum for the status type.
-
getType
-
Get the statusType.
-
getMessage
-
Get a message explaining the error.
-
getStackDump
-
Get a stack dump.
-
- -

The StatusCreate methods are:

-
-
getStatusOK
-
Get a singleton that returns StatusType.OK and a null message and - stackDump.
-
createStatus
-
Create a new Status.
-
deserializeStatus
-
Use this method instead of Status.deserialize(), since this allows OK - status optimization.
-
-

templateMeta.h

-

TBD Michael will explain.

- -

thread.h

- -

ThreadPriority

-
enum ThreadPriority {
-    lowestPriority,
-    lowerPriority,
-    lowPriority,
-    middlePriority,
-    highPriority,
-    higherPriority,
-    highestPriority
-};
- -

Thread

-
-class Thread;
-typedef std::tr1::shared_ptr<Thread> ThreadPtr;
-typedef std::tr1::shared_ptr<epicsThread> EpicsThreadPtr;
-
-class Runnable {
-public:
-    virtual void run() = 0;
-};
-
-class Thread;
-
-class Thread : public epicsThread, private NoDefaultMethods {
-public:
-    Thread(
-        std::string name,
-        ThreadPriority priority,
-        Runnable *runnableReady,
-        epicsThreadStackSizeClass stkcls=epicsThreadStackSmall);
-    ~Thread();
- ...
-};
- -

Runnable must be implement by code that wants to be run via a thread. It has -one virtual method: run. Run is the code that is run as a thread. When run -compeletes it can not be restarted. If code wants to delete a thread then it -MUST arrange that the run returns before the thread can be deleted. An -exception is thrown if run remains active when delete is called.

- -

Thread has the methods:

-
-
Thread
-
The constructor. A thread name and priority must be specified. The run - methods of runnable is executed. When the run methods returns the thread - will no longer be active but the client code must still delete the - thread.
-
~Thread
-
The destructor. This is called as the result of: - 
    delete pthread;
-
-
- -

timeFunction.h

- -

TimeFunction is a facility that measures the average number of seconds a -function call requires. When timeCall is called, it calls function in a loop. -It starts with a loop of one iteration. If the total elapsed time is less then -.1 seconds it increases the number of iterrations by a factor of 10. It keeps -repeating until the elapsed time is greater than .1 seconds. It returns the -average number of seconds per call.

-
class TimeFunctionRequester;
-class TimeFunction;
-typedef std::tr1::shared_ptr<TimeFunctionRequester> TimeFunctionRequesterPtr;
-typedef std::tr1::shared_ptr<TimeFunction> TimeFunctionPtr;
-        
-class TimeFunctionRequester {
-public:              
-    POINTER_DEFINITIONS(TimeFunctionRequester);
-    virtual ~TimeFunctionRequester(){}
-    virtual void function() = 0;
-};  
-
-    
-class TimeFunction {
-public:    
-    POINTER_DEFINITIONS(TimeFunction);
-    TimeFunction(TimeFunctionRequesterPtr const & requester);
-    ~TimeFunction(); 
-    double timeCall();
- ...
-};
- -

TimeFunctionRequester must be implemented by code that wants to time how -long a function takes. It has the single method:

-
-
function
-
This is the function.
-
- -

TimeFunction has the methods:

-
-
TimeFunction
-
Constructor.
-
~TimeFunction
-
Destructor.
-
timeCall
-
Time how long it takes to execute the function. It starts by calling - the function one time. If it takes < 1 seconds to doubles the number - of times to call the function. It repeats this until it takes at least - one second to call it ntimes.
-
- -

timer.h

- -

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: -

-
-
callback
-
This is called when a timer expires. This is called with no locks held. - When called a delay timer is no longer on the queue but a periodioc timer - is on a queue. Thus the callback for a delay timer can issue a new - schedule request but a periodic timer must not. Note the explaination of - TimerNode.cancel below.
-
timerStopped
-
Timer.stop was called when a timer request was queued. or if the timer - is stopped and a schedule request is made.
-
- -

In order to schedule a callback client code must allocate a TimerNode It can -be used to schedule multiple callbacks. It has the methods:

-
-
TimerNode
-
The constructor. User code must create a TimeNode in order to call a - schedule method.
-
~TimerNode
-
The destructor. This is called as a result of the client calling: - 
    delete timerNode;
-
-
cancel
-
This is called to cancel a timer request. If a callback has been - dequeued but the callback not called when cancel is called then a - callback may still happen. New schedule requests can be made after a - cancel request has been made.
-
isScheduled
-
Is the timerNode scheduled to be called.
-
- -

Timer has the methods:

-
-
Timer
-
The consttructor.
-
~Timer
-
The destructor. The queue is emptied and TimerCallback.timerStopped is - called for each element of the queue.
-
scheduleAfterDelay
-
A request to schedule a callback after a delay specified in - seconds.
-
schedulePeriodic
-
Schedule a periodic callback.
-
-

typeCast.h

-

TBD Michael will explain.

- -

pvDataApp/pvMisc

- -

bitSetUtil.h

- -

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:

-
-
compress
-
Compress the bits in a BitSet related to a structure.
- For each structure: -
    -
  1. If the bit for the structure is set then the bit for all subfields - of the structure are cleared.
    2. -
  2. If the bit for the structure is not set but all immediate subfields - have their bit set then the bit for the structure is set and the bits - for all subfields are cleared.
    3. -
- Note that this is a recursive algorithm. That is if every immediate - subfield has it's offset bit set then the bits for ALL fields that reside - in the structure will be cleared.
-
Channel Access can call this before sending data. It can then pass - entire structures if the structure offset bit is set.
-
- -

support for copy and monitor

-

copy and monitor are not used in this project. -They are intended for use by pvAccess and by pvAccess servers. -They are provided with this project because the code depends only on -pvData itself. -

-

This document describes C++ specific code. - -pvRequest.html -provides a language independent overview of copy and monitor. -

-

-NOTE:pvRequest.html must be updated since it is based on an earlier version of pvCopy that -had knowlege of PVRecord. The C++ version was implemented in pvDatabaseCPP -and the Java version on pvIOCJava. -At present only the C++ version of the new API for pvCopy is implemented. -

-

Copy provides: -

-
createRequest
-
- The Channel create methods in pvAccess all have an argument - PVStructure pvRequest.
- Given an ascii string createRequest creates a PVStructure that provides - a pvData representation of the information from the ascii string. - It is this structure that can be passed to the channel create methods.
- The information in a pvRequest selects an arbitrarary subset of the - fields in a top level structure that resides in the server. - In addition options can be specified. Both global and field specific - options can be specified. -
-
pvCopy
-
This is a faculity used by channel providers. - It provides client specific code that manages a copy of an arbitrary - subset of the fields in a top level structure that resides in the - provider. It also allows provider access to options specified - by the client. -
-
-Monitor provides: -
-
monitor
-
This is support code for channel providers that implement channel - monitor. It, together with the queue facility, provides support for - monitor queues. -
-
monitorPlugin
-
This is support for implementing monitor plugins. - A monitor plugin can be developed that has no knowledge - of pvAccess but only pvData. -
-
-

- -

support for copy

-

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. -

- -

createRequest

-

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
-}
-
-

pvCopy

-

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  &copyPVStructure,
-        BitSetPtr const  &bitSet);
-     void updateCopySetBitSet(
-        PVStructurePtr const  &copyPVStructure,
-        BitSetPtr const  &bitSet);
-    void updateCopyFromBitSet(
-        PVStructurePtr const  &copyPVStructure,
-        BitSetPtr const  &bitSet);
-    void updateMaster(
-        PVStructurePtr const  &copyPVStructure,
-        BitSetPtr const  &bitSet);
-    PVStructurePtr getOptions(std::size_t fieldOffset);
-    std::string dump();
-...
-};
-
-where -
-
PVCopyTraverseMasterCallback::nextMasterPVField
-
- PVCopyTraverseMasterCallback is a callback which must - be implemented by the code that uses pvCopy, normally - the channel provider. It has the single method nextMasterPVField -
- nextMasterPVField is called for each field in the master - as a result of a call to traverseMaster. -
-
create
-
- This is the method for creating a PVCopy instance.
-
-
pvMaster
-
the top level sructure managed by the server.
-
pvRequest
-
selects the set of subfields desired - and options for each field.
-
structureName
-
the name for the top level of any PVStructure created. -
-
-
-
getPVMaster
-
- Gets the top level structure from pvMaster. -
-
traverseMaster
-
- Traverse all fields of the top level structure of pvMaster. - For each field the callback is called. -
-
getStructure
-
- Get the introspection interface for a PVStructure for e copy. -
-
createPVStructure
-
Create a copy instance. - Monitors keep a queue of monitor elements. - Since each element needs a PVStructure, multiple top level structures - will be created. -
-
getCopyOffset
-
Given a field in pvMaster. - return the offset in copy for the same field. - A value of std::string::npos means that the copy does not have this field. - Two overloaded methods are provided. The first is called if - the field of master is not a structure. The second is for - subfields of a structure. -
-
getMasterPVField
-
- Given a offset in the copy get the corresponding field in pvMaster. -
-
initCopy
-
- Initialize the fields in copyPVStructure - by giving each field the value from the corresponding field in pvMaster. - bitSet will be set to show that all fields are changed. - This means that bit set will have the value {0}. -
-
updateCopySetBitSet
-
- Set all fields in copyPVStructure to the value of the corresponding field - in pvMaster. Each field that is changed has it's corresponding - bit set in bitSet. -
-
updateCopyFromBitSet
-
- For each set bit in bitSet set the field in copyPVStructure to the value - of the corrseponding field in pvMaster. -
-
updateMaster
-
- For each set bit in bitSet set the field in pvMaster to the value - of the corrseponding field in copyPVStructure. - -
-
getOptions
-
- Get the options for the field at the specified offset. - A NULL is returned if no options were specified for the field. - If options were specified,PVStructurePtr is - a structure with a set of PVString subfields that specify name,value - pairs. name is the subField name and value is the subField value. -
-
- - - - -

support for monitor

-

This consists of two components: -

-
monitor
-
Used by code that implements pvAccess montors.
-
monitorPlugin
-
Code that provides special semantics for monitors.
-
-

-

monitor

-
-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

-

MonitorElement holds the data for one element of a monitor queue. -It has the fields: -

-
pvStructurePtr
-
A top level structure with data values at the time the monitors occurs.
-
changedBitSet
-
Shows which fields have changed since the previous monitor.
-
overrunBitSet
-
Shows which fields have changed more han once since the previous monitor.
-
-

-

monitorElement queue

-

-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

-

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:

-
-
start
-
- Start monitoring. - This will result in a an inital monitor that has the current value - of all fields. -
-
stop
-
- Stop monitoring. -
-
poll
-
- Called to get a monitor element. - If no new elemants are available then a null pointer is returned. -
-
release
-
- Release the monotor element. - The caller owns the monitor element between the calls to poll and release. -
-
-
-

MonitorRequester

-

This must be implemented by a pvAccess client. -It has the methods:

-
-
monitorConnect
-
- A monitor has either connected of disconnected. -
-
monitorEvent
-
- A new monitor element is available. -
-
unlisten
-
- The channel is going away. The client cam no longer access the monitor. -
-
- -

monitorPlugin

-
-class MonitorPlugin
-{
-    virtual std::string const & getName() = 0;
-    virtual bool causeMonitor(
-        PVFieldPtr const &pvField,
-        PVStructurePtr const &pvTop,
-        MonitorElementPtr const &monitorElement) = 0;
-    virtual void monitorDone(
-        MonitorElementPtr const &monitorElement);
-    virtual void startMonitoring();
-    virtual void stopMonitoring();
-    virtual void beginGroupPut();
-    virtual void endGroupPut();
-};
-
-class MonitorPluginCreator
-{
-    virtual MonitorPluginPtr create(
-        FieldConstPtr const &field,
-        StructureConstPtr const &top,
-        PVStructurePtr const &pvFieldOptions) = 0;
-     virtual std::string const & getName() = 0;
-}
-
-class MonitorPluginManager
-{
-    static MonitorPluginManagerPtr get();
-    bool addPlugin(
-         std::string const &pluginName,
-         MonitorPluginCreatorPtr const &creator);
-    MonitorPluginCreatorPtr findPlugin(std::string const &pluginName);
-    void showNames();
-};
-
-
-

MonitorPlugin

-

MonitorPlugin must be implemented by the plugin implementation. -It has methods:

-
-
getName
-
Get the name of the plugin.
-
causeMonitor
-
- Should the value of pvField cause a monitor to be raised. - pvField and pvTop are fields in the top level structure - being monitored. monitorElement has the top level structure - for the copy. - The implementation should not modify the fields in the structure - being monitored. - Called with pvTop locked. -
-
monitorDone
-
- Called just before monitorElement will be given to client. - The plugin can change the data values and bitSets in monitorElement. - Called with pvTop unlocked. -
-
startMonitoring
-
- Monitoring is starting. -
-
stopMonitoring
-
- Monitoring is being stopped. -
-
beginGroupPut
-
- A set of puts is starting. - Called with pvTop locked. -
-
endGroupPut
-
- The set of puts is complete. - Called with pvTop locked. -
-
-

MonitorPluginCreator

-

MonitorPluginCreator must also be implemented by the plugin implementation. -It is called for each field instance that has options of the from -[plugin=name...] where name is the name of the plugin. -Note that a plugin instance will belong to a single client. -It has methods:

-
-
getName
-
Get the name of the plugin.
-
create
-
- Create a new plugin instance. - If the arguments are not compatible with the plugin a NULL shared pointer is - returned.
- pvFieldOptions is - a structure with a set of PVString subfields that specify name,value - pairs. name is the subField name and value is the subField value.
- Note that a plugin will below to a single client. -
-
-

MonitorPluginManager

-

MonitorPluginManager has the methods:

-
-
get
-
- MonitorPluginManager is a singleton. - The first call to get will create the single instance. - Further calls will rerurn the single instance. -
-
addPlugin
-
- Add a new plugin. -
-
findPlugin
-
- Find a plugin. A NULL shared pointer is reurned if it has not been added. -
-
showNames
-
- Show the names of all puugins that have been added. -
-
-

NOTE: -Should the method causeMonitor -have arguments pvField and pvTop -be defined so that they can not be modfied. -This would be posssible if the following was defined: -

-typedef std::tr1::shared_ptr<const PVField> PVFieldConstPtr;
-typedef std::tr1::shared_ptr<const PVStructure> PVStructureConstPtr;
-
-then the definition for causeMonitor could be: -
-virtual bool causeMonitor(
-        PVFieldConstPtr const &pvField,
-        PVStructureConstPtr const &pvTop,
-        MonitorElementPtr const &monitorElement) = 0;
-
-But just adding these definitions is not sufficent. -In addition all methods defined in pvDataCPP must be checked. -In particular many of the methods in Convert must have -their arguments modified. -Big job. -

-

monitorPlugin example

-

Example Plugin Overview

-

This section describes an example plugin that:

-
    -
  • Only raises monitors when a field changes value.
    - If no plugin is provided - the default is to raise a monitor when a put is issued to a field.
    • -
  • Optionally a change will not raise a monitor.
    - The change will, however, - appear if a put to another field raise a monitor.
    • -
-

As an example assume that a channel provided by pvAccess has a top level structure -that represents a power supply.

-
-structure powerSupply
-    structure alarm
-    structure timeStamp
-    structure power
-       double value
-       structure alarm
-       struvture display
-    structure voltage
-       double value
-       structure alarm
-       struvture display
-    structure current
-       double value
-       structure alarm
-       struvture display
-
-

A pvAccess client wants to create a monitor on the powerSupply as follows: -The client wants a top level structure that looks like: -

-structure powerSupply
-    structure alarm
-    structure timeStamp
-    structure power
-       double value
-    structure voltage
-       double value
-    structure current
-       double value
-
-In addition the client wants monitors to occur only when one of the monitored -fields changes value but not just because a put occured. -Also if only the timeStamp changes value then that should not cause a monitor. -

-

The example monitor plugin implements the semantics the -client wants. It can be attached to any field via the following options: -

-[plugin=onChange,raiseMonitor=value]
-
-This plugin will trigger a monitor for the field only if the field changes -value. In addition value equals false means do not raise a monotor -for changes to this field. -But if a change to another field does cause a monitor the change to this field -will be passed to the client. -

-

-Assume that the client has already connected to the channel. -The client can then issue the commands:

-
-std::string request("field(alarm[plugin=onChange]");
-request += ",timeStamp[plugin=onChange,raiseMonitor=false]";
-request += ",power.value[plugin=onChange";
-request += ",voltage.value[plugin=onChange";
-request += ",current.value[plugin=onChange";
-
-PVStructurePtr pvRequest = createRequest->createRequest(request);
-
-MonitorPtr monitor = channel->createMonitor(monitorRequester,pvRequest);
-
-

Example Plugin Code

-

The header file to create the example has the definition:

-
-class ExampleMonitorPlugin{
-public:
-    static void create();
-};
-
-

The implementation is:

-
-class OnChangePlugin : public MonitorPlugin
-{
-public:
-    virtual ~OnChangePlugin(){}
-    OnChangePlugin() {}
-    bool init(
-        FieldConstPtr const &field,
-        StructureConstPtr const &top,
-        PVStructurePtr const &pvFieldOptions)
-   {
-        pvField = getPVDataCreate()->createPVField(field);
-        raiseMonitor = true;
-        if(pvFieldOptions!=NULL) {
-            PVStringPtr pvString =
-                pvFieldOptions->getSubField<PVString>("raiseMonitor");
-                if(pvString!=NULL) {
-                    std::string value = pvString->get();
-                    if(value.compare("false")==0) raiseMonitor = false;
-                }
-        }
-        return true;
-   }
-   virtual std::string &getName(){return pluginName;}
-   virtual bool causeMonitor(
-        PVFieldPtr const &pvNew,
-        PVStructurePtr const &pvTop,
-        MonitorElementPtr const &monitorElement)
-   {
-       bool isSame = convert->equals(pvNew,pvField);
-       if(isSame) return false;
-       convert->copy(pvNew,pvField);
-       return raiseMonitor;
-   }
-private:
-   PVFieldPtr pvField;
-   bool raiseMonitor;
-};
-class OnChangePluginCreator : public MonitorPluginCreator
-{
-public:
-    virtual std::string &getName(){return pluginName;}
-    virtual MonitorPluginPtr create(
-        FieldConstPtr const &field,
-        StructureConstPtr const &top,
-        PVStructurePtr const &pvFieldOptions)
-   {
-       OnChangePluginPtr plugin(new OnChangePlugin());
-       bool result = plugin->init(field,top,pvFieldOptions);
-       if(!result) return MonitorPluginPtr();
-       return plugin;
-   }
-
-};
-
-void ExampleMonitorPlugin::create()
-{
-    static OnChangePluginCreatorPtr plugin;
-    static Mutex mutex;
-    Lock xx(mutex);
-    if(plugin==NULL) {
-        plugin = OnChangePluginCreatorPtr(new OnChangePluginCreator());
-        MonitorPluginManager::get()->addPlugin(pluginName,plugin);
-    }
-}
-
- - -
- - diff --git a/documentation/pvDataCPP_20141110.html b/documentation/pvDataCPP_20141110.html deleted file mode 100644 index dc7e2ea..0000000 --- a/documentation/pvDataCPP_20141110.html +++ /dev/null @@ -1,5478 +0,0 @@ - - - - - - EPICS pvDataCPP - - - - - - - - -
-

EPICS pvDataCPP

- - -

EPICS v4 Working Group, Working Draft, 10-Nov-2014

- -
-
Latest version:
-
pvDataCPP.html -
-
This version:
-
pvDataCPP_20141110.html -
-
Previous version:
-
pvDataCPP_20140723.html -
-
Editors:
-
Marty Kraimer, BNL
-
Michael Davidsaver, BNL
-
Matej Sekoranja, CosyLab
-
David Hickin, Diamond Light Source
-
- -

This product is made available subject to acceptance of the EPICS open source -license.

-
-
- -

Abstract

- -

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 -

- - -

Status of this Document

- -

This is the 10-Nov-2014 version of the C++ implementation of pvData. -

- -

RELEASE_NOTES.md provides changes since the last release. -TODO.md describes things to do before the next release. -

- - - -
-

Table of Contents

-
-
- -

Introduction

- -

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:

-
-
Introduction
-
A brief description of pvData.
-
PVData Meta Language
-
A language used to describe data.
-
- -

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:

-
-
src/pv
-
This subdirectory contains all the public interfaces that describe pvData. - The section from Namespace and Memory Management - through Conversion discuss these interfaces. -
-
src/property
-
This section has support for managing "standard" fields. -
-
src/misc
-
This section has support for facilities required by implementation code.
-
src/copy and src/monitor
-
These sections provide pvData support for implementing pvAccess providers.
-
- -

Examples

-

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:

-
-
fieldCreate
-
This creates instances of introspection objects. - It also provides fieldBuilder, which provides an easier way to create introspection objects. -
-
pvDataCreate
-
This creates instances of data objects. -
-
standardField
-
This provides support for introspection objects for standard fields, - Standard fields are alarm, timeStamp, display, enumerated structure, and value alarm. -
-
standardPVField
-
This provides support for data objects for standard fields, -
-
- - -

Introspection Examples

-

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.

-

Three ways to create a structure

-

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
-
-

enumerated structure

-

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
-
- -

union example

-

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
-
- -

union array example

-

The following:

-
-    UnionArrayConstPtr unionArray = fieldCreate->createUnionArray(
-        fieldCreate->createVariantUnion());
-    cout << *unionArray << "\n\n";
-
-

Produces

-
-any[]
-any
-0x607188
-
-

power supply

-

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
-
-

Data Examples

-

The examples all produce a top level structure.

-

scalar example

-
-    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
-
-

array example

-
-    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
-
-

enumerated example

-
-    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
-
-

power supply example

-
-    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
-
-

union example

-
-    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
-
- -

variant union example

-
-    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
-
- -

big union example

-
-    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
-
- -

Namespace and Memory Management

- -

Namespace

- -

All code in project pvDataCPP appears in namespace:

-
namespace epics { namespace pvData {
-     // ...
-}}
- -

Memory Management

- -

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:

-
-
Ptr
-
When Ptr appears it stands for std::tr1::shared_ptr. -
-
-

For example:

-
-typedef PVScalarValue<boolean> PVBoolean;
-typedef std::tr1::shared_ptr<PVBoolean> PVBooleanPtr;
-
- -

src/pv

- -

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:

-
-
interface
-
The documentation uses the word interface. - This is an analogy with how Java defines interface. - C++ does not have interfaces but directory pv defines classes - with public members that are similar to the Java interfaces. Most of the - implementation is in factory.
-
Naming Conventions
-
The naming conventions for variables, methods, and classes follow the - Java conventions, i. e. class name begin with an upper case letter, - variables and methods begin with a lower case letter.
-
- -

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:

-
-
pvType.h
-
C++ definitions for primitive types.
-
pvIntrospect.h
-
A complete description of the introspection interfaces.
-
pvData.h
-
A complete description of the data interfaces.
-
convert.h
-
A facility that converts between data fields.
-
pvSubArrayCopy.h
-
This provides a facility that performs array coping between - arrays that have the same type.
-
standardField.h
-
Provides access to introspection interfaces for standard structures - like timeStamp, alarm, etc.
-
standardPVField.h
-
Creates data interfaces for standard data structures like timeStamp, - alarm, etc.
-
- -

pvType.h

- -

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

-
-
boolean
-
A c++ bool has the semantics required for boolean. Only the name is - different. C++ code can use either bool or boolean.
-
int8,...,uint64
-
Integers present a problem because short, int, and long are C++ - reserved words but do not have a well defined number of bits. Thus for - C++ the definitions above are used in C++ code. The above definitions - have worked on all C++ implementations tested at present. If they break - in a future implementation they should be changes via "#ifdef" - preprocessor statements.
-
std::string
-
pvData requires that a string be an immutable string that is transferred - over the network as a UTF8 encoded string. Since std::string implements - copy on write semantics, it can be used for support for immutable - strings. It can also be serialized/deserialized as a UTF8 encoded string. - Note that std::string is treated like a primitive type.
-
StringArray definitions
-
typedefs are provided for an array of std::strings, - which is a std::vector<std::string>. - This is used by introspection. -
-
-

TBD

-
-
boolean
-
Question for Michael. Why isn't the definition of boolean just - 
-typedef uint8_t boolean;
-
-
-
printer.h
-
Not documented. Is this needed? Nothing currently uses it.
-
- -

pvIntrospect.h

- -

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.

- -

Type Description

- -

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:

-
-
scalar
-
A scalar of one of the scalar types.
-
scalarArray
-
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 types can be different.
-
structureArray
-
An array where each element is a structure. Each element has the same - structure introspection interface.
-
union_t
-
This is like a structure that has a single subfield. - The type for the subfield can either be any type, which is called a variant union, - of can be one of a specified set of types. - In the data interfaces the type can be changed dynamically. -'
-
unionArray
-
An array where each element is a union. Each element has the same - union introspection interface.
-
- -

ScalarType is one of the following:

-
-
pvBoolean
-
Has the value false or true.
-
pvByte
-
A signed 8 bit integer.
-
pvShort
-
A signed 16 bit integer.
-
pvInt
-
A signed 32 bit integer.
-
pvLong
-
A signed 64 bit integer.
-
pvUByte
-
An unsigned 8 bit integer.
-
pvUShort
-
An unsigned 16 bit integer.
-
pvUInt
-
An unsigned 32 bit integer.
-
pvULong
-
An unsigned 64 bit integer.
-
pvFloat
-
A IEEE float.
-
pvDouble
-
A IEEE double,
-
pvString
-
An immutable string.
-
- -

TypeFunction is a set of convenience methods for Type

-
-
name
-
Returns the name of the type.
-
- -

ScalarTypeFunction is a set of convenience methods for ScalarType

-
-
isInteger
-
Is the scalarType an integer type, i.e. one of pvByte,...pvULong.
-
isUInteger
-
Is the scalarType an unsigned integer type, i.e. one of - pvUByte,...pvULong
-
isNumeric
-
Is the scalarType numeric, i.e. pvByte,...,pvDouble.
-
isPrimitive
-
Is the scalarType primitive, i.e. not pvString
-
name
-
Returns the name of the scalarType.
-
getScalarType
-
Given a string of the form std::string("boolean"),...,std::string("string") - return the scalarType.
-
elementSize
-
Returns the size in bytes of an instance of the scalarType.
-
- -

Introspection Description

- -

This section describes the reflection interfaces which provide the -following:

-
-
Field
-
A field: -
    -
  • Has a Type.
    • -
  • Can be converted to a string.
    • -
  • Can be shared. A reference count is kept. When it becomes 0 the - instance is automatically deleted.
    • -
-
-
Scalar
-
A scalar has a scalarType
-
ScalarArray
-
The element type is a scalarType
-
Structure
-
Has fields that can be any of the supported types.
-
StructureArray
-
The field holds an array of structures. Each element has the same - Structure introspection interface. A pvAccess client can only get/put - entire PVStructure elements NOT subfields of array elements.
-
Union
-
- This has two flavors: a variant union or a union of a fixed set - of types. A PVUnion will have a single subfield. - If the union introspection interface is a variant union then - the single field can be of any type and has the name any. - If the union is not a variant type then the type can be one of - a fixed set of types and a name associated with the type. - The union introspection interface has a field array and a string - array that has the fixed set of types and associated names. -
-
UnionArray
-
- This is an array of unions. A PVUnionArray is an array - of PVUnions. Each element has the same introspection interface - but the subfield of each element can have a different type. -
-
FieldBuilder
-
This is a convenience interface that makes it easier to create - top introspection interfaces. -
-
FieldCreate
-
This is an interface that provides methods to create introspection - interfaces. A factory is provides to create FieldCreate.
-
getFieldCreate
-
Gets a pointer to the single instance of FieldCreate.
-
-

Field,Scalar,ScalarArray,Structure,StructureArray,Union,UnionArray

-
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);
-    
-};
-
-
-
Constructors
-
Note that all constructors are protected or private. The only way to - create instances is via fieldBuilder or fieldCreate. The implementation manages all - storage via shared pointers.
-
dump
-
Many classes provide this. This is a stream method that prints using - the metadata syntax described in pvDataJava.html.
-
- -

Field

-
-
getType
-
Get the field type.
-
getID
-
Get an ID for this introspection interface
-
- -

Scalar

-
-
getScalarType
-
Get that scalar type.
-
getID
-
For each scalarType there is one instance of Scalar. The ID for each is - the metadata name for the type, i. e. one of "boolean" , ... , "string". -
-
- -

ScalarArray

-
-
getElementType
-
Get the element type.
-
getID
-
For each elemnetType there is one instance of ScalarArray. The ID for - each is the metadata name for the type, i. e. one of "boolean[]" , ... , - "string[]".
-
- -

StructureArray

-
-
getStructure
-
Get the introspection interface that each element shares,
-
getID
-
This returns the ID[] where ID is the value returned by - structure->getID().
-
-` -

UnionArray

-
-
getUnion
-
Get the union interface for each element.
-
- -

Structure

-
-
getNumberFields
-
Get the number of immediate subfields.
-
getField
-
Given a name or an index get the introspection interface for the - field.
-
getFieldIndex
-
Given a name get the index, within the array returned by the next - method, of the field.
-
getFields
-
Get the array of introspection interfaces for the field,
-
getFieldNames
-
Get the array of field names for the subfields.
-
getFieldName
-
Get the field name for the specified index.
-
-

Union

-
-
getNumberFields
-
Get the number of possible field types. - Both getFields and getFieldNames will return an array with getNumberFields elements. - A value of 0 is returned for invariant arrays. -
-
getField
-
Given a name or an index the type is returned. - NULL is returned if not found. -
-
getFieldIndex
-
Get the index for name. -1 is returned if not found.
-
getFields
-
Get the array of types.
-
getFieldNames
-
Get the array of names.
-
getFieldName
-
Get the name for the specified index.
-
isVariant
-
returns true if this is variant array and false otherwise.
-
-

fieldBuilder and createField

-
-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();
-
- -

FieldBuilder

-

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. -

-
-
setID
-
This sets an ID for the field, which is the name for the field when it is a subfield. -
-
add
-
- Add a scalar field. -
-
addBoundedString
-
- Add a scalar field that is a string that has a maximum size. -
-
addArray
-
- Add an array field. There are two methods: one to create a scalaArray - and one to create scalarArray, unionArray, or structureArray. -
-
addFixedArray
-
- Add a fixed size scalarArray field. -
-
addBoundedArray
-
- Add a bounded scalarArray field. -
-
createStructure
-
- Create a structure from the fields that are currently present. -
-
createUnion
-
- Create a union from the fields that are currently present. -
-
addNestedStructure
-
- Add a nested structure. This is followed by an arbitrary number of adds - followed by a an endNested. -
-
addNestedUnion
-
- Add a nested union. This is followed by an arbitrary number of adds - followed by a an endNested. -
-
addNestedStructureArray
-
- Add a nested structure array. This is followed by an arbitrary number of adds - followed by a an endNested. -
-
addNestedUnionArray
-
- Add a nested union array. This is followed by an arbitrary number of adds - followed by a an endNested. -
-
endNested
-
- End current nested structure or union. -
-
-

Examples of using fieldBuilder were given earlier in this manual.

-

FieldCreate

-
-
getFieldCreate
-
Get the single instance of FieldCreate.
-
createFieldBuilder
-
Create an instance of a FieldBuilder.
-
createScalar
-
Create a scalar introspection instance.
-
createBoundedString
-
create a scalar introspection instance for a bounded string.
-
createScalarArray
-
Create a scalar array introspection instance.
-
createFixedScalarArray
-
Create a scalar array introspection instance.
-
createBoundedScalarArray
-
Create a scalar array introspection instance.
-
createStructure
-
Create a structure introspection instance. Three methods are provided. - The first creates an empty structure, i. e. a structure with no fields. - The other two are similar. - The only difference is that one provides an ID and the other does - not. The one without will result in ID structure.
-
createStructureArray
-
Ceate a structure array introspection instance. - All elements will have the same introspection interface. -
-
createUnion
-
Create a union. There are two methods. - Each has arguments for an array of types and an array of names. - One method has an id. The other results in id = union. -
-
createVariantUnion
-
- Create a variant union. The id will be any. -
-
createUnionArray
-
Create a union array. punion is the introspection interface - for each element.
-
createVariantUnionArray
-
Create a union array where each element is a variant union.
-
createStructureArray
-
Create a structure array introspection instance.
-
appendField
-
Create a new structure that is like an existing structure but has - an extra field appended to it. -
-
appendFields
-
Create a new structure that is like an existing structure but has - extra fields appended to it. -
-
deserialize
-
Deserialize from given byte buffer.
-
- -

standardField.h

- -

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();
- ...
-};
-
-
scalar
-
Create a scalar with the specified scalar type and name. A structure - will be created with the first element being a scalar with the specified - scalar type and name value. The other fields in the structure will be the - corresponding property structures.
-
regUnion
-
A structure - will be created with the first element being a union with the specified - scalar type and name value. The other fields in the structure will be the - corresponding property structures.
-
variant`Union
-
Create a variant union. A structure - will be created with the first element being a union with the specified - scalar type and name value. The other fields in the structure will be the - corresponding property structures.
-
scalarArray
-
Create a scalarArray with each element having the specified scalar type - and name. A structure will be created with the first element being a - scalarArray with name value. The other fields in the structure will be - the corresponding property structures.
-
structureArray
-
Create a structureArray with the specified structure interface and - name. A structure will be created with the first element being a - structureArray with the specified structure interface and name value. The - other fields in the structure will be the corresponding property - structures.
-
unionArray
-
Create a unionArray with the specified union interface and - name. A structure will be created with the first element being a - unionArray with the specified structure interface and name value. The - other fields in the structure will be the corresponding property - structures.
-
structure
-
Create a structure with the specified name and fields specified by - numFields and fields. A structure will be created with the first element - being a structure with the name value and fields specified by numFields - and fields. The other fields in the structure will be the corresponding - property structures.
-
enumerated
-
Create a structure with the specified name and fields for an enumerated - structure. If properties are specified then a structure will be created - with the first element being a structure with the name value and fields - for an enumerated structure. The other fields in the structure will be - the corresponding property structures.
-
alarm
-
timeStamp
-
display
-
control
-
booleanAlarm
-
byteAlarm
-
shortAlarm
-
intAlarm
-
longAlarm
-
floatAlarm
-
doubleAlarm
-
enumeratedAlarm
-
The above provide introspection interfaces for standard properties. See - the section on Properties for a description of how these are defined.
-
-

pvData.h

- -

This section describes pvData.h This file is quite big so rather than -showing the entire file, it will be described in parts.

- -

typedefs

- -

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

- -

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:

-
-
~PVField
-
Destructor. Since shared pointers are used it should never be called by - user code.
-
getFieldName
-
Get the field name. If the field is a top level structure the field - name will be an empty string.
-
getFullName
-
Fully expand the name of this field using the - names of its parent fields with a dot '.' separating - each name. -
-
getFieldOffset
-
Get offset of the PVField field within top level structure. Every field - within the PVStructure has a unique offset. The top level structure has - an offset of 0. The first field within the structure has offset equal to - 1. The other offsets are determined by recursively traversing each - structure of the tree.
-
getNextFieldOffset
-
Get the next offset. If the field is a scalar or array field then this - is just offset + 1. If the field is a structure it is the offset of the - next field after this structure. Thus (nextOffset - offset) is always - equal to the total number of fields within the field.
-
getNumberFields
-
Get the total number of fields in this field. This is nextFieldOffset - - fieldOffset.
-
isImmutable
-
Is the field immutable?
-
setImmutable
-
Make the field immutable. Once a field is immutable it can never be - changed since there is no method to again make it mutable. This is an - important design decision since it allows immutable array fields to share - the internal primitive data array.
-
getField
-
Get the reflection interface for the data.
-
getParent
-
Get the interface for the parent or null if this is the top level - PVStructure.
-
postPut
-
If a postHandler is registered it is called otherwise no action is - taken.
- NOTE: The implementation of the various data interfaces automatically - call postPut when a field is changed. However this is not true - for a subField of a PVUnion, PVUnionArray, or PVStructureArray. - If a subField of any of these is changed then the code that is making - the modification must call postPut for the PVUnion, PVUnionArray, or PVStructureArray - field. Note also that it is not a good idea to modify a subfield of a PVUnionArray - or a PVStructureArray since it violates the idea of Copy On Write for arrays. -
-
setPostHandler
-
Set the postHandler for the record. Only a single handler can be - registered. - PostHandler is a class that must be implemented by any code that calls setPostHandler. - It's single virtual method. postPut is called whenever PVField::postPut is called. -
-
equals
-
Compare this field with another field. The result will be true only if - the fields have exactly the same field types and if the data values are - equal.
-
dumpValue
-
Method for streams I/O.
-
- -

PVScalar

- -

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

-
-
getScalar
-
Get the introspection interface for the PVScalar.
-
getAs
-
Convert and return the scalar value in the requested type. - Result type is determined from the function template argument - which must be one of the ScalarType enums. - For example: -
-uint32 val = pv->getAs<pvInt>();
-
-
- -
- -

PVScalarValue

- -

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

-
-
get
-
Get the value stored in the object.
-
put
-
Change the value stored in the object.
-
dumpValue
-
ostream method.
-
operator>>=
-
get operator. For example: -
-double value;
-PVDoublePtr pvDouble;
-...
-pvDouble>>=value;
-
-
-
operator<<=
-
put operator. For example: -
-double value;
-PVDoublePtr pvDouble;
-...
-pvDouble<<=value;
-
-
-
getAs
-
Convert and return the scalar value in the requested type. - Result type is determined from the function template argument - which must be one of the ScalarType enums. - For example: -
-int32 val = pv->getAs<pvInt>>();
-
-
-
putFrom
-
Convert the scalar value in the requested type - and put the value into this PVScalarValue. - The source type is determined from the function template argument - which must be one of the ScalarType enums. - For example: -
-int32 val;
-pv->putFrom<pvInt>(val);
-
- -
-
-

PVUnion

-

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;
-};
-
-
-
getUnion
-
Get the introspection interface.
-
get
-
Get the current field. A template version does the conversion. - NULL is returned if no field is selected or if the caller -' asks for the wrong type. -
-
select
-
Select and get the field by index or name. - A templated version does the conversion. - If the index is out of bounds or the name is not valid this methods throws an exception. - The method set should be used for variant unions rather than select. -
-
getSelectedIndex
-
Get the index of the currently selected field.
-
getSelectedFieldName
-
Get the name of the currently selected field.
-
set
-
Set the field to the argument. If invalid type an exception is thrown. - This should always work for a variant union. -
-
- -

PVArray

- -

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;
- ...
-};
-
-
getArray
-
Get the introspection interface.
-
setImmutable
-
Set the data immutable. Note that this is permanent since there is no - methods to make it mutable.
-
getLength
-
Get the current length. This is less than or equal to the capacity.
-
setLength
-
Set the length. If the PVField is not mutable then an exception is - thrown. If this is greater than the capacity setCapacity is called.
-
getCapacity
-
Get the capacity, i.e. this is the size of the underlying data - array.
-
setCapacity
-
Set the capacity. The semantics are implementation dependent but - typical semantics are as follows: If the capacity is not mutable an - exception is thrown. A new data array is created and data is copied from - the old array to the new array.
-
isCapacityMutable
-
Is the capacity mutable
-
setCapacityMutable
-
Specify if the capacity can be changed.
-
setCapacity
-
Set the capacity.
-
dumpValue
-
ostream method
-
- - -

PVScalarArray

- -

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

-
-
getScalarArray
-
Get the introspection interface.
-
getAs
-
Fetch the current value and convert to the requested type. - A copy is made if the requested type does not match the element type. - If the types do match then no copy is made. -
-
putFrom
-
Assign the given value after conversion. - A copy and element-wise conversion is performed unless the element type - of the PVScalarArray matches the type of the provided data. - If the types do match then a new reference to the provided data is kept. -
-
assign
-
Assign the given PVScalarArray's value. - A copy and element-wise conversion is performed unless the element type - of the PVScalarArray matches the type of the provided data. - If the types do match then a new reference to the provided data is kept. -
-
- -

PVStructure

- -

The interface for a structure is:

-
class PVStructure : public PVField,public BitSetSerializable {
-public:
-    POINTER_DEFINITIONS(PVStructure);
-    virtual ~PVStructure();
-    typedef PVStructure & reference;
-    typedef const PVStructure & const_reference;
-
-    virtual void setImmutable();
-    StructureConstPtr getStructure() const;
-    const PVFieldPtrArray & getPVFields() const;
-    PVFieldPtr getSubField(std::string const &fieldName) const;
-
-    template<typename PVT>
-    std::tr1::shared_ptr<PVT> getSubField(std::string const &fieldName) const
-
-    PVFieldPtr getSubField(std::size_t fieldOffset) const;
-
-    template<typename PVT>
-    std::tr1::shared_ptr<PVT> getSubField(std::size_t fieldOffset) const
-
-    virtual void serialize(
-        ByteBuffer *pbuffer,SerializableControl *pflusher) const ;
-    virtual void deserialize(
-        ByteBuffer *pbuffer,DeserializableControl *pflusher);
-    virtual void serialize(ByteBuffer *pbuffer,
-        SerializableControl *pflusher,BitSet *pbitSet) const;
-    virtual void deserialize(ByteBuffer *pbuffer,
-        DeserializableControl*pflusher,BitSet *pbitSet);
-    PVStructure(StructureConstPtr const & structure);
-    PVStructure(StructureConstPtr const & structure,PVFieldPtrArray const & pvFields);
-    virtual std::ostream& dumpValue(std::ostream& o) const;
-};
- -

where

-
-
getStructure
-
Get the introspection interface for the structure.
-
getPVFields
-
Returns the array of subfields. The set of subfields must all have - different field names.
-
getSubField(std::string fieldName)
-
- Get a subField of a field.d - A non-null result is - returned if fieldName is a field of the PVStructure. The fieldName can be - of the form name.name... - If the field does not exist then a Ptr to a NULL value is returned - without any error message being generated. -
- Note The template version replaces getBooleanField, etc.
-
-
getSubField(int fieldOffset)
-
Get the field located a fieldOffset, where fieldOffset is relative to - the top level structure. This returns null if the specified field is not - located within this PVStructure. -
- Note The template version replaces getBooleanField, etc.
-
-
dumpValue
-
Method for streams I/O.
-
- - -

PVValueArray

- -

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

-
-
getArray
-
Get the introspection interface.
-
dumpValue
-
Method for streams I/O.
-
view
-
Fetch a read-only view of the current array data.
-
swap
-
- Callers must ensure that postPut() is called after the last swap() operation. - Before you call this directly, consider using the reuse(), or replace() methods. -
-
replace
-
Discard current contents and replaced with the provided.
-
reuse
-
Remove and return the current array data or an unique copy if shared.
-
-

TBD

-
-
Check for completeness
-
Michael should check that PVScalarArray and PVValueArray - have the correct set of methods and that the descriptions are correct.
-
- -

PVStructureArray

- -

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

-
-
getStructureArray
-
Get the introspection interface shared by each element.
-
compress
-
This moves all null elements and then changes the array capacity. When - done there are no null elements.
-
- -

The other methods are similar to the methods for other array types. - See PVArray above for details.

- -

PVUnionArray

-

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

-
-
getUnionArray
-
Get the introspection interface shared by each element.
-
compress
-
This moves all null elements and then changes the array capacity. When - done there are no null elements.
-
- -

The other methods are similar to the methods for other array types. - See PVArray above for details.

- -

PVDataCreate

- -

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

-
-
getPVDataCreate
-
The returns the PVDataCreate implementation, which is a singleton.
-
createPVField
-
The PVField is created reusing the Field interface. Two methods are - provided. Each calls the corresponding createPVScalar, createPVArray, or - createPVStructure depending in the type of the last argument.
-
createPVScalar
-
Creates an instance of a PVScalar. Four versions are supplied. The - first is passed an introspection interface. - The second provides the scalarType. - The third provides a PVScalar to clone. - The last is a template version. PVAT must be a valid type. - For example: -
-PVDoublePtr pvDouble = getPVDataCreate()->createPVScalar<PVDouble>();
-
-
-
createPVStructure
-
Create an instance of a PVStructure. - Three methods are provided. - The first uses an array of field names and an array of PVFields to initialize the subfields. - The second initializes the subfields by cloning the fields contained in - structToClone. The newly created subfields will have the same values as the original. - If structToClone is null then the new structure is initialized to have 0 subfields. - The third method uses a previously created structure introspection interface. -
-
createPVUnion
-
Create an instance of a PVUnion. Two methods are provided. - The first uses a previously created union introspection interface. - The second clones an existing PVUnion. -
-
createPVVariantUnion
-
Creates an instance of a variant PVUnion. - This is a union which has a single field which can be any pvData supported type, -
-
createPVScalarArray
-
Create an instance of a PVArray. Four versions are supplied. - The first is passed an introspection interface. - The second provides the elementType. - The third provides a PVScalarArray to clone. - The last is a template version. PVAT must be a valid type. - For example: -
-PVDoubleArrayPtr pvDoubleArray = getPVDataCreate()->createPVScalarArray<PVDoubleArray>();
-
-
-
createPVStructureArray
-
Create a PVStructureArray. - Two versions are provided. - The first is passed a StructureArrayConstPtr. - The second is passed a StructureConstPtr which is used to create a StructureArrayConstPtr. - The argument provides the Structure interface for ALL elements of the PVStructureArray. -
-
createPVUnionArray
-
Create a PVUnionArray. - Two versions are provided. - The first is passed a UnionArrayConstPtr. - The second is passed a UnionConstPtr which is used to create a UnionArrayConstPtr. - The argument provides the Union interface for ALL elements of the PVUnionArray. -
-
createPVVariantUnionArray
-
Create a PVUnionArray. - No arguments are needed. -
-
- -

standardPVField.h

- -

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();
-
- -

Conversion

-

There are two facilities for converting between two different PVData -objects:

-
-
Convert
-
This preforms all conversions except for coping subarrays.
-
PVSubArray
-
This copies a subarray from one PVArray to another. - The two arrays must have the same element type.
-
-

convert.h

- -

NOTE about copying immutable array fields. If an entire immutable array -field is copied to another array that has the same elementType, both offsets -are 0, and the length is the length of the source array, then the shareData -method of the target array is called and the target array is set immutable. -Thus the source and target share the same primitive array.

- -

This section describes the supported conversions between data types.

- -
-bool operator==(PVField&, PVField&);
-
-static bool operator!=(PVField& a, PVField& b);
-
-bool operator==(const Field&, const Field&);
-bool operator==(const Scalar&, const Scalar&);
-bool operator==(const ScalarArray&, const ScalarArray&);
-bool operator==(const Structure&, const Structure&);
-bool operator==(const StructureArray&, const StructureArray&);
-bool operator==(const Union&, const Union&);
-bool operator==(const UnionArray&, const UnionArray&);
-
-static inline bool operator!=(const Field& a, const Field& b);
-static inline bool operator!=(const Scalar& a, const Scalar& b);
-static inline bool operator!=(const ScalarArray& a, const ScalarArray& b);
-static inline bool operator!=(const Structure& a, const Structure& b);
-static inline bool operator!=(const StructureArray& a, const StructureArray& b);
-static inline bool operator!=(const Union& a, const Union& b);
-static inline bool operator!=(const UnionArray& a, const UnionArray& b);
-
-class Convert;
-typedef std::tr1::shared_ptr<Convert> ConvertPtr;
-
-class Convert {
-public:
-    static ConvertPtr getConvert();
-    ~Convert();
-    void getFullName(std::string * buf,PVFieldPtr const & pvField);
-    bool equals(PVFieldPtr const &a,PVFieldPtr const &b);
-    bool equals(PVField &a,PVField &b);
-    void getString(std::string * buf,PVFieldPtr const & pvField,int indentLevel);
-    void getString(std::string * buf,PVFieldPtr const & pvField);
-    void getString(std::string * buf,PVField const * pvField,int indentLevel);
-    void getString(std::string * buf,PVField const * pvField);
-    std::size_t fromString(
-        PVStructurePtr const &pv,
-        StringArray const & from,
-        std::size_t fromStartIndex = 0);
-    void fromString(PVScalarPtr const & pv, std::string const & from);
-    std::size_t fromString(PVScalarArrayPtr const & pv, std::string const &from);
-    std::size_t fromStringArray(
-        PVScalarArrayPtr const & pv,
-        std::size_t offset, std::size_t length,
-        StringArray const & from,
-        std::size_t fromOffset);
-    std::size_t toStringArray(PVScalarArrayPtr const & pv,
-        std::size_t offset,
-        std::size_t length,
-        StringArray & to,
-        std::size_t toOffset);
-    bool isCopyCompatible(FieldConstPtr const & from, FieldConstPtr const & to);
-    void copy(PVFieldPtr const & from, PVFieldPtr const & to);
-    bool isCopyScalarCompatible(
-        ScalarConstPtr const & from,
-        ScalarConstPtr const & to);
-    void copyScalar(PVScalarPtr const & from, PVScalarPtr const & to);
-    bool isCopyScalarArrayCompatible(
-        ScalarArrayConstPtr const & from,
-        ScalarArrayConstPtr const & to);
-    bool isCopyStructureCompatible(
-        StructureConstPtr const & from, StructureConstPtr const & to);
-    void copyStructure(PVStructurePtr const & from, PVStructurePtr const & to);
-    bool isCopyStructureArrayCompatible(
-        StructureArrayConstPtr const & from, StructureArrayConstPtr const & to);
-    void copyStructureArray(
-        PVStructureArrayPtr const & from, PVStructureArrayPtr const & to);
-    bool isCopyUnionCompatible(
-        UnionConstPtr const & from, UnionConstPtr const & to);
-    void copyUnion(
-        PVUnionPtr const & from, PVUnionPtr const & to);
-    bool isCopyUnionArrayCompatible(
-        UnionArrayConstPtr const & from, UnionArrayConstPtr const & to);
-    void copyUnionArray(
-        PVUnionArrayPtr const & from, PVUnionArrayPtr const & to);
-    int8 toByte(PVScalarPtr const & pv);
-    int16 toShort(PVScalarPtr const & pv);
-    int32 toInt(PVScalarPtr const & pv);
-    int64 toLong(PVScalarPtr const & pv);
-    uint8 toUByte(PVScalarPtr const & pv);
-    uint16 toUShort(PVScalarPtr const & pv);
-    uint32 toUInt(PVScalarPtr const & pv);
-    uint64 toULong(PVScalarPtr const & pv);
-    float toFloat(PVScalarPtr const & pv);
-    double toDouble(PVScalarPtr const & pv);
-    std::string toString(PVScalarPtr const & pv);
-    void fromByte(PVScalarPtr const & pv,int8 from);
-    void fromShort(PVScalarPtr const & pv,int16 from);
-    void fromInt(PVScalarPtr const & pv, int32 from);
-    void fromLong(PVScalarPtr const & pv, int64 from);
-    void fromUByte(PVScalarPtr const & pv,uint8 from);
-    void fromUShort(PVScalarPtr const & pv,uint16 from);
-    void fromUInt(PVScalarPtr const & pv, uint32 from);
-    void fromULong(PVScalarPtr const & pv, uint64 from);
-    void fromFloat(PVScalarPtr const & pv, float from);
-    void fromDouble(PVScalarPtr const & pv, double from);
-    void newLine(std::string * buf, int indentLevel);
- ...
-}
-
-extern ConvertPtr getConvert();
-
-

newLine is a convenience method for code that implements toString It -generates a newline and inserts blanks at the beginning of the newline.

- -

pvSubArrayCopy.h

-
-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:

-
-
from
-
The source array.
-
fromOffset
-
The offset into the source array.
-
fromStride
-
The interval between source elements.
-
to
-
The destination array. The element type must be the same - as for the source array. If the element type is structure then - the introspection interface for the element types must be the same. -
-
toOffset
-
The offset into the destination array.
-
toStride
-
The interval between destination elements.
-
count
-
The number of elements to copy.
-
-

An exception is thrown if:

-
-
type mismatch
-
The element types for the source and destination differ.
-
immutable
-
The destination array is immutable.
-
capacity immutable
-
The destination array needs to have it's capacity extended - but the capacity is immutable.
-
- -

src/property

- -

Definition of Property

- -

-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
- -

Standard Properties

- -

The following field names have special meaning, i.e. support properties for -general purpose clients.

-
-
value
-
This is normally defined since most general purpose clients access this - field. All other fields in the structure support or describe the value - field. The type can any supported type but is usually one of the - following: -
-
scalar
-
Any of the scalar types.
-
scalarArray
-
An array with the elementType being a scalar type
-
enumerated structure
-
A structure that includes fields named index and choices. index - is an int that selects a choice. choices is an array of strings - that defines the complete set of choices.
-
other
-
Other structure or array types can also be defined if clients and - support code agree on the meaning. Some examples are: 1) A - structure defining a 2D matrix, 2) A structure defining an image, - 3) A structure that simulates a remote method, ...
-
-
-
timeStamp
-
The timeStamp. The type MUST be a timeStamp structure. Also if the - PVData structure does not have a timeStamp then a search up the parent - tree is made to find a timeStamp.
-
alarm
-
The alarm. The type MUST be an alarm structure.
-
display
-
A display structure as described below. It provides display - characteristics for the value field.
-
control
-
A control structure as described below. It provides control - characteristics for the value field.
-
history
-
Provides a history buffer for the value field. Note that currently - PVData does not define history support.
-
other
-
Other standard properties can be defined.
-
- -

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:

-
-
input
-
A field with support that changes the value field. This can be - anything. It can be a channel access link. It can obtain a value from - hardware. Etc.
-
valueAlarm
-
A field with support that looks for alarm conditions based on the - value.
-
output
-
A field with support that reads the current value and sends it - somewhere else. This can be anything. It can be a channel access link. It - can write a value to hardware. Etc.
-
- -

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. -

- -

Overview of Property Support

- -

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();
-     ...
-}
- -

timeStamp

- -

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:

-
-
timeStamp.h
-
Defines a time stamp independent of pvData, i.e. it is a generally - useful class for manipulating timeStamps.
-
pvTimeStamp.h
-
A class that can be attached to a time stamp pvData structure. It - provides get and set methods to get/set a TimeStamp as defined by - timeStamp.h
-
- -

timeStamp.h

- -

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

-
-
TimeStamp()
-
The default constructor. Both seconds and nanoseconds are set to 0.
-
TimeStamp(int64 secondsPastEpoch,int32 nanoseconds = 0)
-
A constructor that gives initial values to seconds and nanoseconds.
-
normalize
-
Adjust seconds and nanoseconds so that - 0<=nanoseconds<nanoSecPerSec.
-
fromTime_t
-
Set time from standard C time.
-
toTime_t
-
Convert timeStamp to standard C time.
-
getSecondsPastEpoch
-
Get the number of seconds since the epoch.
-
getEpicsSecondsPastEpoch
-
Get the number of EPICS seconds since the epoch. EPICS uses Jan 1, 1990 - 00:00:00 UTC as the epoch.
-
getNanoseconds
-
Get the number of nanoseconds. This is always normalized.
-
getUserTag
-
Get the userTag.
-
setUserTag
-
Set the userTag.
-
put(int64 secondsPastEpoch,int32 nanoseconds = 0)
-
Set the timeStamp value. If necessary it will be normalized.
-
put(int64 milliseconds)
-
Set the timeStamp with a value the is the number of milliSeconds since - the epoch.
-
getCurrent()
-
Set the timeStamp to the current time.
-
toSeconds()
-
Convert the timeStamp to a value that is the number of seconds since - the epocj
-
operator =
-
operator!=
-
operator<=
-
operator<
-
operator>=
-
operator>
-
Standard C++ operators.
-
diff
-
diff = a - b
-
getMilliseconds
-
Get the number of milliseconds since the epoch.
-
- -

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);
- -

pvTimeStamp.h

-
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

-
-
PVTimeStamp
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if a timeStamp - structure is found. It looks first at pvField itself and if is not an - appropriate pvData structure but the field name is value it looks up the - parent structure tree.
-
detach
-
Detach from the pvData structure.
-
isAttached
-
Is there an attachment to a timeStamp structure?
-
get
-
Copies data from the pvData structure to a TimeStamp. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from TimeStamp to the pvData structure. An exception is - thrown if not attached to a pvData structure.
-
- -

alarm

- -

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:

-
-
alarm.h
-
Defines an alarm independent of pvData, i.e. it is a generally useful - class for manipulating alarms.
-
pvAlarm.h
-
A class that can be attached to an alarm pvData structure. It provides - get and set methods to get/set alarm data as defined by alarm.h
-
- -

alarm.h

-
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:

-
-
getSeverity
-
Get the alarm severity corresponding to the integer value.
-
getSeverityNames
-
Get the array of severity choices.
-
- -

Alarm Status defines the possible choices for alarm status:

-
-
getStatus
-
Get the alarm status corresponding to the integer value.
-
getStatusNames
-
Get the array of status choices.
-
- -

Alarm has the methods:

-
-
Alarm
-
The constructor. It sets the severity to no alarm and the message to - "".
-
getMessage
-
Get the message.
-
setMessage
-
Set the message.
-
getSeverity
-
Get the severity.
-
setSeverity
-
Set the severity.
-
getStatus
-
Get the status.
-
setStatus
-
Set the status.
-
- -

pvAlarm.h

-
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

-
-
PVAlarm
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if it found an - appropriate pvData structure. It looks first a pvField itself and if is - not an appropriate pvData structure but the field name is value it looks - to see if the parent structure has an appropriate sub structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to an alarm structure?
-
get
-
Copies data from the pvData structure to an Alarm. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from Alarm to the pvData structure. An exception is thrown - if not attached to a pvData structure.
-
- -

control

- -

Control information is represented by the following structure

-
structure control
-    double limitLow
-    double limitHigh
-    double minStep
- -

Two header files are provided for manipulating control:

-
-
control.h
-
Defines control independent of pvData, i.e. it is a generally useful - class for manipulating control.
-
pvControl.h
-
A class that can be attached to an control pvData structure. It - provides get and set methods to get/set control data as defined by - control.h
-
- -

control.h

-
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

-
-
Control
-
The default constructor.
-
getLow
-
Get the low limit.
-
getHigh
-
Get the high limit.
-
setLow
-
Set the low limit.
-
setHigh
-
Set the high limit.
-
setMinStep
-
Set the minimum step size.
-
getMinStep
-
Get he minimum step size.
-
- -

pvControl.h

-
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

-
-
PVControl
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if it found an - appropriate pvData structure. It looks first a pvField itself and if is - not an appropriate pvData structure but the field name is value it looks - to see if the parent structure has an appropriate sub structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to a control structure?
-
get
-
Copies data from the pvData structure to a Control. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from Control to the pvData structure. An exception is - thrown if not attached to a pvData structure.
-
- -

display

- -

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:

-
-
display.h
-
Defines display independent of pvData, i.e. it is a generally useful - class for manipulating display.
-
pvDisplay.h
-
A class that can be attached to an display pvData structure. It - provides get and set methods to get/set display data as defined by - display.h
-
- -

display.h

-
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

-
-
Control
-
The default constructor.
-
getLow
-
Get the low limit.
-
getHigh
-
Get the high limit.
-
setLow
-
Set the low limit.
-
setHigh
-
Set the high limit.
-
getDescription
-
Get the description.
-
setDescription
-
Set the description.
-
getFormat
-
Get the format.
-
setFormat
-
Set the format.
-
getUnits
-
Get the units.
-
setUnits
-
Set the units.
-
- -

pvDisplay.h

-
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

-
-
PVDisplay
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if it found an - appropriate pvData structure. It looks first a pvField itself and if is - not an appropriate pvData structure but the field name is value it looks - to see if the parent structure has an appropriate sub structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to a display structure?
-
get
-
Copies data from the pvData structure to a Display. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from Display to the pvData structure. An exception is - thrown if not attached to a pvData structure.
-
- -

pvEnumerated.h

- -

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

-
-
PVEnumerated
-
The default constructor. Attach must be called before any get or set - method can be called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if pvField (is - not, is) an enumerated structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to an enumerated structure?
-
setIndex
-
Set the index field in the pvData structure. An exception is thrown if - not attached to a pvData structure.
-
getIndex
-
Get the index field in the pvData structure.
-
getChoice
-
Get the std::string value corresponding to the current index field in the - pvData structure. An exception is thrown if not attached to a pvData - structure.
-
choicesMutable
-
Can the choices be changed? Note that this is often true. An exception - is thrown if not attached to a pvData structure.
-
getChoices
-
Get the array of choices. An exception is thrown if not attached to a - pvData structure.
-
getNumberChoices
-
Get the number of choices. An exception is thrown if not attached to a - pvData structure.
-
setChoices
-
Change the choices. An exception is thrown if not attached to a pvData - structure.
-
- - -

src/factory

- -

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

- -

src/misc

- -

Overview

- -

This package provides utility code:

-
-
bitSet.h
-
An implementation of BitSet that can be serialized.
-
byteBuffer.h
-
Used to serialize objects.
-
destroyable.h
-
Provides method destroy.
-
epicsException.h
-
Exception with stack trace.
-
event.h
-
Signal and wait for an event.
-
executor.h
-
Provides a thread for executing commands.
-
localStaticLock.h
-
TBD Matej can You explain what this does?
-
lock.h
-
Support for locking and unlocking.
-
messageQueue.h
-
Support for queuing messages to give to requesters.
-
noDefaultMethods.h
-
When privately extended prevents compiler from implementing default - methods.
-
queue.h
-
A queue implementation that allows the latest queue element to continue - to be used when no free element is available.
-
requester.h
-
Allows messages to be sent to a requester.
-
serialize.h
-
Support for serializing objects.
-
serializeHelper.h
-
More support for serializing objects.
-
sharedPtr.h
-
Defines POINTER_DEFINITIONS.
-
sharedVector.h
-
Like std::vector except that std::shared_ptr is used for - the data array.
-
status.h
-
A way to pass status information to a client.
-
templateMeta.h
-
TBD Michael can You provide an explanation?
-
thread.h
-
Provides thread support.
-
timeFunction.h
-
Time how long a function call requires.
-
timer.h
-
An implementation of Timer that does not require an object to be - created for each timer request.
-
typeCast.h
-
TBD Michael can You provide an explanation?
-
- -

Note that directory testApp/misc has test code for all the classes in misc. -The test code also can be used as examples.

- -

bitSet.h

- -

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

-
-
BitSet()
-
Creates a bitSet of initial size 64 bits. All bits initially false.
-
BitSet(uint32 nbits)
-
Creates a bitSet with the initial of the specified number of bits. All - bits initially false.
-
~BitSet()
-
Destructor.
-
flip(uint32 bitIndex)
-
Flip the specified bit.
-
set(uint32 bitIndex)
-
Set the specified bit true.
-
clear(uint32 bitIndex)
-
Set the specified bit false.
-
set(uint32 bitIndex, bool value)
-
Set the specified bit to value.
-
get(uint32 bitIndex)
-
Return the state of the specified bit.
-
clear()
-
Set all bits to false.
-
nextSetBit(uint32 fromIndex)
-
Get the index of the next true bit beginning with the specified - bit.
-
nextClearBit(uint32 fromIndex)
-
Get the index of the next false bit beginning with the specified - bit.
-
isEmpty()
-
Return (false,true) if (at least one bit true, all bits are false)
-
cardinality()
-
Return the number of true bits.
-
size()
-
Returns the number of bits of space actually in use.
-
operator&=(const BitSet& set)
-
Performs a logical and of this target bit set with the argument bit - set. This bit set is modified so that each bit in it has the value true - if and only if it both initially had the value true and the corresponding - bit in the bit set argument also had the value.
-
operator|=(const BitSet& set)
-
Performs a logical or of this target bit set with the argument bit - set.
-
operator^=(const BitSet& set)
-
Performs a logical exclusive or of this target bit set with the - argument bit set.
-
operator=(const BitSet &set)
-
Assignment operator.
-
or_and(const BitSet& set1, const BitSet& set2)
-
Perform AND operation on set1 and set2, and then OR this bitSet with - the result.
-
operator==(const BitSet &set)
-
Does this bitSet have the same values as the argument.
-
operator!=(const BitSet &set)
-
Is this bitSet different than the argument.
-
virtual void serialize(ByteBuffer *buffer,SerializableControl *flusher) - const;
-
Serialize the bitSet
-
virtual void deserialize(ByteBuffer *buffer,DeserializableControl - *flusher);
-
Deserialize the bitSet.
-
- -

byteBuffer.h

- -

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();
- ...
-};
- -

destroyable.h

-
class Destroyable  {
-public:
-    POINTER_DEFINITIONS(Destroyable);
-    virtual void destroy() = 0;
-    virtual ~Destroyable() {};
-};
- -

epicsException.h

-
/*
- * 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.
- */
- -

event.h

- -

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

-
-
Event
-
The constructor. The initial value can be full or empty. The normal - first state is empty.
-
signal
-
The event becomes full. The current or next wait will complete.
-
wait
-
Wait until event is full or until timeout. The return value is - (false,true) if the wait completed because event (was not, was) full. A - false value normally means that that a timeout occurred. It is also - returned if an error occurs or because the event is being deleted.
-
tryWait
-
returns (false,true) if the event is (empty,full)
-
- -

executor.h

- -

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:

-
-
Executor
-
The constructor. A thread name and priority must be specified.
-
~Executor
-
The destructor. If any commands remain in the execute list they are not - called. All ExecutorNodes that have been created are deleted.
-
execute
-
Request that command be executed. If it is already on the run list - nothing is done.
-
- -

localStaticLock.h

-
-extern epics::pvData::Mutex& getLocalStaticInitMutex();
-
-static class MutexInitializer {
-  public:
-    MutexInitializer ();
-    ~MutexInitializer ();
-} localStaticMutexInitializer; // Note object here in the header.
-
-

TBD Matej will explain.

- -

lock.h

-
-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. -

- -

messageQueue.h

- -

Definitions

- -

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:

-
-
getMessage
-
The message.
-
getMessageType
-
The message type.
-
setMessageNull
-
Set the message to be a null string.
-
- -

A messageQueue is an interface with public methods:

-
-
MessageQueue
-
The constructor. The queue size must be specified.
-
~MessageQueue
-
The destructor.
-
put
-
Put a new message into the queue. False is returned if the queue was - full and true otherwise. If replaceLast is true then the last message is - replaced with this message.
-
get
-
Get the oldest queue element. If the queue is empty null is returned. - Before the next get can be issued release must be called.
-
release
-
Release the queue element returned by the last get.
-
isEmpty
-
Is the queue empty?
-
isFull
-
Is the queue full?
-
getClearOverrun
-
Get the number of times put has been called but no free element is - available.
-
- -

Look at miscTest/testMessageQueue.cpp for an example.

- -

noDefaultMethods.h

- -

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 &);
-    };
- -

queue.h

- -

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:

-
-
clear
-
Make the queue empty.
-
getNumberFree
-
Get the number of free elements in the queue.
-
capacity
-
Get the capacity, i.e. the maximum number of elements the queue can - hold.
-
getNumberFree
-
Get the number of free elements.
-
getNumberUsed
-
Get the number of elements used.
-
getFree
-
Get the next free element. Null is returned if no free elements are - available. If a non null value is returned then the element belongs to - the caller until setUsed is called.
-
setUsed
-
Set a queue element used. This must be the element returned by the last - call to getFree.
-
getUsed
-
Get the next used element of null if no more used elements are - available.
-
releaseUsed
-
Set a queue element free. This must be the element returned by the last - call to getUsed.
-
- -

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.h

- -

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

-
-
-
MessageType
-
Type of message.
-
messageTypeName
-
An array of strings of the message type names, i.e. - std::string("info"),std::string("warning"),std::string("error"),std::string("fatalError").
-
getRequesterName
-
Returns the requester name.
-
message
-
Gives a message to the requester.
-
- -

serialize.h

-
-    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;
-    };
- -

serializeHelper.h

- -

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

-
-
writeSize
-
Serialize the size.
-
readSize
-
Deserialize the size.
-
serializeString
-
Serialize a std::string.
-
serializeSubstring
-
Serialize a substring.
-
deserializeString
-
Deserialize a string.
-
- -

sharedPtr.h

-
-#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;
- -

sharedVector.h

-

-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:

-
-
Differences in behavior
-
- shared_vector models const-ness like shared_ptr. - An equivalent of 'const std::vector<E>' is - 'const shared_vector<const E>'. - However, it is also possible to have 'const shared_vector<E>' - analogous to 'E* const' and 'shared_vector<const E>>' - which is analogous to 'const E*'.i -
- Copying a shared_vector, by construction or assignment, does not copy - its contents. - Modifications to one such "copy" effect all - associated shared_vector instances. -
- std::vector::reserve(N) has no effect if N<=std::vector::capacity(). - However, like resize(), shared_vector<E>::reserve() has the side effect - of always calling make_unique(). -
-
Parts of std::vector interface not implemented
-
- Mutating methods insert(), erase(), shrink_to_fit(), emplace(), and emplace_back() are not implemented. -
- shared_vector does not model an allocator which is bound to the object. Therefore the get_allocator() method and the allocator_type typedef are not provided. -
- The assign() method and the related constructor are not implemented at this time. -
- The comparison operators are not implemented at this time. -
-
Parts not found in std::vector
-
- shared_vector has additional constructors from raw pointers and shared_ptr s. - The copy constructor and assignment operator allow implicit castings - from type 'shared_vector<T>' to 'shared_vector<const T>>'. - To facilitate safe modification the methods unique() and make_unique() are provided - The slice() method selects a sub-set of the shared_vector. - The low level accessors dataPtr(), dataOffset(), dataCount(), and dataTotal(). -
-
- - -
-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
-
Several flavors of constructor are provided. The most commonly used is: - 
-shared_vector(size_t c);
-
- This creates a shared_vector of the specified size/ -
-
max_size
-
The maximum size the C++ implementation allows, i.e., - the maximum possible capacity. - Note that units are number of elements not number of bytes. -
-
capacity
-
The current capacity.
-
reserve
-
Set array capacity.
-
resize
-
Grow or shrink array. - It the second argument is given it is the value to assign to - and new elements. -
-
make_unique
-
Ensure (by copying) that this shared_vector - is the sole owner of the data array. -
-
begin,...,rend
-
Standard iterators.
-
front
-
Return a reference to the first element.
-
back
-
Return a reference to the last element.
-
push_back
-
Add an element to the end of the array.
-
pop_back
-
Remove an element from the end of the array.
-
data
-
Return a pointer to the raw array.
-
operator[](size_t i)
-
Return a reference to the specified element.
-
at
-
Like the previous except that it throws a range-error if - the specified element is out of range.
-
operator=
-
Copy an existing shared_vector.
-
swap
-
Swap the contents of this vector with another.
-
clear
-
Clear contents.
-
unique
-
returns (true,false) if data (is not, is) shared.
-
size
-
Number of elements visible through this vector.
-
empty
-
Is the number of elements zero?
-
slice
-
Reduce the view of this shared_vector.
-
dataPtr
-
A read-only shared_ptr to the array.
-
dataOffset
-
Offset in the data array of first visible element.
-
dataCount
-
Number of visible elements between dataOffset and end of data.
-
dataTotal
-
The total number of elements between dataOffset and the end of data
-
-

TBD -Michael should decide if this is the correct set of methods to describe. -Also he should check for correct descriptions. -

- - -

status.h

- -

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:

-
-
StatusType
-
An enum for the status type.
-
getType
-
Get the statusType.
-
getMessage
-
Get a message explaining the error.
-
getStackDump
-
Get a stack dump.
-
- -

The StatusCreate methods are:

-
-
getStatusOK
-
Get a singleton that returns StatusType.OK and a null message and - stackDump.
-
createStatus
-
Create a new Status.
-
deserializeStatus
-
Use this method instead of Status.deserialize(), since this allows OK - status optimization.
-
-

templateMeta.h

-

TBD Michael will explain.

- -

thread.h

- -

ThreadPriority

-
enum ThreadPriority {
-    lowestPriority,
-    lowerPriority,
-    lowPriority,
-    middlePriority,
-    highPriority,
-    higherPriority,
-    highestPriority
-};
- -

Thread

-
-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:

-
-
Thread
-
The constructor. A thread name and priority must be specified. The run - methods of runnable is executed. When the run methods returns the thread - will no longer be active but the client code must still delete the - thread.
-
~Thread
-
The destructor. This is called as the result of: - 
    delete pthread;
-
-
- -

timeFunction.h

- -

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:

-
-
function
-
This is the function.
-
- -

TimeFunction has the methods:

-
-
TimeFunction
-
Constructor.
-
~TimeFunction
-
Destructor.
-
timeCall
-
Time how long it takes to execute the function. It starts by calling - the function one time. If it takes < 1 seconds to doubles the number - of times to call the function. It repeats this until it takes at least - one second to call it ntimes.
-
- -

timer.h

- -

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: -

-
-
callback
-
This is called when a timer expires. This is called with no locks held. - When called a delay timer is no longer on the queue but a periodic timer - is on a queue. Thus the callback for a delay timer can issue a new - schedule request but a periodic timer must not. Note the explanation of - TimerNode.cancel below.
-
timerStopped
-
Timer.stop was called when a timer request was queued. or if the timer - is stopped and a schedule request is made.
-
- -

In order to schedule a callback client code must allocate a TimerNode It can -be used to schedule multiple callbacks. It has the methods:

-
-
TimerNode
-
The constructor. User code must create a TimeNode in order to call a - schedule method.
-
~TimerNode
-
The destructor. This is called as a result of the client calling: - 
    delete timerNode;
-
-
cancel
-
This is called to cancel a timer request. If a callback has been - dequeued but the callback not called when cancel is called then a - callback may still happen. New schedule requests can be made after a - cancel request has been made.
-
isScheduled
-
Is the timerNode scheduled to be called.
-
- -

Timer has the methods:

-
-
Timer
-
The constructor.
-
~Timer
-
The destructor. The queue is emptied and TimerCallback.timerStopped is - called for each element of the queue.
-
scheduleAfterDelay
-
A request to schedule a callback after a delay specified in - seconds.
-
schedulePeriodic
-
Schedule a periodic callback.
-
-

typeCast.h

-

TBD Michael will explain.

- -

src/pvMisc

- -

bitSetUtil.h

- -

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:

-
-
compress
-
Compress the bits in a BitSet related to a structure.
- For each structure: -
    -
  1. If the bit for the structure is set then the bit for all subfields - of the structure are cleared.
    2. -
  2. If the bit for the structure is not set but all immediate subfields - have their bit set then the bit for the structure is set and the bits - for all subfields are cleared.
    3. -
- Note that this is a recursive algorithm. That is if every immediate - subfield has it's offset bit set then the bits for ALL fields that reside - in the structure will be cleared.
-
Channel Access can call this before sending data. It can then pass - entire structures if the structure offset bit is set.
-
- -

src/copy and src/monitor

-

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:

-
-
createRequest
-
- The Channel create methods in pvAccess all have an argument - PVStructure pvRequest.
- Given an ascii string createRequest creates a PVStructure that provides - a pvData representation of the information from the ascii string. - It is this structure that can be passed to the channel create methods.
- The information in a pvRequest selects an arbitrary subset of the - fields in a top level structure that resides in the server. - In addition options can be specified. Both global and field specific - options can be specified. -
-
pvCopy
-
This is a facility used by channel providers. - It provides client specific code that manages a copy of an arbitrary - subset of the fields in a top level structure that resides in the - provider. It also allows provider access to options specified - by the client. -
-
-Monitor provides: -
-
monitor
-
This is support code for channel providers that implement channel - monitor. It, together with the queue facility, provides support for - monitor queues. -
-
monitorPlugin
-
This is support for implementing monitor plugins. - A monitor plugin can be developed that has no knowledge - of pvAccess but only pvData. -
-
-

src/copy

-

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. -

- -

createRequest

-

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
-}
-
-

pvCopy

-

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  &copyPVStructure,
-        BitSetPtr const  &bitSet);
-     void updateCopySetBitSet(
-        PVStructurePtr const  &copyPVStructure,
-        BitSetPtr const  &bitSet);
-    void updateCopyFromBitSet(
-        PVStructurePtr const  &copyPVStructure,
-        BitSetPtr const  &bitSet);
-    void updateMaster(
-        PVStructurePtr const  &copyPVStructure,
-        BitSetPtr const  &bitSet);
-    PVStructurePtr getOptions(std::size_t fieldOffset);
-    std::string dump();
-...
-};
-
-where -
-
PVCopyTraverseMasterCallback::nextMasterPVField
-
- PVCopyTraverseMasterCallback is a callback which must - be implemented by the code that uses pvCopy, normally - the channel provider. It has the single method nextMasterPVField -
- nextMasterPVField is called for each field in the master - as a result of a call to traverseMaster. -
-
create
-
- This is the method for creating a PVCopy instance.
-
-
pvMaster
-
the top level structure managed by the server.
-
pvRequest
-
selects the set of subfields desired - and options for each field.
-
structureName
-
the name for the top level of any PVStructure created. -
-
-
-
getPVMaster
-
- Gets the top level structure from pvMaster. -
-
traverseMaster
-
- Traverse all fields of the top level structure of pvMaster. - For each field the callback is called. -
-
getStructure
-
- Get the introspection interface for a PVStructure for e copy. -
-
createPVStructure
-
Create a copy instance. - Monitors keep a queue of monitor elements. - Since each element needs a PVStructure, multiple top level structures - will be created. -
-
getCopyOffset
-
Given a field in pvMaster. - return the offset in copy for the same field. - A value of std::string::npos means that the copy does not have this field. - Two overloaded methods are provided. The first is called if - the field of master is not a structure. The second is for - subfields of a structure. -
-
getMasterPVField
-
- Given a offset in the copy get the corresponding field in pvMaster. -
-
initCopy
-
- Initialize the fields in copyPVStructure - by giving each field the value from the corresponding field in pvMaster. - bitSet will be set to show that all fields are changed. - This means that bit set will have the value {0}. -
-
updateCopySetBitSet
-
- Set all fields in copyPVStructure to the value of the corresponding field - in pvMaster. Each field that is changed has it's corresponding - bit set in bitSet. -
-
updateCopyFromBitSet
-
- For each set bit in bitSet set the field in copyPVStructure to the value - of the corresponding field in pvMaster. -
-
updateMaster
-
- For each set bit in bitSet set the field in pvMaster to the value - of the corresponding field in copyPVStructure. - -
-
getOptions
-
- Get the options for the field at the specified offset. - A NULL is returned if no options were specified for the field. - If options were specified,PVStructurePtr is - a structure with a set of PVString subfields that specify name,value - pairs. name is the subField name and value is the subField value. -
-
- - - - -

src/monitor

-

This consists of two components:

-
-
monitor
-
Used by code that implements pvAccess monitors.
-
monitorPlugin
-
Code that provides special semantics for monitors.
-
-

monitor

-
-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

-

MonitorElement holds the data for one element of a monitor queue. -It has the fields: -

-
-
pvStructurePtr
-
A top level structure with data values at the time the monitors occurs.
-
changedBitSet
-
Shows which fields have changed since the previous monitor.
-
overrunBitSet
-
Shows which fields have changed more than once since the previous monitor.
-
-

monitorElement queue

-

-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

-

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:

-
-
start
-
- Start monitoring. - This will result in a an initial monitor that has the current value - of all fields. -
-
stop
-
- Stop monitoring. -
-
poll
-
- Called to get a monitor element. - If no new elements are available then a null pointer is returned. -
-
release
-
- Release the monitor element. - The caller owns the monitor element between the calls to poll and release. -
-
-

MonitorRequester

-

This must be implemented by a pvAccess client. -It has the methods:

-
-
monitorConnect
-
- A monitor has either connected of disconnected. -
-
monitorEvent
-
- A new monitor element is available. -
-
unlisten
-
- The channel is going away. The client cam no longer access the monitor. -
-
- -

monitorPlugin

-
-class MonitorPlugin
-{
-    virtual std::string const & getName() = 0;
-    virtual bool causeMonitor(
-        PVFieldPtr const &pvField,
-        PVStructurePtr const &pvTop,
-        MonitorElementPtr const &monitorElement) = 0;
-    virtual void monitorDone(
-        MonitorElementPtr const &monitorElement);
-    virtual void startMonitoring();
-    virtual void stopMonitoring();
-    virtual void beginGroupPut();
-    virtual void endGroupPut();
-};
-
-class MonitorPluginCreator
-{
-    virtual MonitorPluginPtr create(
-        FieldConstPtr const &field,
-        StructureConstPtr const &top,
-        PVStructurePtr const &pvFieldOptions) = 0;
-     virtual std::string const & getName() = 0;
-}
-
-class MonitorPluginManager
-{
-    static MonitorPluginManagerPtr get();
-    bool addPlugin(
-         std::string const &pluginName,
-         MonitorPluginCreatorPtr const &creator);
-    MonitorPluginCreatorPtr findPlugin(std::string const &pluginName);
-    void showNames();
-};
-
-
-

MonitorPlugin

-

MonitorPlugin must be implemented by the plugin implementation. -It has methods:

-
-
getName
-
Get the name of the plugin.
-
causeMonitor
-
- Should the value of pvField cause a monitor to be raised. - pvField and pvTop are fields in the top level structure - being monitored. monitorElement has the top level structure - for the copy
. - The implementation should not modify the fields in the structure - being monitored. - Called with pvTop locked. -
-
monitorDone
-
- Called just before monitorElement will be given to client. - The plugin can change the data values and bitSets in monitorElement. - Called with pvTop unlocked. -
-
startMonitoring
-
- Monitoring is starting. -
-
stopMonitoring
-
- Monitoring is being stopped. -
-
beginGroupPut
-
- A set of puts is starting. - Called with pvTop locked. -
-
endGroupPut
-
- The set of puts is complete. - Called with pvTop locked. -
-
-

MonitorPluginCreator

-

MonitorPluginCreator must also be implemented by the plugin implementation. -It is called for each field instance that has options of the from -[plugin=name...] where name is the name of the plugin. -Note that a plugin instance will belong to a single client. -It has methods:

-
-
getName
-
Get the name of the plugin.
-
create
-
- Create a new plugin instance. - If the arguments are not compatible with the plugin a NULL shared pointer is - returned.
- pvFieldOptions is - a structure with a set of PVString subfields that specify name,value - pairs. name is the subField name and value is the subField value.
- Note that a plugin will below to a single client. -
-
-

MonitorPluginManager

-

MonitorPluginManager has the methods:

-
-
get
-
- MonitorPluginManager is a singleton. - The first call to get will create the single instance. - Further calls will return the single instance. -
-
addPlugin
-
- Add a new plugin. -
-
findPlugin
-
- Find a plugin. A NULL shared pointer is returned if it has not been added. -
-
showNames
-
- Show the names of all plugins that have been added. -
-
-

NOTE: -Should the method causeMonitor -have arguments pvField and pvTop -be defined so that they can not be modified. -This would be possible if the following was defined: -

-
-typedef std::tr1::shared_ptr<const PVField> PVFieldConstPtr;
-typedef std::tr1::shared_ptr<const PVStructure> PVStructureConstPtr;
-
-then the definition for causeMonitor could be: -
-virtual bool causeMonitor(
-        PVFieldConstPtr const &pvField,
-        PVStructureConstPtr const &pvTop,
-        MonitorElementPtr const &monitorElement) = 0;
-
-But just adding these definitions is not sufficient. -In addition all methods defined in pvDataCPP must be checked. -In particular many of the methods in Convert must have -their arguments modified. -Big job. -

monitorPlugin example

-

Example Plugin Overview

-

This section describes an example plugin that:

- -

As an example assume that a channel provided by pvAccess has a top level structure -that represents a power supply.

-
-structure powerSupply
-    structure alarm
-    structure timeStamp
-    structure power
-       double value
-       structure alarm
-       structure display
-    structure voltage
-       double value
-       structure alarm
-       structure display
-    structure current
-       double value
-       structure alarm
-       structure display
-
-

A pvAccess client wants to create a monitor on the powerSupply as follows: -The client wants a top level structure that looks like: -

-
-structure powerSupply
-    structure alarm
-    structure timeStamp
-    structure power
-       double value
-    structure voltage
-       double value
-    structure current
-       double value
-
-In addition the client wants monitors to occur only when one of the monitored -fields changes value but not just because a put occurred. -Also if only the timeStamp changes value then that should not cause a monitor. -

The example monitor plugin implements the semantics the -client wants. It can be attached to any field via the following options: -

-
-[plugin=onChange,raiseMonitor=value]
-
-This plugin will trigger a monitor for the field only if the field changes -value. In addition value equals false means do not raise a monitor -for changes to this field. -But if a change to another field does cause a monitor the change to this field -will be passed to the client. -

-Assume that the client has already connected to the channel. -The client can then issue the commands:

-
-std::string request("field(alarm[plugin=onChange]");
-request += ",timeStamp[plugin=onChange,raiseMonitor=false]";
-request += ",power.value[plugin=onChange";
-request += ",voltage.value[plugin=onChange";
-request += ",current.value[plugin=onChange";
-
-PVStructurePtr pvRequest = createRequest->createRequest(request);
-
-MonitorPtr monitor = channel->createMonitor(monitorRequester,pvRequest);
-
-

Example Plugin Code

-

The header file to create the example has the definition:

-
-class ExampleMonitorPlugin{
-public:
-    static void create();
-};
-
-

The implementation is:

-
-class OnChangePlugin : public MonitorPlugin
-{
-public:
-    virtual ~OnChangePlugin(){}
-    OnChangePlugin() {}
-    bool init(
-        FieldConstPtr const &field,
-        StructureConstPtr const &top,
-        PVStructurePtr const &pvFieldOptions)
-   {
-        pvField = getPVDataCreate()->createPVField(field);
-        raiseMonitor = true;
-        if(pvFieldOptions!=NULL) {
-            PVStringPtr pvString =
-                pvFieldOptions->getSubField<PVString>("raiseMonitor");
-                if(pvString!=NULL) {
-                    std::string value = pvString->get();
-                    if(value.compare("false")==0) raiseMonitor = false;
-                }
-        }
-        return true;
-   }
-   virtual std::string &getName(){return pluginName;}
-   virtual bool causeMonitor(
-        PVFieldPtr const &pvNew,
-        PVStructurePtr const &pvTop,
-        MonitorElementPtr const &monitorElement)
-   {
-       bool isSame = convert->equals(pvNew,pvField);
-       if(isSame) return false;
-       convert->copy(pvNew,pvField);
-       return raiseMonitor;
-   }
-private:
-   PVFieldPtr pvField;
-   bool raiseMonitor;
-};
-class OnChangePluginCreator : public MonitorPluginCreator
-{
-public:
-    virtual std::string &getName(){return pluginName;}
-    virtual MonitorPluginPtr create(
-        FieldConstPtr const &field,
-        StructureConstPtr const &top,
-        PVStructurePtr const &pvFieldOptions)
-   {
-       OnChangePluginPtr plugin(new OnChangePlugin());
-       bool result = plugin->init(field,top,pvFieldOptions);
-       if(!result) return MonitorPluginPtr();
-       return plugin;
-   }
-
-};
-
-void ExampleMonitorPlugin::create()
-{
-    static OnChangePluginCreatorPtr plugin;
-    static Mutex mutex;
-    Lock xx(mutex);
-    if(plugin==NULL) {
-        plugin = OnChangePluginCreatorPtr(new OnChangePluginCreator());
-        MonitorPluginManager::get()->addPlugin(pluginName,plugin);
-    }
-}
-
- - -
- - diff --git a/documentation/pvDataCPP_20150623.html b/documentation/pvDataCPP_20150623.html deleted file mode 100644 index 53902c0..0000000 --- a/documentation/pvDataCPP_20150623.html +++ /dev/null @@ -1,5480 +0,0 @@ - - - - - - EPICS pvDataCPP - - - - - - - - -
-

EPICS pvDataCPP

- - -

EPICS v4 Working Group, Working Draft, 23-June-2015

- -
-
Latest version:
-
pvDataCPP.html -
-
This version:
-
pvDataCPP_20150623.html -
-
Previous version:
-
pvDataCPP_20141110.html -
-
Editors:
-
Marty Kraimer, BNL
-
Michael Davidsaver, BNL
-
Matej Sekoranja, CosyLab
-
David Hickin, Diamond Light Source
-
- -

This product is made available subject to acceptance of the EPICS open source -license.

-
-
- -

Abstract

- -

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 -

- - -

Status of this Document

- -

This is the 23-June-2015 version of the C++ implementation of pvData. -

- -

RELEASE_NOTES.md provides changes since the last release. -TODO.md describes things to do before the next release. -

- - - -
-

Table of Contents

-
-
- -

Introduction

- -

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:

-
-
Introduction
-
A brief description of pvData.
-
PVData Meta Language
-
A language used to describe data.
-
- -

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:

-
-
src/pv
-
This subdirectory contains all the public interfaces that describe pvData. - The section from Namespace and Memory Management - through Conversion discuss these interfaces. -
-
src/property
-
This section has support for managing "standard" fields. -
-
src/misc
-
This section has support for facilities required by implementation code.
-
src/copy and src/monitor
-
These sections provide pvData support for implementing pvAccess providers.
-
- -

Examples

-

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:

-
-
fieldCreate
-
This creates instances of introspection objects. - It also provides fieldBuilder, which provides an easier way to create introspection objects. -
-
pvDataCreate
-
This creates instances of data objects. -
-
standardField
-
This provides support for introspection objects for standard fields, - Standard fields are alarm, timeStamp, display, enumerated structure, and value alarm. -
-
standardPVField
-
This provides support for data objects for standard fields, -
-
- - -

Introspection Examples

-

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.

-

Three ways to create a structure

-

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
-
-

enumerated structure

-

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
-
- -

union example

-

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
-
- -

union array example

-

The following:

-
-    UnionArrayConstPtr unionArray = fieldCreate->createUnionArray(
-        fieldCreate->createVariantUnion());
-    cout << *unionArray << "\n\n";
-
-

Produces

-
-any[]
-any
-0x607188
-
-

power supply

-

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
-
-

Data Examples

-

The examples all produce a top level structure.

-

scalar example

-
-    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
-
-

array example

-
-    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
-
-

enumerated example

-
-    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
-
-

power supply example

-
-    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
-
-

union example

-
-    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
-
- -

variant union example

-
-    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
-
- -

big union example

-
-    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
-
- -

Namespace and Memory Management

- -

Namespace

- -

All code in project pvDataCPP appears in namespace:

-
namespace epics { namespace pvData {
-     // ...
-}}
- -

Memory Management

- -

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:

-
-
Ptr
-
When Ptr appears it stands for std::tr1::shared_ptr. -
-
-

For example:

-
-typedef PVScalarValue<boolean> PVBoolean;
-typedef std::tr1::shared_ptr<PVBoolean> PVBooleanPtr;
-
- -

src/pv

- -

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:

-
-
interface
-
The documentation uses the word interface. - This is an analogy with how Java defines interface. - C++ does not have interfaces but directory pv defines classes - with public members that are similar to the Java interfaces. Most of the - implementation is in factory.
-
Naming Conventions
-
The naming conventions for variables, methods, and classes follow the - Java conventions, i. e. class name begin with an upper case letter, - variables and methods begin with a lower case letter.
-
- -

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:

-
-
pvType.h
-
C++ definitions for primitive types.
-
pvIntrospect.h
-
A complete description of the introspection interfaces.
-
pvData.h
-
A complete description of the data interfaces.
-
convert.h
-
A facility that converts between data fields.
-
pvSubArrayCopy.h
-
This provides a facility that performs array coping between - arrays that have the same type.
-
standardField.h
-
Provides access to introspection interfaces for standard structures - like timeStamp, alarm, etc.
-
standardPVField.h
-
Creates data interfaces for standard data structures like timeStamp, - alarm, etc.
-
- -

pvType.h

- -

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

-
-
boolean
-
A c++ bool has the semantics required for boolean. Only the name is - different. C++ code can use either bool or boolean.
-
int8,...,uint64
-
Integers present a problem because short, int, and long are C++ - reserved words but do not have a well defined number of bits. Thus for - C++ the definitions above are used in C++ code. The above definitions - have worked on all C++ implementations tested at present. If they break - in a future implementation they should be changes via "#ifdef" - preprocessor statements.
-
std::string
-
pvData requires that a string be an immutable string that is transferred - over the network as a UTF8 encoded string. Since std::string implements - copy on write semantics, it can be used for support for immutable - strings. It can also be serialized/deserialized as a UTF8 encoded string. - Note that std::string is treated like a primitive type.
-
StringArray definitions
-
typedefs are provided for an array of std::strings, - which is a std::vector<std::string>. - This is used by introspection. -
-
-

TBD

-
-
boolean
-
Question for Michael. Why isn't the definition of boolean just - 
-typedef uint8_t boolean;
-
-
-
printer.h
-
Not documented. Is this needed? Nothing currently uses it.
-
- -

pvIntrospect.h

- -

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.

- -

Type Description

- -

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:

-
-
scalar
-
A scalar of one of the scalar types.
-
scalarArray
-
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 types can be different.
-
structureArray
-
An array where each element is a structure. Each element has the same - structure introspection interface.
-
union_t
-
This is like a structure that has a single subfield. - The type for the subfield can either be any type, which is called a variant union, - of can be one of a specified set of types. - In the data interfaces the type can be changed dynamically. -'
-
unionArray
-
An array where each element is a union. Each element has the same - union introspection interface.
-
- -

ScalarType is one of the following:

-
-
pvBoolean
-
Has the value false or true.
-
pvByte
-
A signed 8 bit integer.
-
pvShort
-
A signed 16 bit integer.
-
pvInt
-
A signed 32 bit integer.
-
pvLong
-
A signed 64 bit integer.
-
pvUByte
-
An unsigned 8 bit integer.
-
pvUShort
-
An unsigned 16 bit integer.
-
pvUInt
-
An unsigned 32 bit integer.
-
pvULong
-
An unsigned 64 bit integer.
-
pvFloat
-
A IEEE float.
-
pvDouble
-
A IEEE double,
-
pvString
-
An immutable string.
-
- -

TypeFunction is a set of convenience methods for Type

-
-
name
-
Returns the name of the type.
-
- -

ScalarTypeFunction is a set of convenience methods for ScalarType

-
-
isInteger
-
Is the scalarType an integer type, i.e. one of pvByte,...pvULong.
-
isUInteger
-
Is the scalarType an unsigned integer type, i.e. one of - pvUByte,...pvULong
-
isNumeric
-
Is the scalarType numeric, i.e. pvByte,...,pvDouble.
-
isPrimitive
-
Is the scalarType primitive, i.e. not pvString
-
name
-
Returns the name of the scalarType.
-
getScalarType
-
Given a string of the form std::string("boolean"),...,std::string("string") - return the scalarType.
-
elementSize
-
Returns the size in bytes of an instance of the scalarType.
-
- -

Introspection Description

- -

This section describes the reflection interfaces which provide the -following:

-
-
Field
-
A field: -
    -
  • Has a Type.
    • -
  • Can be converted to a string.
    • -
  • Can be shared. A reference count is kept. When it becomes 0 the - instance is automatically deleted.
    • -
-
-
Scalar
-
A scalar has a scalarType
-
ScalarArray
-
The element type is a scalarType
-
Structure
-
Has fields that can be any of the supported types.
-
StructureArray
-
The field holds an array of structures. Each element has the same - Structure introspection interface. A pvAccess client can only get/put - entire PVStructure elements NOT subfields of array elements.
-
Union
-
- This has two flavors: a variant union or a union of a fixed set - of types. A PVUnion will have a single subfield. - If the union introspection interface is a variant union then - the single field can be of any type and has the name any. - If the union is not a variant type then the type can be one of - a fixed set of types and a name associated with the type. - The union introspection interface has a field array and a string - array that has the fixed set of types and associated names. -
-
UnionArray
-
- This is an array of unions. A PVUnionArray is an array - of PVUnions. Each element has the same introspection interface - but the subfield of each element can have a different type. -
-
FieldBuilder
-
This is a convenience interface that makes it easier to create - top introspection interfaces. -
-
FieldCreate
-
This is an interface that provides methods to create introspection - interfaces. A factory is provides to create FieldCreate.
-
getFieldCreate
-
Gets a pointer to the single instance of FieldCreate.
-
-

Field,Scalar,ScalarArray,Structure,StructureArray,Union,UnionArray

-
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);
-    
-};
-
-
-
Constructors
-
Note that all constructors are protected or private. The only way to - create instances is via fieldBuilder or fieldCreate. The implementation manages all - storage via shared pointers.
-
dump
-
Many classes provide this. This is a stream method that prints using - the metadata syntax described in pvDataJava.html.
-
- -

Field

-
-
getType
-
Get the field type.
-
getID
-
Get an ID for this introspection interface
-
- -

Scalar

-
-
getScalarType
-
Get that scalar type.
-
getID
-
For each scalarType there is one instance of Scalar. The ID for each is - the metadata name for the type, i. e. one of "boolean" , ... , "string". -
-
- -

ScalarArray

-
-
getElementType
-
Get the element type.
-
getID
-
For each elemnetType there is one instance of ScalarArray. The ID for - each is the metadata name for the type, i. e. one of "boolean[]" , ... , - "string[]".
-
- -

StructureArray

-
-
getStructure
-
Get the introspection interface that each element shares,
-
getID
-
This returns the ID[] where ID is the value returned by - structure->getID().
-
-` -

UnionArray

-
-
getUnion
-
Get the union interface for each element.
-
- -

Structure

-
-
getNumberFields
-
Get the number of immediate subfields.
-
getField
-
Given a name or an index get the introspection interface for the - field.
-
getFieldIndex
-
Given a name get the index, within the array returned by the next - method, of the field.
-
getFields
-
Get the array of introspection interfaces for the field,
-
getFieldNames
-
Get the array of field names for the subfields.
-
getFieldName
-
Get the field name for the specified index.
-
-

Union

-
-
getNumberFields
-
Get the number of possible field types. - Both getFields and getFieldNames will return an array with getNumberFields elements. - A value of 0 is returned for invariant arrays. -
-
getField
-
Given a name or an index the type is returned. - NULL is returned if not found. -
-
getFieldIndex
-
Get the index for name. -1 is returned if not found.
-
getFields
-
Get the array of types.
-
getFieldNames
-
Get the array of names.
-
getFieldName
-
Get the name for the specified index.
-
isVariant
-
returns true if this is variant array and false otherwise.
-
-

fieldBuilder and createField

-
-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();
-
- -

FieldBuilder

-

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. -

-
-
setID
-
This sets an ID for the field, which is the name for the field when it is a subfield. -
-
add
-
- Add a scalar field. -
-
addBoundedString
-
- Add a scalar field that is a string that has a maximum size. -
-
addArray
-
- Add an array field. There are two methods: one to create a scalaArray - and one to create scalarArray, unionArray, or structureArray. -
-
addFixedArray
-
- Add a fixed size scalarArray field. -
-
addBoundedArray
-
- Add a bounded scalarArray field. -
-
createStructure
-
- Create a structure from the fields that are currently present. -
-
createUnion
-
- Create a union from the fields that are currently present. -
-
addNestedStructure
-
- Add a nested structure. This is followed by an arbitrary number of adds - followed by a an endNested. -
-
addNestedUnion
-
- Add a nested union. This is followed by an arbitrary number of adds - followed by a an endNested. -
-
addNestedStructureArray
-
- Add a nested structure array. This is followed by an arbitrary number of adds - followed by a an endNested. -
-
addNestedUnionArray
-
- Add a nested union array. This is followed by an arbitrary number of adds - followed by a an endNested. -
-
endNested
-
- End current nested structure or union. -
-
-

Examples of using fieldBuilder were given earlier in this manual.

-

FieldCreate

-
-
getFieldCreate
-
Get the single instance of FieldCreate.
-
createFieldBuilder
-
Create an instance of a FieldBuilder.
-
createScalar
-
Create a scalar introspection instance.
-
createBoundedString
-
create a scalar introspection instance for a bounded string.
-
createScalarArray
-
Create a scalar array introspection instance.
-
createFixedScalarArray
-
Create a scalar array introspection instance.
-
createBoundedScalarArray
-
Create a scalar array introspection instance.
-
createStructure
-
Create a structure introspection instance. Three methods are provided. - The first creates an empty structure, i. e. a structure with no fields. - The other two are similar. - The only difference is that one provides an ID and the other does - not. The one without will result in ID structure.
-
createStructureArray
-
Ceate a structure array introspection instance. - All elements will have the same introspection interface. -
-
createUnion
-
Create a union. There are two methods. - Each has arguments for an array of types and an array of names. - One method has an id. The other results in id = union. -
-
createVariantUnion
-
- Create a variant union. The id will be any. -
-
createUnionArray
-
Create a union array. punion is the introspection interface - for each element.
-
createVariantUnionArray
-
Create a union array where each element is a variant union.
-
createStructureArray
-
Create a structure array introspection instance.
-
appendField
-
Create a new structure that is like an existing structure but has - an extra field appended to it. -
-
appendFields
-
Create a new structure that is like an existing structure but has - extra fields appended to it. -
-
deserialize
-
Deserialize from given byte buffer.
-
- -

standardField.h

- -

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();
- ...
-};
-
-
scalar
-
Create a scalar with the specified scalar type and name. A structure - will be created with the first element being a scalar with the specified - scalar type and name value. The other fields in the structure will be the - corresponding property structures.
-
regUnion
-
A structure - will be created with the first element being a union with the specified - scalar type and name value. The other fields in the structure will be the - corresponding property structures.
-
variant`Union
-
Create a variant union. A structure - will be created with the first element being a union with the specified - scalar type and name value. The other fields in the structure will be the - corresponding property structures.
-
scalarArray
-
Create a scalarArray with each element having the specified scalar type - and name. A structure will be created with the first element being a - scalarArray with name value. The other fields in the structure will be - the corresponding property structures.
-
structureArray
-
Create a structureArray with the specified structure interface and - name. A structure will be created with the first element being a - structureArray with the specified structure interface and name value. The - other fields in the structure will be the corresponding property - structures.
-
unionArray
-
Create a unionArray with the specified union interface and - name. A structure will be created with the first element being a - unionArray with the specified structure interface and name value. The - other fields in the structure will be the corresponding property - structures.
-
structure
-
Create a structure with the specified name and fields specified by - numFields and fields. A structure will be created with the first element - being a structure with the name value and fields specified by numFields - and fields. The other fields in the structure will be the corresponding - property structures.
-
enumerated
-
Create a structure with the specified name and fields for an enumerated - structure. If properties are specified then a structure will be created - with the first element being a structure with the name value and fields - for an enumerated structure. The other fields in the structure will be - the corresponding property structures.
-
alarm
-
timeStamp
-
display
-
control
-
booleanAlarm
-
byteAlarm
-
shortAlarm
-
intAlarm
-
longAlarm
-
floatAlarm
-
doubleAlarm
-
enumeratedAlarm
-
The above provide introspection interfaces for standard properties. See - the section on Properties for a description of how these are defined.
-
-

pvData.h

- -

This section describes pvData.h This file is quite big so rather than -showing the entire file, it will be described in parts.

- -

typedefs

- -

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

- -

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:

-
-
~PVField
-
Destructor. Since shared pointers are used it should never be called by - user code.
-
getFieldName
-
Get the field name. If the field is a top level structure the field - name will be an empty string.
-
getFullName
-
Fully expand the name of this field using the - names of its parent fields with a dot '.' separating - each name. -
-
getFieldOffset
-
Get offset of the PVField field within top level structure. Every field - within the PVStructure has a unique offset. The top level structure has - an offset of 0. The first field within the structure has offset equal to - 1. The other offsets are determined by recursively traversing each - structure of the tree.
-
getNextFieldOffset
-
Get the next offset. If the field is a scalar or array field then this - is just offset + 1. If the field is a structure it is the offset of the - next field after this structure. Thus (nextOffset - offset) is always - equal to the total number of fields within the field.
-
getNumberFields
-
Get the total number of fields in this field. This is nextFieldOffset - - fieldOffset.
-
isImmutable
-
Is the field immutable?
-
setImmutable
-
Make the field immutable. Once a field is immutable it can never be - changed since there is no method to again make it mutable. This is an - important design decision since it allows immutable array fields to share - the internal primitive data array.
-
getField
-
Get the reflection interface for the data.
-
getParent
-
Get the interface for the parent or null if this is the top level - PVStructure.
-
postPut
-
If a postHandler is registered it is called otherwise no action is - taken.
- NOTE: The implementation of the various data interfaces automatically - call postPut when a field is changed. However this is not true - for a subField of a PVUnion, PVUnionArray, or PVStructureArray. - If a subField of any of these is changed then the code that is making - the modification must call postPut for the PVUnion, PVUnionArray, or PVStructureArray - field. Note also that it is not a good idea to modify a subfield of a PVUnionArray - or a PVStructureArray since it violates the idea of Copy On Write for arrays. -
-
setPostHandler
-
Set the postHandler for the record. Only a single handler can be - registered. - PostHandler is a class that must be implemented by any code that calls setPostHandler. - It's single virtual method. postPut is called whenever PVField::postPut is called. -
-
equals
-
Compare this field with another field. The result will be true only if - the fields have exactly the same field types and if the data values are - equal.
-
dumpValue
-
Method for streams I/O.
-
- -

PVScalar

- -

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

-
-
getScalar
-
Get the introspection interface for the PVScalar.
-
getAs
-
Convert and return the scalar value in the requested type. - Result type is determined from the function template argument - which must be one of the ScalarType enums. - For example: -
-uint32 val = pv->getAs<pvInt>();
-
-
- -
- -

PVScalarValue

- -

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

-
-
get
-
Get the value stored in the object.
-
put
-
Change the value stored in the object.
-
dumpValue
-
ostream method.
-
operator>>=
-
get operator. For example: -
-double value;
-PVDoublePtr pvDouble;
-...
-pvDouble>>=value;
-
-
-
operator<<=
-
put operator. For example: -
-double value;
-PVDoublePtr pvDouble;
-...
-pvDouble<<=value;
-
-
-
getAs
-
Convert and return the scalar value in the requested type. - Result type is determined from the function template argument - which must be one of the ScalarType enums. - For example: -
-int32 val = pv->getAs<pvInt>>();
-
-
-
putFrom
-
Convert the scalar value in the requested type - and put the value into this PVScalarValue. - The source type is determined from the function template argument - which must be one of the ScalarType enums. - For example: -
-int32 val;
-pv->putFrom<pvInt>(val);
-
- -
-
-

PVUnion

-

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;
-};
-
-
-
getUnion
-
Get the introspection interface.
-
get
-
Get the current field. A template version does the conversion. - NULL is returned if no field is selected or if the caller -' asks for the wrong type. -
-
select
-
Select and get the field by index or name. - A templated version does the conversion. - If the index is out of bounds or the name is not valid this methods throws an exception. - The method set should be used for variant unions rather than select. -
-
getSelectedIndex
-
Get the index of the currently selected field.
-
getSelectedFieldName
-
Get the name of the currently selected field.
-
set
-
Set the field to the argument. If invalid type an exception is thrown. - This should always work for a variant union. -
-
- -

PVArray

- -

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;
- ...
-};
-
-
getArray
-
Get the introspection interface.
-
setImmutable
-
Set the data immutable. Note that this is permanent since there is no - methods to make it mutable.
-
getLength
-
Get the current length. This is less than or equal to the capacity.
-
setLength
-
Set the length. If the PVField is not mutable then an exception is - thrown. If this is greater than the capacity setCapacity is called.
-
getCapacity
-
Get the capacity, i.e. this is the size of the underlying data - array.
-
setCapacity
-
Set the capacity. The semantics are implementation dependent but - typical semantics are as follows: If the capacity is not mutable an - exception is thrown. A new data array is created and data is copied from - the old array to the new array.
-
isCapacityMutable
-
Is the capacity mutable
-
setCapacityMutable
-
Specify if the capacity can be changed.
-
setCapacity
-
Set the capacity.
-
dumpValue
-
ostream method
-
- - -

PVScalarArray

- -

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

-
-
getScalarArray
-
Get the introspection interface.
-
getAs
-
Fetch the current value and convert to the requested type. - A copy is made if the requested type does not match the element type. - If the types do match then no copy is made. -
-
putFrom
-
Assign the given value after conversion. - A copy and element-wise conversion is performed unless the element type - of the PVScalarArray matches the type of the provided data. - If the types do match then a new reference to the provided data is kept. -
-
assign
-
Assign the given PVScalarArray's value. - A copy and element-wise conversion is performed unless the element type - of the PVScalarArray matches the type of the provided data. - If the types do match then a new reference to the provided data is kept. -
-
- -

PVStructure

- -

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

-
-
getStructure
-
Get the introspection interface for the structure.
-
getPVFields
-
Returns the array of subfields. The set of subfields must all have - different field names.
-
getSubField(std::string const &fieldName)
-
- Get a subField of a field.d - A non-null result is - returned if fieldName is a field of the PVStructure. The fieldName can be - of the form name.name... - If the field does not exist then a Ptr to a NULL value is returned - without any error message being generated. -
- Note The template version replaces getBooleanField, etc.
-
-
getSubField(int fieldOffset)
-
Get the field located a fieldOffset, where fieldOffset is relative to - the top level structure. This returns null if the specified field is not - located within this PVStructure. -
-
getSubFieldT(std::string const &fieldName)
-
Like getSubField except that it throws std::runtime_error if - the field does not exists or has the wrong type.
-
getSubFieldT(int fieldOffset)
-
Like getSubField except that it throws std::runtime_error if - the field does not exists or has the wrong type.
-
dumpValue
-
Method for streams I/O.
-
- - -

PVValueArray

- -

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

-
-
getArray
-
Get the introspection interface.
-
dumpValue
-
Method for streams I/O.
-
view
-
Fetch a read-only view of the current array data.
-
swap
-
- Callers must ensure that postPut() is called after the last swap() operation. - Before you call this directly, consider using the reuse(), or replace() methods. -
-
replace
-
Discard current contents and replaced with the provided.
-
reuse
-
Remove and return the current array data or an unique copy if shared.
-
-

TBD

-
-
Check for completeness
-
Michael should check that PVScalarArray and PVValueArray - have the correct set of methods and that the descriptions are correct.
-
- -

PVStructureArray

- -

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

-
-
getStructureArray
-
Get the introspection interface shared by each element.
-
compress
-
This moves all null elements and then changes the array capacity. When - done there are no null elements.
-
- -

The other methods are similar to the methods for other array types. - See PVArray above for details.

- -

PVUnionArray

-

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

-
-
getUnionArray
-
Get the introspection interface shared by each element.
-
compress
-
This moves all null elements and then changes the array capacity. When - done there are no null elements.
-
- -

The other methods are similar to the methods for other array types. - See PVArray above for details.

- -

PVDataCreate

- -

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

-
-
getPVDataCreate
-
The returns the PVDataCreate implementation, which is a singleton.
-
createPVField
-
The PVField is created reusing the Field interface. Two methods are - provided. Each calls the corresponding createPVScalar, createPVArray, or - createPVStructure depending in the type of the last argument.
-
createPVScalar
-
Creates an instance of a PVScalar. Four versions are supplied. The - first is passed an introspection interface. - The second provides the scalarType. - The third provides a PVScalar to clone. - The last is a template version. PVAT must be a valid type. - For example: -
-PVDoublePtr pvDouble = getPVDataCreate()->createPVScalar<PVDouble>();
-
-
-
createPVStructure
-
Create an instance of a PVStructure. - Three methods are provided. - The first uses an array of field names and an array of PVFields to initialize the subfields. - The second initializes the subfields by cloning the fields contained in - structToClone. The newly created subfields will have the same values as the original. - If structToClone is null then the new structure is initialized to have 0 subfields. - The third method uses a previously created structure introspection interface. -
-
createPVUnion
-
Create an instance of a PVUnion. Two methods are provided. - The first uses a previously created union introspection interface. - The second clones an existing PVUnion. -
-
createPVVariantUnion
-
Creates an instance of a variant PVUnion. - This is a union which has a single field which can be any pvData supported type, -
-
createPVScalarArray
-
Create an instance of a PVArray. Four versions are supplied. - The first is passed an introspection interface. - The second provides the elementType. - The third provides a PVScalarArray to clone. - The last is a template version. PVAT must be a valid type. - For example: -
-PVDoubleArrayPtr pvDoubleArray = getPVDataCreate()->createPVScalarArray<PVDoubleArray>();
-
-
-
createPVStructureArray
-
Create a PVStructureArray. - Two versions are provided. - The first is passed a StructureArrayConstPtr. - The second is passed a StructureConstPtr which is used to create a StructureArrayConstPtr. - The argument provides the Structure interface for ALL elements of the PVStructureArray. -
-
createPVUnionArray
-
Create a PVUnionArray. - Two versions are provided. - The first is passed a UnionArrayConstPtr. - The second is passed a UnionConstPtr which is used to create a UnionArrayConstPtr. - The argument provides the Union interface for ALL elements of the PVUnionArray. -
-
createPVVariantUnionArray
-
Create a PVUnionArray. - No arguments are needed. -
-
- -

standardPVField.h

- -

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();
-
- -

Conversion

-

There are two facilities for converting between two different PVData -objects:

-
-
Convert
-
This preforms all conversions except for coping subarrays.
-
PVSubArray
-
This copies a subarray from one PVArray to another. - The two arrays must have the same element type.
-
-

convert.h

- -

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.

- -

pvSubArrayCopy.h

-
-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:

-
-
from
-
The source array.
-
fromOffset
-
The offset into the source array.
-
fromStride
-
The interval between source elements.
-
to
-
The destination array. The element type must be the same - as for the source array. If the element type is structure then - the introspection interface for the element types must be the same. -
-
toOffset
-
The offset into the destination array.
-
toStride
-
The interval between destination elements.
-
count
-
The number of elements to copy.
-
-

An exception is thrown if:

-
-
type mismatch
-
The element types for the source and destination differ.
-
immutable
-
The destination array is immutable.
-
capacity immutable
-
The destination array needs to have it's capacity extended - but the capacity is immutable.
-
- -

src/property

- -

Definition of Property

- -

-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
- -

Standard Properties

- -

The following field names have special meaning, i.e. support properties for -general purpose clients.

-
-
value
-
This is normally defined since most general purpose clients access this - field. All other fields in the structure support or describe the value - field. The type can any supported type but is usually one of the - following: -
-
scalar
-
Any of the scalar types.
-
scalarArray
-
An array with the elementType being a scalar type
-
enumerated structure
-
A structure that includes fields named index and choices. index - is an int that selects a choice. choices is an array of strings - that defines the complete set of choices.
-
other
-
Other structure or array types can also be defined if clients and - support code agree on the meaning. Some examples are: 1) A - structure defining a 2D matrix, 2) A structure defining an image, - 3) A structure that simulates a remote method, ...
-
-
-
timeStamp
-
The timeStamp. The type MUST be a timeStamp structure. Also if the - PVData structure does not have a timeStamp then a search up the parent - tree is made to find a timeStamp.
-
alarm
-
The alarm. The type MUST be an alarm structure.
-
display
-
A display structure as described below. It provides display - characteristics for the value field.
-
control
-
A control structure as described below. It provides control - characteristics for the value field.
-
history
-
Provides a history buffer for the value field. Note that currently - PVData does not define history support.
-
other
-
Other standard properties can be defined.
-
- -

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:

-
-
input
-
A field with support that changes the value field. This can be - anything. It can be a channel access link. It can obtain a value from - hardware. Etc.
-
valueAlarm
-
A field with support that looks for alarm conditions based on the - value.
-
output
-
A field with support that reads the current value and sends it - somewhere else. This can be anything. It can be a channel access link. It - can write a value to hardware. Etc.
-
- -

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. -

- -

Overview of Property Support

- -

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();
-     ...
-}
- -

timeStamp

- -

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:

-
-
timeStamp.h
-
Defines a time stamp independent of pvData, i.e. it is a generally - useful class for manipulating timeStamps.
-
pvTimeStamp.h
-
A class that can be attached to a time stamp pvData structure. It - provides get and set methods to get/set a TimeStamp as defined by - timeStamp.h
-
- -

timeStamp.h

- -

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

-
-
TimeStamp()
-
The default constructor. Both seconds and nanoseconds are set to 0.
-
TimeStamp(int64 secondsPastEpoch,int32 nanoseconds = 0)
-
A constructor that gives initial values to seconds and nanoseconds.
-
normalize
-
Adjust seconds and nanoseconds so that - 0<=nanoseconds<nanoSecPerSec.
-
fromTime_t
-
Set time from standard C time.
-
toTime_t
-
Convert timeStamp to standard C time.
-
getSecondsPastEpoch
-
Get the number of seconds since the epoch.
-
getEpicsSecondsPastEpoch
-
Get the number of EPICS seconds since the epoch. EPICS uses Jan 1, 1990 - 00:00:00 UTC as the epoch.
-
getNanoseconds
-
Get the number of nanoseconds. This is always normalized.
-
getUserTag
-
Get the userTag.
-
setUserTag
-
Set the userTag.
-
put(int64 secondsPastEpoch,int32 nanoseconds = 0)
-
Set the timeStamp value. If necessary it will be normalized.
-
put(int64 milliseconds)
-
Set the timeStamp with a value the is the number of milliSeconds since - the epoch.
-
getCurrent()
-
Set the timeStamp to the current time.
-
toSeconds()
-
Convert the timeStamp to a value that is the number of seconds since - the epocj
-
operator =
-
operator!=
-
operator<=
-
operator<
-
operator>=
-
operator>
-
Standard C++ operators.
-
diff
-
diff = a - b
-
getMilliseconds
-
Get the number of milliseconds since the epoch.
-
- -

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);
- -

pvTimeStamp.h

-
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

-
-
PVTimeStamp
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if a timeStamp - structure is found. It looks first at pvField itself and if is not an - appropriate pvData structure but the field name is value it looks up the - parent structure tree.
-
detach
-
Detach from the pvData structure.
-
isAttached
-
Is there an attachment to a timeStamp structure?
-
get
-
Copies data from the pvData structure to a TimeStamp. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from TimeStamp to the pvData structure. An exception is - thrown if not attached to a pvData structure.
-
- -

alarm

- -

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:

-
-
alarm.h
-
Defines an alarm independent of pvData, i.e. it is a generally useful - class for manipulating alarms.
-
pvAlarm.h
-
A class that can be attached to an alarm pvData structure. It provides - get and set methods to get/set alarm data as defined by alarm.h
-
- -

alarm.h

-
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:

-
-
getSeverity
-
Get the alarm severity corresponding to the integer value.
-
getSeverityNames
-
Get the array of severity choices.
-
- -

Alarm Status defines the possible choices for alarm status:

-
-
getStatus
-
Get the alarm status corresponding to the integer value.
-
getStatusNames
-
Get the array of status choices.
-
- -

Alarm has the methods:

-
-
Alarm
-
The constructor. It sets the severity to no alarm and the message to - "".
-
getMessage
-
Get the message.
-
setMessage
-
Set the message.
-
getSeverity
-
Get the severity.
-
setSeverity
-
Set the severity.
-
getStatus
-
Get the status.
-
setStatus
-
Set the status.
-
- -

pvAlarm.h

-
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

-
-
PVAlarm
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if it found an - appropriate pvData structure. It looks first a pvField itself and if is - not an appropriate pvData structure but the field name is value it looks - to see if the parent structure has an appropriate sub structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to an alarm structure?
-
get
-
Copies data from the pvData structure to an Alarm. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from Alarm to the pvData structure. An exception is thrown - if not attached to a pvData structure.
-
- -

control

- -

Control information is represented by the following structure

-
structure control
-    double limitLow
-    double limitHigh
-    double minStep
- -

Two header files are provided for manipulating control:

-
-
control.h
-
Defines control independent of pvData, i.e. it is a generally useful - class for manipulating control.
-
pvControl.h
-
A class that can be attached to an control pvData structure. It - provides get and set methods to get/set control data as defined by - control.h
-
- -

control.h

-
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

-
-
Control
-
The default constructor.
-
getLow
-
Get the low limit.
-
getHigh
-
Get the high limit.
-
setLow
-
Set the low limit.
-
setHigh
-
Set the high limit.
-
setMinStep
-
Set the minimum step size.
-
getMinStep
-
Get he minimum step size.
-
- -

pvControl.h

-
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

-
-
PVControl
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if it found an - appropriate pvData structure. It looks first a pvField itself and if is - not an appropriate pvData structure but the field name is value it looks - to see if the parent structure has an appropriate sub structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to a control structure?
-
get
-
Copies data from the pvData structure to a Control. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from Control to the pvData structure. An exception is - thrown if not attached to a pvData structure.
-
- -

display

- -

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:

-
-
display.h
-
Defines display independent of pvData, i.e. it is a generally useful - class for manipulating display.
-
pvDisplay.h
-
A class that can be attached to an display pvData structure. It - provides get and set methods to get/set display data as defined by - display.h
-
- -

display.h

-
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

-
-
Control
-
The default constructor.
-
getLow
-
Get the low limit.
-
getHigh
-
Get the high limit.
-
setLow
-
Set the low limit.
-
setHigh
-
Set the high limit.
-
getDescription
-
Get the description.
-
setDescription
-
Set the description.
-
getFormat
-
Get the format.
-
setFormat
-
Set the format.
-
getUnits
-
Get the units.
-
setUnits
-
Set the units.
-
- -

pvDisplay.h

-
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

-
-
PVDisplay
-
The default constructor. Attach must be called before get or set can be - called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if it found an - appropriate pvData structure. It looks first a pvField itself and if is - not an appropriate pvData structure but the field name is value it looks - to see if the parent structure has an appropriate sub structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to a display structure?
-
get
-
Copies data from the pvData structure to a Display. An exception is - thrown if not attached to a pvData structure.
-
set
-
Copies data from Display to the pvData structure. An exception is - thrown if not attached to a pvData structure.
-
- -

pvEnumerated.h

- -

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

-
-
PVEnumerated
-
The default constructor. Attach must be called before any get or set - method can be called.
-
attach
-
Attempts to attach to pvField It returns (false,true) if pvField (is - not, is) an enumerated structure.
-
detach
-
Just detaches from the pvData structure.
-
isAttached
-
Is there an attachment to an enumerated structure?
-
setIndex
-
Set the index field in the pvData structure. An exception is thrown if - not attached to a pvData structure.
-
getIndex
-
Get the index field in the pvData structure.
-
getChoice
-
Get the std::string value corresponding to the current index field in the - pvData structure. An exception is thrown if not attached to a pvData - structure.
-
choicesMutable
-
Can the choices be changed? Note that this is often true. An exception - is thrown if not attached to a pvData structure.
-
getChoices
-
Get the array of choices. An exception is thrown if not attached to a - pvData structure.
-
getNumberChoices
-
Get the number of choices. An exception is thrown if not attached to a - pvData structure.
-
setChoices
-
Change the choices. An exception is thrown if not attached to a pvData - structure.
-
- - -

src/factory

- -

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

- -

src/misc

- -

Overview

- -

This package provides utility code:

-
-
bitSet.h
-
An implementation of BitSet that can be serialized.
-
byteBuffer.h
-
Used to serialize objects.
-
destroyable.h
-
Provides method destroy.
-
epicsException.h
-
Exception with stack trace.
-
event.h
-
Signal and wait for an event.
-
executor.h
-
Provides a thread for executing commands.
-
localStaticLock.h
-
TBD Matej can You explain what this does?
-
lock.h
-
Support for locking and unlocking.
-
messageQueue.h
-
Support for queuing messages to give to requesters.
-
noDefaultMethods.h
-
When privately extended prevents compiler from implementing default - methods.
-
queue.h
-
A queue implementation that allows the latest queue element to continue - to be used when no free element is available.
-
requester.h
-
Allows messages to be sent to a requester.
-
serialize.h
-
Support for serializing objects.
-
serializeHelper.h
-
More support for serializing objects.
-
sharedPtr.h
-
Defines POINTER_DEFINITIONS.
-
sharedVector.h
-
Like std::vector except that std::shared_ptr is used for - the data array.
-
status.h
-
A way to pass status information to a client.
-
templateMeta.h
-
TBD Michael can You provide an explanation?
-
thread.h
-
Provides thread support.
-
timeFunction.h
-
Time how long a function call requires.
-
timer.h
-
An implementation of Timer that does not require an object to be - created for each timer request.
-
typeCast.h
-
TBD Michael can You provide an explanation?
-
- -

Note that directory testApp/misc has test code for all the classes in misc. -The test code also can be used as examples.

- -

bitSet.h

- -

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

-
-
BitSet()
-
Creates a bitSet of initial size 64 bits. All bits initially false.
-
BitSet(uint32 nbits)
-
Creates a bitSet with the initial of the specified number of bits. All - bits initially false.
-
~BitSet()
-
Destructor.
-
flip(uint32 bitIndex)
-
Flip the specified bit.
-
set(uint32 bitIndex)
-
Set the specified bit true.
-
clear(uint32 bitIndex)
-
Set the specified bit false.
-
set(uint32 bitIndex, bool value)
-
Set the specified bit to value.
-
get(uint32 bitIndex)
-
Return the state of the specified bit.
-
clear()
-
Set all bits to false.
-
nextSetBit(uint32 fromIndex)
-
Get the index of the next true bit beginning with the specified - bit.
-
nextClearBit(uint32 fromIndex)
-
Get the index of the next false bit beginning with the specified - bit.
-
isEmpty()
-
Return (false,true) if (at least one bit true, all bits are false)
-
cardinality()
-
Return the number of true bits.
-
size()
-
Returns the number of bits of space actually in use.
-
operator&=(const BitSet& set)
-
Performs a logical and of this target bit set with the argument bit - set. This bit set is modified so that each bit in it has the value true - if and only if it both initially had the value true and the corresponding - bit in the bit set argument also had the value.
-
operator|=(const BitSet& set)
-
Performs a logical or of this target bit set with the argument bit - set.
-
operator^=(const BitSet& set)
-
Performs a logical exclusive or of this target bit set with the - argument bit set.
-
operator=(const BitSet &set)
-
Assignment operator.
-
or_and(const BitSet& set1, const BitSet& set2)
-
Perform AND operation on set1 and set2, and then OR this bitSet with - the result.
-
operator==(const BitSet &set)
-
Does this bitSet have the same values as the argument.
-
operator!=(const BitSet &set)
-
Is this bitSet different than the argument.
-
virtual void serialize(ByteBuffer *buffer,SerializableControl *flusher) - const;
-
Serialize the bitSet
-
virtual void deserialize(ByteBuffer *buffer,DeserializableControl - *flusher);
-
Deserialize the bitSet.
-
- -

byteBuffer.h

- -

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();
- ...
-};
- -

destroyable.h

-
class Destroyable  {
-public:
-    POINTER_DEFINITIONS(Destroyable);
-    virtual void destroy() = 0;
-    virtual ~Destroyable() {};
-};
- -

epicsException.h

-
/*
- * 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.
- */
- -

event.h

- -

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

-
-
Event
-
The constructor. The initial value can be full or empty. The normal - first state is empty.
-
signal
-
The event becomes full. The current or next wait will complete.
-
wait
-
Wait until event is full or until timeout. The return value is - (false,true) if the wait completed because event (was not, was) full. A - false value normally means that that a timeout occurred. It is also - returned if an error occurs or because the event is being deleted.
-
tryWait
-
returns (false,true) if the event is (empty,full)
-
- -

executor.h

- -

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:

-
-
Executor
-
The constructor. A thread name and priority must be specified.
-
~Executor
-
The destructor. If any commands remain in the execute list they are not - called. All ExecutorNodes that have been created are deleted.
-
execute
-
Request that command be executed. If it is already on the run list - nothing is done.
-
- -

localStaticLock.h

-
-extern epics::pvData::Mutex& getLocalStaticInitMutex();
-
-static class MutexInitializer {
-  public:
-    MutexInitializer ();
-    ~MutexInitializer ();
-} localStaticMutexInitializer; // Note object here in the header.
-
-

TBD Matej will explain.

- -

lock.h

-
-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. -

- -

messageQueue.h

- -

Definitions

- -

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:

-
-
getMessage
-
The message.
-
getMessageType
-
The message type.
-
setMessageNull
-
Set the message to be a null string.
-
- -

A messageQueue is an interface with public methods:

-
-
MessageQueue
-
The constructor. The queue size must be specified.
-
~MessageQueue
-
The destructor.
-
put
-
Put a new message into the queue. False is returned if the queue was - full and true otherwise. If replaceLast is true then the last message is - replaced with this message.
-
get
-
Get the oldest queue element. If the queue is empty null is returned. - Before the next get can be issued release must be called.
-
release
-
Release the queue element returned by the last get.
-
isEmpty
-
Is the queue empty?
-
isFull
-
Is the queue full?
-
getClearOverrun
-
Get the number of times put has been called but no free element is - available.
-
- -

Look at miscTest/testMessageQueue.cpp for an example.

- -

noDefaultMethods.h

- -

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 &);
-    };
- -

queue.h

- -

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:

-
-
clear
-
Make the queue empty.
-
getNumberFree
-
Get the number of free elements in the queue.
-
capacity
-
Get the capacity, i.e. the maximum number of elements the queue can - hold.
-
getNumberFree
-
Get the number of free elements.
-
getNumberUsed
-
Get the number of elements used.
-
getFree
-
Get the next free element. Null is returned if no free elements are - available. If a non null value is returned then the element belongs to - the caller until setUsed is called.
-
setUsed
-
Set a queue element used. This must be the element returned by the last - call to getFree.
-
getUsed
-
Get the next used element of null if no more used elements are - available.
-
releaseUsed
-
Set a queue element free. This must be the element returned by the last - call to getUsed.
-
- -

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.h

- -

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

-
-
-
MessageType
-
Type of message.
-
messageTypeName
-
An array of strings of the message type names, i.e. - std::string("info"),std::string("warning"),std::string("error"),std::string("fatalError").
-
getRequesterName
-
Returns the requester name.
-
message
-
Gives a message to the requester.
-
- -

serialize.h

-
-    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;
-    };
- -

serializeHelper.h

- -

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

-
-
writeSize
-
Serialize the size.
-
readSize
-
Deserialize the size.
-
serializeString
-
Serialize a std::string.
-
serializeSubstring
-
Serialize a substring.
-
deserializeString
-
Deserialize a string.
-
- -

sharedPtr.h

-
-#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;
- -

sharedVector.h

-

-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:

-
-
Differences in behavior
-
- shared_vector models const-ness like shared_ptr. - An equivalent of 'const std::vector<E>' is - 'const shared_vector<const E>'. - However, it is also possible to have 'const shared_vector<E>' - analogous to 'E* const' and 'shared_vector<const E>>' - which is analogous to 'const E*'.i -
- Copying a shared_vector, by construction or assignment, does not copy - its contents. - Modifications to one such "copy" effect all - associated shared_vector instances. -
- std::vector::reserve(N) has no effect if N<=std::vector::capacity(). - However, like resize(), shared_vector<E>::reserve() has the side effect - of always calling make_unique(). -
-
Parts of std::vector interface not implemented
-
- Mutating methods insert(), erase(), shrink_to_fit(), emplace(), and emplace_back() are not implemented. -
- shared_vector does not model an allocator which is bound to the object. Therefore the get_allocator() method and the allocator_type typedef are not provided. -
- The assign() method and the related constructor are not implemented at this time. -
- The comparison operators are not implemented at this time. -
-
Parts not found in std::vector
-
- shared_vector has additional constructors from raw pointers and shared_ptr s. - The copy constructor and assignment operator allow implicit castings - from type 'shared_vector<T>' to 'shared_vector<const T>>'. - To facilitate safe modification the methods unique() and make_unique() are provided - The slice() method selects a sub-set of the shared_vector. - The low level accessors dataPtr(), dataOffset(), dataCount(), and dataTotal(). -
-
- - -
-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
-
Several flavors of constructor are provided. The most commonly used is: - 
-shared_vector(size_t c);
-
- This creates a shared_vector of the specified size/ -
-
max_size
-
The maximum size the C++ implementation allows, i.e., - the maximum possible capacity. - Note that units are number of elements not number of bytes. -
-
capacity
-
The current capacity.
-
reserve
-
Set array capacity.
-
resize
-
Grow or shrink array. - It the second argument is given it is the value to assign to - and new elements. -
-
make_unique
-
Ensure (by copying) that this shared_vector - is the sole owner of the data array. -
-
begin,...,rend
-
Standard iterators.
-
front
-
Return a reference to the first element.
-
back
-
Return a reference to the last element.
-
push_back
-
Add an element to the end of the array.
-
pop_back
-
Remove an element from the end of the array.
-
data
-
Return a pointer to the raw array.
-
operator[](size_t i)
-
Return a reference to the specified element.
-
at
-
Like the previous except that it throws a range-error if - the specified element is out of range.
-
operator=
-
Copy an existing shared_vector.
-
swap
-
Swap the contents of this vector with another.
-
clear
-
Clear contents.
-
unique
-
returns (true,false) if data (is not, is) shared.
-
size
-
Number of elements visible through this vector.
-
empty
-
Is the number of elements zero?
-
slice
-
Reduce the view of this shared_vector.
-
dataPtr
-
A read-only shared_ptr to the array.
-
dataOffset
-
Offset in the data array of first visible element.
-
dataCount
-
Number of visible elements between dataOffset and end of data.
-
dataTotal
-
The total number of elements between dataOffset and the end of data
-
-

TBD -Michael should decide if this is the correct set of methods to describe. -Also he should check for correct descriptions. -

- - -

status.h

- -

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:

-
-
StatusType
-
An enum for the status type.
-
getType
-
Get the statusType.
-
getMessage
-
Get a message explaining the error.
-
getStackDump
-
Get a stack dump.
-
- -

The StatusCreate methods are:

-
-
getStatusOK
-
Get a singleton that returns StatusType.OK and a null message and - stackDump.
-
createStatus
-
Create a new Status.
-
deserializeStatus
-
Use this method instead of Status.deserialize(), since this allows OK - status optimization.
-
-

templateMeta.h

-

TBD Michael will explain.

- -

thread.h

- -

ThreadPriority

-
enum ThreadPriority {
-    lowestPriority,
-    lowerPriority,
-    lowPriority,
-    middlePriority,
-    highPriority,
-    higherPriority,
-    highestPriority
-};
- -

Thread

-
-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:

-
-
Thread
-
The constructor. A thread name and priority must be specified. The run - methods of runnable is executed. When the run methods returns the thread - will no longer be active but the client code must still delete the - thread.
-
~Thread
-
The destructor. This is called as the result of: - 
    delete pthread;
-
-
- -

timeFunction.h

- -

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:

-
-
function
-
This is the function.
-
- -

TimeFunction has the methods:

-
-
TimeFunction
-
Constructor.
-
~TimeFunction
-
Destructor.
-
timeCall
-
Time how long it takes to execute the function. It starts by calling - the function one time. If it takes < 1 seconds to doubles the number - of times to call the function. It repeats this until it takes at least - one second to call it ntimes.
-
- -

timer.h

- -

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: -

-
-
callback
-
This is called when a timer expires. This is called with no locks held. - When called a delay timer is no longer on the queue but a periodic timer - is on a queue. Thus the callback for a delay timer can issue a new - schedule request but a periodic timer must not. Note the explanation of - TimerNode.cancel below.
-
timerStopped
-
Timer.stop was called when a timer request was queued. or if the timer - is stopped and a schedule request is made.
-
- -

In order to schedule a callback client code must allocate a TimerNode It can -be used to schedule multiple callbacks. It has the methods:

-
-
TimerNode
-
The constructor. User code must create a TimeNode in order to call a - schedule method.
-
~TimerNode
-
The destructor. This is called as a result of the client calling: - 
    delete timerNode;
-
-
cancel
-
This is called to cancel a timer request. If a callback has been - dequeued but the callback not called when cancel is called then a - callback may still happen. New schedule requests can be made after a - cancel request has been made.
-
isScheduled
-
Is the timerNode scheduled to be called.
-
- -

Timer has the methods:

-
-
Timer
-
The constructor.
-
~Timer
-
The destructor. The queue is emptied and TimerCallback.timerStopped is - called for each element of the queue.
-
scheduleAfterDelay
-
A request to schedule a callback after a delay specified in - seconds.
-
schedulePeriodic
-
Schedule a periodic callback.
-
-

typeCast.h

-

TBD Michael will explain.

- -

src/pvMisc

- -

bitSetUtil.h

- -

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:

-
-
compress
-
Compress the bits in a BitSet related to a structure.
- For each structure: -
    -
  1. If the bit for the structure is set then the bit for all subfields - of the structure are cleared.
    2. -
  2. If the bit for the structure is not set but all immediate subfields - have their bit set then the bit for the structure is set and the bits - for all subfields are cleared.
    3. -
- Note that this is a recursive algorithm. That is if every immediate - subfield has it's offset bit set then the bits for ALL fields that reside - in the structure will be cleared.
-
Channel Access can call this before sending data. It can then pass - entire structures if the structure offset bit is set.
-
- -

src/copy and src/monitor

-

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:

-
-
createRequest
-
- The Channel create methods in pvAccess all have an argument - PVStructure pvRequest.
- Given an ascii string createRequest creates a PVStructure that provides - a pvData representation of the information from the ascii string. - It is this structure that can be passed to the channel create methods.
- The information in a pvRequest selects an arbitrary subset of the - fields in a top level structure that resides in the server. - In addition options can be specified. Both global and field specific - options can be specified. -
-
pvCopy
-
This is a facility used by channel providers. - It provides client specific code that manages a copy of an arbitrary - subset of the fields in a top level structure that resides in the - provider. It also allows provider access to options specified - by the client. -
-
-Monitor provides: -
-
monitor
-
This is support code for channel providers that implement channel - monitor. It, together with the queue facility, provides support for - monitor queues. -
-
monitorPlugin
-
This is support for implementing monitor plugins. - A monitor plugin can be developed that has no knowledge - of pvAccess but only pvData. -
-
-

src/copy

-

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. -

- -

createRequest

-

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
-}
-
-

pvCopy

-

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  &copyPVStructure,
-        BitSetPtr const  &bitSet);
-     void updateCopySetBitSet(
-        PVStructurePtr const  &copyPVStructure,
-        BitSetPtr const  &bitSet);
-    void updateCopyFromBitSet(
-        PVStructurePtr const  &copyPVStructure,
-        BitSetPtr const  &bitSet);
-    void updateMaster(
-        PVStructurePtr const  &copyPVStructure,
-        BitSetPtr const  &bitSet);
-    PVStructurePtr getOptions(std::size_t fieldOffset);
-    std::string dump();
-...
-};
-
-where -
-
PVCopyTraverseMasterCallback::nextMasterPVField
-
- PVCopyTraverseMasterCallback is a callback which must - be implemented by the code that uses pvCopy, normally - the channel provider. It has the single method nextMasterPVField -
- nextMasterPVField is called for each field in the master - as a result of a call to traverseMaster. -
-
create
-
- This is the method for creating a PVCopy instance.
-
-
pvMaster
-
the top level structure managed by the server.
-
pvRequest
-
selects the set of subfields desired - and options for each field.
-
structureName
-
the name for the top level of any PVStructure created. -
-
-
-
getPVMaster
-
- Gets the top level structure from pvMaster. -
-
traverseMaster
-
- Traverse all fields of the top level structure of pvMaster. - For each field the callback is called. -
-
getStructure
-
- Get the introspection interface for a PVStructure for e copy. -
-
createPVStructure
-
Create a copy instance. - Monitors keep a queue of monitor elements. - Since each element needs a PVStructure, multiple top level structures - will be created. -
-
getCopyOffset
-
Given a field in pvMaster. - return the offset in copy for the same field. - A value of std::string::npos means that the copy does not have this field. - Two overloaded methods are provided. The first is called if - the field of master is not a structure. The second is for - subfields of a structure. -
-
getMasterPVField
-
- Given a offset in the copy get the corresponding field in pvMaster. -
-
initCopy
-
- Initialize the fields in copyPVStructure - by giving each field the value from the corresponding field in pvMaster. - bitSet will be set to show that all fields are changed. - This means that bit set will have the value {0}. -
-
updateCopySetBitSet
-
- Set all fields in copyPVStructure to the value of the corresponding field - in pvMaster. Each field that is changed has it's corresponding - bit set in bitSet. -
-
updateCopyFromBitSet
-
- For each set bit in bitSet set the field in copyPVStructure to the value - of the corresponding field in pvMaster. -
-
updateMaster
-
- For each set bit in bitSet set the field in pvMaster to the value - of the corresponding field in copyPVStructure. - -
-
getOptions
-
- Get the options for the field at the specified offset. - A NULL is returned if no options were specified for the field. - If options were specified,PVStructurePtr is - a structure with a set of PVString subfields that specify name,value - pairs. name is the subField name and value is the subField value. -
-
- - - - -

src/monitor

-

This consists of two components:

-
-
monitor
-
Used by code that implements pvAccess monitors.
-
monitorPlugin
-
Code that provides special semantics for monitors.
-
-

monitor

-
-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

-

MonitorElement holds the data for one element of a monitor queue. -It has the fields: -

-
-
pvStructurePtr
-
A top level structure with data values at the time the monitors occurs.
-
changedBitSet
-
Shows which fields have changed since the previous monitor.
-
overrunBitSet
-
Shows which fields have changed more than once since the previous monitor.
-
-

monitorElement queue

-

-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

-

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:

-
-
start
-
- Start monitoring. - This will result in a an initial monitor that has the current value - of all fields. -
-
stop
-
- Stop monitoring. -
-
poll
-
- Called to get a monitor element. - If no new elements are available then a null pointer is returned. -
-
release
-
- Release the monitor element. - The caller owns the monitor element between the calls to poll and release. -
-
-

MonitorRequester

-

This must be implemented by a pvAccess client. -It has the methods:

-
-
monitorConnect
-
- A monitor has either connected of disconnected. -
-
monitorEvent
-
- A new monitor element is available. -
-
unlisten
-
- The channel is going away. The client cam no longer access the monitor. -
-
- -

monitorPlugin

-
-class MonitorPlugin
-{
-    virtual std::string const & getName() = 0;
-    virtual bool causeMonitor(
-        PVFieldPtr const &pvField,
-        PVStructurePtr const &pvTop,
-        MonitorElementPtr const &monitorElement) = 0;
-    virtual void monitorDone(
-        MonitorElementPtr const &monitorElement);
-    virtual void startMonitoring();
-    virtual void stopMonitoring();
-    virtual void beginGroupPut();
-    virtual void endGroupPut();
-};
-
-class MonitorPluginCreator
-{
-    virtual MonitorPluginPtr create(
-        FieldConstPtr const &field,
-        StructureConstPtr const &top,
-        PVStructurePtr const &pvFieldOptions) = 0;
-     virtual std::string const & getName() = 0;
-}
-
-class MonitorPluginManager
-{
-    static MonitorPluginManagerPtr get();
-    bool addPlugin(
-         std::string const &pluginName,
-         MonitorPluginCreatorPtr const &creator);
-    MonitorPluginCreatorPtr findPlugin(std::string const &pluginName);
-    void showNames();
-};
-
-
-

MonitorPlugin

-

MonitorPlugin must be implemented by the plugin implementation. -It has methods:

-
-
getName
-
Get the name of the plugin.
-
causeMonitor
-
- Should the value of pvField cause a monitor to be raised. - pvField and pvTop are fields in the top level structure - being monitored. monitorElement has the top level structure - for the copy
. - The implementation should not modify the fields in the structure - being monitored. - Called with pvTop locked. -
-
monitorDone
-
- Called just before monitorElement will be given to client. - The plugin can change the data values and bitSets in monitorElement. - Called with pvTop unlocked. -
-
startMonitoring
-
- Monitoring is starting. -
-
stopMonitoring
-
- Monitoring is being stopped. -
-
beginGroupPut
-
- A set of puts is starting. - Called with pvTop locked. -
-
endGroupPut
-
- The set of puts is complete. - Called with pvTop locked. -
-
-

MonitorPluginCreator

-

MonitorPluginCreator must also be implemented by the plugin implementation. -It is called for each field instance that has options of the from -[plugin=name...] where name is the name of the plugin. -Note that a plugin instance will belong to a single client. -It has methods:

-
-
getName
-
Get the name of the plugin.
-
create
-
- Create a new plugin instance. - If the arguments are not compatible with the plugin a NULL shared pointer is - returned.
- pvFieldOptions is - a structure with a set of PVString subfields that specify name,value - pairs. name is the subField name and value is the subField value.
- Note that a plugin will below to a single client. -
-
-

MonitorPluginManager

-

MonitorPluginManager has the methods:

-
-
get
-
- MonitorPluginManager is a singleton. - The first call to get will create the single instance. - Further calls will return the single instance. -
-
addPlugin
-
- Add a new plugin. -
-
findPlugin
-
- Find a plugin. A NULL shared pointer is returned if it has not been added. -
-
showNames
-
- Show the names of all plugins that have been added. -
-
-

NOTE: -Should the method causeMonitor -have arguments pvField and pvTop -be defined so that they can not be modified. -This would be possible if the following was defined: -

-
-typedef std::tr1::shared_ptr<const PVField> PVFieldConstPtr;
-typedef std::tr1::shared_ptr<const PVStructure> PVStructureConstPtr;
-
-then the definition for causeMonitor could be: -
-virtual bool causeMonitor(
-        PVFieldConstPtr const &pvField,
-        PVStructureConstPtr const &pvTop,
-        MonitorElementPtr const &monitorElement) = 0;
-
-But just adding these definitions is not sufficient. -In addition all methods defined in pvDataCPP must be checked. -In particular many of the methods in Convert must have -their arguments modified. -Big job. -

monitorPlugin example

-

Example Plugin Overview

-

This section describes an example plugin that:

- -

As an example assume that a channel provided by pvAccess has a top level structure -that represents a power supply.

-
-structure powerSupply
-    structure alarm
-    structure timeStamp
-    structure power
-       double value
-       structure alarm
-       structure display
-    structure voltage
-       double value
-       structure alarm
-       structure display
-    structure current
-       double value
-       structure alarm
-       structure display
-
-

A pvAccess client wants to create a monitor on the powerSupply as follows: -The client wants a top level structure that looks like: -

-
-structure powerSupply
-    structure alarm
-    structure timeStamp
-    structure power
-       double value
-    structure voltage
-       double value
-    structure current
-       double value
-
-In addition the client wants monitors to occur only when one of the monitored -fields changes value but not just because a put occurred. -Also if only the timeStamp changes value then that should not cause a monitor. -

The example monitor plugin implements the semantics the -client wants. It can be attached to any field via the following options: -

-
-[plugin=onChange,raiseMonitor=value]
-
-This plugin will trigger a monitor for the field only if the field changes -value. In addition value equals false means do not raise a monitor -for changes to this field. -But if a change to another field does cause a monitor the change to this field -will be passed to the client. -

-Assume that the client has already connected to the channel. -The client can then issue the commands:

-
-std::string request("field(alarm[plugin=onChange]");
-request += ",timeStamp[plugin=onChange,raiseMonitor=false]";
-request += ",power.value[plugin=onChange";
-request += ",voltage.value[plugin=onChange";
-request += ",current.value[plugin=onChange";
-
-PVStructurePtr pvRequest = createRequest->createRequest(request);
-
-MonitorPtr monitor = channel->createMonitor(monitorRequester,pvRequest);
-
-

Example Plugin Code

-

The header file to create the example has the definition:

-
-class ExampleMonitorPlugin{
-public:
-    static void create();
-};
-
-

The implementation is:

-
-class OnChangePlugin : public MonitorPlugin
-{
-public:
-    virtual ~OnChangePlugin(){}
-    OnChangePlugin() {}
-    bool init(
-        FieldConstPtr const &field,
-        StructureConstPtr const &top,
-        PVStructurePtr const &pvFieldOptions)
-   {
-        pvField = getPVDataCreate()->createPVField(field);
-        raiseMonitor = true;
-        if(pvFieldOptions!=NULL) {
-            PVStringPtr pvString =
-                pvFieldOptions->getSubField<PVString>("raiseMonitor");
-                if(pvString!=NULL) {
-                    std::string value = pvString->get();
-                    if(value.compare("false")==0) raiseMonitor = false;
-                }
-        }
-        return true;
-   }
-   virtual std::string &getName(){return pluginName;}
-   virtual bool causeMonitor(
-        PVFieldPtr const &pvNew,
-        PVStructurePtr const &pvTop,
-        MonitorElementPtr const &monitorElement)
-   {
-       bool isSame = convert->equals(pvNew,pvField);
-       if(isSame) return false;
-       convert->copy(pvNew,pvField);
-       return raiseMonitor;
-   }
-private:
-   PVFieldPtr pvField;
-   bool raiseMonitor;
-};
-class OnChangePluginCreator : public MonitorPluginCreator
-{
-public:
-    virtual std::string &getName(){return pluginName;}
-    virtual MonitorPluginPtr create(
-        FieldConstPtr const &field,
-        StructureConstPtr const &top,
-        PVStructurePtr const &pvFieldOptions)
-   {
-       OnChangePluginPtr plugin(new OnChangePlugin());
-       bool result = plugin->init(field,top,pvFieldOptions);
-       if(!result) return MonitorPluginPtr();
-       return plugin;
-   }
-
-};
-
-void ExampleMonitorPlugin::create()
-{
-    static OnChangePluginCreatorPtr plugin;
-    static Mutex mutex;
-    Lock xx(mutex);
-    if(plugin==NULL) {
-        plugin = OnChangePluginCreatorPtr(new OnChangePluginCreator());
-        MonitorPluginManager::get()->addPlugin(pluginName,plugin);
-    }
-}
-
- - -
- -