EPICS pvArray

Introduction

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:

shared pointers: Java has a garbage collector. In C++ the implementation manages memory. The primary tool is std::tr1::shared_ptr.
PVArray: The Java garbage collector allows raw data arrays, e. g. int[], 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
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 naming and other conventions for C++ standard library containers.

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:

pvDataCreate

There should be a new method something like:

PVScalarArrayPtr createPVScalarArray(const PVScalarArray &, size_t offset, size_t length);

This will share the raw data array but allow a new window.

convert

This will be changed to do conversions itself instead of calling methods like getAs. It will again support methods toXXXArray and fromXXXArray, with a raw array replaced by a shared_vector. Templates should be able to minimize the code required.

PVStructureArray

Can this also use shared_vector to hold elements?

pvDataApp/pv

pvData.h

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.

PVField

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:

~PVField: Destructor. Since shared pointers are used it should never be called by user code.
message: Code attached to this field can call this method to report problems.
getFieldName: Get the field name. If the field is a top level structure the field name will be an empty string.
setRequester: Sets a requester to be called when message or getRequesterName are called. This is only legal for the top level PVField.
getFieldOffset: Get offset of the PVField field within top level structure. Every field within the PVStructure has a unique offset. The top level structure has an offset of 0. The first field within the structure has offset equal to 1. The other offsets are determined by recursively traversing each structure of the tree.
getNextFieldOffset: Get the next offset. If the field is a scalar or array field then this is just offset + 1. If the field is a structure it is the offset of the next field after this structure. Thus (nextOffset - offset) is always equal to the total number of fields within the field.
getNumberFields: Get the total number of fields in this field. This is nextFieldOffset - fieldOffset.
getPVAuxInfo: Get the PVAuxInfo for this field. PVAuxInfo is described below.
isImmutable: Is the field immutable?
setImmutable: Make the field immutable. Once a field is immutable it can never be changed since there is no method to again make it mutable. This is an important design decision since it allows immutable array fields to share the internal primitive data array.
getField: Get the reflection interface for the data.
getParent: Get the interface for the parent or null if this is the top level PVStructure.
replacePVField: Replace the data implementation for the field.
renameField: Rename the field name.
postPut: If a postHandler is registered it is called otherwise no action is taken.
setPostHandler: Set the postHandler for the record. Only a single handler can be registered.
operator<<: Stream output

PVScalar

class PVScalar : public PVField {
public:
    POINTER_DEFINITIONS(PVScalar);
    virtual ~PVScalar();

    typedef PVScalar &reference;
    typedef const PVScalar& const_reference;

    const ScalarConstPtr getScalar() const;
...
};

where

getScalar: Get the introspection interface for the PVScalar.

PVScalarValue

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

get: Get the value stored in the object.
put: Change the value stored in the object.
operator<<: Methods for stream I/O.

PVArray

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

getLength: Get the current length. This is less than or equal to the capacity.
setLength: Set the length. If the PVField is not mutable then an exception is thrown. If this is greater than the capacity setCapacity is called.
isCapacityMutable: Is the capacity mutable
setCapacityMutable: Specify if the capacity can be changed.
getCapacity: Get the capacity, i.e. this is the size of the underlying data array.
setCapacity: Set the capacity. The semantics are implementation dependent but typical semantics are as follows: If the capacity is not mutable an exception is thrown. A new data array is created and data is copied from the old array to the new array.

PVScalarArray

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

getScalarArray: Get the introspection interface.

PVValueArray

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

get: Get the shared_vector that holds the data. Code that calls this is able to modify the array elements but should be very careful if it does. For example it must call postPut after modifying the array elements. It must also respect isImmutable().
put: This is the recommended method for modifying the array elements. It may change the capacity if len asks for more elements than the cureent capacity allows. It does not change the current length.
shareData: Share data with an existing shared_vector. Note that if capacity is every changed then data will no longer be shared.
operator<<: Methods for stream I/O.

shared_vector

Status

I think that all public components of sharedVector.h are now documented, but not all have a description or example. Thus the documentation needs more work.

When NOTE EXISTING appears it means that there is a question about the existing shared_vector implementation.

Introduction

A shared_vector is a container as defined by the C++ standard library. It is like std::vector but provides two additional features 1) shared raw array and 2) a window into the raw array.

To support these two features a shared_vector keeps the following private data:

m_data: This is a std::tr1::shared_ptr for the actual data array.
m_offset: This is the offset of the first element seen by the window.
m_count: This is the size, i. e. total number of elements, seen by the window.
m_total: This is the number of elements between offset and the end of the array referenced by m_data.

