EPICS pvDataCPP

EPICS v4 Working Group, Working Draft, 19-Dec-2011

This version:
pvDataCPP_20111219.html
Latest version:
pvDataCPP.html
Editors:
Marty Kraimer, BNL

Abstract

pvData (Process Variable Data) defines and implements an efficent way to store, access, and transmit memory resident structured data.

This document describes the C++ implementation of EPICS v4 pvData.

For more information about the EPICS, please refer to the home page of the Experimental Physics and Industrial Control System.

Status of this Document

This is the 19-Dec-2011 version of the C++ implementation of pvData. It is a complete implementation of pvData as currently defined.

TODO

CONTENTS


Preface


This product is available via an open source license

This is the overview for pvDataCPP. Doxygen documentation is available at doxygenDoc

pvData is one of a set of related projects:

pvData
Describes and implements structured data.
pvAccess
Provides networking for pvData.
pvIOC
Provides a database based on pvData together with record processing, record scanning, and extensible support.

pvData

pvData describes and implements structured data. Interspection interfaces are used to describe the data and for each type of data a data interface provides a container to hold the data.

Introspection

pvData is modeled as a structured set of fields. A field has a name are a type. The type must be one of:

scalar
A scalar has a scalar type which must be one of the following:
boolean
Is always either true or false.
byte
An 8 bit signed integer.
short
A 16 bit signed integer.
int
A 32 bit signed integer.
long
A 64 bit signed integer.
float
A IEEE 32 bit float.
double
A IEEE 64 bit float.
string
A UTF8 string.
scalarArray
An array where all elements have the same scalar type.
structure
An array of fields. Each field can have a different type including structure. Thus complex structured data is supported.
structureArray
An array of structure fields where each element has the exact same introspection interface.

Introspection interface Field provides the name and type for the field. In addition each type has an introspection interface: Scalar, ScalarArray, Structure, and StructureArray.

Data

Interface PVField provides access to the common information of every data container. In addition every possible type has an interface for accessing the data:

scalar
The interfaces are PVBoolean, PVByte, PVShort, PVInt, PVLong, PVFloat, PVDouble, and PVString.
scalarArray
The interfaces are PVBooleanArray, PVByteArray, PVShortArray, PVIntArray, PVLongArray, PVFloatArray, PVDoubleArray, and PVStringArray.
structure
The interface is PVStructure.
structureArray
The interface is PVStructureArray.

Property Structures

pvData provides support, via pvData structures and associated support, for the following:

timeStamp
Time since the POSIX Epoch.
alarm
Alarm information.
display
Display Info
control
Control Info.
enumerated structrure
This is a pvData structure with two field: index and choices.

pvAccess

pvAccess provides client/server support for transmitting pvData objects. The server must provide access to objects identified by name. Each object must have a network wide unique name. A client issues a create channel request, specifying the channel name in order to connect to the object on the server. After the client has connected, it can issue the following types of request.

process
Asks that the channel process. The process semantics are determined by the server.
get
Ask the get data from the server. The client can optionally ask the server to process before returning data.
put
Puts data to the server. The server can optionally be asked to process after receiving the data.
putGet
Puts data to the server, optionally ask the server to process, and then get data from the server.
monitor
Request that the server send data to the client when new data is available.
channelArray
This can get and put a sub- array.
channelRPC
This is similar to a putGet except that the server will create a new PVStructure and send it to the client.

Associated with each type of request is a create method. The method has an argument that allows the client to specify options. This argument is a top level PVStructure called a pvRequest. The pvRequest is sent to the server. The server side looks at what is requested and creates a top level PVStructrure that will hold the data that is transfered between client and server. It then sends the introspection info to the client side of pvAccess, which also creates a top level PVStructure for holding data. At this time the client is notified that it can start making requests. Thus when data is passed between client and server it flows between the two top level PVStructures without requiring the creation on new objects.

pvAccess provides many of the features of systems like CORBA and ICE (Internet Communication Engine) but is designed to provide the following features:

No IDL (Interface Definition Language) or associated compiler
The introspection interfaces replace the IDL.
Efficent use of network
Introspection info is only passed at creation time. For data requests data is passed without any interspection information.
Multiple small objects are automatically combined into a single network packet.
Large objects automatically span network packets.

pvIOC

IOC means Input/Output Controller, which is an EPICS term. A pvIOC is modeled after an EPICS IOC but supports pvData instead of flat record structures. At the present time the only implementation is in Java and called javaIOC. The c++ implementaion will be called pvIOC and will be able to run in an existing EPICS IOC.

Like an EPICS IOC a pvIOC provides the followig features:

Record Processing
A record can be processed, i.e. records are "smart". Each field can optionally have attached support. When a record is asked to process the support attacked to the top level PVStructure is called.
Record Scanning
A record can be scanned. Two types are supported: periodic and event. The way event scanning is implemented provides both the I/O Intr scanning and event scanning implemented by a EPICS IOC.
Extensible Support
Each field can optionally have support attached. Support is written to process particular types of fields. At initilization support uses interspection to look at the fields to which it is attached. If the fields are not what it expects it reports a problem and terminates.

For pvAccess, the pvIOC provides the following:

Local channel implementation
The way the remote pvAccess server code works is to find one or more local implementations of the Channel interface. It calls this to implement the various operations it supports.
Access to data
Support is a available that allows a client to access an arbitrary set of fields in a record. From this it creates a top level structure that holds the copy of the fields. It also provides the support to copy date between the copy and the record. It also provides support for monitor queues and algortihms.
Access to EPICS V3 records
This is a local Channel implementation that privides support for attaching to V3 records. It makes the V3 fields look like a pvData structure.
Access to pvIOC records
This is a local Channel implementation that privides support for attaching to pvIOC records.

Introduction


PVData is one of a set of related projects: pvData, pvAccess, and javaIOC. It describes and implements the data that the other projects use. Thus it is not useful by itself but understanding pvData is required in order to understand the other projects. The reader should also become familar with pvAccess and javaIOC, which are located via the same sourceforge site as this project. Project PVAccess provides network support for transporting pvData. Project javaIOC provides a memory resident "smart" database of pvData data.

This document describes the C++ implementation of pvData, which was first implemented in Java. A C++ implementation of pvAccess is being developed in parallel with pvDataCPP. In the future a C++ implementation of javaIOC will be developed and the name javaIOC will become pvIOC.

pvData (Process Variable Data) defines and implements an efficent way to store, access, and transmit memory resident structured data.

description
The header files pvIntrospect.h and pvData.h provide the C++ description of pvData.
implementation
Directory factory provides a complete C++ definition for pvData. It also provides abstract and base classes that support specialized implementations of the data classes.
efficient
Small memory footprint, low cpu overhead, and concise code base.
data storage
pvData provides introspection and data interfaces. The introspection interfaces provide access to immutable objects, which allows introspection instances to be freely shared. The introspection interface for a process variable can be accessed without requiring access to the data.
data access
Client code can access pvData via the introspection and data interfaces. For "well known" data, e.g. timeStamp, specialized interfaces can be implemented without requiring any changes to the core software.
data transfer
The separation of introspection and data interfaces allows for efficient network data transfer. At connection time introspection information is passed from server to client. Each side creates a data instance. The data is transferred between these instances. The data in the network packets does not have to be self describing since each side has the introspection information.
memory resident
pvData only defines memory resident data.
structured data
pvData has four types: scalar, scalar array, structure, and structure array. A scalar can be one of the following: boolean, byte, short, int, long, float, double, string. A scalar array is a one dimensional array with the element type being one of the scalar types. A structure is an ordered set of fields where each field has a name and type. A structure array is a one dimensional array of structures where each element has the same introspection interface. Since a field can have type structure complex structures are supported. No other types are needed since structures can be defined that simulate types.

