parameter.hh

Go to the documentation of this file.

#ifndef _DRAMA2_PARAMETER_INC
#define _DRAMA2_PARAMETER_INC
 
/*
 * History:
 *   07-Jan-2014 - TJF - Original version'
 *   21-Jun-2015 - TJF - the examples in the comments should use "TaskPtr()"
 *                         rather then "this".
 *   09-Dec-2016 - TJF - Code from Minh for ostream<< operator and equality
 *                         operators.
 *
 * The above ID is for Doxygen, this one has the format ACMM i`s looking for.
 * "@(#) $Id$"
*/
 
#include "drama/task.hh"
#include "drama/sds.hh"
#include <string>
#include "Sdp.h"
#include "DitsParam.h"
#include "DitsMonitor.h"
 
#include <iostream>
#include <type_traits>  // for enable_if and is_base_of.
 
namespace drama { 
    
 
    template<typename SDS_T> class Parameter {
        
    private:
 
        /*
         * Pointer to the DRAMA task this parameter is part of.
         */
        std::weak_ptr<Task> _theTask;
        const std::string _name;
    public:
        typedef Parameter<SDS_T> class_type;
        Parameter(std::weak_ptr<Task>  task, 
                  const std::string &name, 
                  const SDS_T &initVal) : _theTask(task), _name(name) {
            //SdsCodeType code = SdsTypes::CodeForType<SDS_T>();
 
            /*
             * Access the parameter system and insert the value.
             */
            sds::Id parSys = sds::Id::CreateFromSdsIdType((long)(DitsGetParId()));
            parSys.Put(name, initVal);
        }
        class_type &operator =(SDS_T val) {
 
            // Parameter updates trigger monitors and possible entry to
            //  task, so must take lock.
            Task::guardType DramaLock(std::shared_ptr<Task>(_theTask)->Lock());
 
            // Fill in code to set value.
            StatusType status = STATUS__OK;
            Sdp::Put(_name, val, &status);
 
            if (status != STATUS__OK)
                DramaTHROW_F(status,"Failed setting parameter {0}", 
                             _name);
 
            return *this;
        }
        operator SDS_T() const {
            SDS_T val;
            StatusType status = STATUS__OK;
            Sdp::Get(_name, &val, &status);
 
            if (status != STATUS__OK)
                DramaTHROW_F(status,"Failed fetching parameter {0}", 
                                        _name);
 
            return val;
        }
        virtual ~Parameter() {
        }
        
        template<typename T>
        friend bool operator==(T&& lhs, const Parameter& p)
        {
            return (p.operator SDS_T() == lhs);
        }
 
        template<typename T>
        bool operator==(T&& rhs) const
        {
          return (this->operator SDS_T() == rhs);
        }
 
        template<typename T>
        friend bool operator!=(T&& lhs, const Parameter& p)
        {
            return (p.operator SDS_T() != lhs);
        }
 
        template<typename T>
        bool operator!=(T&& rhs) const
        {
            return (this->operator SDS_T() != rhs);
        }
 
 
    }; //template<typename SDS_T> class Parameter 
 
    /*
     * @brief  Support formatting a Parameter as per the underlying type - Scalar/string types.
     *
     * This function Allows fmt::format to work with the Scalar/String Parameter type items.
     * 
     * You can use any of the fmt::format specifiers that are allowed for
     * the underlying type.
     *
     * @param[in]  t           The Parameter item you wish to format.
     *
     * @tparam     SDS_T       Underlying SDS scalar type or string.
     *
     * @return     t converted to to the underling thype.
     */
    template <typename SDS_T>
    auto format_as(Parameter<SDS_T> t) { return static_cast<SDS_T>(t); }
 
    /*
     * Most of this specialization is implemented in parameters.cpp, mainly
     * to avoid this file getting to large for a rarely used feature.
     */
 
    template<> class Parameter<drama::sds::Id> {
        
    private:
        /*
         * Pointer to the DRAMA task this parameter is part of.
         */
        std::weak_ptr<Task> _theTask;
        const std::string _name;   // Name of this parameter.
        sds::Id           _parSys; // Reference to task parameter system.
    public:
        typedef Parameter<drama::sds::Id> class_type;
        Parameter(std::weak_ptr<Task>  task, 
                  const std::string &name, 
                  const sds::IdPtr &initVal,
                  bool copy = true);
 
        void Set(const sds::IdPtr &newVal, 
                 bool copy = true,
                 bool create = false);
 
        sds::Id Get() const;
 
        void UpdateMonitors() const;
 
        virtual ~Parameter();
    }; //  template<> class Parameter<drama::sds::Id>
 
