V4 Design: epicsTypes

EPICS: epicsTypes - C++ support for Network Accessable Data

May 20 2005

Overview

This document describes the C++ definitions for storing data that is accessable from outside the code that manages the data. The goal to be able to describe and transport structured data without requiring pre-complied code that understands the structure.

Some examples are:

1. IOC records - Everything accessable from outside record support
2. Channel Access Gateway - Everything accessable by channel access clients
3. Channel Access Clients - Everything a client sends or receives

NOTE: This is NOT a replacement for dataAccess

Standard support can be provided to access, via dataAccess, epicsType data. For example standard support can be provided to move IOC record data between record instances and a Channel Access server.

epicsType is an enum that lists the following:

• epicsBooleanT,...,epicsFloat64T - Each maps to a C++ primitive type
• epicsStringT - Support for UTF-8 Encoded Strings
• epicsArrayT - Support for 1dim arrays. The array can be any epicsType.
• epicsStructT - Support for a structure. A structure has fields that can be any epicsType.
• epicsImageT - An ndim array of one of the primitive types

Since an array can have type epicsStructT and a structure can have fields of type epicsStructT and epicsArrayT complicated data can be described.

epicsTypes

epicsTypes.h contains the following:

    /* The following may require OSD definitions*/
    typedef bool               epicsBoolean;
    typedef char               epicsOctet;
    typedef short              epicsInt16;
    typedef unsigned short     epicsUInt16;
    typedef int                epicsInt32;
    typedef unsigned int       epicsUInt32;
    typedef long long          epicsInt64;
    typedef unsigned long long epicsUInt64;
    typedef float              epicsFloat32;
    typedef double             epicsFloat64;
   
    enum epicsType {
        epicsUnknownT,
        epicsBooleanT,     // epicsBoolean
        epicsOctetT,       // epicsOctet
        epicsInt16T,       // epicsInt16
        epicsUInt16T,      // epicsUInt16
        epicsInt32T,       // epicsInt32
        epicsUInt32T,      // epicsUInt32
        epicsInt64T,       // epicsInt64
        epicsUInt64T,      // epicsUInt64
        epicsFloat32T,     // epicsFloat32
        epicsFloat64T,     // epicsFloat64
        epicsStringT,      // described in epicsString.h
        epicsArrayT,       // described in epicsArray.h
        epicsStructT,      // described in epicsStruct.h
        epicsImageT        // described in epicsImage.h
    };

Discussion of epicsTypes

epicsTypes provides classes for describing data that can be introspected and can be passed between different platforms. All data that is sent to or received from EPICS records will be composed of epicsTypes.

The types epicsBooleanT, ..., epicsFloat64T all map to a C++ standard type. It may be necessary to provide operating system dependent definitions for some of the types. For example on some architectures a epicsInt64 may have to be defined as a long rather than a long long.

The types epicsStringT, epicsArrayT, epicsStructT, and epicsImageT are designed so that any data can be described, introspected, and passed over a network. An epicsStruct can contain epicsArrays and epicsStructs and a epicsArray can be an array of any epicsType except epicsUnknownT.

epicsUnknownT is provided in case something expected to produce an epicsType fails.

epicsString

