EPICS pvDataDiscussion

Introduction

As pvDataCPP progressed PVField and derived classes accumulated more and more member functions. These member functions have nothing to do with the primary primary purpose for pvData:

pvData (Process Variable Data) defines and implements an efficient way to store, access, and communicate memory resident data structures.

This statement appears as the first sentence of pvDataJava.html. A few sentences later the document makes it clear that communication includes efficient network communication. Thus pvData provides an interface for network accessible structured data. The problem of adding member functions that have nothing to do with the primary purpose started with the Java API. It already had extra methods that solved problems that should have had a different solution. This document removes the extra methods so that when new problems arise in the future the solution will not involve adding new member functions to the introspection and data API.

The introspection and data API for pvData should only encapsulate methods that support the primary purpose stated above. The interfaces for C++ and Java should be similar so that someone who understands the interface in one of the languages and knows both languages will quickly understand the interface of the other language.

There is another problem with the existing API. There are methods that allow the "structure" to change after an pvData object is created. An example is PVField::renameField(std::string newName). Such methods should not exist.

There are methods regarding immutability: setImmutable, isImmutablei, setCapacityMutable, and isCapacityMutable. Should they exists? For now lets assume no.

One last issue is the interface for array data. This document proposes a simplified version of what currently exists. It requires that the implementation always provides storage for the complete raw array. The existing APIs allow the implementation to provide the data in "chunks". Giving up this requirement simplifies the array interfaces. The existing C++ implementation of PVValueArray has serious problems. The shared_vector that is implemented in pvDataCP-md provides the solution to fixing the problems. This document describes an API that is very similar to the new Java API except that raw arrays are replaced by shared_vector.

This document will first describe changes to the existing Java interfaces and then the corresponding C++ API.

Java API

The following shows which methods will be removed from the existing interfaces and what will be added. The methods to be removed are in red and methods to add are in blue Also the removed methods are at the end with a comment above. The new methods also have a comment.

Introspection Interfaces

interface Field extends Serializable {
    std::string getId();
    Type getType();
    // following will be removed
    void toString(StringBuilder buf);
    void toString(StringBuilder buf,int indentLevel);
    std::string toString();
}


// new interface
interface FieldTostd::string {
    std::string toString(Field field);
}

interface Scalar extends Field {
    ScalarType getScalarType();
}

interface ScalarArray extends Field {
    ScalarType getElementType();
}

interface Structure extends Field {
    Field getField(std::string fieldName);
    int getFieldIndex(std::string fieldName);
    Field[] getFields();
    Field getField(int fieldIndex);
    std::string[] getFieldNames();
    std::string getFieldName(int fieldIndex)
}

interface StructureArray extends Field {
    Structure getStructure();
}

interface FieldCreate {
    Scalar createScalar(ScalarType scalarType);
    ScalarArray createScalarArray(ScalarType elementType);
    StructureArray createStructureArray(Structure elementStructure);
    Structure createStructure(std::string[] fieldNames, Field[] field);
    Structure createStructure(std::string id,std::string[] fieldNames, Field[] field);
    Structure createStructure(Structure structToClone);
    Field deserialize(ByteBuffer buffer, DeserializableControl control);
    // following will be removed
    Structure appendField(Structure structure,std::string fieldName, Field field);
    Structure appendFields(Structure structure,std::string[] fieldNames, Field[] fields);
}

Data Interfaces

interface PVField extends Requester, Serializable {
    std::string getFieldName();
    void setRequester(Requester requester);
    int getFieldOffset();
    int getNextFieldOffset();
    int getNumberFields();
    Field getField();
    PVStructure getParent();
    void postPut();
    void setPostHandler(PostHandler postHandler);
    // following will be removed
    PVAuxInfo getPVAuxInfo();
    boolean isImmutable();
    void setImmutable();
    void renameField(std::string newName);
    void toString(StringBuilder buf);
    void toString(StringBuilder buf,int indentLevel);
    std::string toString();
}


// The following is a new interface
interface PVFieldTostd::string {
    std::string toString(PVField pvField);
    void setMaxInitialArrayElements(int num);
    void setMaxFinalArrayElements(int num);
    int getMaxInitialArrayElements();
    int getMaxFinalArrayElements();
}
    
interface PVScalar extends PVField{
    Scalar getScalar();
}

interface PVDouble extends PVScalar{
    double get();
    void put(double value);
}
// also PVBoolean, PVByte, PVShort, PVInt, PVLong, PVFloat, and PVString

interface PVArray extends PVField, SerializableArray {
    int getLength();
    void setLength(int length);
    int getCapacity();
    void setCapacity(int length);
    // following will be removed
    boolean isCapacityMutable();
    void setCapacityMutable(boolean isMutable);
}