The javaIOC implements a Process Variable (PV) Database, which is a memory resident database holding pvData with the following features:

pvData was initially created to support the javaIOC and was part of the javaIOC project. It is now a separate project that is used by the javaIOC. In addition to the javaIOC, pvData is intended for use by 1) channel access clients, 2) Interface between client and network, 3) Interface between network and channel access server, 4) Interface between server and IOC database. Since it is an interface to data, it could also be used by other systems, e.g. TANGO, TINE, etc. A high level Physics application can hold data as pvData. By starting a channel access server, the data can made available to network clients.

pvData contains everything required to support Channel Access and Channel Access clients and servers.

This project has many concepts that are similar to EPICS (Experimental Physics and Industrial Control System). This C++ implementation uses the EPICS build system and also EPICS libCom. The directory structure for this project is a standard EPICS application. The following source directories appear under pvDataApp:

misc
Support for pvData. This support is described in a major section below.
pv
The C++ introspection and data descriptions for pvData.
factory
The C++ definitions for pvData.
property
Support code for "standard" pvData structures, e.g. timeStamp and alarm.

PVData Meta Language


This section describes a meta language for describing pvData. Currently there are no plans for a parser for the meta language. It is used for documentation. The toString introspection and data methods described below do present data in a format similar to the metadata syntax. The meta language is used to describe both introspection interfaces and data interfaces.

Definition

PVData supports structured data. All data appears as a top level structure. A structure has an ordered set of fields where each field has a fieldDef defined as follows:

type fieldName value // comment

where value is present for data objects and // indicates the the rest of the line is a comment.

type is one of the following:

scalar
A scalar field can be any of the following:
boolean
Has the valuetrue or false
byte
An 8 bit signed integer.
short
An 16 bit signed integer.
int
An 32 bit signed integer.
long
An 64 bit signed integer.
float
A IEEE float.
double
A IEEE double.
string
An immutable string.
scalarArray
A scalarArray field is an array of any of the scalar types.
boolean[]
byte[]
short[]
int[]
long[]
float[]
double[]
string[]
structure
A structure field has the definition:
     structure fieldName
         fieldDef
         ...
      
or
     xxx_t fieldName
         // if data object then following appear
         fieldDef
         ...
      
For structure fieldName each fieldDef must have a unique fieldName within the structure For "xxx_t fieldName" xxx_t must be a previously structure definition of the form:
    structure xxx_t
        ...
structureArray
A structureArray field has the definition:
     structure[] fieldName
          structureDef
          ...
          

or

    xxx_t[] fieldName
      

Thus a structure array is an array where each element is a structure but all elements have the same introspection interface. For introspection the structureDef appears once without any data valuies.

The above is used to describe introspection objects. Data objects are describe in a similar way but each scalar field and each array field has data values. The definition of the data values depends on the type. For scalars the data value is whatever is valid for the type.

boolean
The value must be true or false
byte,...long
Any valid integer or hex value, e.g. 3 0xff are valid values
float,double
Any valid integer or real e.g. 3 3.0 3e0 are valid values
string
The value can be an alphanumeric value or any set of characters enclosed in "" Within quotes a quote is expressed as \" Examples are aValue "a value" "a\" xxx" are valid values.

For scalar arrays the syntax is:

      = [value,...,value]

where each value is a valid scalar data value depending on the type. Thus it is a comma separated set of values enclosed in [] White space is permitted surrounding each comma.

Examples

Define the following top level structure:

structure timeStamp_t
    long secondsPastEpoch
    int nanoSeconds 

Then the following introspection objects can be defined:

structure scalarDoubleExample // introspection object
    double value
    timeStamp_t timeStamp
or
structure scalarDoubleExample // introspection object
    double value
    structure timeStamp
        long secondsPastEpoch
        int  nanoSeconds

The following data objects can be defined:

structure scalarDoubleExample // data object
    double value 1.0
    timeStamp_t timeStamp
         long secondsPastEpoch 0
         int  nanoSeconds 0
or
scalar arrayDoubleExample
    double[] value  [1.0,2.0]
    structure timeStamp
         long secondsPastEpoch 0
         int  nanoSeconds 0

If the following interface is defined:

structure point_t
    double x
    double y

Then the following introspection objects can be defined:

structure lineExample
    point_t begin
    point_t end

structure pointArrayExample
    point_t[] points
    
or
structure lineExample
    structure begin
        double x
        double y
    structure end
        double x
        double y

structure pointArrayExample
    structure[] points
        structure point
            double x
            double y

And the following data objects can be defined:

structure lineExample
    point_t begin
        double x 0.0
        double y 0.0
    point_t end
        double x 10
        double y 10

structure pointArrayExample
    point_t[] value
        structure point
            double x 0.0
            double y 0.0
        structure point
            double x 10.0
            double y 10.0

or

structure lineExample
    structure begin
        double x 0
        double y 0
    structure end
        double x 10
        double y 10

structure pointArrayExample
    structure[] value
        structure point
            double x 0.0
            double y 0.0
        structure point
            double x 10.0
            double y 10.0

PV - User Description


Overview

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

A PVStructure is a field that contains an array of subfields. Each field has code for accessing the field. The interface for each field is PVField or an interface that extends PVField. Each field also has an introspection interface, which is Field or an extension of Field. This section describes the complete set of data and introspection interfaces for pvData.

A class FieldCreate creates introspection objects. A class PVDataCreate creates data objects. A 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 the pvData 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

This provides C/C++ definitions for the pvData primitive types: boolean, byte, short, int, 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 bool     boolean;
typedef int8_t   byte;
typedef int8_t   int8;
typedef int16_t  int16;
typedef int32_t  int32;
typedef int64_t  int64;
typedef uint32_t uint32;
typedef uint64_t uint64;
// float and double are types
typedef std::string String;

typedef bool * BooleanArray;
typedef int8 * ByteArray;
typedef int16 * ShortArray;
typedef int32 * IntArray;
typedef int64 * LongArray;
typedef float * FloatArray;
typedef double * DoubleArray;
typedef String* StringArray;

// convenience definition for toString methods
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,...,int64
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. Note that byte and int8 are both defined just for consistency. The unsigned 32 and 64 bit integer definitions are provided because the serialization/deserialization code uses them. Thus they must be compatable over the network.
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
A typedef is provided for an array of each of the primitive types.

Process Variable Reflection

This subsection describes pvIntrospect.h

Given a pvname, which consists of a record name and field name, it is possible to introspect the field without requiring access to data. The reflection and data interfaces are separate because the data may not be available. For example when a 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,
    pvFloat,pvDouble,
    pvString;
};