    template<typename SDS_T> class ArrayParameter {
        
    private:
 
        /*
         * Pointer to the DRAMA task this parameter is part of.
         */
        std::weak_ptr<Task> _theTask;
        const std::string _name;
        sds::Id _parSys;
    public:
        ArrayParameter(std::weak_ptr<Task>  task, 
                       const std::string &name, 
                       unsigned nElements,
                       const SDS_T initVal) : _theTask(task), _name(name) {
            /*
             * Access the parameter system 
             */
            _parSys = sds::Id::CreateFromSdsIdType((long)(DitsGetParId()));
            /*
             * Create and insert the new parameter
             *
             * We don't bother keeping ID about, because it could be changed
             * by other access to the parameter - we find it each time we want it.
             */
            _parSys.CreateChildArray(_name, sds::CodeForType<SDS_T>(), nElements);
 
            /*
             * Fill the array with the initial value.  Don't update monitors, there
             * can't be any at this point.
             */
            Fill(initVal, false);
        }
        template <typename F>
        void Fill(const F filler, bool updateMonitors=true) {
            // Need to find the parameter.
            auto id = _parSys.Find(_name);
 
            // Use the SDS array write helper to access the array.
            sds::ArrayWriteHelper<F> array;
            id.ArrayAccess(&array);
 
            auto count = array.Size();
            for (unsigned i = 0 ; i < count ; ++i)
            {
                array[i] = filler;
            }    
 
            if (updateMonitors)
            {
                /*
                 *Parameter updates trigger monitors and possible entry to
                 * task, so must take lock.
                 */
                Task::guardType DramaLock(std::shared_ptr<Task>(_theTask)->Lock());
 
                StatusType status = STATUS__OK;
                DitsMonitor(_name.c_str(),DITS_MON_TRUST,(SdsIdType)(id),&status);
                if (status != STATUS__OK)
                {
                    DramaTHROW_F(status,
                                 "Error filling array parameter {0}, DitsMonitor() failed", 
                                 _name);
                }
            }
            
        } 
        template <class ContainerType>
        void Set(const ContainerType &vals) {
 
 
            // Need to find the parameter.
            auto id = _parSys.Find(_name);
 
            // Use the SDS array write helper to access the array.
            sds::ArrayWriteHelper<SDS_T> array;
            id.ArrayAccess(&array);
 
            /*
             * Get the parameter array size and then ensure we
             * don't index past the container size.
             */
            auto count = array.Size();
 
            if (vals.size() < count)
                count = vals.size();
 
            /*
             * Assign the values
             */
            for (unsigned i = 0 ; i < count ; ++i)
            {
                array[i] = vals[i];
            }    
 
            /*
             *Parameter updates trigger monitors and possible entry to
             * task, so must take lock.
             */
            Task::guardType DramaLock(std::shared_ptr<Task>(_theTask)->Lock());
            
            StatusType status = STATUS__OK;
            DitsMonitor(_name.c_str(),DITS_MON_TRUST,(SdsIdType)(id),&status);
            if (status != STATUS__OK)
            {
                DramaTHROW_F(status,
                             "Error setting array parameter {0}, DitsMonitor() failed", 
                             _name);
            }
        }
 
        /*
         * Return the value of an array parameter.
         *
         * @return A vector containing the values. The type of the vector
         *         elements will be SDS_T.
         */
        std::vector<SDS_T> Get() const {
 
 
            // Need to find the parameter.
            auto id = _parSys.Find(_name);
 
            // Access the SDS array for read.
            sds::ArrayReadHelper<SDS_T> array;
            id.ArrayAccess(&array);
 
            auto count = array.Size();
            std::vector<SDS_T> result;
            result.resize(count);
            /*
             * copy the values.
             */
            for (unsigned i = 0; i < count ; ++i)
            {
                result[i] = array[i];
            }
            return result;
            
        }
 
        void Set(size_t index, SDS_T val, bool updateMonitors = true) {
 
 
            // Need to find the parameter.
            auto id = _parSys.Find(_name);
 
            // Use the SDS array write helper to access the array.
            sds::ArrayWriteHelper<SDS_T> array;
            id.ArrayAccess(&array);
 
            if (index >= array.Size())
            {
                DramaTHROW_F(DRAMA2__PAR_ARRAY_ERR,
                             "Tired to set index {0} in array parameter is size {1}",
                             index, array.Size());
            
            }
            array[index] = val;
 
            /*
             * If requested, update any  parameter monitors.
             */ 
            if (updateMonitors)
            {
                /*
                 *Parameter updates trigger monitors and possible entry to
                 * task, so must take lock.
                 */
                Task::guardType DramaLock(std::shared_ptr<Task>(_theTask)->Lock());
                
                StatusType status = STATUS__OK;
                DitsMonitor(_name.c_str(),DITS_MON_TRUST,(SdsIdType)(id),&status);
                if (status != STATUS__OK)
                {
                    DramaTHROW_F(status,
                                 "Error setting array parameter {0}, DitsMonitor() failed", 
                                 _name);
                }
            }
        }
 
        SDS_T Get(size_t index) const {
 
 
            // Need to find the parameter.
            auto id = _parSys.Find(_name);
 
            // Access the SDS array for read.
            sds::ArrayReadHelper<SDS_T> array;
            id.ArrayAccess(&array);
 
            if (index >= array.Size())
            {
                DramaTHROW_F(DRAMA2__PAR_ARRAY_ERR,
                             "Tired to set index {0} in array parameter is size {1}",
                             index, array.Size());
            
            }
            return array[index];
        }
 
 
 
        /* Return the size of the array
         *
         * @warning Not very efficient since it must presume the parameter
         *          has changed in various ways and hence finds the parameter
         *          ID and does a full inquiry for every call.
         *
         * @return The size of the array.
         */
        unsigned Size() const {
 
            // Need to find the parameter.
            auto id = _parSys.Find(_name);
 
            std::vector<unsigned> dims;
            id.GetDims(&dims);
 
            if (dims.size() != 1)
            {
                DramaTHROW(DRAMA2__PAR_ARRAY_ERR,
                           "Dimensions of array parameter is NOT 1.  Can only use drama::ArrayParameter for single dimension array parameters");
            }
            return dims[0];
 
        }
 
        virtual ~ArrayParameter() {
        } 
 
        SDS_T operator[](size_t index) const {
 
            return Get(index);
 
        }
 
    }; // template<typename SDS_T> class ArrayParameter 
 