interface PVScalarArray extends PVArray {
    ScalarArray getScalarArray();
}


//following will be removed
public class DoubleArrayData {
    public double[] data;
    public int offset;
}

interface PVDoubleArray extends PVArray {
    // following are new
    double[] get();
    void swap(double[] value);
    //following will be removed
    int get(int offset, int len, DoubleArrayData data);
    int put(int offset,int len, double[] from, int fromOffset);
    void shareData(double[] from);
}

// also PVBooleanArray, ..., PVStringArray


interface PVStructure extends PVField , BitSetSerializable{
    Structure getStructure();
    PVField[] getPVFields();
    PVField getSubField(std::string fieldName);
    PVField getSubField(int fieldOffset);
    // The following are convenience methods
    PVBoolean getBooleanField(std::string fieldName);
    PVByte getByteField(std::string fieldName);
    PVShort getShortField(std::string fieldName);
    PVInt getIntField(std::string fieldName);
    PVLong getLongField(std::string fieldName);
    PVFloat getFloatField(std::string fieldName);
    PVDouble getDoubleField(std::string fieldName);
    PVString getStringField(std::string fieldName);
    PVScalarArray getScalarArrayField(std::string fieldName);
    PVStructureArray getStructureArrayField(std::string fieldName);
    PVStructure getStructureField(std::string fieldName);
    PVArray getArrayField(std::string fieldName,ScalarType elementType);
    // following will be removed
    void appendPVField(std::string fieldName,PVField pvField);
    void appendPVFields(std::string[] fieldNames,PVField[] pvFields);
    void removePVField(std::string fieldName);
    void replacePVField(PVField oldPVField,PVField newPVField);
    std::string getExtendsStructureName();
    boolean putExtendsStructureName(std::string extendsStructureName);
    public boolean checkValid();
}
 

//following will be removed
public class StructureArrayData {
    public PVStructure[] data;
    public int offset;
}


interface PVStructureArray extends PVArray{
    StructureArray getStructureArray();
    // following are new
    PVStructure[] get();
    void swap(PVStructure[] value);
    // following will be removed
    int get(int offset, int length, StructureArrayData data);
    int put(int offset,int length, PVStructure[] from, int fromOffset);
    void shareData(PVStructure[] from);
}


public interface PVDataCreate {
    PVField createPVField(Field field);
    PVField createPVField(PVField fieldToClone);
    PVScalar createPVScalar(Scalar scalar);
    PVScalar createPVScalar(ScalarType fieldType);
    PVScalar createPVScalar(PVScalar scalarToClone);
    PVScalarArray createPVScalarArray(ScalarArray array);
    PVScalarArray createPVScalarArray(ScalarType elementType);
    PVScalarArray createPVScalarArray(PVScalarArray arrayToClone;
    PVStructureArray createPVStructureArray(StructureArray structureArray);
    PVStructure createPVStructure(Structure structure);
    PVStructure createPVStructure(std::string[] fieldNames,Field[] fields);
    PVStructure createPVStructure(PVStructure structToClone);
    // following will be removed
    PVField[] flattenPVStructure(PVStructure pvStructure);
}

PVFieldTostd::string

In addition to toString this has methods to limit the number of array element to display. The existing Java implementation of toString displayed all elements. For large arrays this is not desirable. The new methods provide a way for the client to limit the number of elements. The default might be set to something like display up to 10 elements with 5 from the beginning and 5 from the end.

For C++ this can be a replacement for dumpValue.

PVBooleanArray, ..., PVStructureArray

The old get and put are replaced by two new and simpler methods:

get: Returns the raw array. If the client code modifies the elements in the array then the client must call postPut. The client also has to realize that if the raw array held by the PVXXXArray changes then the client is no longer sharing data
swap: This exchanges the old raw data with the new raw data.

The method setCapacity will always create a new raw array and copy old data from the old to the new array. This is not true now since the implementation does not create a new array if the old capacity is equal to the requested capacity.

C++ API

The C++ class definitions are similar to the Java definitions with two main exceptions:

toString: In c++ this is replaced by std::ostream.
raw array data: Java supports array data like double[] The C++ replacement is shared_vector<double>, which is implemented in pvDataCPP-md.

EPICS pvDataDiscussion

EPICS v4 Working Group, Working Draft, 03-Jul-2013

Table of Contents

Introduction

Java API

Introspection Interfaces

Data Interfaces

PVFieldTostd::string

PVBooleanArray, ..., PVStructureArray

C++ API

Introspection Interfaces

Data Interfaces