Note that only m_data is shared. Thus each shared_vector has it's own window.

The following subsections are organized as follows:

shared_vector example: The example code is based on a shared_vector<int32> This subsection show the C++ definitions that are assumed by the example code. The source that contains the example code will be part of this project but not yet.
std::vector compatible subsections: The types and methods that have the same names as std::vector.
share_vector specific: The methods that are not part of std::vector.

The subsections that are compatible with std::vector are organized and start with a brief summary modeled after Section 31.3(STL Containers) in:
"The C++ Programming Language, C++11, Fourth Edition", Bjarne Stroustrup,2013
The subsection names are the same names that Stroustrup uses. Each subsection starts with a brief summary that is similar to the summary Stroustrup has at the beginnining of each subsection.

The comparison is always with std::vector. In addition it shows what is defined by by std::vector but not by shared_vector.

Someone who already understand the C++ STL can understand shared_vector by just looking at the brief summarys. For others the brief summary is followed by tutorial information.

shared_vector example

The examples all assume that the following has been defined:

typedef shared_vector<int32> Int32Array;
...
static void dumpArray(String const &message,Int32Array const& int32Array);

The following:

Int32Array int32Array(5);
dumpArray("example",int32Array);

creates a shared vector that holds an array of five elements where each element is a 32 bit signed integer. The call to dumpArray displays the message and the array elements on standard out:

example 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0

exampleSharedVector is a main program that has the code for the examples shown below.

Member Types

Brief Summary

value_type              Type of element
size_type               Unsigned type of subscripts, element counts, etc.
difference_type         Signed type of difference between iterators
iterator                Behaves like value_type*
const_iterator          Behaves like const value_type*
reverse_iterator        Behaves like value_type*
const_reverse_iterator  Behaves like const value_type*
reference               value_types&
const_reference         const_value_type&
pointer                 Behaves like value_type *
const_pointer           Behaves like const value_type*
//not part of std::vector
element_type            same as value_type
shared_pointer_type     std::tr1::shared_ptr<value_type>
// defined by std::vector but not by shared_vector
allocator_type

The typedefs are compatible with the STL container member types. These define types for various types of variables that belong to a container or are used to access a container.

value_type, reference, and const_reference

These three typedefs define the same types as the equivalent types for an element of the shared_vector.

Int32Array::value_type value;
//is the same as
int32 value;

Int32Array::reference rvalue = value;
//is the same as
int32 & rvalue = value;

Int32Array::const_reference rvalue = value;
//is the same as
const int32 & rvalue = value;

pointer and const_pointer

The following is an example of code that uses the pointer typedef:

Int32Array int32Array(5);
Int32Array::pointer pint32Array = int32Array.data();
size_t len = int32Array.size();
for(size_t i=0; i<len; ++i) pint32Array[i] = i;

A const_pointer is like a pointer except that only read access to the array elements is allowed.

Dangorous: data should not be used unless it is necessary to call C code. The above code should be:

Int32Array int32Array(5);
size_t len = int32Array.size();
for(size_t i=0; i<len; ++i) int32Array[i] = i;

difference_type

This is used to get the number of elements between two elements. For example:

Int32Array::difference_type pdiff = int32Array[3] - int32Array[1];
// pdiff will have the value 2

element_type and shared_pointer_type

These are member types defined by std::tr1::shared_ptr. These are not used by any of the client methods.

Constructors, Destructor, and Assignments

Brief Summary

C c();         Default constructor; c is empty.
C c(n);        c is initialized with n elementis with the value value_type{};
               offset is 0; size is n;
C c(n,e);      Initialize c with n copies of e.
               offset is 0; size is n;

C c(c);        Copy an existing shared_vector of the same type.
               offset and taken same as v.
               shared_ptr is copied; not the raw array
C operator=(c) Assignment constructor.
               shared_ptr is copied; not the raw array
C c(c,o,n);    Copy an existing std::tr1::shared_ptr<value_type>
               offset is o; size is c;
C c(r,o,n);    Use an existing raw pointer.
               default deleter use "delete[]" to delete.
               offset is o; size is c;
C c(r,d,o,n);  Use an existing raw pointer and deleter d;
               offset is o; size is c;

not implemented
~C()           The C++ default destructor is used.
C++11 specific
&& constructor move constructor
{} constructor uniform initializer constructor

where