class ScalarTypeFunc {
public:
    static bool isInteger(ScalarType type);
    static bool isNumeric(ScalarType type);
    static bool isPrimitive(ScalarType type);
    static ScalarType getScalarType(String value);
    const char* name(ScalarType);
    static 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.
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,...pvlong.
isNumeric
Is the scalarType numeric, i.e. pvByte,...,pvDouble.
isPrimitive
Is the scvalarType 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.

Reflection Description

This section describes the reflection interfaces which provide the following:

Field
A field:
Has a name.
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 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;


protected:class Field :  public std::tr1::enable_shared_from_this<Field> {
public:
    typedef std::tr1::shared_ptr<Field> shared_pointer;
    typedef std::tr1::shared_ptr<const Field> const_shared_pointer;

    String getFieldName() const{return m_fieldName;}
    Type getType() const{return m_type;}
    virtual void toString(StringBuilder buf) const{toString(buf,0);}
    virtual void toString(StringBuilder buf,int indentLevel) const;
    void renameField(String  newName);
    Field(String fieldName,Type type);
    virtual ~Field();
};

class Scalar : public Field{
public:
   typedef std::tr1::shared_ptr<Scalar> shared_pointer;
   typedef std::tr1::shared_ptr<const Scalar> const_shared_pointer;
   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;
protected:
   Scalar(String fieldName,ScalarType scalarType);
   virtual ~Scalar();
 ...
};

class ScalarArray : public Field{
public:
   typedef std::tr1::shared_ptr<ScalarArray> shared_pointer;
   typedef std::tr1::shared_ptr<const ScalarArray> const_shared_pointer;
   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;
protected:
   ScalarArray(String fieldName,ScalarType scalarType);
   virtual ~ScalarArray();
 ...
};

class StructureArray : public Field{
public:
  typedef std::tr1::shared_ptr<StructureArray> shared_pointer;
   typedef std::tr1::shared_ptr<const StructureArray> const_shared_pointer;
   typedef StructureArray& reference;
   typedef const StructureArray& const_reference;

   const Structure& structure() const {return *pstructure;}
   StructureConstPtr  getStructure() const {return pstructure;}
   virtual void toString(StringBuilder buf,int indentLevel=0) const;
};

class Structure : public Field {
public:
   typedef std::tr1::shared_ptr<Structure> shared_pointer;
   typedef std::tr1::shared_ptr<const Structure> const_shared_pointer;
   typedef Structure& reference;
   typedef const Structure& const_reference;

   int getNumberFields() const {return numberFields;}
   FieldConstPtr getField(String fieldName) const;
   int getFieldIndex(String fieldName) const;
   FieldConstPtrArray getFields() const {return fields;}
   void appendField(FieldConstPtr field);
   void appendFields(int numberFields,FieldConstPtrArray fields);
   void removeField(int index);
   virtual void toString(StringBuilder buf) const{toString(buf,0);}
   virtual void toString(StringBuilder buf,int indentLevel) const;
protected:
   Structure(String fieldName, int numberFields,FieldConstPtrArray fields);
   virtual ~Structure();
 ...
};

class FieldCreate : NoDefaultMethods {
public:
   FieldConstPtr  create(String fieldName,FieldConstPtr  field) const;
   ScalarConstPtr  createScalar(String fieldName,ScalarType scalarType) const;
   ScalarArrayConstPtr createScalarArray(String fieldName,
       ScalarType elementType) const;
   StructureConstPtr createStructure (String fieldName,
       int numberFields,FieldConstPtrArray fields) const;
   StructureArrayConstPtr createStructureArray(String fieldName,
       StructureConstPtr structure) const;
};

extern FieldCreate * getFieldCreate();

The following methods are common to all of the reflection class descriptions:

Constructor and Destructor
Note that all constructors and destructors are protected or private. The only way to create instances is via FieldCreate. The implementation manages all storage and automatically calls delete when no client is attached. A few details are discussed in a later section.
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 has the methods:

getReferenceCount
Get the total number of current references to this field instance.
getFieldName
Get the name of the field.
getType
Get the field type.
renameField
Rename the field name.
incReferenceCount
Increment the reference count. This must be called by any code that wants to "clone" an instance of the introspection interface and use it as the introspection interface for a data field. The library that creates data instances usually calls this so user code almost never calls this. If the field is a structure then this is recursively called for each sub field of the structure.
decReferenceCount
This must be called to match each incReferenceCount. It is called when the "cloned" version is no longer needed. This is almost always called by a PVField instance when it is being deleted for a field that has no parents. If the field is a structure then this is recursively called for each sub field of the structure. OTHER code should not call this.
dumpReferenceCount
Adds a report of the the current reference count for this field. If the field is a structure then dumpReferenceCount is called for each sub field.
operator==
Returns (false,true) if the two objects (do not,do) have the same values. Thus means the same types and names.
operator!=
Returns (false,true) if the two objects (do,do not) have the same values.

Scalar has the methods:

getScalarType
Get that scalar type.

ScalarArray has the methods:

getElementType
Get the element type.

StructureArray has the methods:

getStructure
Get the introspection interface that each element shares,

Structure has the methods:

getNumberFields
Get the number of immediate subfields.
getField
Given a name 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,
appendField
Append a field to the Structure.
appendFields
Append the fields to the Structure. The caller is responsible for the storage for the array for the fields. It is OK if the array is allocate on the stack.
removeField
Remove the field at the specified index. An exception is thrown if the index is out of bounds.

FieldCreate has the methods:

create
Given a field name and an existing introspection interface create a new introspection object. The existing introspection interface can be any of the allowed types. If the argument field is shared, i.e. has been obtained from an existing oject, then field->incReferenceCount() must be called before this method.
createScalar
Create a scalar introspection instance.
createScalarArray
Create a scalar array introspection instance.
createStructure
Create a structure introspection instance. The FieldConstPtrArray fields MUST be allocated on the heap NOT on the stack. It will automatically be deleted when the structure instance is deleted. For any element of fields that is shared, i.e. has been obtained from an existing onject, then fields[index]->incReferenceCount() must be called before this method.
createStructureArray
Create a structure array introspection instance. If the argument structure is shared, i.e. has been obtained from an existing object, then structure->incReferenceCount() must be called before this method.

Standard Fields

The file standardField.h has a class description for creating or sharing Field objects for standard fields. For each type of standard object two methods are defined: one with no properties and with properties. 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 fieldName 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(
        String("value"),
        pvDouble,
        String("value,alarm,timeStamp"));

Will result in a Field definition that has the form:

structure example
    double value
    structure alarm
        structure severity
            int index
            string[] choices
       structure timeStamp
            long secondsPastEpoch
            int  nanoSeconds

In addition there are methods that create each of the property structures, i.e. the methods named: alarm, .... enumeratedAlarm."

standardField.h contains:

class StandardField : private NoDefaultMethods {
public:
    StandardField();
    ~StandardField();
    ScalarConstPtr scalar(String fieldName,ScalarType type);
    StructureConstPtr scalar(String fieldName,
        ScalarType type,String properties);
    ScalarArrayConstPtr scalarArray(String fieldName,
        ScalarType elementType);
    StructureConstPtr scalarArray(String fieldName,
        ScalarType elementType, String properties);
    StructureArrayConstPtr structureArray(String fieldName,
        StructureConstPtr structure);
    StructureConstPtr structureArray(String fieldName,
        StructureConstPtr structure,String properties);
    StructureConstPtr structure(String fieldName,
        int numFields,FieldConstPtrArray fields);
    StructureConstPtr enumerated(String fieldName);
    StructureConstPtr enumerated(String fieldName, String properties);
    ScalarConstPtr scalarValue(ScalarType type);
    StructureConstPtr scalarValue(ScalarType type,String properties);
    ScalarArrayConstPtr scalarArrayValue(ScalarType elementType);
    StructureConstPtr scalarArrayValue(ScalarType elementType,
        String properties);
    StructureArrayConstPtr structureArrayValue(StructureConstPtr structure);
    StructureConstPtr structureArrayValue(StructureConstPtr structure,
        String properties);
    StructureConstPtr structureValue(
        int numFields,FieldConstPtrArray fields);
    StructureConstPtr enumeratedValue(StringArray choices);
    StructureConstPtr enumeratedValue(StringArray choices,
         String properties);
    StructureConstPtr alarm();
    StructureConstPtr timeStamp();
    StructureConstPtr display();
    StructureConstPtr control();
    StructureConstPtr booleanAlarm();
    StructureConstPtr byteAlarm();
    StructureConstPtr shortAlarm();
    StructureConstPtr intAlarm();
    StructureConstPtr longAlarm();
    StructureConstPtr floatAlarm();
    StructureConstPtr doubleAlarm();
    StructureConstPtr enumeratedAlarm();
private:
    static void init();
};

extern StandardField * getStandardField();

Where

scalar
Create a scalar with the specified scalar type and name. If properties are specified then 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. If properties are specified then 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. If properties are specified then 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. If properties are specified then 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.
scalarValue
scalarArrayValue
structureArrayValue
structureValue
enumeratedValue
These are all like the version without the "Value" suffix. The field name will always be "value"
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.

PVField - Data Interfaces

This section defines the Java Interfaces for accessing the data within a PV record.

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:
    virtual void postPut() = 0;
};

