/* pvData.h */ /* * Copyright information and license terms for this software can be * found in the file LICENSE that is included with the distribution */ /** * @author mrk */ #ifndef PVDATA_H #define PVDATA_H #include #include #include #include #include #include #include #include #include #include #include #include #include #include #if defined(vxWorks) && !defined(_WRS_VXWORKS_MAJOR) typedef class std::ios std::ios_base; #endif namespace epics { namespace pvData { /** @defgroup pvcontainer Value containers * * The core of the pvDataCPP library are the typed, structured, data containers. */ class PostHandler; class PVField; class PVScalar; class PVScalarArray; class PVStructure; class PVUnion; template class PVScalarValue; template class PVValueArray; /** * typedef for a pointer to a PostHandler. */ typedef std::tr1::shared_ptr PostHandlerPtr; /** * typedef for a pointer to a PVField. */ typedef std::tr1::shared_ptr PVFieldPtr; /** * typedef for a pointer to a array of pointer to PVField. */ typedef std::vector PVFieldPtrArray; typedef std::vector::iterator PVFieldPtrArray_iterator; typedef std::vector::const_iterator PVFieldPtrArray_const__iterator; /** * typedef for a pointer to a PVScalar. */ typedef std::tr1::shared_ptr PVScalarPtr; /** * typedef for a pointer to a PVScalarArray. */ typedef std::tr1::shared_ptr PVScalarArrayPtr; /** * typedef for a pointer to a PVStructure. */ typedef std::tr1::shared_ptr PVStructurePtr; /** * typedef for a pointer to a array of pointer to PVStructure. */ typedef std::vector PVStructurePtrArray; typedef std::vector::iterator PVStructurePtrArray_iterator; typedef std::vector::const_iterator PVStructurePtrArray_const__iterator; /** * typedef for a pointer to a PVStructureArray. */ typedef PVValueArray PVStructureArray; typedef std::tr1::shared_ptr PVStructureArrayPtr; typedef std::vector PVStructureArrayPtrArray; typedef std::tr1::shared_ptr PVStructureArrayPtrArrayPtr; /** * typedef for a pointer to a PVUnion. */ typedef std::tr1::shared_ptr PVUnionPtr; /** * typedef for a pointer to a array of pointer to PVUnion. */ typedef std::vector PVUnionPtrArray; typedef std::vector::iterator PVUnionPtrArray_iterator; typedef std::vector::const_iterator PVUnionPtrArray_const__iterator; /** * typedef for a pointer to a PVUnionArray. */ typedef PVValueArray PVUnionArray; typedef std::tr1::shared_ptr PVUnionArrayPtr; typedef std::vector PVUnionArrayPtrArray; typedef std::tr1::shared_ptr PVUnionArrayPtrArrayPtr; class PVDataCreate; typedef std::tr1::shared_ptr PVDataCreatePtr; /** * @brief This class is implemented by code that calls setPostHander * */ class epicsShareClass PostHandler { public: POINTER_DEFINITIONS(PostHandler); /** * Destructor */ virtual ~PostHandler(){} /** * This is called every time postPut is called for this field. */ virtual void postPut() = 0; }; /** * @brief PVField is the base class for each PVData field. * * Each PVData field has an interface that extends PVField. * * @ingroup pvcontainer */ class epicsShareClass PVField : virtual public Serializable, public std::tr1::enable_shared_from_this { public: POINTER_DEFINITIONS(PVField); /** * Destructor */ virtual ~PVField(); /** * Get the fieldName for this field. * @return The name or empty string if top-level field. */ inline const std::string& getFieldName() const {return fieldName;} /** * Fully expand the name of this field using the * names of its parent fields with a dot '.' separating * each name. */ std::string getFullName() const; /** * 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. * @return The offset. */ std::size_t getFieldOffset() const; /** * 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 number of fields within the field. * @return The offset. */ std::size_t getNextFieldOffset() const; /** * Get the total number of fields in this field. * This is equal to nextFieldOffset - fieldOffset. */ std::size_t getNumberFields() const; /** * Is the field immutable, i.e. does it not allow changes. * @return (false,true) if it (is not, is) immutable. */ inline bool isImmutable() const {return immutable;} /** * Set the field to be immutable, i.e. it can no longer be modified. * This is permanent, i.e. once done the field cannot be made mutable. */ virtual void setImmutable(); /** * Get the Field that describes the field. * @return Field, which is the reflection interface. */ inline const FieldConstPtr & getField() const {return field;} /** * Get the parent of this field. * @return The parent interface or null if this is PVRecord */ inline PVStructure * getParent() {return parent;} inline const PVStructure * getParent() const {return parent;} /** * postPut. Called when the field is updated by the implementation. */ void postPut() ; /** * Set the handler for postPut. * At most one handler can be set. * @param postHandler The handler. */ void setPostHandler(PostHandlerPtr const &postHandler); /** * Is this field equal to another field. * @param pv other field * @return (false,true) if (is not,is) equal. */ virtual bool equals(PVField &pv); /** * Puts the PVField raw value to the stream. * @param o output stream. * @return The output stream. */ virtual std::ostream& dumpValue(std::ostream& o) const = 0; void copy(const PVField& from); void copyUnchecked(const PVField& from); static size_t num_instances; // use atomic::get() or volatile* access enum {isPVField=1}; protected: PVField::shared_pointer getPtrSelf() { return shared_from_this(); } explicit PVField(FieldConstPtr field); void setParentAndName(PVStructure *parent, std::string const & fieldName); private: static void computeOffset(const PVField *pvField); static void computeOffset(const PVField *pvField,std::size_t offset); std::string fieldName; PVStructure *parent; const FieldConstPtr field; size_t fieldOffset; size_t nextFieldOffset; bool immutable; PostHandlerPtr postHandler; friend class PVDataCreate; friend class PVStructure; EPICS_NOT_COPYABLE(PVField) }; epicsShareExtern std::ostream& operator<<(std::ostream& o, const PVField& f); /** * @brief PVScalar is the base class for each scalar field. * * @ingroup pvcontainer */ class epicsShareClass PVScalar : public PVField { // friend our child class(s) so that it // can call protected methods of other // PVScalar instances. template friend class PVScalarValue; public: POINTER_DEFINITIONS(PVScalar); /** * Destructor */ virtual ~PVScalar(); typedef PVScalar &reference; typedef const PVScalar& const_reference; /** * Get the Scalar introspection interface for the PVScalar. * @return the interface. */ const ScalarConstPtr getScalar() const ; /** * Convert and return the scalar value in the requested type. * Result type is determined from the function template argument * which must be one of the ScalarType enums. * Uses castUnsafe() for value conversion. @code PVScalar* pv = ...; uint32 val = pv->getAs(); @endcode */ template inline T getAs() const { T result; this->getAs((void*)&result, (ScalarType)ScalarTypeID::value); return result; } protected: virtual void getAs(void *, ScalarType) const = 0; public: virtual void getAs(AnyScalar& v) const =0; /** * Convert and assign the provided value. * The value type is determined from the function template argument * which must be one of the ScalarType enums. * Uses castUnsafe() for value conversion. @code PVScalar* pv = ...; pv->putFrom((int32)42); @endcode */ template inline void putFrom(T val) { this->putFrom((const void*)&val, (ScalarType)ScalarTypeID::value); } //! Convert and assign virtual void putFrom(const void *, ScalarType) = 0; inline void putFrom(const AnyScalar& v) { if(v) putFrom(v.unsafe(), v.type()); } virtual void assign(const PVScalar&) = 0; virtual void copy(const PVScalar& from) = 0; virtual void copyUnchecked(const PVScalar& from) = 0; protected: explicit PVScalar(ScalarConstPtr const & scalar); EPICS_NOT_COPYABLE(PVScalar) }; namespace detail { template struct ScalarStorageOps { T value; typedef T arg_type; inline void store(T v) { value = v; } ScalarStorageOps() :value(0) {} }; template<> struct ScalarStorageOps { std::string value; size_t maxLength; typedef const std::string& arg_type; void store(const std::string& val) { if (maxLength > 0 && val.length() > maxLength) throw std::overflow_error("string too long"); value = val; } ScalarStorageOps(): value(), maxLength(0) {} // initialized in PVString::PVString }; } // namespace detail /** * @brief Class that holds the data for each possible scalar type. * * @ingroup pvcontainer */ template class epicsShareClass PVScalarValue : public PVScalar { typedef detail::ScalarStorageOps storage_t; public: POINTER_DEFINITIONS(PVScalarValue); typedef T value_type; typedef T* pointer; typedef const T* const_pointer; static const ScalarType typeCode; /** * Destructor */ virtual ~PVScalarValue(); /** * Get the value. * @return The value. */ typename storage_t::arg_type get() const { return storage.value; } /** * Put a new value into the PVScalar. * @param value The value. */ inline void put(typename storage_t::arg_type v) { storage.store(v); PVField::postPut(); } virtual std::ostream& dumpValue(std::ostream& o) const OVERRIDE; // get operator // double value; doubleField >>= value; // NOTE: virtual is needed for MS C++ compiler to get this operator exported virtual void operator>>=(T& value) const; // put operator // double value = 12.8; doubleField <<= value; // NOTE: virtual is needed for MS C++ compiler to get this operator exported virtual void operator<<=(typename storage_t::arg_type value); template inline T1 getAs() const { T1 result(castUnsafe(get())); return result; } template inline void putFrom(typename detail::ScalarStorageOps::arg_type val) { put(castUnsafe(val)); } inline void putFrom(const AnyScalar& v) { // the template form of putFrom() hides the base class AnyScalar overload PVScalar::putFrom(v); } virtual void assign(const PVScalar& scalar) OVERRIDE FINAL; virtual void copy(const PVScalar& from) OVERRIDE FINAL; virtual void copyUnchecked(const PVScalar& from) OVERRIDE FINAL; virtual void serialize(ByteBuffer *pbuffer, SerializableControl *pflusher) const OVERRIDE; virtual void deserialize(ByteBuffer *pbuffer, DeserializableControl *pflusher) OVERRIDE FINAL; protected: explicit PVScalarValue(ScalarConstPtr const & scalar) : PVScalar(scalar), storage() {} virtual void getAs(void * result, ScalarType rtype) const OVERRIDE FINAL { const T src = get(); castUnsafeV(1, rtype, result, typeCode, (const void*)&src); } public: virtual void getAs(AnyScalar& v) const OVERRIDE FINAL { v = get(); } virtual void putFrom(const void *src, ScalarType stype) OVERRIDE FINAL { T result; castUnsafeV(1, typeCode, (void*)&result, stype, src); put(result); } protected: friend class PVDataCreate; storage_t storage; EPICS_NOT_COPYABLE(PVScalarValue) }; /** * @brief Some explicit specializations exist */ template<> inline std::ostream& PVScalarValue::dumpValue(std::ostream& o) const { return o << static_cast(get()); } template<> inline std::ostream& PVScalarValue::dumpValue(std::ostream& o) const { return o << static_cast(get()); } template<> inline std::ostream& PVScalarValue::dumpValue(std::ostream& o) const { return o << std::boolalpha << static_cast(get()); } /* * typedefs for the various possible scalar types. */ typedef PVScalarValue PVBoolean; typedef PVScalarValue PVByte; typedef PVScalarValue PVShort; typedef PVScalarValue PVInt; typedef PVScalarValue PVLong; typedef PVScalarValue PVUByte; typedef PVScalarValue PVUShort; typedef PVScalarValue PVUInt; typedef PVScalarValue PVULong; typedef PVScalarValue PVFloat; typedef PVScalarValue PVDouble; typedef std::tr1::shared_ptr PVBooleanPtr; typedef std::tr1::shared_ptr PVBytePtr; typedef std::tr1::shared_ptr PVShortPtr; typedef std::tr1::shared_ptr PVIntPtr; typedef std::tr1::shared_ptr PVLongPtr; typedef std::tr1::shared_ptr PVUBytePtr; typedef std::tr1::shared_ptr PVUShortPtr; typedef std::tr1::shared_ptr PVUIntPtr; typedef std::tr1::shared_ptr PVULongPtr; typedef std::tr1::shared_ptr PVFloatPtr; typedef std::tr1::shared_ptr PVDoublePtr; /** * @brief PVString is special case, since it implements SerializableArray * * @ingroup pvcontainer */ class epicsShareClass PVString : public PVScalarValue, SerializableArray { public: /** * Destructor */ virtual ~PVString() {} virtual std::ostream& dumpValue(std::ostream& o) const OVERRIDE FINAL; virtual void serialize(ByteBuffer *pbuffer, SerializableControl *pflusher) const OVERRIDE FINAL; virtual void serialize(ByteBuffer *pbuffer, SerializableControl *pflusher, size_t offset, size_t count) const OVERRIDE FINAL; protected: explicit PVString(ScalarConstPtr const & scalar); friend class PVDataCreate; EPICS_NOT_COPYABLE(PVString) }; typedef std::tr1::shared_ptr PVStringPtr; /** * @brief PVArray is the base class for all array types. * * The array types are unionArray, strucrtureArray and scalarArray. * There is a scalarArray type for each scalarType. * * @ingroup pvcontainer */ class epicsShareClass PVArray : public PVField, public SerializableArray { public: POINTER_DEFINITIONS(PVArray); /** * Destructor */ virtual ~PVArray(){}; /** * Get the introspection interface * @return The interface. */ virtual ArrayConstPtr getArray() const = 0; /** * Set the field to be immutable, i.e. it can no longer be modified. * This is permanent, i.e. once done the field cannot be made mutable. */ virtual void setImmutable() OVERRIDE; /** * Get the array length. * @return The length. */ virtual std::size_t getLength() const = 0; /** * Set the array length. * @param length The length. */ virtual void setLength(std::size_t length) = 0; /** * Get the array capacity. * @return The capacity. */ virtual std::size_t getCapacity() const = 0; /** * Can the capacity be changed. * @return (false,true) if (can not, can) be changed. */ bool isCapacityMutable() const; /** * Set the mutability of the array capacity. * @return false or true */ void setCapacityMutable(bool isMutable); /** * Set the array capacity. * @param capacity The capacity. */ virtual void setCapacity(std::size_t capacity) = 0; using PVField::dumpValue; virtual std::ostream& dumpValue(std::ostream& o, std::size_t index) const = 0; protected: explicit PVArray(FieldConstPtr const & field); void checkLength(size_t length) const; private: bool capacityMutable; friend class PVDataCreate; EPICS_NOT_COPYABLE(PVArray) }; epicsShareExtern std::ostream& operator<<(format::array_at_internal const& manip, const PVArray& array); /** * @brief Base class for a scalarArray. * * @ingroup pvcontainer */ class epicsShareClass PVScalarArray : public PVArray { public: POINTER_DEFINITIONS(PVScalarArray); /** * Destructor */ virtual ~PVScalarArray(); typedef PVScalarArray &reference; typedef const PVScalarArray& const_reference; /** * Get the introspection interface * @return The interface. */ const ScalarArrayConstPtr getScalarArray() const ; protected: virtual void _getAsVoid(shared_vector&) const = 0; virtual void _putFromVoid(const shared_vector&) = 0; public: /** * Fetch the current value and convert to the requested type. * * A copy is made if the requested type does not match * the element type. If the types do match then * no copy is made. */ template void getAs(shared_vector& out) const { shared_vector temp; _getAsVoid(temp); out = shared_vector_convert(temp); } /** * Assign the given value after conversion. * * A copy and element-wise conversion is performed unless * the element type of the PVScalarArray matches the * type of the provided data. * If the types do match then a new reference to the provided * data is kept. * * Calls postPut() */ template inline void putFrom(const shared_vector& inp) { shared_vector temp(static_shared_vector_cast(inp)); _putFromVoid(temp); } /** * Assign the given PVScalarArray's value. * * A copy and element-wise conversion is performed unless * the element type of the PVScalarArray matches the * type of the provided data. * If the types do match then a new reference to the provided * data is kept. */ void assign(const PVScalarArray& pv) { if (isImmutable()) throw std::invalid_argument("destination is immutable"); copyUnchecked(pv); } void copy(const PVScalarArray& from) { assign(from); } void copyUnchecked(const PVScalarArray& from) { if (this==&from) return; shared_vector temp; from._getAsVoid(temp); _putFromVoid(temp); } protected: explicit PVScalarArray(ScalarArrayConstPtr const & scalarArray); private: friend class PVDataCreate; EPICS_NOT_COPYABLE(PVScalarArray) }; /** * @brief Data interface for a structure, * * @ingroup pvcontainer */ class epicsShareClass PVStructure : public PVField, public BitSetSerializable { public: POINTER_DEFINITIONS(PVStructure); /** * Destructor */ virtual ~PVStructure(); typedef PVStructure & reference; typedef const PVStructure & const_reference; /** * Set the field to be immutable, i.e. it can no longer be modified. * This is permanent, i.e. once done the field cannot be made mutable. */ virtual void setImmutable() OVERRIDE FINAL; /** * Get the introspection interface * @return The interface. */ inline const StructureConstPtr &getStructure() const { return structurePtr; } /** * Get the array of pointers to the subfields in the structure. * @return The array. */ inline const PVFieldPtrArray & getPVFields() const { return pvFields; } /** * Get the subfield with the specified offset. * @param a A sub-field name or index * @return Pointer to the field or NULL if field does not exist. */ template FORCE_INLINE std::tr1::shared_ptr getSubField(A a) { return getSubFieldImpl(a, false); } template FORCE_INLINE std::tr1::shared_ptr getSubField(A a) const { return getSubFieldImpl(a, false); } /** * Get a subfield with the specified name. * @param a A sub-field name or index * @returns A pointer to the sub-field or null if field does not exist or has a different type * @code * PVIntPtr ptr = pvStruct->getSubField("substruct.leaffield"); * @endcode * * A field name is a '.' delimited list of child field names (no whitespace allowed) */ template inline std::tr1::shared_ptr getSubField(A a) { STATIC_ASSERT(PVD::isPVField); // only allow cast from PVField sub-class return std::tr1::dynamic_pointer_cast(getSubFieldImpl(a, false)); } template inline std::tr1::shared_ptr getSubField(A a) const { STATIC_ASSERT(PVD::isPVField); // only allow cast from PVField sub-class return std::tr1::dynamic_pointer_cast(getSubFieldImpl(a, false)); } /** * Get the subfield with the specified offset. * @param a A sub-field name or index * @throws std::runtime_error if the requested sub-field doesn't exist, or has a different type * @return Pointer to the field */ template FORCE_INLINE std::tr1::shared_ptr getSubFieldT(A a) { return getSubFieldImpl(a, true); } template FORCE_INLINE std::tr1::shared_ptr getSubFieldT(A a) const { return getSubFieldImpl(a, true); } private: static void throwBadFieldType(const char *name); static void throwBadFieldType(std::size_t fieldOffset); static FORCE_INLINE void throwBadFieldType(const std::string& name) { throwBadFieldType(name.c_str()); } public: template inline std::tr1::shared_ptr getSubFieldT(A a) { STATIC_ASSERT(PVD::isPVField); // only allow cast from PVField sub-class std::tr1::shared_ptr ret(std::tr1::dynamic_pointer_cast(getSubFieldImpl(a, true))); if(!ret) throwBadFieldType(a); return ret; } template inline std::tr1::shared_ptr getSubFieldT(A a) const { STATIC_ASSERT(PVD::isPVField); // only allow cast from PVField sub-class std::tr1::shared_ptr ret(std::tr1::dynamic_pointer_cast(getSubFieldImpl(a, true))); if(!ret) throwBadFieldType(a); return ret; } /** * Serialize. * @param pbuffer The byte buffer. * @param pflusher Interface to call when buffer is full. */ virtual void serialize( ByteBuffer *pbuffer,SerializableControl *pflusher) const OVERRIDE FINAL; /** * Deserialize * @param pbuffer The byte buffer. * @param pflusher Interface to call when buffer is empty. */ virtual void deserialize( ByteBuffer *pbuffer,DeserializableControl *pflusher) OVERRIDE FINAL; /** * Serialize. * @param pbuffer The byte buffer. * @param pflusher Interface to call when buffer is full. * @param pbitSet A bitset the specifies which fields to serialize. */ virtual void serialize(ByteBuffer *pbuffer, SerializableControl *pflusher,BitSet *pbitSet) const OVERRIDE FINAL; /** * Deserialize * @param pbuffer The byte buffer. * @param pflusher Interface to call when buffer is empty. * @param pbitSet A bitset the specifies which fields to deserialize. */ virtual void deserialize(ByteBuffer *pbuffer, DeserializableControl*pflusher,BitSet *pbitSet) OVERRIDE FINAL; /** * Constructor * @param structure The introspection interface. */ explicit PVStructure(StructureConstPtr const & structure); /** * Constructor * @param structure The introspection interface. * @param pvFields The array of fields for the structure. */ PVStructure(StructureConstPtr const & structure,PVFieldPtrArray const & pvFields); virtual std::ostream& dumpValue(std::ostream& o) const OVERRIDE FINAL; void copy(const PVStructure& from); void copyUnchecked(const PVStructure& from); void copyUnchecked(const PVStructure& from, const BitSet& maskBitSet, bool inverse = false); struct Formatter { enum mode_t { Auto, Plain, ANSI, }; enum format_t { Raw, NT, JSON, }; private: const PVStructure& xtop; const BitSet* xshow; const BitSet* xhighlight; mode_t xmode; format_t xfmt; public: explicit Formatter(const PVStructure& top) :xtop(top) ,xshow(0) ,xhighlight(0) ,xmode(Auto) ,xfmt(NT) {} // those fields (and their parents) to be printed. non-NT mode. FORCE_INLINE Formatter& show(const BitSet& set) { xshow = &set; return *this; } // those fields (and not their parents) to be specially highlighted. non-NT mode. FORCE_INLINE Formatter& highlight(const BitSet& set) { xhighlight = &set; return *this; } FORCE_INLINE Formatter& mode(mode_t m) { xmode = m; return *this; } FORCE_INLINE Formatter& format(format_t f) { xfmt = f; return *this; } friend epicsShareFunc std::ostream& operator<<(std::ostream& strm, const Formatter& format); friend void printRaw(std::ostream& strm, const PVStructure::Formatter& format, const PVStructure& cur); }; FORCE_INLINE Formatter stream() const { return Formatter(*this); } private: inline PVFieldPtr getSubFieldImpl(const std::string& name, bool throws) const { return getSubFieldImpl(name.c_str(), throws); } PVFieldPtr getSubFieldImpl(const char *name, bool throws) const; PVFieldPtr getSubFieldImpl(std::size_t fieldOffset, bool throws) const; PVFieldPtrArray pvFields; StructureConstPtr structurePtr; std::string extendsStructureName; friend class PVDataCreate; EPICS_NOT_COPYABLE(PVStructure) }; epicsShareFunc std::ostream& operator<<(std::ostream& strm, const PVStructure::Formatter& format); /** * @brief PVUnion has a single subfield. * * The type for the subfield is specified by a union introspection interface. * * @ingroup pvcontainer */ class epicsShareClass PVUnion : public PVField { public: POINTER_DEFINITIONS(PVUnion); /** * Destructor */ virtual ~PVUnion(); typedef PVUnion & reference; typedef const PVUnion & const_reference; /** * Undefined index. * Default value upon PVUnion construction. Can be set by the user. * Corresponds to @c null value. */ static const int32 UNDEFINED_INDEX; /** * Get the introspection interface * @return The interface. */ inline const UnionConstPtr& getUnion() const { return unionPtr; } /** * Get the @c PVField value stored in the field. * @return @c PVField value of field, @c null if {@code getSelectedIndex() == UNDEFINED_INDEX}. */ inline const PVFieldPtr& get() { return value; } inline PVField::const_shared_pointer get() const { return value; } template inline std::tr1::shared_ptr get() { STATIC_ASSERT(PVT::isPVField); // only allow cast from PVField sub-class return std::tr1::dynamic_pointer_cast(get()); } template inline std::tr1::shared_ptr get() const { STATIC_ASSERT(PVT::isPVField); // only allow cast from PVField sub-class return std::tr1::dynamic_pointer_cast(get()); } /** * Select field (set index) and get the field at the index. * @param index index of the field to select. * @return corresponding PVField (of undetermined value), @c null if {@code index == UNDEFINED_INDEX}. * @throws std::invalid_argument if index is invalid (out of range). */ PVFieldPtr select(int32 index); template inline std::tr1::shared_ptr select(int32 index) { STATIC_ASSERT(PVT::isPVField); // only allow cast from PVField sub-class return std::tr1::dynamic_pointer_cast(select(index)); } /** * Select field (set index) and get the field by given name. * @param fieldName the name of the field to select. * @return corresponding PVField (of undetermined value). * @throws std::invalid_argument if field does not exist. */ PVFieldPtr select(std::string const & fieldName); template inline std::tr1::shared_ptr select(std::string const & fieldName) { return std::tr1::dynamic_pointer_cast(select(fieldName)); } /** * Get selected field index. * @return selected field index. */ inline int32 getSelectedIndex() const { return selector; } /** * Get selected field name. * @return selected field name, empty string if field does not exist. */ std::string getSelectedFieldName() const; /** * Set the @c PVField (by reference!) as selected field. * If a value is not a valid union field an @c std::invalid_argument * exception is thrown. * @param value the field to set. */ inline void set(PVFieldPtr const & value) { set(selector, value); } /** * Set the @c PVField (by reference!) as field at given index. * If a value is not a valid union field an @c std::invalid_argument * exception is thrown. * Use @c select(int32) to put by value. * @param index index of a field to put. * @param value the field to set. * @see #select(int32) */ void set(int32 index, PVFieldPtr const & value); /** * Set the @c PVField (by reference!) as field by given name. * If a value is not a valid union field an @c std::invalid_argument * exception is thrown. * Use @c select(std::string const &) to put by value. * @param fieldName Name of the field to put. * @param value the field to set. * @see #select(std::string const &) */ void set(std::string const & fieldName, PVFieldPtr const & value); /** * Serialize. * @param pbuffer The byte buffer. * @param pflusher Interface to call when buffer is full. */ virtual void serialize( ByteBuffer *pbuffer,SerializableControl *pflusher) const OVERRIDE FINAL; /** * Deserialize * @param pbuffer The byte buffer. * @param pflusher Interface to call when buffer is empty. */ virtual void deserialize( ByteBuffer *pbuffer,DeserializableControl *pflusher) OVERRIDE FINAL; /** * Constructor * @param punion The introspection interface. */ explicit PVUnion(UnionConstPtr const & punion); virtual std::ostream& dumpValue(std::ostream& o) const OVERRIDE FINAL; void copy(const PVUnion& from); void copyUnchecked(const PVUnion& from); private: static PVDataCreatePtr pvDataCreate; friend class PVDataCreate; UnionConstPtr unionPtr; // same as PVField::getField() int32 selector; PVFieldPtr value; bool variant; EPICS_NOT_COPYABLE(PVUnion) }; namespace detail { // adaptor to allow epics::pvData::shared_vector to hold a reference // to a shared_ptr > template struct shared_ptr_vector_deletor { typedef std::tr1::shared_ptr > shared_vector; shared_vector vec; shared_ptr_vector_deletor(const shared_vector& v) :vec(v) {} void operator()(T*){vec.reset();} }; //! Common code for PV*Array template class PVVectorStorage : public Base { public: typedef T value_type; typedef T* pointer; typedef const T* const_pointer; //TODO: full namespace can be removed along with local typedef 'shared_vector' typedef ::epics::pvData::shared_vector svector; typedef ::epics::pvData::shared_vector const_svector; protected: template explicit PVVectorStorage(A a) : Base(a) {} public: virtual ~PVVectorStorage(){} // Primitive array manipulations //! Fetch a read-only view of the current array data virtual const_svector view() const = 0; /** Exchange our contents for the provided. * @throws std::logic_error for Immutable arrays. * * Callers must ensure that postPut() is called * after the last swap() operation. * * Before you call this directly, consider using * the reuse(), or replace() methods. */ virtual void swap(const_svector& other) = 0; //! Discard current contents and replaced with the provided. //! Fails for Immutable arrays //! calls postPut() virtual void replace(const const_svector& next) = 0; // Derived operations /** Remove and return the current array data * or an unique copy if shared. * * Does @b not (and should not) call postPut() * * The returned shared_vector will * have unique()==true. */ inline svector reuse() { const_svector result; this->swap(result); return thaw(result); } EPICS_NOT_COPYABLE(PVVectorStorage) }; } // namespace detail /** * @brief template class for all extensions of PVArray. * * The direct extensions are pvBooleanArray, pvByteArray, ..., pvStringArray. * There are specializations for PVStringArray, PVStructureArray, and PVUnionArray. * * @ingroup pvcontainer */ template class epicsShareClass PVValueArray : public detail::PVVectorStorage { typedef detail::PVVectorStorage base_t; public: POINTER_DEFINITIONS(PVValueArray); typedef T value_type; typedef T* pointer; typedef const T* const_pointer; //TODO: full namespace can be removed along with local typedef 'shared_vector' typedef ::epics::pvData::shared_vector svector; typedef ::epics::pvData::shared_vector const_svector; static const ScalarType typeCode; /** * Destructor */ virtual ~PVValueArray(); /** * Get introspection interface. */ virtual ArrayConstPtr getArray() const OVERRIDE FINAL; virtual std::ostream& dumpValue(std::ostream& o) const OVERRIDE FINAL; virtual std::ostream& dumpValue(std::ostream& o, size_t index) const OVERRIDE FINAL; virtual size_t getLength() const OVERRIDE FINAL {return value.size();} virtual size_t getCapacity() const OVERRIDE FINAL {return value.capacity();} virtual void setCapacity(size_t capacity) OVERRIDE FINAL; virtual void setLength(size_t length) OVERRIDE FINAL; virtual const_svector view() const OVERRIDE FINAL {return value;} virtual void swap(const_svector &other) OVERRIDE FINAL; virtual void replace(const const_svector& next) OVERRIDE FINAL; // from Serializable virtual void serialize(ByteBuffer *pbuffer,SerializableControl *pflusher) const OVERRIDE FINAL; virtual void deserialize(ByteBuffer *pbuffer,DeserializableControl *pflusher) OVERRIDE FINAL; virtual void serialize(ByteBuffer *pbuffer, SerializableControl *pflusher, size_t offset, size_t count) const OVERRIDE FINAL; protected: virtual void _getAsVoid(epics::pvData::shared_vector& out) const OVERRIDE FINAL; virtual void _putFromVoid(const epics::pvData::shared_vector& in) OVERRIDE FINAL; explicit PVValueArray(ScalarArrayConstPtr const & scalar); const_svector value; friend class PVDataCreate; EPICS_NOT_COPYABLE(PVValueArray) }; /** * @brief Data class for a structureArray * * @ingroup pvcontainer */ template<> class epicsShareClass PVValueArray : public detail::PVVectorStorage { typedef detail::PVVectorStorage base_t; public: POINTER_DEFINITIONS(PVStructureArray); typedef PVStructurePtr value_type; typedef PVStructurePtr* pointer; typedef const PVStructurePtr* const_pointer; typedef PVStructureArray &reference; typedef const PVStructureArray& const_reference; //TODO: full namespace can be removed along with local typedef 'shared_vector' typedef ::epics::pvData::shared_vector svector; typedef ::epics::pvData::shared_vector const_svector; /** * Destructor */ virtual ~PVValueArray() {} virtual ArrayConstPtr getArray() const OVERRIDE FINAL { return std::tr1::static_pointer_cast(structureArray); } virtual size_t getLength() const OVERRIDE FINAL {return value.size();} virtual size_t getCapacity() const OVERRIDE FINAL {return value.capacity();} /** * Set the array capacity. * @param capacity The length. */ virtual void setCapacity(size_t capacity) OVERRIDE FINAL; /** * Set the array length. * @param length The length. */ virtual void setLength(std::size_t length) OVERRIDE FINAL; /** * Get the introspection interface * @return The interface. */ StructureArrayConstPtr getStructureArray() const {return structureArray;} /** * Append new elements to the end of the array. * @param number The number of elements to add. * @return the new length of the array. */ std::size_t append(std::size_t number); /** * Remove elements from the array. * @param offset The offset of the first element to remove. * @param number The number of elements to remove. * @return (false,true) if the elements were removed. */ bool remove(std::size_t offset,std::size_t number); /** * Compress. This removes all null elements from the array. */ void compress(); virtual const_svector view() const OVERRIDE FINAL { return value; } virtual void swap(const_svector &other) OVERRIDE FINAL; virtual void replace(const const_svector &other) OVERRIDE FINAL { checkLength(other.size()); value = other; PVField::postPut(); } virtual void serialize(ByteBuffer *pbuffer, SerializableControl *pflusher) const OVERRIDE FINAL; virtual void deserialize(ByteBuffer *buffer, DeserializableControl *pflusher) OVERRIDE FINAL; virtual void serialize(ByteBuffer *pbuffer, SerializableControl *pflusher, std::size_t offset, std::size_t count) const OVERRIDE FINAL; virtual std::ostream& dumpValue(std::ostream& o) const OVERRIDE FINAL; virtual std::ostream& dumpValue(std::ostream& o, std::size_t index) const OVERRIDE FINAL; void copy(const PVStructureArray& from); void copyUnchecked(const PVStructureArray& from); protected: PVValueArray(StructureArrayConstPtr const & structureArray); private: StructureArrayConstPtr structureArray; const_svector value; friend class PVDataCreate; EPICS_NOT_COPYABLE(PVValueArray) }; /** * @brief Data class for a unionArray * * @ingroup pvcontainer */ template<> class epicsShareClass PVValueArray : public detail::PVVectorStorage { typedef detail::PVVectorStorage base_t; public: POINTER_DEFINITIONS(PVUnionArray); typedef PVUnionPtr value_type; typedef PVUnionPtr* pointer; typedef const PVUnionPtr* const_pointer; typedef PVUnionArray &reference; typedef const PVUnionArray& const_reference; //TODO: full namespace can be removed along with local typedef 'shared_vector' typedef ::epics::pvData::shared_vector svector; typedef ::epics::pvData::shared_vector const_svector; /** * Destructor */ virtual ~PVValueArray() {} virtual ArrayConstPtr getArray() const OVERRIDE FINAL { return std::tr1::static_pointer_cast(unionArray); } virtual size_t getLength() const OVERRIDE FINAL {return value.size();} virtual size_t getCapacity() const OVERRIDE FINAL {return value.capacity();} /** * Set the array capacity. * @param capacity The length. */ virtual void setCapacity(size_t capacity) OVERRIDE FINAL; /** * Set the array length. * @param length The length. */ virtual void setLength(std::size_t length) OVERRIDE FINAL; /** * Get the introspection interface * @return The interface. */ UnionArrayConstPtr getUnionArray() const {return unionArray;} /** * Append new elements to the end of the array. * @param number The number of elements to add. * @return the new length of the array. */ std::size_t append(std::size_t number); /** * Remove elements from the array. * @param offset The offset of the first element to remove. * @param number The number of elements to remove. * @return (false,true) if the elements were removed. */ bool remove(std::size_t offset,std::size_t number); /** * Compress. This removes all null elements from the array. */ void compress(); virtual const_svector view() const OVERRIDE { return value; } virtual void swap(const_svector &other) OVERRIDE; virtual void replace(const const_svector &other) OVERRIDE FINAL { checkLength(other.size()); value = other; PVField::postPut(); } virtual void serialize(ByteBuffer *pbuffer, SerializableControl *pflusher) const OVERRIDE FINAL; virtual void deserialize(ByteBuffer *buffer, DeserializableControl *pflusher) OVERRIDE FINAL; virtual void serialize(ByteBuffer *pbuffer, SerializableControl *pflusher, std::size_t offset, std::size_t count) const OVERRIDE FINAL; virtual std::ostream& dumpValue(std::ostream& o) const OVERRIDE FINAL; virtual std::ostream& dumpValue(std::ostream& o, std::size_t index) const OVERRIDE FINAL; void copy(const PVUnionArray& from); void copyUnchecked(const PVUnionArray& from); protected: explicit PVValueArray(UnionArrayConstPtr const & unionArray); private: UnionArrayConstPtr unionArray; const_svector value; friend class PVDataCreate; EPICS_NOT_COPYABLE(PVValueArray) }; /** * Definitions for the various scalarArray types. */ typedef PVValueArray PVBooleanArray; typedef std::tr1::shared_ptr PVBooleanArrayPtr; typedef PVValueArray PVByteArray; typedef std::tr1::shared_ptr PVByteArrayPtr; typedef PVValueArray PVShortArray; typedef std::tr1::shared_ptr PVShortArrayPtr; typedef PVValueArray PVIntArray; typedef std::tr1::shared_ptr PVIntArrayPtr; typedef PVValueArray PVLongArray; typedef std::tr1::shared_ptr PVLongArrayPtr; typedef PVValueArray PVUByteArray; typedef std::tr1::shared_ptr PVUByteArrayPtr; typedef PVValueArray PVUShortArray; typedef std::tr1::shared_ptr PVUShortArrayPtr; typedef PVValueArray PVUIntArray; typedef std::tr1::shared_ptr PVUIntArrayPtr; typedef PVValueArray PVULongArray; typedef std::tr1::shared_ptr PVULongArrayPtr; typedef PVValueArray PVFloatArray; typedef std::tr1::shared_ptr PVFloatArrayPtr; typedef PVValueArray PVDoubleArray; typedef std::tr1::shared_ptr PVDoubleArrayPtr; typedef PVValueArray PVStringArray; typedef std::tr1::shared_ptr PVStringArrayPtr; namespace detail { struct pvfield_factory; } /** * @brief This is a singleton class for creating data instances. * */ class epicsShareClass PVDataCreate { friend struct detail::pvfield_factory; public: /** * get the singleton * @return The PVDataCreate implementation */ static const PVDataCreatePtr &getPVDataCreate(); /** * Create a PVField using given Field introspection data. * @param field The introspection data to be used to create PVField. * @return The PVField implementation. */ PVFieldPtr createPVField(FieldConstPtr const & field); /** * Create a PVField using given a PVField to clone. * This method calls the appropriate createPVScalar, createPVArray, or createPVStructure. * @param fieldToClone The field to clone. * @return The PVField implementation */ PVFieldPtr createPVField(PVFieldPtr const & fieldToClone); /** * Create an implementation of a scalar field reusing the Scalar introspection interface. * @param scalar The introspection interface. * @return The PVScalar implementation. */ PVScalarPtr createPVScalar(ScalarConstPtr const & scalar); /** * Create an implementation of a scalar field. A Scalar introspection interface is created. * @param scalarType The scalar type. * @return The PVScalar implementation. */ PVScalarPtr createPVScalar(ScalarType scalarType); /** * Create an implementation of a scalar field by cloning an existing PVScalar. * The new PVScalar will have the same value and auxInfo as the original. * @param scalarToClone The PVScalar to clone. * @return The PVScalar implementation. */ PVScalarPtr createPVScalar(PVScalarPtr const & scalarToClone); /** * template version * @tparam PVT must be a valid PVType * @return The PVScalar implementation. */ template std::tr1::shared_ptr createPVScalar() { return std::tr1::static_pointer_cast(createPVScalar(PVT::typeCode)); } /** * Create implementation for PVStructure. * @param structure The introspection interface. * @return The PVStructure implementation */ PVStructurePtr createPVStructure(StructureConstPtr const & structure); /** * Create implementation for PVStructure. * @param fieldNames The field names. * @param pvFields Array of PVFields * @return The PVStructure implementation */ PVStructurePtr createPVStructure( StringArray const & fieldNames,PVFieldPtrArray const & pvFields); /** * Create implementation for PVStructure. * @param structToClone A structure. Each subfield and any auxInfo is cloned and added to the newly created structure. * @return The PVStructure implementation. */ PVStructurePtr createPVStructure(PVStructurePtr const & structToClone); /** * Create implementation for PVUnion. * @param punion The introspection interface. * @return The PVUnion implementation */ PVUnionPtr createPVUnion(UnionConstPtr const & punion); /** * Create implementation for PVUnion. * @param unionToClone A union. Each subfield is cloned and added to the newly created union. * @return The PVUnion implementation. */ PVUnionPtr createPVUnion(PVUnionPtr const & unionToClone); /** * Create variant union implementation. * @return The variant PVUnion implementation. */ PVUnionPtr createPVVariantUnion(); /** * Create an implementation of an array field reusing the Array introspection interface. * @param scalarArray The introspection interface. * @return The PVScalarArray implementation. */ PVScalarArrayPtr createPVScalarArray(ScalarArrayConstPtr const & scalarArray); /** * Create an implementation for an array field. An Array introspection interface is created. * @param elementType The element type. * @return The PVScalarArray implementation. */ PVScalarArrayPtr createPVScalarArray(ScalarType elementType); /** * Create an implementation of an array field by cloning an existing PVArray. * The new PVArray will have the same value and auxInfo as the original. * @param scalarArrayToClone The PVScalarArray to clone. * @return The PVScalarArray implementation. */ PVScalarArrayPtr createPVScalarArray(PVScalarArrayPtr const & scalarArrayToClone); /** * template version * @tparam PVT must be a valid pvType * @return The PVScalarArray implementation. */ template std::tr1::shared_ptr createPVScalarArray() { return std::tr1::static_pointer_cast(createPVScalarArray(PVAT::typeCode)); } /** * Create an implementation of an array with structure elements. * @param structureArray The introspection interface. * All elements share the same introspection interface. * @return The PVStructureArray implementation. */ PVStructureArrayPtr createPVStructureArray(StructureArrayConstPtr const & structureArray); /** * Create an implementation of an array with structure elements. * @param structure The introspection interface that is used to create StructureArrayConstPtr. * All elements share the same introspection interface. * @return The PVStructureArray implementation. */ PVStructureArrayPtr createPVStructureArray(StructureConstPtr const & structure) { return createPVStructureArray(fieldCreate->createStructureArray(structure)); } /** * Create an implementation of an array with union elements. * @param unionArray The introspection interface. * All elements share the same introspection interface. * @return The PVUnionArray implementation. */ PVUnionArrayPtr createPVUnionArray(UnionArrayConstPtr const & unionArray); /** * Create an implementation of an array with union elements. * @param punion The introspection interface that is used to create UnionArrayConstPtr. * All elements share the same introspection interface. * @return The PVUnionArray implementation. */ PVUnionArrayPtr createPVUnionArray(UnionConstPtr const & punion) { return createPVUnionArray(fieldCreate->createUnionArray(punion)); } /** * Create variant union array implementation. * @return The variant PVUnionArray implementation. */ PVUnionArrayPtr createPVVariantUnionArray(); private: PVDataCreate(); FieldCreatePtr fieldCreate; EPICS_NOT_COPYABLE(PVDataCreate) }; /** * Get the single class that implements PVDataCreate * @return The PVDataCreate factory. * * @ingroup pvcontainer */ FORCE_INLINE const PVDataCreatePtr& getPVDataCreate() { return PVDataCreate::getPVDataCreate(); } bool epicsShareExtern operator==(const PVField&, const PVField&); static inline bool operator!=(const PVField& a, const PVField& b) {return !(a==b);} }} /** * stream support for pvField */ namespace std{ epicsShareExtern std::ostream& operator<<(std::ostream& o, const epics::pvData::PVField *ptr); } #endif /* PVDATA_H */