C: The class name, e. g. shared_vector<int32>
c: shared_vector instance
n: size, i. e. the number of elements
o: offset
e: element instance
r: raw pointer, e. g. int32 *
d: a deleter, i. e. object that destroys the raw array.

Construct by creating new raw array

shared_vector();
shared_vector(size_t n);
shared_vector(size_t n, value_type e);

The first three constructors all create a new shared_vector by also creating a new raw array, The difference is the size of the array, i.e. how many elements it contains, and how the elements are initalized.

shared_vector(): The array is empty, i.e. it has no elements.
shared_vector(size_t n): The array has n elements. Each element is initialized by the default constructor for the element type. For numeric elements, like int32, this means 0.
shared_vector(size_t n, value_type e): The array has n elements. Each element has the initial value e.

The following:

    cout << "***exampleConstructors***" << endl;
    Int32Array emptyArray();
    Int32Array zeroArray(16);
    int32 value = 1;
    Int32Array oneArray(8, value);
    dumpArray("emptyArray",emptyArray);
    dumpArray("zeroArray",zeroArray);
    dumpArray("oneArray",oneArray);

produces

***exampleConstructors***
emptyArray 1
zeroArray {16}[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, ...]
oneArray {8}[1, 1, 1, 1, 1, 1, 1, 1]

NOTE EXISTING: Why did emptyArray disply the above. Should it be "emptyArray {0} []"?

Construct by sharing raw array from a shared_vector

shared_vector(const shared_vector& o);
shared_vector_base& operator=(const shared_vector_base& o);

These create a vector by coping the contents of an existing shared_vector of the same type into the newly created vector. Note that the complete raw array is not copied but just the std::tr1:: shared_ptr that holds the array.

The following:

    cout << "***exampleCopyConstructors***" << endl;
    size_t max = 16;
    Int32Array int32Array(max);
    for(size_t i=0; i<max; ++i) int32Array[i] = i+1;
    Int32Array xxx(int32Array);    //copy constructor
    Int32Array yyy = int32Array;   //copy assignment
    cout << "dataPtr int32Array " << int32Array.dataPtr();
    cout << " xxx " << xxx.dataPtr();
    cout << " yyy " << yyy.dataPtr() << endl;
    dumpArray("int32Array",emptyArray);
    dumpArray("xxx",emptyArray);
    dumpArray("yyy",emptyArray);

produces

***exampleConstructors***
dataPtr int32Array 0x136ea90 xxx 0x136ea90 yyy 0x136ea90
int32Array {16}[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, ...]
xxx {16}[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, ...]
yyy {16}[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, ...]

Construct by wrapping an existing raw array

shared_vector(A v, size_t o, size_t c)
shared_vector(A d, B b, size_t o, size_t c)

NOTE EXISTING: Are these constructors necessary? If code wants to wrap an existing raw array then a std::tr1::shared_ptr can first be created and the constructor in the next section can be called.

These "wrap" an existing raw pointer. They allows access to a sub-array starting at offset o> and has size c The second provides a destructor and the first has a default deleter.

The default deleter does the following: When the shared_vector is deleted, i. e. when no code references it, the statement "delete[] a;" is executed.

An example of wrapping a raw array without using these constructors is:

class Int32ArrayDeleter
{
//Note that this an example that does nothing.
//But it could have private data
public:
     Int32ArrayDeleter() {}
     virtual ~Int32ArrayDeleter() {}
     void operator()(int32* a){
         // MUST HANDLE DELETION
         // default is "delete[] a;"
     }
};
...
int32 *pother; // something managed by other code
size_t capacity; // size of array managed by other code

Int32Array int32Array(pother,int32array_deleter,0,capacity);

This is used to wrap arrays that are managed by other code. This should only be used if You understand the other code and know what your deleter has to do. An example, exampleShareRawArray, gives a more complete example.

Create a shared_vector from an existing shared_ptr

shared_vector(const std::tr1::shared_ptr<E1>& d, size_t o, size_t c)

This creates a vector from an existing smart pointer. Thus the vector will share reference counting with the existing smart pointer. This is useful for creating "windows" into the array that the smart pointer references.

Create a shared_vector from an existing shared_vector

 template<typename E1>
    shared_vector(const shared_vector<E1>& o) :base_t(o) {}

NOTE EXISTING: I do not understand how this works or what it does.

This create a vector by coping the contents of an existing shared_vector of the same or a different but related type into the newly created vector. This constructor creates a new raw array and copies the elements from the existing array to the new array.

Size and Capacity

Brief Summary

