A base class for communicating with Hardware, typically firmware by the software. More...

Collaboration diagram for HardwareCommandQueue< t_type >:

Classes
struct	CommandQueueItem
	An item in the command queue containing the command, arguments, and validation regex. More...
struct	CommandRecord
	A record of a command execution with timing information. More...

Public Member Functions
void	addCommandToFront (t_type command, const String &args=String(), const String &regex=String())
	Adds a command to the front of the queue so it executes next.
virtual bool	allowMultipleCommandsInStream (t_type command, const StringView &args) const
	Returns whether multiple instances of the same command are allowed in the queue.
uint04	bufferOffset () const
	Returns the current buffer offset for data reads.
virtual void	cancelCommand ()
	Cancels the currently executing command and records its statistics.
void	clearCommands ()
	Removes all pending and blocking commands from the queue.
CommandInformation	commandInformation (t_type command)
	Returns the stored statistics and configuration for the given command.
TimeSpan	commandTimeout () const
	Returns the response timeout for the currently executing command.
const String &	currentArgs () const
	Returns the arguments for the currently executing command.
t_type	currentCommand () const
	Returns the currently executing command type.
const String &	currentRegex () const
	Returns the validation regex for the currently executing command.
void	disableCommand (t_type command)
	Disables a command, removing it from the queue and marking it as unsupported.
virtual void	endCommandQueue ()
	Called when the command queue is shutting down.
virtual void	executeCommand (const t_type &command, const StringView &args)=0
	Executes a command with the given arguments.
void	executeCommandBlocking (const t_type &command, const StringView &args=StringView())
	Posts a command and blocks until it has been executed and completed.
void	finishCommand ()
	Marks the current command as finished and records its execution statistics.
String	getCommandCSVInfo (bool only_supported, bool include_identity_info, char deliminator=',') const
	Serializes all command information to a CSV-formatted string.
JSONNode	getCommandJSONInfo (bool only_supported) const
	Serializes all command information to a JSON tree.
bool	hasPending () const
	Returns whether there are any pending or currently executing commands.
bool	hasPendingCommand (t_type command) const
	Checks whether a specific command is pending in the queue.
virtual void	onFailure (const t_type &command)
	Called when a command fails.
bool	popCommandAndExecute ()
	Pops the next command from the queue and executes it.
void	postCommand (t_type command, const StringView &args=StringView(), const StringView &regex=StringView())
	Posts a command to the end of the queue.
void	removeCommand (t_type command)
	Removes all instances of the given command from the queue.
virtual void	retryCommand ()
	Cancels the current command and re-adds it to the front of the queue for retry.
TimeSpan	rxDelay () const
	Returns the receive delay for the currently executing command.
void	setBufferOffset (uint04 buffer_offset)
	Sets the buffer offset for data reads.
void	setFromJSONInfo (const JSONNode &root, bool allow_command_override, LogPtr log)
	Loads command configuration and statistics from a JSON tree.
void	setSupport (t_type command, CommandSupport support)
	Sets the support status for a command.
void	setSupported (t_type command, bool supported)
	Sets whether a command is supported or not.
virtual bool	supportsCommand (t_type command) const
	Checks whether the hardware supports the given command.
TimeSpan	txDelay () const
	Returns the transmission delay for the currently executing command.

Static Public Attributes
static const uint04	s_buffer_size = 256000
	The default buffer size for command data.

Protected Attributes
uint04	m_buffer_offset = 0
	The current offset into the data buffer.
Dictionary< t_type, CommandInformation >	m_command_info
	Map of command types to their configuration and statistics.
CommandQueueItem	m_current_command
	The command currently being executed.
Time	m_current_command_start_time = Constant<Time>::Invalid
	When the current command began executing.
Buffer< CommandQueueItem >	m_ordered_commands
	The ordered list of commands waiting to be executed.
CommandQueueItem	m_pending_block_command
	A blocking command waiting to be executed with priority.
Dictionary< t_type, uint04 >	m_pending_commands
	Map of pending command types to their count in the queue.
Buffer< CommandRecord >	m_records
	Historical records of executed commands.

Detailed Description

template<class t_type>
class HardwareCommandQueue< t_type >

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.

Definition at line 81 of file HardwareCommandQueue.h.

Member Function Documentation

◆ addCommandToFront()

template<class t_type>

void HardwareCommandQueue< t_type >::addCommandToFront	(	t_type	command,
		const String &	args = String(),
		const String &	regex = String() )

inline

Adds a command to the front of the queue so it executes next.

Parameters

[in]	command	The command to add.
[in]	args	Optional arguments for the command.
[in]	regex	Optional validation regex for the response.

Definition at line 161 of file HardwareCommandQueue.h.

References allowMultipleCommandsInStream(), m_ordered_commands, and m_pending_commands.

Referenced by retryCommand().

◆ allowMultipleCommandsInStream()

template<class t_type>

virtual bool HardwareCommandQueue< t_type >::allowMultipleCommandsInStream	(	t_type	command,
		const StringView &	args ) const