epicsString.h contains the following:

    class EpicsUTF_8Buffer;
    
    /*EpicsString holds UTF-8 characters*/
    class EpicsString  {
    public:
        EpicsUTF_8Buffer    *pbuffer;
    };

    class EpicsUTF_8Expose {
        // return (false,true) means (call if more data, done)
        bool expose(epicsOctet *pdata,
                 epicsInt32 offset, epicsInt32 limit) = 0;
    };
    class EpicsUTF_8Buffer {
    public:
        virtual epicsInt32 allocate(epicsInt32 capacity) = 0;
        virtual void release(bool onlyStorage) = 0;
        virtual epicsInt32 capacity() = 0;
        virtual epicsInt32 limit() = 0;
        virtual void limit(epicsInt32 newLimit) = 0;
        virtual epicsInt32 get(epicsOctet *pto,
                               epicsInt32 offset, epicsInt32 limit) = 0;
        virtual void epicsInt32 put(const epicsOctet *pfrom,
                               epicsInt32 offset, epicsInt32 limit) = 0;
        virtual void expose(EpicsUTF_8Expose *expose,
                            epicsInt32 offset, epicsInt32 limit);
        virtual bool isEqual(const EpicsUTF_8Buffer *pbuffer) = 0;
        virtual bool isEqual(const epicsOctet *pstring, epicsInt32 len) = 0;
        virtual epicsUint32 hash(epicsInt16 nBitsHashIndex) = 0;
    };

    typedef EpicsUTF_8Buffer *(EpicsUTF_8BufferAllocate)();
    class EpicsUTF_8BufferFactory {
    public:
        static epicsUint16 typeToTypeID(const char *type);
        static EpicsUTF_8Buffer *allocate(epicsUint16 typeId);
        static void register(const epicsStringBufferType type,
                         EpicsUTF_8BufferAllocate allocater,
                         const char *type);
    };
    // type : At least "Contiguous" and "Segmented" are implemented

Discussion of epicsString

An EpicsString contains UTF-8 encoded character strings. It has the following fields:

pbuffer

The address of a EpicsUTF_8Buffer, which is a class that manages the string storage.

EpicsUTF_8Buffer is a pure abstract base classe because multiple implementation of each are allowed.

EpicsUTF_8Buffer

NOTE: EpicsUTF_8Buffer uses ideas from the Java nio Buffer class.

An EpicsUTF_8Buffer contains storage for a UTF-8 encoded string. In addition to holding storage for a string, a string buffer keeps the following information.

capacity

The number of octets allocated, i.e. the number of UTF-8 characters the buffer can hold.

limit

The current size, i.e. the index of the first octet that can not hold data. Data can not be read from or written into a buffer beyond limit. When data is being written to a buffer limit is normally equal to capacity. When data is being read from a buffer limit is normally less than capacity and indicates the end of valid data.

EpicsUTF_8Buffer has the following methods:

allocate

This allocates space for up to capacity octets. The number of octets allocated is returned. An implementation attempts to allocate the requested capacity but some implemenations, e.g. network buffers, may impose a maximum size. If capacity is not zero when this is called and new storage is allocated then the old storage is freed or reused and the octets spanned by position, limit appear in the newly allocated storage.

release

Releases storage. If onlyStorage is true then the storage for the string is freed and capacity is set to zero; otherwise the string storage and the storage for EpicsUTF_8Buffer itself is freed.

capacity

return the capacity

limit

Two methods are available, one to get the current limit and one to set the limit.

get

copies characters to pto and returns the number of octets transfered.

put

copies characters from pfrom and puts them into the buffer and returns the nimber of octets transfered.

expose

This is a request to call the expose method of EpicsUTF_8Expose. The expose method may get called multiple times if the string is stored in segments.

isEqual(EpicsUTF_8Buffer *)

Compares the string stored in the buffer with a string stored in a different buffer. This is normally called by code that uses an EpicsUTF_8Buffer.

isEqual(epicsOctet *pstring, epicsInt32 len)

Compares the string stored in the buffer with a string supplied by the caller. This is normally called by EpicsUTF_8Buffer itself to compare it's string with the string stored in another buffer.

hash

implement a hash on the octets stored in the buffer.

EpicsUTF_8BufferFactory

This is a class for allocating an EpicsUTF_8Buffer and also for registering EpicsUTF_8Buffer implementations.

epicsArray