size()      Return the number of elements in the window
empty()     Is the window empty? this means shared_ptr is empty
max_size()  The maximum possible number of elements.
capacity()  The number of possible elements without re-allocating raw array.
reserve(n)  Reserve at least n elements in raw array; May cause reallocation.
resize(n)   Change size to n; May cause reallocation
clear()     shared_ptr is reset, Window will be empty.

not implemented
resize(n,v)
shrink_to_fit()

Details

size_t size() const;
bool empty() const;
size_t max_size() const;
size_t capacity() const;
void reserve(size_t n);
void resize(size_t n);
void clear();

size: The current number of elements in the window.
empty: (true,false) if size is (0,>0)
max_size: Maximum possible number of elements. NOTE EXISTING; Should this be sizof(W)/(size_t -1) ?
capacity: The maximum size the window can be without reallocating raw array
reserve: Set the maximum number of element that the window can see. If the caller is the only user of the window and the number of elements specified does not cause the number of elements to change then this method just returns. In all other cases a new raw array is allocated.
resize: Change the window size: may cause a reallocation of the raw array.
clear: If the shared_vector is not already empty the shared_ptr will be reset. The new size will be 0.

The following:

static void exampleSizeEtc()
{
    cout << "***exampleSizeEtc***" << endl;
    size_t max = 16;
    Int32Array int32Array(max);
    size_t capacity = int32Array.capacity();
    size_t size = int32Array.size();
    bool empty = int32Array.empty();
    size_t max_size = int32Array.max_size();
    cout<< "capacity" << capacity;
    cout<< " size " << size;
    cout<< " empty " << (empty ? true : false) ;
    cout<< " max_size " << max_size << endl;
}

produces:

***exampleSizeEtc***
capacity16 size 16 empty 0 max_size 18446744073709551615

Iterators

Brief Summary

begin()      First element
end()        One past last element
cbegin()     Constant first element
cend()       Constant last element
rbegin()     First element of reverse sequence
rend()       One past last element of reverse sequence
crbegin()    Constant first element of reverse sequence
crend()      Constant last element of reverse sequence

shared_vector supports both iterators and reverse iterators as defined by the STL. For both constant iterators are also defined. A constant iterator does not allow an array elemnent to be modified.

The following is an example of a constant iterator.

int32 sum = 0;
for(Int32Array::const_iterator iter=int32Array.begin(); iter<int32Array.end(); ++iter )
{
     sum += *iter;
}

The following is an example of a non constant iterator.

int32 value = 0;
for(Int32Array::iterator iter=int32Array.begin(); iter<int32Array.end(); ++iter )
{
     *iter += ++value;
}

Element Access

Brief Summary

operator[i]    random element access 
data()         return the raw array

implemented by std::vector but not implemented
front()
back()
at()

Note that:

Int32Array::pointer pint32= int32Array.data();

is NOT gauranteed to be the same as

int32 * pint32 = int32Array.data();

NOTE EXISTING: data() should be defined to return a const_pointer. It is currently defined to return a plain pointer.

Stack Operations

Brief Summary

push_back(x)     Add an element after the last element
pop_back(x)      Remove the last element.

List operations

shared_vector does not support the standard list operations like:

implemented by std::vector but not by shared_vector

insert(p,x)   Add x before p
...

Other Operations

Brief Summary

operator==       Do all elements of both containers compare equal.
operator!=       Does any element not compare equal.
operator<<       ostream operator
swap(c2)         Swap the contents of two shared_vectors of the same type.
swap(c1,c2)      Swap the contents of two shared_vectors of the same type.

not implemented
operator<
operator<=
operator>
operator>=

operators equals, not equals, and ostream

template<typename A, typename B>
bool operator==(const epics::pvData::shared_vector<A>& a,
                const epics::pvData::shared_vector<B>& b);

template<typename A, typename B>
bool operator!=(const epics::pvData::shared_vector<A>& a,
                const epics::pvData::shared_vector<B>& b);

template<typename E>
std::ostream& operator<<(
    std::ostream& strm, const epics::pvData::shared_vector<E>& arr);

swap

Swap the contents of two shared_vectors. The following code:

    cout << "***exampleSwap***" << endl;
    Int32Array first(8);
    Int32Array second(16);
    cout << " before swap  size ";
    cout<< "first " << first.size() << " second " << second.size() << endl;
    first.swap(second);
    cout << " after swap   size ";
    cout<< "first " << first.size() << " second " << second.size() << endl;
    swap(first,second);
    cout << " swap again   size ";
    cout<< "first " << first.size() << " second " << second.size() << endl;

