This is the documentation for the scalarArray data type as defined by pvDataCPP-md. -When complete it will be merged into pvDataCPP.html. -Only sharedVector is currently documented. -It is documented in the next section, but when merged into pvDataCPP.html, -will appear in a later section. -For now ignore the documentation in pvDataApp/pv.
-When NOTE EXISTING appears it means that there is a question about -the existing shared_vector implementation.
+This is the documentation for pvData.h as defined by pvDataCPP-md. +When complete it will be merged into pvDataCPP.html.
++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 +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 differences are mainly related to language differences. +Some differences are: +
There is one big difference from the existing Java implelentation: +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: +
+ double[] get(); ++
The existing version allowed the data source to provide the array in chunks. +The new version assumes that the data source always provides contiguous storage +for the entire raw array. If this is accepted it simplifies a lot of code. +
+Three topics not discussed in this document are: +
+PVScalarArrayPtr createPVScalarArray(const PVScalarArray &, size_t offset, size_t length); ++ This will share the raw data array but allow a new window. +
This provides the interface for network accessible data. +Although templates are used to minimize the amount of code, +the interface is not meant to be extended. +Only the types defined by pvIntrospect are implemented.
+ ++class PVField +: virtual public Serializable, + public std::tr1::enable_shared_from_this++{ +public: + POINTER_DEFINITIONS(PVField); + 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; + std::size_t getNumberFields() const; + PVAuxInfoPtr & getPVAuxInfo(); + bool isImmutable() const; + void setImmutable(); + const FieldConstPtr & getField() const; + PVStructure * getParent() const; + void replacePVField(const PVFieldPtr& newPVField); + void renameField(String const & newName); + void postPut(); + void setPostHandler(PostHandlerPtr const &postHandler); + virtual std::ostream& operator<<(std::ostream& o) const; + std::ostream& operator<<(std::ostream& o, size_t index) const; +... +}; + +std::ostream& operator<<(std::ostream& o, const PVFieldPtr & f); +std::ostream& operator<<(std::ostream& o, const PVFieldPtr & f, size_t index); +
The public methods for PVField are:
+
+class PVScalar : public PVField {
+public:
+ POINTER_DEFINITIONS(PVScalar);
+ virtual ~PVScalar();
+
+ typedef PVScalar &reference;
+ typedef const PVScalar& const_reference;
+
+ const ScalarConstPtr getScalar() const;
+...
+};
+
+where
++template+ ++class PVScalarValue : public PVScalar { +public: + POINTER_DEFINITIONS(PVScalarValue); + typedef T value_type; + typedef T* pointer; + typedef const T* const_pointer; + + virtual ~PVScalarValue() {} + virtual T get() const = 0; + virtual void put(T value) = 0; + + std::ostream& operator<<(std::ostream& o) const + std::ostream& operator<<(std::ostream& o, size_t index) const; +... +}; +typedef PVScalarValue<uint8> PVBoolean; +typedef PVScalarValue<int8> PVByte; +typedef PVScalarValue<int16> PVShort; +typedef PVScalarValue<int32> PVInt; +typedef PVScalarValue<int64> PVLong; +typedef PVScalarValue<uint8> PVUByte; +typedef PVScalarValue<uint16> PVUShort; +typedef PVScalarValue<uint32> PVUInt; +typedef PVScalarValue<uint64> PVULong; +typedef PVScalarValue<float> PVFloat; +typedef PVScalarValue<double> PVDouble; +typedef std::tr1::shared_ptr<PVBoolean> PVBooleanPtr; +typedef std::tr1::shared_ptr<PVByte> PVBytePtr; +typedef std::tr1::shared_ptr<PVShort> PVShortPtr; +typedef std::tr1::shared_ptr<PVInt> PVIntPtr; +typedef std::tr1::shared_ptr<PVLong> PVLongPtr; +typedef std::tr1::shared_ptr<PVUByte> PVUBytePtr; +typedef std::tr1::shared_ptr<PVUShort> PVUShortPtr; +typedef std::tr1::shared_ptr<PVUInt> PVUIntPtr; +typedef std::tr1::shared_ptr<PVULong> PVULongPtr; +typedef std::tr1::shared_ptr<PVFloat> PVFloatPtr; +typedef std::tr1::shared_ptr<PVDouble> PVDoublePtr; + +// PVString is special case, since it implements SerializableArray +class PVString : public PVScalarValue<String>, SerializableArray { +public: + virtual ~PVString() {} + ... +}; +
where
+PVArray is the base interface for all the other PV Array interfaces. It +extends PVField and provides the additional methods:
+class PVArray : public PVField, public SerializableArray {
+public:
+ POINTER_DEFINITIONS(PVArray);
+ virtual ~PVArray();
+ virtual std::size_t getLength() const = 0;
+ virtual void setLength(std::size_t length) = 0;
+ bool isCapacityMutable() const;
+ void setCapacityMutable(bool isMutable);
+ virtual std::size_t getCapacity() const = 0;
+ virtual void setCapacity(std::size_t capacity) = 0;
+ ...
+};
+PVScalarArray is the base class for scalar array data. PVValueArray is a +templete for the various scalar array data classes. There is a class for each +possible scalar type, i. e. PVBooleanArray, ..., PVStringArray.
+class PVScalarArray : public PVArray {
+public:
+ POINTER_DEFINITIONS(PVScalarArray);
+ typedef PVScalarArray &reference;
+ typedef const PVScalarArray& const_reference;
+
+ virtual ~PVScalarArray();
+ const ScalarArrayConstPtr getScalarArray() const;
+ ...
+};
+
+// PVString is special case, since it implements SerializableArray
+class PVString : public PVScalarValue<String>, SerializableArray {
+public:
+ virtual ~PVString() {}
+ ...
+};
+
+
+where
+This is a template class plus instances for PVBooleanArray, ..., +PVStringArray.
+template<typename T>
+class PVValueArray :
+public PVScalarArray
+...
+{
+public:
+ POINTER_DEFINITIONS(PVValueArray);
+ typedef T value_type;
+ typedef T* pointer;
+ typedef const T* const_pointer;
+ typedef PVValueArray & reference;
+ typedef const PVValueArray & const_reference;
+
+ typedef shared_vector<T> svector;
+ typedef shared_vector<const T> const_svector;
+
+ virtual ~PVValueArray() {}
+ const_svector & get();
+ size_t put(size_t offset,size_t length, const_svector &from, size_t fromOffset);
+
+ void shareData(const_svector &from);
+
+ virtual std::ostream& operator<<(std::ostream& o) const;
+ std::ostream& operator<<(std::ostream& o, size_t index) const;
+...
+};
+
+typedef PVValueArray<uint8> PVBooleanArray;
+typedef std::tr1::shared_ptr<PVBooleanArray> PVBooleanArrayPtr;
+
+typedef PVValueArray<int8> PVByteArray;
+typedef std::tr1::shared_ptr<PVByteArray> PVByteArrayPtr;
+
+typedef PVValueArray<int16> PVShortArray;
+typedef std::tr1::shared_ptr<PVShortArray> PVShortArrayPtr;
+
+typedef PVValueArray<int32> PVIntArray;
+typedef std::tr1::shared_ptr<PVIntArray> PVIntArrayPtr;
+
+typedef PVValueArray<int64> PVLongArray;
+typedef std::tr1::shared_ptr<PVLongArray> PVLongArrayPtr;
+
+typedef PVValueArray<uint8> PVUByteArray;
+typedef std::tr1::shared_ptr<PVUByteArray> PVUByteArrayPtr;
+
+typedef PVValueArray<uint16> PVUShortArray;
+typedef std::tr1::shared_ptr<PVUShortArray> PVUShortArrayPtr;
+
+typedef PVValueArray<uint32> PVUIntArray;
+typedef std::tr1::shared_ptr<PVUIntArray> PVUIntArrayPtr;
+
+typedef PVValueArray<uint64> PVULongArray;
+typedef std::tr1::shared_ptr<PVULongArray> PVULongArrayPtr;
+
+typedef PVValueArray<float> PVFloatArray;
+typedef std::tr1::shared_ptr<PVFloatArray> PVFloatArrayPtr;
+
+typedef PVValueArray<double> PVDoubleArray;
+typedef std::tr1::shared_ptr<PVDoubleArray> PVDoubleArrayPtr;
+
+typedef PVValueArray<String> PVStringArray;
+typedef std::tr1::shared_ptr<PVStringArray> PVStringArrayPtr;
+
+
+where
+When NOTE EXISTING appears it means that there is a question about +the existing shared_vector implementation.
A shared_vector is a container as defined by the C++ standard library. It is like std::vector but provides two additional features @@ -738,260 +1124,6 @@ use_count 1 offset 0 count 16 total 16
Not yet documented
-INGORE REST OF DOCUMENT!!!!
-PVArray is the base interface for all the other PV Array interfaces. It -extends PVField and provides the additional methods:
-class PVArray : public PVField, public SerializableArray {
-public:
- POINTER_DEFINITIONS(PVArray);
- virtual ~PVArray();
- virtual void setImmutable();
- std::size_t getLength() const;
- virtual void setLength(std::size_t length);
- std::size_t getCapacity() const;
- bool isCapacityMutable() const;
- void setCapacityMutable(bool isMutable);
- virtual void setCapacity(std::size_t capacity) = 0;
- ...
-};
-PVScalarArray is the base class for scalar array data. PVValueArray is a -templete for the various scalar array data classes. There is a class for each -possible scalar type, i. e. PVBooleanArray, ..., PVStringArray.
-class PVScalarArray : public PVArray {
-public:
- POINTER_DEFINITIONS(PVScalarArray);
- virtual ~PVScalarArray();
- typedef PVScalarArray &reference;
- typedef const PVScalarArray& const_reference;
- const ScalarArrayConstPtr getScalarArray() const ;
- virtual std::ostream& dumpValue(std::ostream& o, size_t index) const = 0;
- ...
-}
-
-where
-This is a template class plus instances for PVBooleanArray, ..., -PVStringArray.
-template<typename T>
-class PVValueArray : public PVScalarArray {
-public:
- POINTER_DEFINITIONS(PVValueArray);
- typedef T value_type;
- typedef T* pointer;
- typedef const T* const_pointer;
- typedef PVArrayData<T> ArrayDataType;
- typedef std::vector<T> vector;
- typedef const std::vector<T> const_vector;
- typedef std::tr1::shared_ptr<vector> shared_vector;
- typedef PVValueArray & reference;
- typedef const PVValueArray & const_reference;
-
- virtual ~PVValueArray() {}
- virtual std::size_t get(
- std::size_t offset, std::size_t length, ArrayDataType &data) = 0;
- virtual std::size_t put(std::size_t offset,
- std::size_t length, const_pointer from, std::size_t fromOffset) = 0;
- virtual std::size_t put(std::size_t offset,
- std::size_t length, const_vector &from, std::size_t fromOffset);
- virtual void shareData(
- shared_vector const & value,
- std::size_t capacity,
- std::size_t length) = 0;
- virtual pointer get() = 0;
- virtual pointer get() const = 0;
- virtual vector const & getVector() = 0;
- virtual shared_vector const & getSharedVector() = 0;
- std::ostream& dumpValue(std::ostream& o) const;
- std::ostream& dumpValue(std::ostream& o, size_t index) const;
-protected:
- PVValueArray(ScalarArrayConstPtr const & scalar)
- : PVScalarArray(scalar) {}
- friend class PVDataCreate;
-};
-
-template<typename T>
-std::size_t PVValueArray<T>::put(
- std::size_t offset,
- std::size_t length,
- const_vector &from,
- std::size_t fromOffset)
-{ return put(offset,length, &from[0], fromOffset); }
-
-/**
- * Definitions for the various scalarArray types.
- */
-typedef PVArrayData<uint8> BooleanArrayData;
-typedef PVValueArray<uint8> PVBooleanArray;
-typedef std::tr1::shared_ptr<PVBooleanArray> PVBooleanArrayPtr;
-
-typedef PVArrayData<int8> ByteArrayData;
-typedef PVValueArray<int8> PVByteArray;
-typedef std::tr1::shared_ptr<PVByteArray> PVByteArrayPtr;
-
-typedef PVArrayData<int16> ShortArrayData;
-typedef PVValueArray<int16> PVShortArray;
-typedef std::tr1::shared_ptr<PVShortArray> PVShortArrayPtr;
-
-typedef PVArrayData<int32> IntArrayData;
-typedef PVValueArray<int32> PVIntArray;
-typedef std::tr1::shared_ptr<PVIntArray> PVIntArrayPtr;
-
-typedef PVArrayData<int64> LongArrayData;
-typedef PVValueArray<int64> PVLongArray;
-typedef std::tr1::shared_ptr<PVLongArray> PVLongArrayPtr;
-
-typedef PVArrayData<uint8> UByteArrayData;
-typedef PVValueArray<uint8> PVUByteArray;
-typedef std::tr1::shared_ptr<PVUByteArray> PVUByteArrayPtr;
-
-typedef PVArrayData<uint16> UShortArrayData;
-typedef PVValueArray<uint16> PVUShortArray;
-typedef std::tr1::shared_ptr<PVUShortArray> PVUShortArrayPtr;
-
-typedef PVArrayData<uint32> UIntArrayData;
-typedef PVValueArray<uint32> PVUIntArray;
-typedef std::tr1::shared_ptr<PVUIntArray> PVUIntArrayPtr;
-
-typedef PVArrayData<uint64> ULongArrayData;
-typedef PVValueArray<uint64> PVULongArray;
-typedef std::tr1::shared_ptr<PVULongArray> PVULongArrayPtr;
-
-typedef PVArrayData<float> FloatArrayData;
-typedef PVValueArray<float> PVFloatArray;
-typedef std::tr1::shared_ptr<PVFloatArray> PVFloatArrayPtr;
-
-typedef PVArrayData<double> DoubleArrayData;
-typedef PVValueArray<double> PVDoubleArray;
-typedef std::tr1::shared_ptr<PVDoubleArray> PVDoubleArrayPtr;
-
-typedef PVArrayData<String> StringArrayData;
-typedef PVValueArray<String> PVStringArray;
-typedef std::tr1::shared_ptr<PVStringArray> PVStringArrayPtr;
-
-where
-Both get and put return the number of elements actually transfered. The -arguments are:
-The caller must be prepared to make multiple calls to retrieve or put an -entire array. A caller should accept or put partial arrays. For example the -following reads an entire array:
-void getArray(PVDoubleArrayPtr & pv,DoubleArray const & to)
-{
- size_t len = pv->getLength();
- if(to.size()<len) to.resize(len);
- DoubleArrayData data;
- size_t offset = 0;
- while(offset<len) {
- size_t num = pv->get(offset,(len-offset),data);
- DoubleArray &from = data.data;
- size_t fromOffset = data.offset;
- for(size_t i=0; i<num; i++) to[i+offset] = from[i + fromOffset];
- offset += num;
- }
-}
-
-