Command queue¶

This chapter describes the CommandQueue interface. This interface enables the client to queue command sequences in a queue belonging to an axis control (group).

Queue behavior¶

A command queue executes command sequences in FIFO order: it executes command sequences in the same order as they are queued. The same holds for commands in a command sequence: the queue executes commands in the sequence in the same order as they are ordered in the sequence. Creating and queueing commands shows the behavior of the queueing mechanism. The figure shows the creation, queueing and execution of a command sequence consisting of a single command of type AbsMove.

Creating and queueing commands¶

Creating and queueing commands demonstrates that an AbsMove command needs configuration, i.e. a desired position and end velocity need to be set. Additionally, for commands that inherit from ParameterSet, a parameter set can be selected. Finally, commands that inherit from MoveCommand support setting of a completion criterion.

IAxisControlBase.CommandQueue
ICommandQueue.CreateCommandSequence()
ICommandSequence.Commands
IAbsMove.Configuration
IMoveCommand.CompletionCriterion
ICommandQueue.Queue()
ICommandSequence.WaitComplete()

C++

IAxisControlBase::GetCommandQueue()
ICommandQueue::CreateCommandSequence()
ICommandSequence::GetCommands()
IAbsMove::SetConfiguration()
IMoveCommand::SetCompletionCriterion()
ICommandQueue::Queue()
ICommandSequence::WaitComplete()

Completion criterion¶

The Command completion criterion determines when the queue will consider the move command to be finished.

Upon reaching this criterion, the queue continues execution of the next command, unless the next command is a move command. Conceptually, this implies that at any time there may be multiple commands in a queue of which the state is Running. When a next move command is executed depends on the end velocity configured for the running move command:

Zero end velocity: when the StabilizingComplete input is active, typically connected to the equally named event of the settling state machine.
Non-zero end velocity: when the TrajectoryComplete input is active, typically connected to the equally named event of the trajectory interpolator.