produces:

***exampleSwap***
 before swap  size first 8 second 16
 after swap   size first 16 second 8
 swap again   size first 8 second 16

shared_vector specific operations

Brief Summary

void make_unique()         Make caller the only user of std::tr1::shared_ptr
bool unique()              Is the caller the only user of std::tr1::shared_ptr
void slice(offset,length)  Change window offset andsize

// following should only be used for debugging
const std::tr1::shared_ptr<E>&
       dataPtr()           Return const  shared_ptr
size_t dataOffset()        Return offset.
size_t dataCount()         Return count which is also the size
size_t dataTotal()         Return total number of elements between
                           offset and end of the raw array

// following converts from type FROM to type TO
shared_vector static_shared_vector_cast(const shared_vector<FROM>& src);

// following casts from const Type to Type
shared_vector
const_shared_vector_cast(const shared_vector<const TYPE>& src)

NOTE EXISTING: The C++ standard library considers a slice to be every nth element of some part of an array, i. e., slice has arguments (offset,length,stride). shared_vector only has offset and length. Perhaps it should have another name like rewindow.

make_unique and unique

void make_unique();
bool unique() const;

make_unique: Makes sure that caller is the only user of this standard_vector. If the caller is not already the only user a new raw array is allocated.
unique: Returns (true,false) if there is only one user of the shared_vector.

slice

void slice(size_t offset, size_t length=(size_t)-1);

This modifies the "window" into the raw array starting at offset and of the specified length. The offset and length are forced to be within the raw array. Note that this method never reallocates the underlying raw array.

The following code:

static void exampleSlice()
{
    cout << "***exampleSlice***" << endl;
    size_t max = 16;
    Int32Array int32Array(max);
    int32 value = 0;
    for(Int32Array::iterator iter = int32Array.begin(); iter!=int32Array.end(); ++iter)
    {
        *iter = ++value;
    }
    dumpArray("int32Array",int32Array);
    size_t offset = 0;
    size_t length = 8;
    Int32Array window1(int32Array);
    window1.slice(offset,length);
    dumpArray("window1",window1);
    offset = 8;
    length = 8;
    Int32Array window2(int32Array);
    window2.slice(offset,length);
    dumpArray("window2",window2);
    offset = 2;
    length = 4;
    Int32Array window3(window2);
    window3.slice(offset,length);
    dumpArray("window3",window3);
}

produces the following output:

***exampleSlice***
int32Array 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
window1 1 2 3 4 5 6 7 8
window2 9 10 11 12 13 14 15 16
window3 11 12 13 14

dataPtr, dataOffset, dataCount, and dataTotal

dataPtr: Returns the shared_ptr that holds the raw array.
dataOffset: Offset in the data array of first element
dataCount: Number of visible elements. Same as size.
dataTotal: Total number of elements between m_offset and the end of data. Same as capacity.

The following:

static void exampleDataEtc()
{
    cout << "***exampleDataEtc***" << endl;
    size_t max = 16;
    Int32Array int32Array(max);
    long use_count = int32Array.dataPtr().use_count();
    long offset = int32Array.dataOffset();
    long count = int32Array.dataCount();
    long total = int32Array.dataTotal();
    cout << "use_count " << use_count;
    cout << " offset " << offset;
    cout << " count " << count;
    cout << " total " <<  total << endl;
}

produces:

***exampleDataEtc***
use_count 1 offset 0 count 16 total 16

static_shared_vector_cast

Not yet documented

const_shared_vector_cast

Not yet documented

specialization for untyped pointers

Not yet documented

EPICS Array

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

Table of Contents

Introduction

pvDataApp/pv

pvData.h

PVField

PVScalar

PVScalarValue

PVArray

PVScalarArray

PVValueArray

shared_vector

Status

Introduction

shared_vector example

Member Types

value_type, reference, and const_reference

pointer and const_pointer

difference_type

element_type and shared_pointer_type

Constructors, Destructor, and Assignments

Construct by creating new raw array

Construct by sharing raw array from a shared_vector

Construct by wrapping an existing raw array

Create a shared_vector from an existing shared_ptr

Create a shared_vector from an existing shared_vector

Size and Capacity

Iterators

Element Access

Stack Operations

List operations

Other Operations

operators equals, not equals, and ostream

swap

shared_vector specific operations

make_unique and unique

slice

dataPtr, dataOffset, dataCount, and dataTotal

static_shared_vector_cast

const_shared_vector_cast

specialization for untyped pointers