epics/pvData
0
0
Fork 0
Code Issues Pull Requests Projects Wiki Activity

minor changes

Browse Source
This commit is contained in:
Marty Kraimer
2013-06-28 14:17:23 -04:00
parent 5f52f14094
commit b58b97a916
1 changed files with 55 additions and 92 deletions
Download Patch File Download Diff File Expand all files Collapse all files

147
documentation/pvArray.html
View File

@@ -37,7 +37,7 @@
<h1>EPICS Array</h1>
<!-- Maturity: Working Draft or Request for Comments, or Recommendation, and date. -->
<h2 class="nocount">EPICS v4 Working Group, Working Draft, 23-Jun-2013</h2>
<h2 class="nocount">EPICS v4 Working Group, Working Draft, 28-Jun-2013</h2>
<dl>
<dt>Latest version:</dt>
@@ -66,6 +66,22 @@ license.</a></p>
<div id="contents" class="contents">
<h2>Changes</h2>
<p>Since the last version of this document the following changes have
been made to the proposed interface definitionsi for PVValueArray:</p>
<dl>
<dt>put(const svector &amp;from)</dt>
<dd>This has been removed. shareData can be used instead.</dd>
<dt>get</dt>
<dd>The get methods has been replaced by two methods.
One allows write access to array elements and the other does not.
</dd>
</dl>
<p>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.</p>
<p>A few minor changes were made because of mistakes in documenting
existing API descriptions.</p>
<h2>Introduction</h2>
<p>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:<br />
<b>pvData (Process Variable Data) defines and implements an efficent
way to store, access, and communicate memory resident data structures.</b><br />
purpose for pvData:
<blockquote>pvData (Process Variable Data) defines and implements an efficent
way to store, access, and communicate memory resident data structures.</blockquote>
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.</p>
<p>
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:
<dl>
@@ -99,8 +113,8 @@ Some differences are:
to be shared. For C++ a shared_vector holds the raw data.
</dd>
<dt>ostream replaces toString</dt>
<dd>In Java every object has method toString.
For C++ operator&lt;&lt; replaces toString</dd>
<dd>In Java every object has method toString().
For C++ stream operator&lt;&lt; replaces toString</dd>
<dt>shared_vector</dt>
<dd>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.
</dd>
</dl>
<p>There is one big difference from the existing Java implelentation:
<p>There is one big difference from the existing Java API:
The method PVValueArray::get.
As an example the Java definition for PVDoubleArray is currently:
<pre>
int get(int offset, int length, DoubleArrayData data);
</pre>
This document assumes this be replaced by:
This document assumes this will be replaced by:
<pre>
double[] get();
</pre>
@@ -137,13 +151,13 @@ PVScalarArrayPtr createPVScalarArray(const PVScalarArray &amp;, size_t offset, s
methods like getAs. It will again support methods toXXXArray and fromXXXArray.
Templates should be used to minimize the code required.</dd>
<dt>PVStructureArray</dt>
<dd>Can this also use shared_vector to hold elements?</dd>
<dd>This should also be able to use shared_vector to hold elements.</dd>
</dl>
</p>
<h2>PVXXX: pvDataJava, pvDataCPP, pvDataCPP-md, and proposed interface</h2>
<p>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.
</p>
<h3>PVField</h3>
<p>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&lt;&lt;.
the dumpValue method is replaced by the stream operator&lt;&lt;.
</p>
<h4>Java</h4>
<pre>interface PVField extends Requester, Serializable {
@@ -199,7 +213,7 @@ public:
virtual bool equals(PVField &amp;pv);
virtual void toString(StringBuilder buf) ;
virtual void toString(StringBuilder buf,int indentLevel);
std::ostream&amp; dumpValue(std::ostream&amp; o) const;
virtual std::ostream&amp; dumpValue(std::ostream&amp; o) const =0;
...
}
@@ -250,7 +264,6 @@ public:
virtual ~PVField();
virtual void message(String message,MessageType messageType);
const String&amp; getFieldName() const;
String getFullName() const;
virtual void setRequester(RequesterPtr const &amp;prequester);
std::size_t getFieldOffset() const;
std::size_t getNextFieldOffset() const;
@@ -265,13 +278,12 @@ public:
void postPut();
void setPostHandler(PostHandlerPtr const &amp;postHandler);
virtual bool equals(PVField &amp;pv);
virtual std::ostream&amp; operator&lt;&lt;(std::ostream&amp; o) const = 0;
virtual std::ostream&amp; operator&lt;&lt;(std::ostream&amp; o, size_t index) const = 0;
void toString(StringBuilder buf) ;
void toString(StringBuilder buf,int indentLevel);
std::ostream&amp; operator&lt;&lt;(std::ostream&amp; o) const;
...
};
std::ostream&amp; operator&lt;&lt;(std::ostream&amp; o, const PVFieldPtr &amp; f);
std::ostream&amp; operator&lt;&lt;(std::ostream&amp; o, const PVFieldPtr &amp; f, size_t index);
</pre>
<h3>PVScalar</h3>
<p>The Java and pvDataCPP versions differ in that Java has an interface definition
@@ -448,8 +460,6 @@ public:
void operator&gt;&gt;=(T&amp; value) const;
void operator&lt;&lt;=(T value);
virtual std::ostream&amp; operator&lt;&lt;(std::ostream&amp; o) const
virtual std::ostream&amp; operator&gt;&gt;(std::ostream&amp; o, size_t index) const;
...
};
typedef PVScalarValue&lt;uint8&gt; PVBoolean;
@@ -501,6 +511,7 @@ For example PVDoubleArray::get becomes:
The corresponding C++ version becomes:
<pre>
const svector &amp; get();
const const_svector &amp; get() const;
</pre>
</p>
<p>The remaining difference is that dumpValue is replaced by the stream operator&lt;&lt;. </p>
@@ -511,17 +522,13 @@ This allows the C++ interface to be more similar to Java.</p>
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:
</pre>
void put(const svector &amp;from);
</pre>
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.
</p>
<p>Note that two get methods exist.
One allows write access to the raw data and the other doesn't/</p>
<h4>pvDataJava</h4>
<pre>interface PVArray extends PVField, SerializableArray {
int getLength();
@@ -564,8 +571,6 @@ public:
...
};
std::ostream&amp; operator&lt;&lt;(format::array_at_internal const&amp; manip, const PVArray&amp; array);
template&lt;typename T&gt;
class PVArrayData {
@@ -590,13 +595,11 @@ public:
typedef PVScalarArray &amp;reference;
typedef const PVScalarArray&amp; const_reference;
const ScalarArrayConstPtr getScalarArray() const ;
virtual std::ostream&amp; dumpValue(std::ostream&amp; o, size_t index) const = 0;
...
}
template&lt;typename T&gt;
class PVValueArray : public detail::PVVectorStorage&lt;T,PVScalarArray&gt; {
typedef detail::PVVectorStorage&lt;T,PVScalarArray&gt; base_t;
class PVValueArray : public PVScalarArray {
public:
POINTER_DEFINITIONS(PVValueArray);
typedef T value_type;
@@ -630,13 +633,6 @@ public:
...
};
template&lt;typename T&gt;
std::size_t PVValueArray&lt;T&gt;::put(
std::size_t offset,
std::size_t length,
const_vector &amp;from,
std::size_t fromOffset)
{ return put(offset,length, &amp;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&lt;String&gt;, SerializableArray {
public:
virtual ~PVString() {}
...
};
template&lt;typename T&gt;
class PVValueArray :
public PVScalarArray
...
class PVValueArray : public PVScalarArray
{
public:
POINTER_DEFINITIONS(PVValueArray);
@@ -844,13 +831,11 @@ public:
typedef shared_vector&lt;const T&gt; const_svector;
virtual ~PVValueArray() {}
const svector &amp; get() const;
const svector &amp; get() ;
const const_svector &amp;get() const;
size_t put(size_t offset,size_t length, const_pointer from, size_t fromOffset);
void put(const svector &amp; from);
void shareData(const svector &amp;from);
virtual std::ostream&amp; operator&lt;&lt;(std::ostream&amp; o) const;
virtual std::ostream&amp; operator&lt;&lt;(std::ostream&amp; o, size_t index) const;
...
};
@@ -882,7 +867,6 @@ public:
virtual ~PVField();
virtual void message(String message,MessageType messageType);
const String&amp; getFieldName() const;
String getFullName() const;
virtual void setRequester(RequesterPtr const &amp;prequester);
std::size_t getFieldOffset() const;
std::size_t getNextFieldOffset() const;
@@ -897,8 +881,9 @@ public:
void postPut();
void setPostHandler(PostHandlerPtr const &amp;postHandler);
virtual bool equals(PVField &amp;pv);
virtual std::ostream&amp; operator&lt;&lt;(std::ostream&amp; o) const = 0;
virtual std::ostream&amp; operator&lt;&lt;(std::ostream&amp; o, size_t index) const = 0;
void toString(StringBuilder buf) ;
void toString(StringBuilder buf,int indentLevel);
std::ostream&amp; operator&lt;&lt;(std::ostream&amp; o) const;
...
};
@@ -995,9 +980,6 @@ public:
virtual void put(T value) = 0;
void operator&gt;&gt;=(T&amp; value) const;
void operator&lt;&lt;=(T value);
virtual std::ostream&amp; operator&lt;&lt;(std::ostream&amp; o) const
virtual std::ostream&amp; operator&lt;&lt;(std::ostream&amp; o, size_t index) const;
...
};
typedef PVScalarValue&lt;uint8&gt; PVBoolean;
@@ -1095,13 +1077,6 @@ public:
const ScalarArrayConstPtr getScalarArray() const;
...
};
// PVString is special case, since it implements SerializableArray
class PVString : public PVScalarValue&lt;String&gt;, SerializableArray {
public:
virtual ~PVString() {}
...
};
</pre>
<p>where</p>
@@ -1115,10 +1090,7 @@ public:
<p>This is a template class plus instances for PVBooleanArray, ...,
PVStringArray.</p>
<pre>template&lt;typename T&gt;
class PVValueArray :
public PVScalarArray
...
{
class PVValueArray : public PVScalarArray {
public:
POINTER_DEFINITIONS(PVValueArray);
typedef T value_type;
@@ -1131,14 +1103,11 @@ public:
typedef shared_vector&lt;const T&gt; const_svector;
virtual ~PVValueArray() {}
const svector &amp; get() const;
const svector &amp; get() ;
const const_svector &amp;get() const;
size_t put(size_t offset,size_t length, const_pointer from, size_t fromOffset);
void put(const svector &amp; from);
void shareData(const svector &amp;from);
virtual std::ostream&amp; operator&lt;&lt;(std::ostream&amp; o) const
virtual std::ostream&amp; operator&lt;&lt;(std::ostream&amp; o, size_t index) const;
...
};
@@ -1195,19 +1164,13 @@ typedef std::tr1::shared_ptr&lt;PVStringArray&gt; PVStringArrayPtr;
than the cureent capacity allows.
It does not change the current length.
</dd>
<dt>void put(const svector &amp; from);</dt>
<dd>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.</dd>
<dt>shareData</dt>
<dd>Share data with an existing shared_vector.
Note that if capacity is ever changed then data will no
longer be shared.</dd>
<dt>operator&lt;&lt;</dt>
<dt>operator&gt;&gt;</dt>
<dd>Methods for stream I/O.</dd>
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.
</dd>
</dl>
<h2>shared_vector</h2>