class PVField
: public Serializable,
  private NoDefaultMethods
{
public:
    virtual ~PVField();
    virtual void message(String message,MessageType messageType) ;
    virtual void setRequester(Requester *prequester);
    int getFieldOffset() ;
    int getNextFieldOffset() ;
    int getNumberFields() ;
    PVAuxInfo * getPVAuxInfo();
    bool isImmutable() ;
    virtual void setImmutable();
    FieldConstPtr getField() ;
    PVStructure * getParent() ;
    bool renameField(String  newName);
    void postPut() ;
    void setPostHandler(PostHandler *postHandler);
    virtual bool equals(PVField &pv);
    virtual void toString(StringBuilder buf) ;
    virtual void toString(StringBuilder buf,int indentLevel) ;
protected:
    PVField(PVStructure *parent,FieldConstPtr field);
    void setParent(PVStructure *parent);
private:
};

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.

Serializable, and NoDefaultMethods are described in a later section.

The public methods for PVField are:

~PVField
destructor which must be called by whatever created the PVfield via a call to one of the methods of PVDataCreate
message
Code attached to this field can call this method to report problems.
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.
renameField
Rename the field name. (false,true) is returned if the name (was not,was) changed. It is not changed if the field is an an element of a structure that already has a field with the same 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.

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:
    PVAuxInfo(PVField *pvField);
    ~PVAuxInfo();
    PVField * getPVField();
    PVScalar * createInfo(String key,ScalarType scalarType);
    PVScalarMap getInfos();
    PVScalar * getInfo(String key);
    void toString(StringBuilder buf);
    void toString(StringBuilder buf,int indentLevel);
private:
};

where

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

PVScalar and extensions

class PVScalar : public PVField {
public:
    virtual ~PVScalar();
    ScalarConstPtr getScalar() ;
protected:
    PVScalar(PVStructure *parent,ScalarConstPtr scalar);
};
Primitive PVField types

The interfaces for primitive data types are:

template<typename T>
class PVScalarValue : public PVScalar {
public:
    typedef std::tr1::shared_ptr<PVScalarValue> shared_pointer;
    typedef std::tr1::shared_ptr<const PVScalarValue> const_shared_pointer;

    typedef T value_type;
    typedef T* pointer;
    typedef const T* const_pointer;

    virtual ~PVScalarValue() {}
    virtual T get() = 0;
    virtual void put(T value) = 0;
protected:
    PVScalarValue(PVStructure *parent,ScalarConstPtr scalar)
    : PVScalar(parent,scalar) {}
private:
};

typedef PVScalarValue<bool> PVBoolean;
typedef PVScalarValue<int8> PVByte;
typedef PVScalarValue<int16> PVShort;
typedef PVScalarValue<int32> PVInt;
typedef PVScalarValue<int64> PVLong;
typedef PVScalarValue<float> PVFloat;
typedef PVScalarValue<double> PVDouble;

// PVString is special case, since it implements SerializableArray
class PVString : public PVScalarValue<String>, SerializableArray {
public:
    virtual ~PVString() {}
protected:
    PVString(PVStructure *parent,ScalarConstPtr scalar)
    : PVScalarValue<String>(parent,scalar) {}
};

PVArray and Extensions

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:
    virtual ~PVArray();
    int getLength() ;
    void setLength(int length);
    int getCapacity() ;
    bool isCapacityMutable() ;
    void setCapacityMutable(bool isMutable);
    virtual void setCapacity(int capacity) = 0;
protected:
    PVArray(PVStructure *parent,FieldConstPtr field);
    void setCapacityLength(int capacity,int length);
};
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.
PVArray Extensions

The interface for each array type has get and put methods which have the same arguments except for the data type. For example PVDoubleArray is:

template<typename T>
class PVArrayData {
public:
    typedef std::tr1::shared_ptr<PVArrayData> shared_pointer;
    typedef std::tr1::shared_ptr<const PVArrayData> const_shared_pointer;

    typedef T  value_type;
    typedef T* pointer;
    typedef const T* const_pointer;

    pointer data;
    int offset;
};


class PVScalarArray : public PVArray {
public:
    typedef std::tr1::shared_ptr<PVScalarArray> shared_pointer;
    typedef std::tr1::shared_ptr<const PVScalarArray> const_shared_pointer;

    virtual ~PVScalarArray();
    ScalarArrayConstPtr getScalarArray() ;

protected:
    PVScalarArray(PVStructure *parent,ScalarArrayConstPtr scalarArray);
private:
};
template<typename T>
class PVValueArray : public PVScalarArray {
public:
    typedef std::tr1::shared_ptr<PVValueArray> shared_pointer;
    typedef std::tr1::shared_ptr<const PVValueArray> const_shared_pointer;

    typedef T  value_type;
    typedef T* pointer;
    typedef const T* const_pointer;
    typedef PVArrayData<T> ArrayDataType;

    virtual ~PVValueArray() {}
    virtual int get(int offset, int length, ArrayDataType *data) = 0;
    virtual int put(int offset,int length, pointer from, int fromOffset) = 0;
    virtual void shareData(pointer value,int capacity,int length) = 0;
protected:
    PVValueArray(PVStructure *parent,ScalarArrayConstPtr scalar)
    : PVScalarArray(parent,scalar) {}
private:
};
typedef PVArrayData<bool> BooleanArrayData;
typedef PVValueArray<bool> PVBooleanArray;

typedef PVArrayData<int8> ByteArrayData;
typedef PVValueArray<int8> PVByteArray;

typedef PVArrayData<int16> ShortArrayData;
typedef PVValueArray<int16> PVShortArray;

