From b58b97a9162baf87bb46efd931ec8705c7d9e0a6 Mon Sep 17 00:00:00 2001 From: Marty Kraimer Date: Fri, 28 Jun 2013 14:17:23 -0400 Subject: [PATCH] minor changes --- documentation/pvArray.html | 147 ++++++++++++++----------------------- 1 file changed, 55 insertions(+), 92 deletions(-) diff --git a/documentation/pvArray.html b/documentation/pvArray.html index 8621bb7..b5c53c3 100644 --- a/documentation/pvArray.html +++ b/documentation/pvArray.html @@ -37,7 +37,7 @@

EPICS Array

-

EPICS v4 Working Group, Working Draft, 23-Jun-2013

+

EPICS v4 Working Group, Working Draft, 28-Jun-2013

Latest version:
@@ -66,6 +66,22 @@ license.

+

Changes

+

Since the last version of this document the following changes have +been made to the proposed interface definitionsi for PVValueArray:

+
+
put(const svector &from)
+
This has been removed. shareData can be used instead.
+
get
+
The get methods has been replaced by two methods. + One allows write access to array elements and the other does not. +
+
+

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.

Introduction

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:

@@ -99,8 +113,8 @@ Some differences are: to be shared. For C++ a shared_vector holds the raw data.
ostream replaces toString
-
In Java every object has method toString. - For C++ operator<< replaces toString
+
In Java every object has method toString(). + For C++ stream operator<< replaces toString
shared_vector
This is similar to std::vector but uses a shared_ptr to wrap the raw data and also supports a window into the raw data. It does follow the @@ -109,13 +123,13 @@ Some differences are: like iterators and algorithms can get the shared_vector.
-

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.
PVStructureArray
-
Can this also use shared_vector to hold elements?
+
This should also be able to use shared_vector to hold elements.

PVXXX: pvDataJava, pvDataCPP, pvDataCPP-md, and proposed interface

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.

PVField

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

Java

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

PVScalar

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/

pvDataJava

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.
       
-   
void put(const svector & from);

-     
This puts data into the PVValueArray from the shared_vector.
-     If the shared_vector holds the same raw array as the PVValueArray then
-     the shared_vector held by the PVValueArray is put in sync with from.
-     If not the  shared_vector will share the data.
-     potsPut will always be called.

    
shareData

       
Share data with an existing shared_vector.
         Note that if capacity is ever changed then data will no
-        longer be shared.

-  
operator<<

-  
operator>>

-     
Methods for stream I/O.

+        longer be shared.
+        This method can also be called to force the PVValueArray to have a new
+        raw array. This is usefull for implementing Copy On Write.
+      
 
 
 
shared_vector