    /*
     * Most of this specialization is implemented in parameters.cpp, mainly
     * to avoid this file getting to large for a rarely used feature.
     */
    template<> class ArrayParameter<std::string> {
        
    private:
 
        /*
         * Pointer to the DRAMA task this parameter is part of.
         */
        std::weak_ptr<Task> _theTask;
        const std::string _name;
        sds::Id _parSys;
    public:
        ArrayParameter(std::weak_ptr<Task>  task, 
                       const std::string &name, 
                       unsigned nElements,
                       unsigned strLen=100,
                       const std::string initVal="");
        void Fill(const std::string &filler, bool updateMonitors=true);
        template <class ContainerType, 
                  /*
                   * This complicated bit of code is about ensuring that only containers containing
                   * a sub-class of std::string are considered when trying to determine if 
                   * this template function is a valid specialization to use.
                   *
                   * A relevant reference is SFINAE ("Substitution Failure Is Not An Error")
                   *  E.g. http://en.cppreference.com/w/cpp/language/sfinae
                   *
                   * The problem we are tying to solve is that without this, any type 
                   * could trigger this specialization. If for example  var.Set(2, "ten"); was 
                   * invoked, without this, it would try to specialize this template to see 
                   * if it was a possible overload for the other Set method below.  Compilation 
                   * would then fail when .size() is invoked.
                   * 
                   * std::enable_if is being used to this template is only used when the
                   * ContainerType value is a sub-class of std::string.  The following
                   * references will help explain this:
                   *   http://www.cplusplus.com/reference/type_traits/enable_if/?kw=enable_if
                   *   http://www.boost.org/doc/libs/1_45_0/libs/utility/enable_if.html
                   *
                   * In addition, the use of "typename ContainerType::value_type" to ensure
                   * we refer to the actual type of the ContainerType template argument. 
                   * This should also trigger a failure if the container does not have a
                   * value_type member.  Here  typename can be used to declare that a 
                   * dependent name is a type.
                   */
                  typename std::enable_if<std::is_base_of<std::string, 
                                                          typename ContainerType::value_type>::value>::type* = nullptr>
 
        void Set(const ContainerType &vals, bool updateMonitors=true) {
 
            // Need to find the parameter.
            auto id = _parSys.Find(_name);
 
            // Access data for write.
            std::vector<unsigned long> dims;
            sds::ArrayWriteHelper<char> array;
            id.ArrayAccess(&array, 2, &dims);
 
            /*
             * Validate we have a two dimensional array
             */
            if (dims.size() != 2)
            {
                DramaTHROW(DRAMA2__PAR_ARRAY_ERR,
                           "Dimensions of string array parameter is NOT 2.  Can only use drama::ArrayParameter<std::string> for two dimension array parameters");
            }
 
            /*
             * Get the parameter array size and then ensure we
             * do not index past the container size.
             */
            auto count = dims[1];
            if (vals.size() < count)
                count = vals.size();
            /*
             * Access the parameter raw data array of the parameter so we
             * can copy it in.
             */
            char *parData = (char *)array.DataAddress();
            /*
             * Length of each individual string parameter.
             */
            unsigned sLen = dims[0];
            /*
             * Number of values to transfer, the min of the parameter or
             * what was supplied.
             */
            unsigned nVals = dims[1];
 
            if (nVals > vals.size())
                nVals = vals.size();
 
            /*
             * Assign the values to the elements.
             */
            for (unsigned i = 0 ; i < nVals ; ++i)
            {
                char *thisElement = (&parData[i*sLen]);
                // Copy the new value. Must limit the length to the space available.
                strncpy(thisElement, vals[i].c_str(), sLen);
                // Ensure null termination.
                thisElement[sLen-1] = '\0';
            }    
            if (updateMonitors)
            {
                /*
                 *Parameter updates trigger monitors and possible entry to
                 * task, so must take lock.
                 */
                Task::guardType DramaLock(std::shared_ptr<Task>(_theTask)->Lock());
                
                StatusType status = STATUS__OK;
                DitsMonitor(_name.c_str(),DITS_MON_TRUST,(SdsIdType)(id),&status);
                if (status != STATUS__OK)
                {
                    DramaTHROW_F(status,
                                 "Error setting array parameter {0}, DitsMonitor() failed", 
                                 _name);
                }
            }
        }
 
        /*
         * Return the value of an array parameter.
         *
         * @return A vector containing the values. The type of the vector
         *         elements will be SDS_T.
         */
        std::vector<std::string> Get() const;
 
        void Set(size_t index, const std::string &val, bool updateMonitors = true);
        std::string Get(size_t index) const;
 
 
        /* Return the size of the array
         *
         * This returns the number of elements, does not provide the
         * length of each element.
         *
         * @warning Not very efficient since it must presume the parameter
         *          has changed in various ways and hence finds the parameter
         *          ID and does a full inquiry for every call.
         *
         * @return The size of the array.
         */
        virtual unsigned Size() const;
 
        /* Return the maximum size of each string in the array.
         *
         * This returns the size of each string.
         *
         * @warning Not very efficient since it must presume the parameter
         *          has changed in various ways and hence finds the parameter
         *          ID and does a full inquiry for every call.
         *
         * @return The maximum size of each string within the array, including
         *          a null terminator.
         */
        virtual unsigned Strlen() const;
 
        virtual ~ArrayParameter();
 
        virtual std::string operator[](size_t index) const {
 
            return Get(index);
 
        }
 
    }; // class ArrayParameter<std::string>
 
 
    /*
    * Support writing to streams.
    */
    template<typename SDS_T> std::ostream& operator<<(std::ostream& os, const Parameter<SDS_T>& p) { 
        os << p.operator SDS_T();
        return os; 
    }
 
    template<> std::ostream& operator<<(std::ostream& os, const Parameter<sds::Id>& p) ;
 
 
    template<> std::ostream& operator<<(std::ostream& os, const Parameter<std::string>& p);
 
 
 
} // namespace drama
 
#endif