typedef PVArrayData<int32> IntArrayData;
typedef PVValueArray<int32> PVIntArray;

typedef PVArrayData<int64> LongArrayData;
typedef PVValueArray<int64> PVLongArray;


typedef PVArrayData<float> FloatArrayData;
typedef PVValueArray<float> PVFloatArray;

typedef PVArrayData<double> DoubleArrayData;
typedef PVValueArray<double> PVDoubleArray;

typedef PVArrayData<String> StringArrayData;
typedef PVValueArray<String> PVStringArray;

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

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 doubleArray getArray(PVDoubleArray *pv,doubleArray *to,int lenArray)
    {
        int len = pv->getLength();
        if(lenArray<len) len = lenArray;
        DoubleArrayData data;
        int offset = 0;
        while(offset < len) {
            int num = pv->get(offset,(len-offset),&data);
            doubleArray from = &data.data[data.offset];
            doubleArray to = &to[offset]
            int numbytes = num*sizeof(double);
            memcopy(from,to,numBytes);
            offset += num;
        }
    } 

shareData results in the PVArray using the primitive array that is passed to this method. 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.

PVStructure

The interface for a structure is:

class PVStructure : public PVField,public BitSetSerializable {
public:
    
};virtual ~PVStructure();
    StructureConstPtr getStructure();
    PVFieldPtrArray getPVFields();
    PVField *getSubField(String fieldName);
    PVField *getSubField(int fieldOffset);
    void appendPVField(PVField *pvField);
    void appendPVFields(int numberFields,PVFieldPtrArray pvFields);
    void removePVField(String fieldName);
    PVBoolean *getBooleanField(String fieldName);
    PVByte *getByteField(String fieldName);
    PVShort *getShortField(String fieldName);
    PVInt *getIntField(String fieldName);
    PVLong *getLongField(String fieldName);
    PVFloat *getFloatField(String fieldName);
    PVDouble *getDoubleField(String fieldName);
    PVString *getStringField(String fieldName);
    PVStructure *getStructureField(String fieldName);
    PVScalarArray *getScalarArrayField(
        String fieldName,ScalarType elementType);
    PVStructureArray *getStructureArrayField(String fieldName);
    String getExtendsStructureName();
    bool putExtendsStructureName(
        String 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(PVStructure *parent,StructureConstPtr structure);
    PVStructure(
        PVStructure *parent,
        StructureConstPtr structure,
        PVFieldPtrArray 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.
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.
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:

class StructureArrayData {
public:
    PVStructurePtrArray data;
    int offset;
};

class PVStructureArray : public PVArray {
public:
    virtual ~PVStructureArray() {}
    virtual StructureArrayConstPtr getStructureArray() = 0;
    virtual int append(int number) = 0;
    virtual bool remove(int offset,int number) = 0;
    virtual void compress() = 0;
    virtual int get(int offset, int length,
        StructureArrayData *data) = 0;
    virtual int put(int offset,int length,
        PVStructurePtrArray from, int fromOffset) = 0;
    virtual void shareData( PVStructurePtrArray value,int capacity,int length) = 0;
protected:
    PVStructureArray(PVStructure *parent,
        StructureArrayConstPtr structureArray);
};

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:
   PVField *createPVField(PVStructure *parent,
       FieldConstPtr field);
   PVField *createPVField(PVStructure *parent,
       String fieldName,PVField * fieldToClone);
   PVScalar *createPVScalar(PVStructure *parent,ScalarConstPtr scalar);
   PVScalar *createPVScalar(PVStructure *parent,
       String fieldName,ScalarType scalarType);
   PVScalar *createPVScalar(PVStructure *parent,
       String fieldName,PVScalar * scalarToClone);
   PVScalarArray *createPVScalarArray(PVStructure *parent,
       ScalarArrayConstPtr scalarArray);
   PVScalarArray *createPVScalarArray(PVStructure *parent,
       String fieldName,ScalarType elementType);
   PVScalarArray *createPVScalarArray(PVStructure *parent,
       String fieldName,PVScalarArray * scalarArrayToClone);
   PVStructureArray *createPVStructureArray(PVStructure *parent,
       StructureArrayConstPtr structureArray);
   PVStructure *createPVStructure(PVStructure *parent,
       StructureConstPtr structure);
   PVStructure *createPVStructure(PVStructure *parent,
       String fieldName,int numberFields,FieldConstPtrArray fields);
   PVStructure *createPVStructure(PVStructure *parent,
       String fieldName,int numberFields,PVFieldPtrArray pvFields);
   PVStructure *createPVStructure(PVStructure *parent,
       String fieldName,PVStructure *structToClone);
protected:
   PVDataCreate();
   friend PVDataCreate * getPVDataCreate();
};

extern PVDataCreate * 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. WARNING If the FieldConstPtr field argument is passed and field is already used by another data object then the caller MUST call field->incReferenceCount() before calling this method.
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. WARNING If the ScalarAConstPtr scalar argument is passed and scalar is already used by another data object then the caller MUST call scalar->incReferenceCount() before calling this method.
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. WARNING If the ScalarArrayConstPtr scalarArray argument is passed and scalarArray is already used by another data object then the caller MUST call scalarArray->incReferenceCount() before calling this method.
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. If structureArray is alreadt used by another data object than structureArray->incReferenceCount() MUST be called before calling this method.
createPVStructure
Create an instance of a PVStructure. Four methods are provided. The first method uses a previously created structure introspection interface. The second uses a Field array to initialize the sub-fields. For the third the PVField array is the subfields for the PVStructure. The parent of each PVField array element is set to the PVStructure being created. The forth 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. WARNING If theStructureConstPtr structure argument is passed and structure is already used by another data object then the caller MUST call structure->incReferenceCount() before calling this method.

Standard Data Fields

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 : private NoDefaultMethods {
public:
    StandardPVField();
    ~StandardPVField();
    PVScalar * scalar(PVStructure *parent,String fieldName,ScalarType type);
    PVStructure * scalar(PVStructure *parent,
        String fieldName,ScalarType type,String properties);
    PVScalarArray * scalarArray(PVStructure *parent,
        String fieldName,ScalarType elementType);
    PVStructure * scalarArray(PVStructure *parent,
        String fieldName,ScalarType elementType, String properties);
    PVStructureArray * structureArray(PVStructure *parent,
        String fieldName,StructureConstPtr structure);
    PVStructure* structureArray(PVStructure *parent,
        String fieldName,StructureConstPtr structure,String properties);
    PVStructure * enumerated(PVStructure *parent,
        String fieldName,StringArray choices, int number);
    PVStructure * enumerated(PVStructure *parent,
        String fieldName,StringArray choices, int number, String properties);
    PVScalar * scalarValue(PVStructure *parent,ScalarType type);
    PVStructure * scalarValue(PVStructure *parent,
        ScalarType type,String properties);
    PVScalarArray * scalarArrayValue(PVStructure *parent,ScalarType elementType);
    PVStructure * scalarArrayValue(PVStructure *parent,
        ScalarType elementType, String properties);
    PVStructureArray * structureArrayValue(PVStructure *parent,
        StructureConstPtr structure);
    PVStructure * structureArrayValue(PVStructure *parent,
        StructureConstPtr structure,String properties);
    PVStructure * enumeratedValue(PVStructure *parent,StringArray choices);
    PVStructure * enumeratedValue(PVStructure *parent,
        StringArray choices, String properties);
    PVStructure * alarm(PVStructure *parent);
    PVStructure * timeStamp(PVStructure *parent);
    PVStructure * display(PVStructure *parent);
    PVStructure * control(PVStructure *parent);
    PVStructure * booleanAlarm(PVStructure *parent);
    PVStructure * byteAlarm(PVStructure *parent);
    PVStructure * shortAlarm(PVStructure *parent);
    PVStructure * intAlarm(PVStructure *parent);
    PVStructure * longAlarm(PVStructure *parent);
    PVStructure * floatAlarm(PVStructure *parent);
    PVStructure * doubleAlarm(PVStructure *parent);
    PVStructure * enumeratedAlarm(PVStructure *parent);
    PVStructure * powerSupply(PVStructure *parent);
};

Convert

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 : NoDefaultMethods {
public:
    Convert();
    ~Convert();
    void getFullName(StringBuilder buf,PVField *pvField);
    bool equals(PVField &a,PVField &b);
    void getString(StringBuilder buf,PVField * pvField,int indentLevel);
    void getString(StringBuilder buf,PVField *pvField);
    void fromString(PVScalar *pv, String from);
    int fromString(PVScalarArray *pv, String from);
    int fromStringArray(PVScalarArray *pv, int offset, int length,
        StringArray from, int fromOffset);
    int toStringArray(PVScalarArray *pv, int offset, int length,
        StringArray to, int toOffset);
    bool isCopyCompatible(FieldConstPtr from, FieldConstPtr to);
    void copy(PVField *from,PVField *to);
    bool isCopyScalarCompatible(
         ScalarConstPtr from, ScalarConstPtr to);
    void copyScalar(PVScalar *from, PVScalar *to);
    bool isCopyScalarArrayCompatible(ScalarArrayConstPtr from,
        ScalarArrayConstPtr to);
    int copyScalarArray(PVScalarArray *from, int offset,
        PVScalarArray *to, int toOffset, int length);
    bool isCopyStructureCompatible(
        StructureConstPtr from, StructureConstPtr to);
    void copyStructure(PVStructure *from, PVStructure *to);
    bool isCopyStructureArrayCompatible(
        StructureArrayConstPtr from, StructureArrayConstPtr to);
    void copyStructureArray(
        PVStructureArray *from, PVStructureArray *to);
    int8 toByte(PVScalar *pv);
    int16 toShort(PVScalar *pv);
    int32 toInt(PVScalar *pv);
    int64 toLong(PVScalar *pv);
    float toFloat(PVScalar *pv);
    double toDouble(PVScalar *pv);
    String toString(PVScalar *pv);
    void fromByte(PVScalar *pv,int8 from);
    void fromShort(PVScalar *pv,int16 from);
    void fromInt(PVScalar *pv, int32 from);
    void fromLong(PVScalar *pv, int64 from);
    void fromFloat(PVScalar* pv, float from);
    void fromDouble(PVScalar *pv, double from);
    int toByteArray(PVScalarArray *pv, int offset, int length,
        ByteArray to, int toOffset);
    int toShortArray(PVScalarArray *pv, int offset, int length,
        ShortArray to, int toOffset);
    int toIntArray(PVScalarArray *pv, int offset, int length,
        IntArray to, int toOffset);
    int toLongArray(PVScalarArray *pv, int offset, int length,
        LongArray to, int toOffset);
    int toFloatArray(PVScalarArray *pv, int offset, int length,
        FloatArray to, int toOffset);
    int toDoubleArray(PVScalarArray *pv, int offset, int length,
        DoubleArray to, int toOffset);
    int fromByteArray(PVScalarArray *pv, int offset, int length,
        ByteArray from, int fromOffset);
    int fromShortArray(PVScalarArray *pv, int offset, int length,
        ShortArray from, int fromOffset);
    int fromIntArray(PVScalarArray *pv, int offset, int length,
        IntArray from, int fromOffset);
    int fromLongArray(PVScalarArray *pv, int offset, int length,
        LongArray from, int fromOffset);
    int fromFloatArray(PVScalarArray *pv, int offset, int length,
        FloatArray from, int fromOffset);
    int fromDoubleArray(PVScalarArray *pv, int offset, int length,
        DoubleArray from, int fromOffset);
    void newLine(StringBuilder buf, int indentLevel);    
};

extern Convert * 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.


Namespace and Memory Management


Namespace

All code in project pvDataCPP appears in namespace:

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

Memory Managemment

NoDefaultMethods

Any class that does not want the compiler to generate default methods can privately extend the following class which is defined in file noDefaultMethods.h:

class NoDefaultMethods {
protected:
    // allow by derived objects
    NoDefaultMethods(){};
    ~NoDefaultMethods(){}
private:
    // do not implment
    NoDefaultMethods(const NoDefaultMethods&);
    NoDefaultMethods & operator=(const NoDefaultMethods &);
};

PVData introspection objects

Introspection objects are meant to be shared. They are all made available via std::tri::shared_pointer.

PVData data objects

All PVData data objects must publically extend PVField, which does not allow default methods but does have a virtual destructor. It is expected that each data object is "owned" by some entity. For example a pvIOC (not implemented) database will own all records and thus all PVData data objects in the database. It is the ONLY entity that will create and destroy the data objects. All other code only receives pointers to the data objects. Before a record is deleted any code that is connected to a record is notified before the record is deleted. After deletion all pointers to data in the record are invalid. Similarly pvAccess creates and destroys PVData objects and notifies clients before destroying PVData data objects.

Other code in this project

The classes in property, i.e. alarm, timeStamp, display, and control are all meant to be free copied and shared. They can be created on the stack. In most cases it is not necessary to create them on the heap.

Other clases privately extend NoDefaultClasses and are not normally meant to be extended. Thus they can only be created via "new" and must be destroyed via "delete".


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) {
   PVField *valuePV = pvStructure->getSubField(String("value"));
   if(valuePV==0) {
       buf += "value field not found";
       return;
   }
   buf += "value ";
   valuePV->toString(buf);
   PVField *timeStampPV = pvStructure->getSubField(String("timeStamp"));
   if(timeStampPV==0) {
       buf += "timeStamp field not found";
       return;
   }
   buf += " timeStamp ";
   timeStampPV->toString(buf);
}