The conditions coincide with the moment that the Command state machine transitions from Running` to Completed and with the moment that the command is removed from the queue.

Configuration update¶

A move command can be updated by calling its configuration function. Updating the configuration of a command is always allowed in command state Idle and never allowed in states Completed and Failed.

Support for updating the configuration in states Queued and Running is command type specific. For example, updating the configuration of an AbsMove command can result in a so-called end-point correction. Whether this is supported depends on the the type of trajectory generator used.

IAbsMove.Configuration

C++

IAbsMove::GetConfiguration()

IAbsMove::SetConfiguration()

Command queue priority¶

To allow a client to interrupt execution of a command sequence in favor of another command sequence, a command sequence can be queued with high Command queue priority.

Command queue priority¶
Command queue priority	Description
Normal	Queueing priority of the command is normal.
High	Queueing priority of the command is high.

Upon queueing a command sequence with high priority, this command sequence is moved to the head of the queue and the commands in the command sequence are therefore immediately executed. At the moment the prioritized command sequence is executed, any running command is aborted.

Note

Move commands remain in state Running until a new move command is started.

All commands that are queued at the moment of queueing a command sequence with high priority are set to Failed. The states of all sequences to which these failed commands belong are also set to Failed.

Command abortion¶

A running command can be aborted by the command queue for the following reasons:

Queueing of a command sequence with high Command queue priority
Clearing of the command queue.
Executing a Command sequence event response
Aborting a Command sequence event response

When the command queue aborts a running command, its execution is no longer under the supervision of the command queue and its state is set to Failed.

Command queue state machine¶

When the execution of a command fails, the command state goes to Failed. The effect on the Command queue state machine, however, depends on potential other running commands. If no other command is running, the queue state transits directly to Halted. If a move command is running, and it is not the failed command, the queue transits to Halted after the move command is completed or failed. No other commands are executed while in this state.

Note

A transition to Failed as a consequence of queueing of a high priority command sequence is not considered a failure of the command, i.e. this does not halt the queue.

Command queue state machine¶

Note

The ResponseActive state and the “[response triggered]” condition relate to the command sequence event response. See section State behaviour for a description of the command sequence event response state behaviour.

Note

The “[empty]” and “[not empty]” conditions relate to the definition of an empty queue.

ICommandQueue.Clear()

ICommandQueue.Continue()

C++

ICommandQueue::Clear()

ICommandQueue::Continue()

Events¶

The command queue contains state events and an empty queue event as described in the following sections.

State events¶

The command queue has an event for each command queue state. When the command queue enters a state, the corresponding event becomes active and remains active for the entire duration the command queue remains in the state. Command queue state machine states and events lists the command queue state events and their corresponding command queue states.

Command queue state machine states and events¶
Command queue state	Event name	Description
Idle	QueueIdle	Queue is idle
Running	QueueRunning	Queue is non-empty and executing commands
Halted	QueueHalted	Queue is not executing commands
ResponseActive	QueueResponseActive	Queue is executing a Command sequence event response

Queue empty¶

The queue is considered empty when all queued commands are not is state Queued or Running. The QueueEmpty event is generated when the command queue becomes empty and remains active for the entire duration the queue is empty.

Note

Commands configured for the Command sequence event response are not considered part of the queue.

Command sequence creation¶

The command queue is a factory for command sequences and the commands that these sequences hold, i.e. the function CreateCommandSequence is used to create a command sequence that contains commands of the specific command types. The command sequence is subsequently queued on the queue it was created on.

Errors¶

When an error occurs during processing of a command, queue processing halts. Errors can only occur when a command is in state Running. Command queue error sequence shows an example sequence.

Command queue error sequence¶

IEventSource.SubscribeEvents()
ICommandQueue.Queue()
ICommandQueue.Continue()
ICommandQueue.Clear()

C++

IEventSource::SubscribeEvents()
ICommandQueue::Queue()
ICommandQueue::Continue()
ICommandQueue::Clear()

Signals¶

The signals for command queue are visible in table Command queue signals.

Command queue signals¶
Name	Data type	R/W	Description
RunningCommand	UInt32	R	ID of the running command or `0xFFFFFFFF` if no command is running.
RunningMoveCommand	UInt32	R	ID of the running move command or `0xFFFFFFFF` if no move command is running.

As section Queue behavior explains, there may be multiple commands in the command queue of which the state is Running. If this is the case, a move command reached its completion criterion and the command queue started execution of the subsequent non-move command that was queued. In this case, the RunningCommand and RunningMoveCommand have a different value representing the running commands. Before reaching the completion criterion of a move command, the signal values are identical.

Event responder¶

The command queue is an event responder, i.e. CommandQueue implements EventResponder.

Command sequence event response¶

A command sequence can be executed as a response to an event. The command sequence to be executed can be configured on the CommandSequenceEventResponse interface. A typical use-case for this event response is a continuous scanning application where the command queue is filled with move commands with non-zero end-velocity. If the user application can not fill the command queue with new move commands in time, the command sequence event response can execute a SmoothStop command on the empty queue event to safely stop the axes.

ICommandSequenceEventResponse.Sequence

C++

ICommandSequenceEventResponse::GetSequence()

ICommandSequenceEventResponse::SetSequence()

State behaviour¶

When the event response is triggered and the command queue is not in state Halted, the queue transitions to state ResponseActive. If a command was running (i.e. the queue was in state Running), the running command is aborted.

Note

State commands are atomic and can not be interrupted.

Note

Move commands remain in state Running until a new move command is started.

The aborted command enters state Failed, but remains unhandled (i.e. doesn’t force the command queue to enter state Halted), until the event response is finished, or Clear is called. When the command sequence is finished (i.e. reaches either state Completed or Failed), the queue transitions to either of the following states:

Halted, when a failed command is present (either already present before the response started (e.g. an aborted command) or failed during execution of the response)
Idle, when no failed commands are present and the queue is empty at the moment the executed command sequence is Completed
Running, when no failed commands are present and the queue is not empty at the moment the executed command sequence is Completed

If the event response is triggered while the command queue is in state Halted, the command sequence is not executed and its state is set to Failed (the state of the commands in the command sequence remains unchanged). The command queue remains in Halted.

At event response execution, the configured command sequence and corresponding commands are set to state Queued and the first command in the sequence starts executing.

Execution¶

Command sequence event response sequence diagram shows the typical behavior of the command sequence event response. This sequence diagram shows the configuration and execution of a command sequence event response consisting of a single command of type SmoothStop.

Command sequence event response sequence diagram¶

Execution of the command sequence event response can be interrupted by calling Abort. Commands of the configured command sequence in state Queued will be set to Failed and the running command is aborted.

Note

A command sequence configured for the event response cannot be queued. Calling the Queue method throws an exception.

Note

The command sequence event response for an axis control part of an axis control group can be configured. However, if the event response is triggered while the axis control is part of a axis control group, the command sequence is not executed since the queue is in use by the command queue of the group. Instead the command sequence event response of the group queue can be configured.

Note

Calling Reuse on an executed command sequence (i.e. state equals Completed or Failed) is allowed, but not required in order to re-execute the command sequence in the event response context.