command.hpp File Reference

Go to the source code of this file.

Description

Steam-Layer command frontend.

A command is a functor, which can be invoked according to a pre-defined HandlingPattern. Most notably, command invocation can be scheduled and logged with the serialiser, and the effect of any command invocation can be undone later on by invoking the "undo operation" defined alongside with the command's operation. The command operation is defined through a C/C++ function and may receive an arbitrary number and type of arguments. After setting up such a CommandDef , it can be referred for use through a symbolic ID. Before being able to invoke the command, concrete function arguments need to be provided (this is called "binding" or "closing the function arguments"). These function arguments are stored within the command definition and remain opaque to the client code actually invoking the command. Behind the scenes, there is a CommandRegistry, holding an index of the registered commands and managing the storage for command definitions and arguments. The actual Command object used by client code is a small, copyable and ref-counting handle to this stored definition backend.

Command definition, argument types and UNDO operation

For a command to be usable at all, a concrete command definition need to be supplied somewhere in the code base. Typically this is done through static command-setup bindings. Such a command definition links three functions with the name-ID of the command

• the actual command operation
• a function to capture state
• a function to undo the effect of the operation These functions may take arbitrary arguments, but the signature of this operation is captured at compile time and embedded as invisible type information within the implementation storage. While this allows to verify the type of the actual command arguments, this type sanity check can happen only late, at invocation time (and result in raising an exception). In a similar vein, the state capturing and the undo function must match with the signature of the main operation, since these functions are provided with the same arguments as presented to the command function. The UNDO functionality in Lumiera is based on capturing a state memento, not on applying a reverse function. So it is the responsibility of the capture function to take a suitable state snapshot, such as to be able to revert to the situation before activating this command, but only as far as the effect of the actual command function is concerned.

See also

command-def.hpp

command-use1-test.cpp

command-use2-test.cpp

command-use3-test.cpp

SteamDispatcher

Session

Definition in file command.hpp.

#include "lib/error.hpp"
#include "lib/symbol.hpp"
#include "steam/common.hpp"
#include "steam/control/argument-erasure.hpp"
#include "steam/control/argument-tuple-accept.hpp"
#include "steam/control/handling-pattern.hpp"
#include "lib/meta/tuple-helper.hpp"
#include "lib/diff/gen-node.hpp"
#include "lib/handle.hpp"
#include <string>

Classes
class	Command
	Handle object representing a single Command instance to be used by client code. More...

Typedefs
using	FuncPtr = void *

Macros
#define	_FAILSAFE_COMMAND_QUERY(_ID_, _QUERY_)

Functions
	LUMIERA_ERROR_DECLARE (INVALID_ARGUMENTS)
	Arguments provided for binding doesn't match stored command function parameters.
	LUMIERA_ERROR_DECLARE (UNBOUND_ARGUMENTS)
	Command functor not yet usable, because arguments aren't bound.
	LUMIERA_ERROR_DECLARE (MISSING_MEMENTO)
	Undo functor not yet usable, because no undo state has been captured.
	LUMIERA_ERROR_DECLARE (INVALID_COMMAND)
	Unknown or insufficiently defined command.
	LUMIERA_ERROR_DECLARE (DUPLICATE_COMMAND)
	Attempt to redefine an already existing command definition.
bool	operator!= (Command const &c1, Command const &c2)
bool	operator< (Command const &c1, Command const &c2)
	allow for sets and associative containers
bool	operator== (Command const &c1, Command const &c2)

Namespaces
	lumiera
	Lumiera public interface.
	steam
	Steam-Layer implementation namespace root.
	steam::control
	Steam-Layer dispatcher, controller and administrative facilities.

Macro Definition Documentation

_FAILSAFE_COMMAND_QUERY

#define _FAILSAFE_COMMAND_QUERY	(		_ID_,
			_QUERY_
	)

Value:

try                                       \
        {                                        \
          return Command::get(_ID_)._QUERY_;      \
        }                                          \
      catch(lumiera::error::Invalid&)              \
        {                                          \
          lumiera_error(); /* ignore errorstate */ \
          return false;                            \
        }

Definition at line 270 of file command.hpp.