Creating PVData

Example of creating a scalar field.

    PVDataCreate *pvDataCreate = getPVDataCreate();
    PVDouble *pvValue = pvDataCreate->createPVScalar(
      0,
      String("value"),
      pvDouble);

Create an alarm structure the hard way

    FieldCreate *fieldCreate = getFieldCreate();
    PVDataCreate *pvDataCreate = getPVDataCreate();
    FieldConstPtrArray fields = new FieldConstPtr[2];
    fields[0] = fieldCreate->createScalar(String("severity"),pvInt);
    fields[1] = fieldCreate->createScalar(String("message"),pvString);
    StructureConstPtralarmField = fieldCreate->createStructure(String("alarm"),2,fields);

Create an alarm structure the easy way.

    StandardPVField *standardPVField = getStandardPVField();
    PVStructure *pvAlarm = standardPVField->alarm(parent);

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

    StandardPVField *standardPVField = getStandardPVField();
    PVStructure *pvStructure = standardPVField->scalar(
        0, //parent is null
        String("example"),
        String("timeStamp,alarm"))

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
    structure alarm
    structure timeStamp
    double value
    structure display
        string description "Sample Description"
        string format "%f"
        string units volts
        structure limit
            double low 0.0
            double high 10.0

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 powerSupplyValueStructure
    double value
    structure alarm

