Since the last version of this document the following changes have +been made to the proposed interface definitionsi for PVValueArray:
+The stream operator++ methods were changed so that they only appear +in PVField. All the complexity should be hidden in the implementation +and, perhaps like Java, in the convert facility.
+A few minor changes were made because of mistakes in documenting +existing API descriptions.
This is the documentation for pvData.h as defined by pvDataCPP-md.
When complete it will be merged into pvDataCPP.html.
@@ -73,21 +89,19 @@ This document proposes an implementation of the PVXXX interfaces that are
different than the existing pvDataCPP-md interfaces.
See the next section for a comparison of the four interface descriptions.
The main reason for proposing a different definition is the primary
-purpose for pvData:
-pvData (Process Variable Data) defines and implements an efficent
-way to store, access, and communicate memory resident data structures.
+purpose for pvData:
+
pvData (Process Variable Data) defines and implements an efficent +way to store, access, and communicate memory resident data structures.This statement appears as the first sentence of pvDataJava.html. A few sentances later the document makes clear that communication includes network communication. -Thus it is important to keep the Java and C++ descriptions similar. -
-pvData provides an interface for network accessible structured data. -The interfaces for C++ and Java are similar. -Thus someone who understands the interface in one of the languages +Thus pvData provides an interface for network accessible structured data. +If the interfaces for C++ and Java are similar then +someone who understands the interface in one of the languages and knows both languages will quickly understand the interface of the other language. With only a few exceptions the naming and other conventions do not follow the C++ standard library conventions. -The definition of pvData is similar to the definition for Java. +The pvData.h API is similar to the definition for Java. The differences are mainly related to language differences. Some differences are:
There is one big difference from the existing Java implelentation: +
There is one big difference from the existing Java API: The method PVValueArray::get. As an example the Java definition for PVDoubleArray is currently:
int get(int offset, int length, DoubleArrayData data);
-This document assumes this be replaced by:
+This document assumes this will be replaced by:
double[] get();
@@ -137,13 +151,13 @@ PVScalarArrayPtr createPVScalarArray(const PVScalarArray &, size_t offset, s
methods like getAs. It will again support methods toXXXArray and fromXXXArray.
Templates should be used to minimize the code required.
The following compares the definitions of the following: PVField, PVScalar and extensions, PVArray and extensions. -Note, however, that PVStructureArray is not discussed. +PVStructureArray is not discussed.
This is the base for all the PVXXX iterfaces. @@ -152,7 +166,7 @@ traversing structured data. The pvDataJava and pvDataCPP definitions are similar. pvDataCPP-md added method getFullName. The proposed interface is like the existing pvDataCPP except that -the toString and dumpValue methods are replaced by the stream operator<<. +the dumpValue method is replaced by the stream operator<<.
interface PVField extends Requester, Serializable {
@@ -199,7 +213,7 @@ public:
virtual bool equals(PVField &pv);
virtual void toString(StringBuilder buf) ;
virtual void toString(StringBuilder buf,int indentLevel);
- std::ostream& dumpValue(std::ostream& o) const;
+ virtual std::ostream& dumpValue(std::ostream& o) const =0;
...
}
@@ -250,7 +264,6 @@ public:
virtual ~PVField();
virtual void message(String message,MessageType messageType);
const String& getFieldName() const;
- String getFullName() const;
virtual void setRequester(RequesterPtr const &prequester);
std::size_t getFieldOffset() const;
std::size_t getNextFieldOffset() const;
@@ -265,13 +278,12 @@ public:
void postPut();
void setPostHandler(PostHandlerPtr const &postHandler);
virtual bool equals(PVField &pv);
- virtual std::ostream& operator<<(std::ostream& o) const = 0;
- virtual std::ostream& operator<<(std::ostream& o, size_t index) const = 0;
+ void toString(StringBuilder buf) ;
+ void toString(StringBuilder buf,int indentLevel);
+ std::ostream& operator<<(std::ostream& o) const;
...
};
-std::ostream& operator<<(std::ostream& o, const PVFieldPtr & f);
-std::ostream& operator<<(std::ostream& o, const PVFieldPtr & f, size_t index);
The Java and pvDataCPP versions differ in that Java has an interface definition @@ -448,8 +460,6 @@ public: void operator>>=(T& value) const; void operator<<=(T value); - virtual std::ostream& operator<<(std::ostream& o) const - virtual std::ostream& operator>>(std::ostream& o, size_t index) const; ... }; typedef PVScalarValue<uint8> PVBoolean; @@ -501,6 +511,7 @@ For example PVDoubleArray::get becomes: The corresponding C++ version becomes:
const svector & get();
+ const const_svector & get() const;
The remaining difference is that dumpValue is replaced by the stream operator<<.
@@ -511,17 +522,13 @@ This allows the C++ interface to be more similar to Java. the extra methods and allows the client access to the shared_vector. The client is then able to perform C++ specific things to the data. -BUT it also means that if the client modifies the shared_vector the client is also responsibel -for ensuring that the immutable and capacity related features of PVField and PVArray are +BUT it also means that if the client modifies the shared_vector +the client is also responsible for ensuring that the +immutable and capacity related features of PVField and PVArray are respected and the postPut is properly handled. -The new method for PVValueArray: - - void put(const svector &from); - -helps ensure that shared_vector from the client is kept in sync with the shared_vector wrapped -by PVValueArray. But the used is still responsible for making sure that -PVField::isImmutable is honored. +Note that two get methods exist. +One allows write access to the raw data and the other doesn't/
interface PVArray extends PVField, SerializableArray {
int getLength();
@@ -564,8 +571,6 @@ public:
...
};
-std::ostream& operator<<(format::array_at_internal const& manip, const PVArray& array);
-
template<typename T>
class PVArrayData {
@@ -590,13 +595,11 @@ public:
typedef PVScalarArray &reference;
typedef const PVScalarArray& const_reference;
const ScalarArrayConstPtr getScalarArray() const ;
- virtual std::ostream& dumpValue(std::ostream& o, size_t index) const = 0;
...
}
template<typename T>
-class PVValueArray : public detail::PVVectorStorage<T,PVScalarArray> {
- typedef detail::PVVectorStorage<T,PVScalarArray> base_t;
+class PVValueArray : public PVScalarArray {
public:
POINTER_DEFINITIONS(PVValueArray);
typedef T value_type;
@@ -630,13 +633,6 @@ public:
...
};
-template<typename T>
-std::size_t PVValueArray<T>::put(
- std::size_t offset,
- std::size_t length,
- const_vector &from,
- std::size_t fromOffset)
-{ return put(offset,length, &from[0], fromOffset); }
/**
* Definitions for the various scalarArray types.
@@ -820,17 +816,8 @@ public:
...
};
-// PVString is special case, since it implements SerializableArray
-class PVString : public PVScalarValue<String>, SerializableArray {
-public:
- virtual ~PVString() {}
- ...
-};
-
template<typename T>
-class PVValueArray :
-public PVScalarArray
-...
+class PVValueArray : public PVScalarArray
{
public:
POINTER_DEFINITIONS(PVValueArray);
@@ -844,13 +831,11 @@ public:
typedef shared_vector<const T> const_svector;
virtual ~PVValueArray() {}
- const svector & get() const;
+ const svector & get() ;
+ const const_svector &get() const;
size_t put(size_t offset,size_t length, const_pointer from, size_t fromOffset);
- void put(const svector & from);
void shareData(const svector &from);
- virtual std::ostream& operator<<(std::ostream& o) const;
- virtual std::ostream& operator<<(std::ostream& o, size_t index) const;
...
};
@@ -882,7 +867,6 @@ public:
virtual ~PVField();
virtual void message(String message,MessageType messageType);
const String& getFieldName() const;
- String getFullName() const;
virtual void setRequester(RequesterPtr const &prequester);
std::size_t getFieldOffset() const;
std::size_t getNextFieldOffset() const;
@@ -897,8 +881,9 @@ public:
void postPut();
void setPostHandler(PostHandlerPtr const &postHandler);
virtual bool equals(PVField &pv);
- virtual std::ostream& operator<<(std::ostream& o) const = 0;
- virtual std::ostream& operator<<(std::ostream& o, size_t index) const = 0;
+ void toString(StringBuilder buf) ;
+ void toString(StringBuilder buf,int indentLevel);
+ std::ostream& operator<<(std::ostream& o) const;
...
};
@@ -995,9 +980,6 @@ public:
virtual void put(T value) = 0;
void operator>>=(T& value) const;
void operator<<=(T value);
-
- virtual std::ostream& operator<<(std::ostream& o) const
- virtual std::ostream& operator<<(std::ostream& o, size_t index) const;
...
};
typedef PVScalarValue<uint8> PVBoolean;
@@ -1095,13 +1077,6 @@ public:
const ScalarArrayConstPtr getScalarArray() const;
...
};
-
-// PVString is special case, since it implements SerializableArray
-class PVString : public PVScalarValue<String>, SerializableArray {
-public:
- virtual ~PVString() {}
- ...
-};
where
@@ -1115,10 +1090,7 @@ public:This is a template class plus instances for PVBooleanArray, ..., PVStringArray.
template<typename T>
-class PVValueArray :
-public PVScalarArray
-...
-{
+class PVValueArray : public PVScalarArray {
public:
POINTER_DEFINITIONS(PVValueArray);
typedef T value_type;
@@ -1131,14 +1103,11 @@ public:
typedef shared_vector<const T> const_svector;
virtual ~PVValueArray() {}
- const svector & get() const;
+ const svector & get() ;
+ const const_svector &get() const;
size_t put(size_t offset,size_t length, const_pointer from, size_t fromOffset);
- void put(const svector & from);
void shareData(const svector &from);
-
- virtual std::ostream& operator<<(std::ostream& o) const
- virtual std::ostream& operator<<(std::ostream& o, size_t index) const;
...
};
@@ -1195,19 +1164,13 @@ typedef std::tr1::shared_ptr<PVStringArray> PVStringArrayPtr;
than the cureent capacity allows.
It does not change the current length.
-