epicsArray.h contains the following:

    class EpicsArrayExpose {
        // return (false,true) means (call if more data, done)
        bool expose(void *pdata,
                 epicsUInt32 offset, epicsUInt32 limit) = 0;
    };
    class EpicsArrayBuffer {
    public:
        virtual epicsUInt32 allocate(
                    epicsUInt32 capacity,epicsUint16 elementSize) = 0;
        virtual void release(bool onlyStorage) = 0;
        virtual epicsUInt32 capacity() = 0;
        virtual epicsUInt32 elementSize() = 0;
        virtual epicsUInt32 limit() = 0;
        virtual void limit(epicsUInt32 newLimit) = 0;
        virtual epicsUInt32 position() = 0;
        virtual void position(epicsUInt32 newPosition) = 0;
        virtual epicsUInt32 expose(EpicsArrayExpose *expose,
                                  epicsUInt32 offset, epicsUInt32 limit);
    }

    class EpicsArray {
    public:
        epicsType        type; 
        EpicsArrayBuffer *pbuffer;
    };

    typedef EpicsArrayBuffer *(EpicsArrayBufferAllocate)();
    class EpicsArrayBufferFactory {
    public:
        static epicsUint16 typeToTypeID(const char *type);
        static EpicsArrayBuffer *allocate(epicsUint16 typeId);
        static void register(const epicsStringBufferType type,
                         EpicsArrayBufferAllocate allocater,
                         const char *type);
    };
    // type : At least "Contiguous" and "Segmented" are implemented

Discussion of epicsArray

EpicsArrayBuffer has the following methods:

allocate

This allocates space for up to capacity octets. The number of octets allocated is returned. An implementation attempts to allocate the requested capacity but some implemenations, e.g. network buffers, may impose a maximum size. If capacity is not zero when this is called and new storage is allocated then the old storage is freed or reused and the octets spanned by position, limit appear in the newly allocated storage.

release

Releases storage. If onlyStorage is true then the storage for the string is freed and capacity is set to zero; otherwise the string storage and the storage for EpicsUTF_8Buffer itself is freed.

capacity

return the capacity

limit

Two methods are available, one to get the current limit and one to set the limit.

position

Two methods are available, one to get the current position and one to set the position.

expose

This is a request to call the expose method of EpicsArrayExpose. The expose method may get called multiple times if the string is stored in segments.

epicsStruct

epicsStruct.h contains the following:

    class EpicsStructField {
    public:
        EpicsString name;
        epicsType   type;
    };
   
    class EpicsStructDef{
    public:
        EpicsString  name;
        Interface    *plifetime; // references a StructDbdLifetime
        epicsInt16     nfields;
        EpicsStructField *pfield[]; // ptr to array of ptr to EpicsStructField
    };

    class EpicsStruct{
    public:
        EpicsStructDef *pstructDef;
        void    *pstorage;
    };

Discussion of epicsStruct

MARTY DISCUSS

epicsImage

epicsImage.h contains the following:

    class EpicsImageExpose {
        // return (false,true) means (call if more data, done)
        bool expose(void *pdata,
                 epicsUInt32 offset, epicsUInt32 limit) = 0;
    };
    class EpicsImageBuffer {
    public:
        virtual epicsUInt32 allocate(
                    epicsUInt32 capacity,epicsUint16 elementSize) = 0;
        virtual void release(bool onlyStorage) = 0;
        virtual epicsUInt32 capacity() = 0;
        virtual epicsUInt32 elementSize() = 0;
        virtual epicsUInt32 expose(EpicsArrayExpose *expose);
    };

    class EpicsImageBounds {
        epicsUInt32 low;
        epicsUInt32 high;
    };
    class EpicsNdimImage {
    public:
        epicsUInt32  capacity;  //capacity in number of elements 
        epicsInt16  ndim;      // number of dimensions
        epicsType   type; 
        void      *pstorage; // storage for capacity elements of type
        EpicsImageBounds bounds[]; // bounds[ndim]
    };

    class EpicsImage {
    public:
       epicsType type;
       EpicsNdimImage *pEpicsNdimImage;
       EpicsImageBuffer *pbuffer;
    };

    typedef EpicsImageBuffer *(EpicsImageBufferAllocate)();
    class EpicsImageBufferFactory {
    public:
        static epicsUint16 typeToTypeID(const char *type);
        static EpicsImageBuffer *allocate(epicsUint16 typeId);
        static void register(const epicsStringBufferType type,
                         EpicsImageBufferAllocate allocater,
                         const char *type);
    };
    // type : At least "Contiguous" and "Segmented" are implemented

Discussion of epicsImage

MARTY DISCUSS