inlinevirtual

Returns whether multiple instances of the same command are allowed in the queue.

Parameters

[in]	command	The command to check.
[in]	args	The arguments for the command.

Returns: True if multiple instances are allowed. Default returns false.

Definition at line 190 of file HardwareCommandQueue.h.

Referenced by addCommandToFront(), and postCommand().

◆ commandInformation()

template<class t_type>

CommandInformation HardwareCommandQueue< t_type >::commandInformation ( t_type command )

inline

Returns the stored statistics and configuration for the given command.

Parameters

[in] command The command to query.

Returns: The CommandInformation for the command, or a default if not found.

Definition at line 360 of file HardwareCommandQueue.h.

References m_command_info.

◆ commandTimeout()

template<class t_type>

TimeSpan HardwareCommandQueue< t_type >::commandTimeout ( ) const

inline

Returns the response timeout for the currently executing command.

Returns: The timeout TimeSpan, or zero if no command is active.

Definition at line 419 of file HardwareCommandQueue.h.

References m_command_info, and m_current_command.

◆ disableCommand()

template<class t_type>

void HardwareCommandQueue< t_type >::disableCommand ( t_type command )

inline

Disables a command, removing it from the queue and marking it as unsupported.

Parameters

[in] command The command to disable.

Definition at line 377 of file HardwareCommandQueue.h.

References e_not_supported, m_command_info, m_ordered_commands, and m_pending_commands.

◆ endCommandQueue()

template<class t_type>

virtual void HardwareCommandQueue< t_type >::endCommandQueue ( )

inlinevirtual

Called when the command queue is shutting down.

Override to perform cleanup.

Definition at line 413 of file HardwareCommandQueue.h.

◆ executeCommand()

template<class t_type>

virtual void HardwareCommandQueue< t_type >::executeCommand	(	const t_type &	command,
		const StringView &	args )

pure virtual

Executes a command with the given arguments.

Must be implemented by subclasses.

Parameters

[in]	command	The command to execute.
[in]	args	The arguments for the command.

Referenced by popCommandAndExecute().

◆ executeCommandBlocking()

template<class t_type>

void HardwareCommandQueue< t_type >::executeCommandBlocking	(	const t_type &	command,
		const StringView &	args = StringView() )

inline

Posts a command and blocks until it has been executed and completed.

Parameters

[in]	command	The command to execute.
[in]	args	Optional arguments for the command.

Definition at line 313 of file HardwareCommandQueue.h.

References m_current_command, m_pending_block_command, and ThreadFunctions::RequestSleep().

◆ getCommandCSVInfo()

template<class t_type>

String HardwareCommandQueue< t_type >::getCommandCSVInfo	(	bool	only_supported,
		bool	include_identity_info,
		char	deliminator = ',' ) const

inline

Serializes all command information to a CSV-formatted string.

Parameters

[in]	only_supported	If true, only includes commands that are supported.
[in]	include_identity_info	If true, includes default args, delays, regex, and timeout.
[in]	deliminator	The delimiter character to use between fields.

Returns: A CSV-formatted String containing command statistics.

Definition at line 539 of file HardwareCommandQueue.h.

References cast(), CommandInformation::default_argument, String::DisplayString(), e_not_supported, TimeSpan::elapsedSeconds(), TranslatedString::englishTranslation(), m_command_info, CommandInformation::number_of_attempts, CommandInformation::number_of_failures, CommandInformation::response_timeout, CommandInformation::rx_delay, CommandInformation::supports_command, CommandInformation::total_time, CommandInformation::tx_delay, and CommandInformation::validation_regex.

◆ getCommandJSONInfo()

template<class t_type>

JSONNode HardwareCommandQueue< t_type >::getCommandJSONInfo ( bool only_supported ) const

inline

Serializes all command information to a JSON tree.

Parameters

[in] only_supported If true, only includes commands that are supported.

Returns: A JSONNode containing command statistics and configuration.

Definition at line 498 of file HardwareCommandQueue.h.

◆ hasPending()

template<class t_type>

bool HardwareCommandQueue< t_type >::hasPending ( ) const

inline

Returns whether there are any pending or currently executing commands.

Returns: True if a command is active or queued.

Definition at line 596 of file HardwareCommandQueue.h.

References m_current_command, and m_pending_commands.

◆ hasPendingCommand()

template<class t_type>

bool HardwareCommandQueue< t_type >::hasPendingCommand ( t_type command ) const

inline

Checks whether a specific command is pending in the queue.

Parameters

[in] command The command to check for.

Returns: True if the command is pending.

Definition at line 108 of file HardwareCommandQueue.h.

References m_pending_commands.

◆ onFailure()

template<class t_type>

virtual void HardwareCommandQueue< t_type >::onFailure ( const t_type & command )

inlinevirtual

Called when a command fails.

Updates failure statistics and support status.

Parameters

[in] command The command that failed.

Definition at line 291 of file HardwareCommandQueue.h.