structure powerSupplySimple
    structure alarm
    structure timeStamp
    powerSupplyValueStructure voltage
    powerSupplyValueStructure power
    powerSupplyValueStructure current

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
One of boolean, byte, short, int, long, float, double, or string
scalarArray
An array with the elementType being a scalar type
enumerated structure
A structure that includes fields named index, choice, and choices. index is an int that selects a choice. choice is the currently selected 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 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(PVField *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
    int64 secondsPartEpoch
    int32 nanoSeconds
    int32 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 and pvTimeStamp.h timeStamp.h defines a time stamp independent of pvData, i.e. it is a generally useful class for manipulating timeStamps. pvTimeStamp.h is 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 ;
extern int64 posixEpochAtEpicsEpoch;

class TimeStamp {
public:
    TimeStamp();
    TimeStamp(int64 secondsPastEpoch,int32 nanoSeconds = 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();
    int64 getEpicsSecondsPastEpoch() const;
    int32 getNanoSeconds() const;
    int32 getUserTag() const;
    void setUserTag(int userTag);
    void put(int64 secondsPastEpoch,int32 nanoSeconds = 0);
    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(PVField *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
    int32 severity
    int32 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 and pvAlarm.h alarm.h defines a time stamp independent of pvData, i.e. it is a generally useful class for manipulating alarms. pvAlarm.h is a class that can be attached to a time stamp pvData structure. It provides get and set methods to get/set a Alarm as defined by alarm.h

alarm.h

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


enum AlarmStatus {
    noStatus,deviceStatus,driverStatus,recordStatus,
    dbStatus,confStatus,undefinedStatus,clientStatus
};

class Alarm {
public:
    Alarm();
    //default constructors and destructor are OK
    String getMessage();
    void setMessage(String 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(PVField *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 &) 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
    structure limit
        double low
        double high

Two header files are provided for manipulating controls: control.h and pvControl.h control.h defines a time stamp independent of pvData, i.e. it is a generally useful class for manipulating controls. pvControl.h is a class that can be attached to a time stamp pvData structure. It provides get and set methods to get/set a Control as defined by control.h

control.h

class Control {
public:
    Control();
    //default constructors and destructor are OK
    double getLow() const;
    double getHigh() const;
    void setLow(double value);
    void setHigh(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.

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(PVField *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
    structure limit
        double low
        double high
    string description
    string format
    string units

Two header files are provided for manipulating controls: display.h and pvDisplay.h display.h defines display information independent of pvData, i.e. it is a generally useful class for manipulating display infomation. pvDisplay.h is a class that can be attached to a display pvData structure. It provides get and set methods to get/set a Diaplay as defined by diaplay.h

display.h

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 value);
    String getFormat() const;
    void setFormat(String value);
    String getUnits() const;
    void setUnits(String 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(PVField *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

An enumerated structure is a structure that has fields:

structure
    int32 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(PVField *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.

PVData Factories


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


Miscellanous Classes


Overview

This package provides utility code:

bitSet.h
An implementation of BitSet that can be serialized.
byteBuffer.h
Used to serialize objects.
event.h
Signal and wait for an event.
exception.h
Exception with stack trace.
executor.h
Provides a thread for executing commands.
linkedList.h
A double linked list facility that requires the user to allocate a node. It is more efficient that std::list and does not require the implementation to allocate storage for the nodes.
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.
requester.h
Allows messages to be sent to a requester.
serialize.h
Support for serializing objects.
CDRMonitor.h
Provides support monitoring memory usage for objects of a class.
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.
queue.h
A queue implementation that allows the latest queue element to continue to be used when no free element is available.

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

BitSet

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

class BitSet /*: public Serializable*/ {
public:
    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;
    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.
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.

ByteBuffer

A ByteBuffer is used to serialize and deserialize primitive data. File byteBuffer.h is:

class ByteBuffer {
public:
    ByteBuffer(int size = 32, int byteOrder = EPICS_BYTE_ORDER);
    ~ByteBuffer();
    ByteBuffer* clear();
    ByteBuffer* flip();
    ByteBuffer* rewind();
    bool getBoolean();
    int8 getByte();
    int16 getShort();
    int32 getInt();
    int64 getLong();
    float getFloat();
    double getDouble();
    void get(char* dst, int offset, int count);
    ByteBuffer* put(const char* src, int offset, int count);
    ByteBuffer* putBoolean(bool value);
    ByteBuffer* putByte(int8 value);
    ByteBuffer* putShort(int16 value);
    ByteBuffer* putInt(int32 value);
    ByteBuffer* putLong(int64 value);
    ByteBuffer* putFloat(float value);
    ByteBuffer* putDouble(double value);
    inline int getSize() const;
    inline int getArrayOffset() const;
    inline int getPosition() const;
    inline int getLimit() const;
    inline int getRemaining() const;
    inline int getByteOrder() const;
    inline const char* getArray() const;
    // TODO must define arrays
private:
};

x

Event

This class provides coordinates activity between threads. One thread can wait for the event and the other signals the event.

class Event : private NoDefaultMethods {
public:
    Event(bool full);
    ~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)

Exception

File epicsException.h describes:

class BaseException : public std::exception {
public:
    BaseException(const char* message, const char* file,
        int line, std::exception* cause = 0);
    virtual ~BaseException();
    virtual const char* what();
    void toString(std::string& str, unsigned int depth = 0);
    static inline void getStackTrace(
         std::string* trace, unsigned int skip_frames = 0, unsigned int max_frames = 63)
private:
     // ...
}

x

Executor

An Executor is a thread that can execute commands. The user can request that a single command be executed.

class ExecutorNode;

class Command {
public:
    virtual void command() = 0;
};

class Executor : private NoDefaultMethods {
public:
    Executor(String threadName,ThreadPriority priority);
    ~Executor();
    ExecutorNode * createNode(Command *command);
    void execute(ExecutorNode *node);
private:
    class ExecutorPvt *pImpl;
};

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.
createNode
Create a ExecutorNode that can be passed to execute.
execute
Request that command be executed. If it is already on the run list nothing is done.

Linked List

LinkedList implements a double linked list that requires a user to allocate the nodes. It is more efficent that std::list. linkedList.h is a template that is both a complete description and definition. It uses linkedListVoid for method definitions. linkedListVoid is not meant for use except via linkedList.

A node can only be on one list at a time but can be put, at different times, on different lists as long as they all hold the same type of objects. An exception is thrown if an attempt is made to put a node on a list if the node is already on a list.

template <typename T>
class LinkedList;

template <typename T>
class LinkedListNode : private LinkedListVoidNode {
public:
    LinkedListNode(T &object) : LinkedListVoidNode(&object){}
    ~LinkedListNode() {}
    T &getObject() { return *static_cast<T *>(LinkedListVoidNode::getObject());}
    bool isOnList() {return LinkedListVoidNode::isOnList();}
    friend  class LinkedList<T>;
};

template <typename T>
class LinkedList : private LinkedListVoid {
public:
    LinkedList() : LinkedListVoid() {}
    ~LinkedList() {}
    int getLength();
    void addTail(LinkedListNode<T> &listNode);
    void addHead(LinkedListNode<T> &listNode);
    void insertAfter(LinkedListNode<T> &listNode,LinkedListNode<T> &addNode);
    void insertBefore(LinkedListNode<T> &listNode,LinkedListNode<T> &addNode);
    LinkedListNode<T> *removeTail();
    LinkedListNode<T> *removeHead();
    void remove(LinkedListNode<T> &listNode);
    LinkedListNode<T> *getHead();
    LinkedListNode<T> *getTail();
    LinkedListNode<T> *getNext(LinkedListNode<T> &listNode);
    LinkedListNode<T> *getPrev(LinkedListNode<T> &listNode);
    bool isEmpty();
};

LinkedListNode has the methods:

LinkedListNode
The constructor. The object must be specified.
~LinkedListNode
The destructor.
getObject
Returns the nobject.
isOnList
returns (false,true) if the node (is not, is) on a list.

LinkedList has the methods:

LinkedList
The constructor.
~LinkedList
The destructor.
getLength
Get the numbet of nodes currently on the list.
addTail
Add a node to the end of the list. An exception is thrown if the node is already on a list.
addHead
Add a node to the beginning of the list. An exception is thrown if the node is already on a list.
insertAfter
Insert addNode after node. An exception is thrown if the addNode is already on a list or if node is not on this list..
insertBefore
Insert addNode before node. An exception is thrown if the addNode is already on a list or if node is not on this list.
removeTail
Remove and return the last node. Null is returned if the list is empty.
removeHead
Remove and return the first node. Null is returned if the list is empty.
remove
Remove the specified node or object. An exception is thrown if the node is not on a list.
getHead
Get the first list node. Null is returned if the list is empty.
getTail
Get the last list node. Null is returned if the list is empty.
getNext
Get the node after node. An exception is thrown if node is not on this list. Null is returned if the is node is the last node on the list.
getPrev
Get the node before node. An exception is thrown if node is not on this list. Null is returned if the is node is the first node on the list.
isEmpty
Is the list empty.
contains
Does the list contain the specified object?

Lock and Mutex

lock.h is:

class Mutex  {
public:
    Mutex();
    ~Mutex();
    void lock();
    void unlock();
};


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
    }

Message Queue

Definitions

class MessageNode {
public:
    String getMessage() const;
    MessageType getMessageType() const;
    void setMessageNull();
};

class MessageQueue : private NoDefaultMethods {
public:
    MessageQueue(int size);
    ~MessageQueue();
    MessageNode *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() const;
    bool isFull() const;
    int getClearOverrun();
};

MessageQueue

This is for use by code that wants to handle messages without blocking higher priority threads.

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

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

Requester

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 StringArray messageTypeName;

class Requester {
public:
    virtual String getRequesterName() = 0;
    virtual void message(String 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

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);
private:
};

class SerializableControl {
public:
    virtual void flushSerializeBuffer() =0;
    virtual void ensureBuffer(int size) =0;
};
class DeserializableControl {

public:
    virtual void ensureData(int size) =0;
};
class Serializable {
public:
    virtual void serialize(ByteBuffer *buffer,
        SerializableControl *flusher) = 0;
    virtual void deserialize(ByteBuffer *buffer,
        DeserializableControl *flusher) = 0;
};
class BitSetSerializable {
public:
    virtual void serialize(ByteBuffer *buffer,
        SerializableControl *flusher,BitSet *bitSet) = 0;
    virtual void deserialize(ByteBuffer *buffer,
        DeserializableControl *flusher,BitSet *bitSet) = 0;
};
class SerializableArray : public Serializable {
public:
    virtual void serialize(ByteBuffer *buffer,
         SerializableControl *flusher, int offset, int count) = 0;
};

where

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

The following interfaces are called by pvAccess for transporting data over the network. The abstract and base classes ensure that these methods are properly implemented.

x

x

CDRMonitor - Monitor and Report Construction and Destruction

This is a facility that allows a class to report how many objects of that class have been created and destroyed. This can help find memory leaks.

struct CDRCount {
     size_t cons, dtys;
     long refs;
};

class CDRMonitor : private NoDefaultMethods {
public:
    static CDRMonitor& get();
    CDRNode* addNode(CDRNode& next);
    CDRCount current();
    CDRNode* first();
    CDRNode* first();
    void show(FILE*)
    void show(std::ostream&) const;
};
class CDRNode : private NoDefaultMethods {
public:
    CDRNode(const String& name);
    void construct();
    void destruct(){Lock x(guard);
     void incRef();
    void decRef();
    CDRNode* next();
     CDRCount get();
    void show(FILE*);
    void show(std::ostream&);
};

static inline CDRNode* getNode(CDRNodeInstance *inst);

Status

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 message);
    Status(StatusType type, epics::pvData::String 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

ThreadPriority

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

class ThreadPriorityFunc {
public:
    static unsigned int const * const getEpicsPriorities();
    static int getEpicsPriority(ThreadPriority threadPriority);
};

Thread

class Runnable {
public:
    virtual void run() = 0;
};

class Thread;

class Thread :  private NoDefaultMethods {
public:
    Thread(String name,ThreadPriority priority,Runnable *runnableReady);
    ~Thread();
    String getName();
    ThreadPriority getPriority();
    static void showThreads(StringBuilder buf);
    static void sleep(double seconds);
private:
};

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;
getName
Get the thread name.
getPriority
Get the thread priority.
showThreads
Get a String that has the name and priority of all currently allocated threads.
sleep
Make the current thread sleep for the specified number of seconds.

Time Function Call

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 {
public:
    virtual void function() = 0;
};

class TimeFunction : private NoDefaultMethods {
public:
    TimeFunction(TimeFunctionRequester *requester);
    ~TimeFunction();
    double timeCall();
private:
    TimeFunctionRequester *requester;
};

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

This provides a general purpose timer. It allows a user callback to be called after a delay or periodically.

class TimerCallback {
public:
    virtual void callback() = 0;
    virtual void timerStopped() = 0;
};

class TimerNode : private NoDefaultMethods {
public:
    TimerNode(TimerCallback *timerCallback);
    ~TimerNode();
    void cancel();
    bool isScheduled();
private:
};

class Timer : private NoDefaultMethods {
public:
    Timer(String threadName, ThreadPriority priority);
    ~Timer();
    void scheduleAfterDelay(TimerNode &timerNode,double delay);
    void schedulePeriodic(TimerNode &timerNode,double delay,double period);
private:
};

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.

Queue

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 QueueElement : private QueueElementVoid {
public:
    T *getObject() { return static_cast<T *>(QueueElementVoid::getObject());}
protected:
};

template <typename T>
class Queue : private QueueVoid {
public:
    Queue(T *array[],int number);
    ~Queue();
    void clear();
    int getNumberFree();
    int capacity();
    QueueElement<T> *getFree();
    void setUsed(QueueElement<T> *queueElement);
    QueueElement<T> *getUsed();
    void releaseUsed(QueueElement<T> *queueElement);
};

miscTest/queueTest.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.
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);
     }

pvMisc


BitSetUtil

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

MultiChoice

MultiChoice defines an array of strings and a bit set that selects an arbitrary set of the choices. This will be implemented if the java version is accepted.

NOT DONE