HardwareCommandQueue.h

Go to the documentation of this file.

/*--------------------------------------------------------------------------------------------
Copyright (c) 2019, NDEVR LLC
tyler.parke@ndevr.org
  __    __   ____     _____ __     __  _______
 |  \  |  | |  __ \  |  ___|\ \   / / |   __  \
 |   \ |  | | |  \ \ | |___  \ \ / /  |  |__)  |
 |  . \|  | | |__/ / | |___   \ V /   |   _   /
 |  |\    |_|_____/__|_____|___\_/____|  | \  \
 |__| \__________________________________|  \__\
 
Subject to the terms of the Enterprise+ Agreement, NDEVR hereby grants
Licensee a limited, non-exclusive, non-transferable, royalty-free license
(without the right to sublicense) to use the API solely for the purpose of
Licensee's internal development efforts to develop applications for which
the API was provided.
 
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
 
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
 
Library: Hardware
File: HardwareCommandQueue
Included in API: True
Author(s): Tyler Parke
 *-----------------------------------------------------------------------------------------**/
#pragma once
#include "DLLInfo.h"
#include <NDEVR/BaseValues.h>
#include <NDEVR/String.h>
#include <NDEVR/Dictionary.h>
#include <NDEVR/RWLock.h>
#include <NDEVR/Time.h>
#include <NDEVR/TimeSpan.h>
#include <NDEVR/Thread.h>
#include <NDEVR/JSONNode.h>
#include <NDEVR/ProgressInfo.h>
#include <NDEVR/LogMessage.h>
#include <NDEVR/Exception.h>
namespace NDEVR
{
    /**--------------------------------------------------------------------------------------------------
    \brief Describes whether a HardwareCommandQueue supports certain commands. This is usually firmware.
    **/
    enum class CommandSupport
    {
        e_supported
        , e_not_supported
        , e_not_known
    };
    /**--------------------------------------------------------------------------------------------------
    \brief Stores long-term statistics for commands executed using HardwareCommandQueue.
    **/
    struct CommandInformation
    {
        String command;
        String validation_regex;
        String default_argument;
        TimeSpan total_time = TimeSpan(0.0f);
#ifdef _DEBUG
        fltp04 average_time = 0.0;
#endif
        uint04 number_of_attempts = 0;
        uint04 number_of_failures = 0;
        TimeSpan tx_delay = TimeSpan(0.0f);
        TimeSpan rx_delay = TimeSpan(0.0f);
        TimeSpan response_timeout = TimeSpan(0.0f);
        CommandSupport supports_command = CommandSupport::e_supported;
    };
    /**--------------------------------------------------------------------------------------------------
    \brief A base class for communicating with Hardware, typically firmware by the software.
    Commands a queued up and sent, before waiting for a response for each command. 
    **/
    template<class t_type>
    class HardwareCommandQueue
    {
    public:
        struct CommandQueueItem
        {
            t_type command = t_type(0);
            String args;
            String regex;
            void clear()
            {
                command = t_type(0);
                args.clear();
                regex.clear();
            }
        };
        struct CommandRecord
        {
            Time start_time;
            Time end_time;
            t_type command;
        };
        bool hasPendingCommand(t_type command) const
        {
            return m_pending_commands.hasKey(command);
        }
        static const uint04 s_buffer_size = 256000;
        void postCommand(t_type command, const String& args = String(), const String& regex = String())
        {
            WLock lock(&m_pending_commands);
            if (allowMultipleCommandsInStream(command, args) || !m_pending_commands.hasKey(command))
            {
                m_ordered_commands.add({ command, args, regex });
                if (!m_pending_commands.hasKey(command))
                    m_pending_commands[command] = 0;
                m_pending_commands[command]++;
            }
            else
            {
                for (uint04 i = 0; i < m_ordered_commands.size(); i++)
                {
                    if (m_ordered_commands[i].command == command)
                    {
                        m_ordered_commands[i].args = args;
                        m_ordered_commands[i].regex = regex;
                    }
                }
            }
        }
        void removeCommand(t_type command)
        {
            WLock lock(&m_pending_commands);
            if (m_pending_commands.hasKey(command))
            {
                for (uint04 i = m_ordered_commands.size() - 1; !IsInvalid(i); i--)
                {
                    if (m_ordered_commands[i].command == command)
                    {
                        m_ordered_commands.removeIndex(i);
                    }
                }
                m_pending_commands.erase(command);
            }
        }
        void addCommandToFront(t_type command, const String& args = String(), const String& regex = String())
        {
            WLock lock(&m_pending_commands);
            if (allowMultipleCommandsInStream(command, args) || !m_pending_commands.hasKey(command))
            {
                m_ordered_commands.add(0, { command, args, regex });
                if (!m_pending_commands.hasKey(command))
                    m_pending_commands[command] = 0;
                m_pending_commands[command]++;
            }
            else
            {
                for (uint04 i = 0; i < m_ordered_commands.size(); i++)
                {
                    if (m_ordered_commands[i].command == command)
                    {
                        m_ordered_commands[i].args = args;
                        m_ordered_commands[i].regex = args;
                        if (i != 0)
                            m_ordered_commands.swapIndices(0, i);
                    }
 
                }
            }
        }
        virtual bool allowMultipleCommandsInStream(t_type command, const String& args) const
        {
            UNUSED(command);
            UNUSED(args);
            return false;
        }
        bool popCommandAndExecute()
        {
            //WLock current_command_lock(&m_current_command);
            if (m_current_command.command == t_type(0))
            {
                {
                    WLock lock(&m_pending_block_command);
                    if (m_pending_block_command.command != t_type(0))
                    {
                        m_current_command = m_pending_block_command;
                        m_pending_block_command.clear();
                        m_current_command_start_time = Time::SystemTime();
                        executeCommand(m_current_command.command, m_current_command.args);
                        return true;
                    }
                }
                {
                    WLock lock(&m_pending_commands);
                    if (m_ordered_commands.size() > 0)
                    {
                        m_current_command = m_ordered_commands[0];
                        m_ordered_commands.removeIndex(0);
                        m_pending_commands[m_current_command.command]--;
                        if (m_pending_commands[m_current_command.command] == 0)
                            m_pending_commands.erase(m_current_command.command);
                    }
                    else
                    {
                        return false;
                    }
                }
                m_current_command_start_time = Time::SystemTime();
                executeCommand(m_current_command.command, m_current_command.args);
                return true;
            }
            return false;
        }
        void finishCommand()
        {
            if (m_current_command.command != t_type(0))
            {
                //WLock lock(&m_current_command);
                //if (m_current_command != t_type(0))
                {
                    CommandRecord record;
                    record.start_time = m_current_command_start_time;
                    record.end_time = Time::SystemTime();
                    record.command = m_current_command.command;
                    m_records.add(record);
                    m_command_info[m_current_command.command].total_time += (record.end_time - record.start_time);
                    m_command_info[m_current_command.command].number_of_attempts++;
#ifdef _DEBUG
                    m_command_info[m_current_command.command].average_time = m_command_info[m_current_command.command].total_time.elapsedSeconds() / m_command_info[m_current_command.command].number_of_attempts;
#endif
                    m_current_command.clear();
                    m_current_command_start_time = Constant<Time>::Invalid;
 
 
                }
            }
        }
        virtual void retryCommand()
        {
            if (m_current_command.command != t_type(0))
            {
                const CommandQueueItem command = m_current_command;
                cancelCommand();
                addCommandToFront(command.command, command.args, command.regex);
            }
        }
        virtual void cancelCommand()
        {
            if (m_current_command.command != t_type(0))
            {
                CommandRecord record;
                record.start_time = m_current_command_start_time;
                record.end_time = Time::SystemTime();
                record.command = m_current_command.command;
                m_records.add(record);
                m_command_info[m_current_command.command].total_time += (record.end_time - record.start_time);
                m_command_info[m_current_command.command].number_of_attempts++;
#ifdef _DEBUG
                m_command_info[m_current_command.command].average_time = m_command_info[m_current_command.command].total_time.elapsedSeconds() / m_command_info[m_current_command.command].number_of_attempts;
#endif
                m_current_command.clear();
                m_current_command_start_time = Constant<Time>::Invalid;
            }
        }
        virtual void onFailure(const t_type& command)
        {
            if (m_command_info[command].supports_command == CommandSupport::e_not_known)
                m_command_info[command].supports_command = CommandSupport::e_not_supported;
            m_command_info[command].number_of_failures++;
        }
        void clearCommands()
        {
            WLock lock(&m_pending_commands);
            m_pending_commands.clear();
            m_ordered_commands.clear();
            WLock block_lock(&m_pending_block_command);
            m_pending_block_command.clear();
        }
        virtual void executeCommand(const t_type& command, const String& args) = 0;
        void executeCommandBlocking(const t_type& command, const String& args = String())
        {
            bool finished = false;
            for (;;)//wait to write pending command
            {
                {
                    WLock lock(&m_pending_block_command);//prevent new commands from being issued
                    if (m_pending_block_command.command == t_type(0))
                    {
                        m_pending_block_command.command = command;
                        m_pending_block_command.args = args;
                        finished = true;
                    }
                }
                if (finished)
                    break;
                else
                    ThreadFunctions::RequestSleep(TimeSpan(0.1));
            }
            finished = false;
            for (;;)//Wait for command to be executed
            {
                {
                    RLock lock(&m_pending_block_command);//prevent new commands from being issued
                    finished = m_pending_block_command.command != command;
                }
                if (finished)
                    break;
                else
                    ThreadFunctions::RequestSleep(TimeSpan(0.1));
            }
            finished = false;
            for (;;)//Wait for command execution to complete
            {
                {
                    //RLock lock(&m_current_command);//prevent new commands from being issued
                    finished = m_current_command.command != command;
                }
                if (finished)
                    break;
                else
                    ThreadFunctions::RequestSleep(TimeSpan(0.1));
            }
        }
        CommandInformation commandInformation(t_type command)
        {
            if (m_command_info.contains(command))
                return m_command_info.get(command);
            return CommandInformation();
        }
        virtual bool supportsCommand(t_type command) const
        {
            if (m_command_info.contains(command))
                return m_command_info.get(command).supports_command != CommandSupport::e_not_supported;
            return true;
        }
        void disableCommand(t_type command)
        {
            if (!m_command_info.contains(command))
            {
                m_command_info.add(command, CommandInformation());
            }
            for (uint04 i = 0; i < m_ordered_commands.size(); i++)
            {
                if (m_ordered_commands[i].command == command)
                {
                    m_ordered_commands.removeIndex(i--);
                    m_pending_commands[command]--;
                    if (m_pending_commands[command] == 0)
                        m_pending_commands.erase(command);
                }
            }
            m_command_info.get(command).supports_command = CommandSupport::e_not_supported;
        }
        void setSupport(t_type command, CommandSupport support)
        {
            m_command_info[command].supports_command = support;
        }
        void setSupported(t_type command, bool supported)
        {
            if (supported)
                m_command_info[command].supports_command = CommandSupport::e_supported;
            else
                m_command_info[command].supports_command = CommandSupport::e_not_supported;
        }
        virtual void endCommandQueue()
        {
 
        }
        TimeSpan commandTimeout() const
        {
            if (m_current_command.command != t_type(0) && m_command_info.hasKey(m_current_command.command))
                return m_command_info.get(m_current_command.command).response_timeout;
            return TimeSpan(0);
        }
        TimeSpan txDelay() const
        {
            if (m_current_command.command != t_type(0) && m_command_info.hasKey(m_current_command.command))
                return m_command_info.get(m_current_command.command).tx_delay;
            return TimeSpan(0);
        }
        TimeSpan rxDelay() const
        {
            if (m_current_command.command != t_type(0) && m_command_info.hasKey(m_current_command.command))
                return m_command_info.get(m_current_command.command).rx_delay;
            return TimeSpan(0);
        }
        void setFromJSONInfo(const JSONNode& root, bool allow_command_override, ProgressInfo* log)
        {
            for (uint04 i = 0; i < Constant<uint04>::Invalid; i++)
            {
                t_type command = cast<t_type>(i);
                String display = String::DisplayString(command).englishTranslation();
                if (display.size() == 0)
                    break;
                try
                {
                    CommandInformation info;
                    if (m_command_info.contains(command))
                    {
                        info = m_command_info.get(command);
                    }
                    if (root.hasNode(display))
                    {
                        const JSONNode& node = root[display];
                        if (node.hasNode("Attempt Count"))
                            info.number_of_attempts = node["Attempt Count"].getAs<uint04>();
                        if (node.hasNode("Failure Count"))
                            info.number_of_failures = node["Failure Count"].getAs<uint04>();
                        if (node.hasNode("Total Response Time"))
                            info.total_time = TimeSpan(node["Total Response Time"].getAs<fltp08>());
                        if (allow_command_override)
                        {
                            if (node.hasNode("Supported"))
                                info.supports_command = node["Supported"].getAs<String>().getAs<CommandSupport>();
                            if (node.hasNode("Command"))
                                info.command = node["Command"].getAs<String>();
                            if (node.hasNode("Validation Regex"))
                                info.validation_regex = node["Validation Regex"].getAs<String>();
                            if (node.hasNode("Default Args"))
                                info.default_argument = node["Default Args"].getAs<String>();
                            if (node.hasNode("Transmission Delay"))
                                info.tx_delay = TimeSpan(node["Transmission Delay"].getAs<fltp08>());
                            if (node.hasNode("Receive Delay"))
                                info.rx_delay = TimeSpan(node["Receive Delay"].getAs<fltp08>());
                            if (node.hasNode("Response Timeout"))
                                info.response_timeout = TimeSpan(node["Response Timeout"].getAs<fltp08>());
                        }
                    }
                    m_command_info[command] = info;
                }
                catch (Exception& e)
                {
                    if (log) log->addMessage(e.getMessage(), LogMessage::e_error);
                }
            }
        }
        JSONNode getCommandJSONInfo(bool only_supported) const
        {
            JSONNode root;
            for (uint04 i = 0; i < Constant<uint04>::Invalid; i++)
            {
                t_type command = cast<t_type>(i);
 
                String display = String::DisplayString(command).englishTranslation();
                if (display.size() == 0)
                    break;
                CommandInformation info;
                if (m_command_info.contains(command))
                {
                    info = m_command_info.get(command);
                }
                if (only_supported && info.supports_command == CommandSupport::e_not_supported)
                    continue;
                JSONNode& node = root[display];
                node["Command"] = info.command;
                if (!only_supported)
                    node["Supported"] = String(info.supports_command);
                node["Attempt Count"] = info.number_of_attempts;
                node["Failure Count"] = info.number_of_failures;
                node["Total Response Time"] = info.total_time.elapsedSeconds();
                if (info.number_of_attempts > 0)
                    node["Average Response Time"] = info.total_time.elapsedSeconds() / info.number_of_attempts;
                else
                    node["Average Response Time"] = 0;
                node["Default Args"] = info.default_argument;
                node["Transmission Delay"] = info.tx_delay;
                node["Receive Delay"] = info.rx_delay;
                node["Response Timeout"] = info.response_timeout;
                node["Validation Regex"] = info.validation_regex;
            }
            return root;
        }
        String getCommandCSVInfo(bool only_supported, bool include_identity_info, char deliminator = ',') const
        {
            String del(deliminator);
            String root;
            root += "Command" + del;
            if (!only_supported)
                root += "Supported" + del;
            root += "Attempt Count" + del;
            root += "Failure Count" + del;
            root += "Total Response Time" + del;
            root += "Average Response Time" + del;
            if (include_identity_info)
            {
                root += "Default Args" + del;
                root += "Transmission Delay" + del;
                root += "Receive Delay" + del;
                root += "Response Timeout" + del;
                root += "Validation Regex" + del;
            }
            for (uint04 i = 0; i < Constant<uint04>::Invalid; i++)
            {
                root.last() = '\n';
                t_type command = cast<t_type>(i);
 
                String display = String::DisplayString(command).englishTranslation();
                if (display.size() == 0)
                    break;
                CommandInformation info;
                if (m_command_info.contains(command))
                {
                    info = m_command_info.get(command);
                }
                if (only_supported && info.supports_command == CommandSupport::e_not_supported)
                    continue;
                root += display + del;
                if (!only_supported)
                    root += String(info.supports_command) + del;
                root += String(info.number_of_attempts) + del;
                root += String(info.number_of_failures) + del;
                root += String(info.total_time.elapsedSeconds()) + del;
                if (info.number_of_attempts > 0)
                    root += String(info.total_time.elapsedSeconds() / info.number_of_attempts) + del;
                else
                    root += "0" + del;
                if (include_identity_info)
                {
                    root += info.default_argument + del;
                    root += String(info.tx_delay) + del;
                    root += String(info.rx_delay) + del;
                    root += String(info.response_timeout) + del;
                    root += info.validation_regex + del;
                }
            }
            return root;
        }
        bool hasPending() const { return m_current_command.command != t_type(0) || m_pending_commands.size() > 0; };
 
        t_type currentCommand() const { return m_current_command.command; }
        const String& currentArgs() const { return m_current_command.args; }
        const String& currentRegex() const { return m_current_command.regex; }
        uint04 bufferOffset() const { return m_buffer_offset; };
        void setBufferOffset(uint04 buffer_offset) { m_buffer_offset = buffer_offset; }
    protected:
        Dictionary<t_type, CommandInformation> m_command_info;
        Dictionary<t_type, uint04> m_pending_commands;
        Buffer<CommandQueueItem> m_ordered_commands;
        Buffer<CommandRecord> m_records;
        Time m_current_command_start_time = Constant<Time>::Invalid;
        CommandQueueItem m_current_command;
        CommandQueueItem m_pending_block_command;
        uint04 m_buffer_offset = 0;
    };
    template class HARDWARE_API StringStream<CommandSupport>;
}