References e_not_known, e_not_supported, and m_command_info.

◆ popCommandAndExecute()

template<class t_type>

bool HardwareCommandQueue< t_type >::popCommandAndExecute ( )

inline

Pops the next command from the queue and executes it.

Returns: True if a command was executed, false if the queue was empty.

Definition at line 198 of file HardwareCommandQueue.h.

References executeCommand(), m_current_command, m_current_command_start_time, m_ordered_commands, m_pending_block_command, m_pending_commands, and Time::SystemTime().

◆ postCommand()

template<class t_type>

void HardwareCommandQueue< t_type >::postCommand	(	t_type	command,
		const StringView &	args = StringView(),
		const StringView &	regex = StringView() )

inline

Posts a command to the end of the queue.

If the command already exists and multiple commands are not allowed, the existing entry is updated instead.

Parameters

[in]	command	The command to post.
[in]	args	Optional arguments for the command.
[in]	regex	Optional validation regex for the response.

Definition at line 118 of file HardwareCommandQueue.h.

References allowMultipleCommandsInStream(), m_ordered_commands, and m_pending_commands.

◆ removeCommand()

template<class t_type>

void HardwareCommandQueue< t_type >::removeCommand ( t_type command )

inline

Removes all instances of the given command from the queue.

Parameters

[in] command The command to remove.

Definition at line 142 of file HardwareCommandQueue.h.

References IsValid(), m_ordered_commands, and m_pending_commands.

◆ rxDelay()

template<class t_type>

TimeSpan HardwareCommandQueue< t_type >::rxDelay ( ) const

inline

Returns the receive delay for the currently executing command.

Returns: The rx delay TimeSpan, or zero if no command is active.

Definition at line 435 of file HardwareCommandQueue.h.

References m_command_info, and m_current_command.

◆ setBufferOffset()

template<class t_type>

void HardwareCommandQueue< t_type >::setBufferOffset ( uint04 buffer_offset )

inline

Sets the buffer offset for data reads.

Parameters

[in] buffer_offset The new buffer offset.

Definition at line 607 of file HardwareCommandQueue.h.

References m_buffer_offset.

◆ setFromJSONInfo()

template<class t_type>

void HardwareCommandQueue< t_type >::setFromJSONInfo	(	const JSONNode &	root,
		bool	allow_command_override,
		LogPtr	log )

inline

Loads command configuration and statistics from a JSON tree.

Parameters

[in]	root	The JSON node containing command information.
[in]	allow_command_override	If true, allows overriding command strings, delays, and support status.
[in]	log	The log to report errors to.

Definition at line 445 of file HardwareCommandQueue.h.

◆ setSupport()

template<class t_type>

void HardwareCommandQueue< t_type >::setSupport	(	t_type	command,
		CommandSupport	support )

inline

Sets the support status for a command.

Parameters

[in]	command	The command to update.
[in]	support	The new CommandSupport status.

Definition at line 398 of file HardwareCommandQueue.h.

References m_command_info.

◆ setSupported()

template<class t_type>

void HardwareCommandQueue< t_type >::setSupported	(	t_type	command,
		bool	supported )

inline

Sets whether a command is supported or not.

Parameters

[in]	command	The command to update.
[in]	supported	True to mark as supported, false to mark as unsupported.

Definition at line 405 of file HardwareCommandQueue.h.

References e_not_supported, e_supported, and m_command_info.

◆ supportsCommand()

template<class t_type>

virtual bool HardwareCommandQueue< t_type >::supportsCommand ( t_type command ) const

inlinevirtual

Checks whether the hardware supports the given command.

Parameters

[in] command The command to check.

Returns: True if the command is supported or unknown, false if explicitly not supported.

Definition at line 369 of file HardwareCommandQueue.h.

References e_not_supported, and m_command_info.

◆ txDelay()

template<class t_type>

TimeSpan HardwareCommandQueue< t_type >::txDelay ( ) const

inline

Returns the transmission delay for the currently executing command.

Returns: The tx delay TimeSpan, or zero if no command is active.

Definition at line 427 of file HardwareCommandQueue.h.

References m_command_info, and m_current_command.

The documentation for this class was generated from the following file:

Hardware/Headers/HardwareCommandQueue.h

Classes

Public Member Functions

Static Public Attributes

Protected Attributes

Detailed Description

Member Function Documentation

◆ addCommandToFront()

◆ allowMultipleCommandsInStream()

◆ commandInformation()

◆ commandTimeout()

◆ disableCommand()

◆ endCommandQueue()

◆ executeCommand()

◆ executeCommandBlocking()

◆ getCommandCSVInfo()

◆ getCommandJSONInfo()

◆ hasPending()

◆ hasPendingCommand()

◆ onFailure()

◆ popCommandAndExecute()

◆ postCommand()

◆ removeCommand()

◆ rxDelay()

◆ setBufferOffset()

◆ setFromJSONInfo()

◆ setSupport()

◆ setSupported()

◆ supportsCommand()

◆ txDelay()