#include "steam/control/command-instance-manager.hpp"

Description

Maintain a current command instance for parametrisation.

The definition of a Steam-Layer command is used like a prototype. For invocation, an anonymous clone copy is created from the definition by calling newInstance. Several competing usages of the same command can be kept apart with the help of the invocationID, which is used to decorate the basic command-ID to form a distinct _instanceID_. After newInstance has "opened" an instance this way and returned the instanceID, the actual Command handle can be retrieved with getInstance. It represents an anonymous instance kept alive solely by the CommandInstanceManager (i.e. there is no registration of a command under that instanceID in the global CommandRegistry). When done with the parametrisation, by calling dispatch, this anonymous instance will be handed over to the Dispatcher (installed on construction). Typically, this will in fact be the steam::control::SteamDispatcher, which runs in a dedicated thread ("session loop thread") and maintains a queue of commands to be dispatched towards the current session. Since Command is a smart handle, the enqueued instance will stay alive until execution and then go out of scope. But, after dispatch, it is no longer accessible from the CommandInstanceManger, and while it is still waiting in the execution queue, the next instance for the same invocationID might already be opened.

Warning: CommandInstanceManager is not threadsafe

Definition at line 90 of file command-instance-manager.hpp.

Public Member Functions
	CommandInstanceManager (CommandDispatch &)
	create a CommandInstanceManager and wire it with the given CommandDispatch implementation. More...

void	bindAndDispatch (Symbol instanceID, Rec const &argSeq)
	fire and forget anonymous command instance. More...

bool	contains (Symbol instanceID) const

void	dispatch (Symbol instanceID)
	hand over the designated command instance to the dispatcher installed on construction. More...

Command	getInstance (Symbol instanceID)
	access the currently "opened" instance with the given instanceID More...

Symbol	newInstance (Symbol prototypeID, string const &invocationID)
	Create and thus "open" a new anonymous command instance. More...

Private Member Functions
Command	getCloneOrInstance (Symbol, bool)

void	handOver (Command &&)

Private Member Functions inherited from NonCopyable
	NonCopyable (NonCopyable const &)=delete

NonCopyable &	operator= (NonCopyable const &)=delete

Private Attributes
CommandDispatch &	dispatcher_

std::unordered_map< Symbol, Command >	table_

Constructor & Destructor Documentation

◆ CommandInstanceManager()

CommandInstanceManager ( CommandDispatch & dispatcher )

create a CommandInstanceManager and wire it with the given CommandDispatch implementation.

Typically, this is done in SessionCommandService. The embedded hash table for pending command instances is sized in relation to the number of registered global Command definitions.

Definition at line 161 of file command-setup.cpp.

References Command::definition_count().

Here is the call graph for this function:

Member Function Documentation

◆ newInstance()

Symbol newInstance	(	Symbol	prototypeID,
		string const &	invocationID
	)

Create and thus "open" a new anonymous command instance.

Parameters

prototypeID	the underlying Command definition to create a clone copy
invocationID	used to decorate the prototypeID to from an unique instanceID

Exceptions

error::Logic in case an instance is for this ID combination is already "open"

Definition at line 173 of file command-setup.cpp.

Referenced by SessionCommandService::cycle().

Here is the caller graph for this function:

◆ getInstance()

Command getInstance ( Symbol instanceID )

access the currently "opened" instance with the given instanceID

Parameters

instanceID ID as returned from newInstance, or a global commandID

Returns: instance handle of handle of a global command as fallback

Note: when given a commandID, which is not known as (decorated) instanceID within our local registration table, just the globally registered Command instance is returned.

Remarks: deliberately this function returns by-value. Returning a reference into the global command registry would be dangerous under concurrency.

Exceptions

error::Invalid	when the given cmdID unknown both locally and globally.
error::Logic	when accessing an instance that was known but is currently no longer "open" (already dispatched command instance)

Definition at line 205 of file command-setup.cpp.

References steam::mobject::session::query::anonymous_namespace{fake-configrules.cpp}::entry(), and Command::get().

Here is the call graph for this function:

◆ dispatch()

void dispatch ( Symbol instanceID )

hand over the designated command instance to the dispatcher installed on construction.

Either the given ID corresponds to a global command definition, in which case an anonymous clone copy is created from this command. Alternatively the given ID matches a previously "opened" local instance (known only to this instance manager). In this case, the instance will really be moved over into the dispatcher, which also means this instance is no longer "open" for parametrisation.

Exceptions

error::Logic when the command's arguments aren't bound

Definition at line 275 of file command-setup.cpp.

References CommandInstanceManager::getCloneOrInstance(), and CommandInstanceManager::handOver().

Referenced by SessionCommandService::invoke().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ bindAndDispatch()

void bindAndDispatch	(	Symbol	instanceID,
		Rec const &	argSeq
	)

fire and forget anonymous command instance.

This is a simplified interface, allowing to create a clone instance from a global command definition (prototype), bind the arguments and pass this instance to the dispatcher in one shot. To integrate with the extended usage cycle, as a variation the given ID may indicate a previously opened instance, which will then be bound and dispatched likewise.

Parameters

instanceID	global commandID or previously opened local instanceID
argSeq	command argument tuple packaged as Record<GenNode>, which is the standard format sent for command execution via UI-bus

Definition at line 293 of file command-setup.cpp.

◆ getCloneOrInstance()

Command getCloneOrInstance	(	Symbol	instanceID,
		bool	must_be_bound
	)

private

retrieve either global or local command instance When matching a globally defined command, an anonymous clone instance will be created. Otherwise a lookup in the local instance table is performed and a matching entry is moved out of the table.

Definition at line 224 of file command-setup.cpp.

Referenced by CommandInstanceManager::dispatch().

Here is the caller graph for this function:

◆ handOver()

void handOver ( Command && toDispatch )

private

hand a command over to the dispatcher

Definition at line 257 of file command-setup.cpp.

Referenced by CommandInstanceManager::dispatch().

Here is the caller graph for this function:

Inheritance diagram for CommandInstanceManager:

Collaboration diagram for CommandInstanceManager:

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

Description

Public Member Functions

Private Member Functions

Private Attributes

Constructor & Destructor Documentation

◆ CommandInstanceManager()

Member Function Documentation

◆ newInstance()

◆ getInstance()

◆ dispatch()

◆ bindAndDispatch()

◆ getCloneOrInstance()

◆ handOver()