Task is a base class for all SMTK tasks. More...

#include <Task.h>

Inheritance diagram for smtk::task::Task:

Collaboration diagram for smtk::task::Task:

Public Types
enum	RelatedTasks { RelatedTasks::Depend, RelatedTasks::Child }
	The types of related tasks to visit. More...

using	Observer = std::function< void(Task &, State, State)>
	A task's state changes may be observed.

using	Observers = smtk::common::Observers< Observer >
	The collection of all observers of this task instance.

using	Dependencies = std::map< WeakPtr, typename Observers::Key, std::owner_less< WeakPtr > >
	A task's dependencies are other tasks stored as weak pointers.

using	PassedDependencies = std::set< Ptr >
	A task's dependencies are other tasks passed as shared pointers.

using	Configuration = nlohmann::json
	Tasks are configured with arbitrary JSON objects, though this may change.

using	Visitor = std::function< smtk::common::Visit(Task &)>
	Signature of functions invoked when visiting dependencies or children while allowing early termination.

Public Types inherited from smtk::resource::Component
typedef std::function< void(const ComponentPtr &)>	Visitor

typedef detail::ComponentLinks	Links

typedef detail::ComponentProperties	Properties

Public Member Functions
	smtkTypeMacro (smtk::task::Task)

	smtkSuperclassMacro (smtk::resource::Component)

	smtkCreateMacro (smtk::resource::PersistentObject)

	Task (const Configuration &config, Manager &taskManager, const std::shared_ptr< smtk::common::Managers > &managers=nullptr)

	Task (const Configuration &config, const PassedDependencies &dependencies, Manager &taskManager, const std::shared_ptr< smtk::common::Managers > &managers=nullptr)

void	configure (const Configuration &config)
	A method called by all constructors passed Configuration information. More...

const common::UUID &	id () const override
	Set/get the task's unique identifier.

bool	setId (const common::UUID &newId) override
	Assign an ID to this object (used by readers; not for arbitrary reuse). More...

std::string	name () const override
	Return the task's name.

virtual void	setName (const std::string &name)

const std::shared_ptr< resource::Resource >	resource () const override
	Components are required to return their owning resource (if any). More...

const std::string &	title () const
	Return the title of the task (if one was provided).

void	setTitle (const std::string &title)
	Set the title of the task to be presented to users. More...

virtual const std::unordered_map< smtk::string::Token, Port * > &	ports () const
	Return a set of ports for this task indexed by their function (a descriptive string).

bool	changePortName (Port *port, const std::string &newName, std::function< bool()> fp)
	Change the Name of a Port. More...

virtual std::shared_ptr< PortData >	portData (const Port *port) const
	Given a port owned by this task, return data to be transmitted over the port. More...

virtual void	portDataUpdated (const Port *port)
	Accept notification that data on the given port has been updated. More...

const std::set< smtk::string::Token > &	style () const
	Set/get style classes for the task. More...

bool	addStyle (const smtk::string::Token &styleClass)

bool	removeStyle (const smtk::string::Token &styleClass)

bool	clearStyle ()

virtual bool	getViewData (smtk::common::TypeContainer &configuration) const
	Populate a type-container with view-related data for configuration. More...

virtual State	state () const
	Get the state. More...

bool	isCompleted () const
	Return whether or not the task has been marked completed.

State	agentState () const
	Returns the state of a task's agents.

State	childrenState () const
	Returns the state of a task's children.

State	dependencyState () const
	Returns the state of a task's dependencies.

virtual bool	editableCompletion () const
	Return whether or not users are allowed to mark a task completed. More...

virtual bool	markCompleted (bool completed)
	This public method allows user-interface components to indicate when the user marks a task complete (or unmarks it). More...

bool	areDependenciesStrict () const
	Return true if this task has been configured with strict dependency enforcement. More...

PassedDependencies	dependencies () const
	Return the tasks which this task depends upon. More...

bool	canAddDependency (const std::shared_ptr< Task > &dependency)
	Check whether inserting a dependency would induce a cycle. More...

bool	addDependency (const std::shared_ptr< Task > &dependency)
	Add a dependency. More...

template<typename Container >
bool	addDependencies (const Container &tasks)
	Add a container of task-pointers as dependencies. More...

bool	removeDependency (const std::shared_ptr< Task > &dependency)
	Remove a dependency. More...

template<typename Container >
bool	removeDependencies (const Container &tasks)
	Remove a container of task-pointers as dependencies. More...

Task *	parent () const
	Return a parent task if one exists; null otherwise.

virtual smtk::common::Visit	visit (RelatedTasks relation, Visitor visitor) const
	Visit children. More...

virtual bool	hasChildren () const
	Return whether or not the task has children.

const std::unordered_set< Task * >	children () const
	Return the children of the task.

std::unordered_set< Agent * >	agents () const
	Return the agents of the task. More...

Observers &	observers ()
	Return this object's observers so other classes may insert themselves.

virtual bool	updateAgentState (const Agent *agent, State prev, State next, bool signal=true)
	Updates the state of the task based on the change of an agent. More...

Manager *	manager () const
	Return the tasks's manager (or null if unmanaged).

std::shared_ptr< smtk::common::Managers >	managers () const
	Return the application-state container. More...

Public Member Functions inherited from smtk::resource::Component
	smtkTypeMacro (smtk::resource::Component)

	smtkSuperclassMacro (smtk::resource::PersistentObject)

	smtkSharedFromThisMacro (smtk::resource::PersistentObject)

virtual Resource *	parentResource () const
	Return a raw (not shared) pointer to the resource that owns this component. More...

template<typename ResourceType >
ResourceType *	parentResourceAs () const
	This variant of parentResource casts the result to the given ResourceType.

Links &	links () override
	Return the links that connect this component to external resources/components.

const Links &	links () const override

Properties &	properties () override
	Return properties defined on this component.

const Properties &	properties () const override

Public Member Functions inherited from smtk::resource::PersistentObject
	smtkTypeMacroBase (smtk::resource::PersistentObject)

template<typename T >
T::Ptr	as ()
	Attempt to cast this object to a subclass.

template<typename T >
T::ConstPtr	as () const
	Attempt to cast this object to a subclass.

Protected Member Functions
bool	changeState (State previous, State next)
	Indicate the state of this task has changed. More...

virtual bool	updateDependencyState (Task &dependency, State prev, State next)
	Update our state because a dependent task has changed state or a subclass has marked the internal state as changed. More...

virtual bool	updateChildrenState (const Task *child, State prev, State next)
	Updates the state of the task based on the change of a child task. More...

virtual State	computeDependencyState () const
	Compute the state based on the state of the task's dependencies. More...

virtual State	computeAgentState () const
	Compute the state based on state of the task's agents.

virtual State	computeChildrenState () const
	Compute the state based on the state of the task's children.

Protected Attributes
std::string	m_name
	A task name to present to the user.

std::set< smtk::string::Token >	m_style
	The set of style classes for this task.

bool	m_completed = false
	Whether the user has marked the task completed or not.

std::map< WeakPtr, Observers::Key, std::owner_less< WeakPtr > >	m_dependencies
	A set of dependent tasks and the keys used to observe their state so that this task can update its state in response.

bool	m_strictDependencies = false
	Should dependencies be strictly enforced?

std::set< WeakPtr, std::owner_less< WeakPtr > >	m_dependents
	Tasks upon which this task depends. More...

Observers	m_observers
	The set of observers of this task's state.

Task *	m_parent = nullptr
	If this task is the child of another task, this pointer references its parent. More...

std::weak_ptr< smtk::task::Manager >	m_manager
	If this task is being managed, this will refer to its manager.

smtk::common::UUID	m_id
	The unique identifier for this task.

std::unordered_set< Task * >	m_children
	The children of the task.

std::unordered_set< std::unique_ptr< Agent > >	m_agents
	The agents of the task.

std::unordered_map< smtk::string::Token, Port * >	m_ports
	The ports of the Task.

State	m_agentState = State::Completable

State	m_dependencyState = State::Irrelevant

State	m_childrenState = State::Irrelevant

Friends
SMTKCORE_EXPORT void	workflowsOfTask (Task , std::set< smtk::task::Task > &, std::set< smtk::task::Task * > &)
	Free functions that populate a set of workflow "head" tasks for an input task (this is the set of tasks that task ultimately depends on but are not themselves dependent on any task). More...

Detailed Description

Task is a base class for all SMTK tasks.

SMTK tasks are nodes in a graph whose arcs connect them to dependencies. The state of each task and its dependencies determine the set of available (or reachable) tasks. An application's user interface typically gets reconfigured when the active task changes to help direct users through a workflow, although tasks should not attempt to modify the user interface themselves. Instead, tasks should be solely focused on determining whether conditions are met for them to be (a) accessible to users and (b) marked completed by users. Once the first set of conditions is met, users are allowed to undertake the task. Once the second set of conditions is met, users are allowed to mark the task complete and thus gain access to those tasks which depend on it.

Member Enumeration Documentation

◆ RelatedTasks

enum smtk::task::Task::RelatedTasks

strong

The types of related tasks to visit.

Enumerator
Depend	Visit tasks this task depends upon.
Child	Visit child tasks.

Member Function Documentation

◆ addDependencies()

template<typename Container >

bool smtk::task::Task::addDependencies ( const Container & tasks )

Add a container of task-pointers as dependencies.

Returns true if all dependencies were added, false if any already existed or were null. This method will invoke observers if adding the dependencies changes this task's state.

◆ addDependency()

bool smtk::task::Task::addDependency ( const std::shared_ptr< Task > & dependency )

Add a dependency.

Returns true if the dependency was added, false if it already existed or is null. This method will invoke observers if adding the dependency changes this task's state.

◆ agents()

std::unordered_set< Agent * > smtk::task::Task::agents ( ) const

Return the agents of the task.

Note that the agents returned are owned by the task and should not be deleted.

◆ areDependenciesStrict()

bool smtk::task::Task::areDependenciesStrict ( ) const

inline

Return true if this task has been configured with strict dependency enforcement.

When true, a task will (1) not become available until all its dependencies are marked completed and (2) not be completable until all its dependencies are marked completed.

When false, a task will become available once its internal state becomes incomplete or completable, regardless of its dependent tasks. However, it will not be allowed to be marked complete until its dependencies are marked complete.

◆ canAddDependency()

bool smtk::task::Task::canAddDependency ( const std::shared_ptr< Task > & dependency )

Check whether inserting a dependency would induce a cycle.

Note that this method does not check adaptors as it is possible that they may have cycles and yet terminate. (It is also possible adaptors have cycles that would not terminate.)

This method is invoked by addDependency().

◆ changePortName()

bool smtk::task::Task::changePortName	(	Port *	port,
		const std::string &	newName,
		std::function< bool()>	fp
	)

Change the Name of a Port.

This method is used to update internal data structures. Please use task::Port::setName to change the name of the Port - it will call this method with an appropriate lambda.

◆ changeState()

bool smtk::task::Task::changeState	(	State	previous,
		State	next
	)

protected

Indicate the state of this task has changed.

This method invokes observers if and only if previous and next are different. It will also update m_completed to match the new state.

Note that this method invokes Agent::taskStateChanged() for each of the task's agents and any agent may interrupt the state change inside this method. If this occurs, the agent is responsible for calling Task::updateAgentState(), which in turn will call Task::changeState() with a different next value. This nested call will fire observers once the final state allowed by agents is determined. This means that not all calls to Task::changeState() will result in observers being fired, even when the state is changing.

It returns false if previous == next or if an agent disallowed the state change to next (in which case observers from a nested call to changeState will have already succeeded) and true otherwise.

◆ computeDependencyState()

State smtk::task::Task::computeDependencyState ( ) const

protectedvirtual

Compute the state based on the state of the task's dependencies.

Each task instance may be configured with a "dependency strictness" that determines when users may work on a task with incomplete dependencies and whether users are allowed to mark a task with incomplete dependencies as completed.

A subclass that wishes to autocomplete might invoke the base-class method although this could frustrate users.

◆ configure()

void smtk::task::Task::configure ( const Configuration & config )

A method called by all constructors passed Configuration information.

In general, this method should set member variables directly instead of calling set/get methods since those may invoke observers with an uninitialized object.

Depedendencies (if they were provided) will already have been added when this method is called.

◆ dependencies()

Task::PassedDependencies smtk::task::Task::dependencies ( ) const

Return the tasks which this task depends upon.

WARNING: The returned set is read-only (modifying it does not modify this Task); however, modifying tasks in the returned set can affect this Task's state.

◆ editableCompletion()

bool smtk::task::Task::editableCompletion ( ) const

virtual

Return whether or not users are allowed to mark a task completed.

User interfaces (e.g., qtDiagramView) should check this to decide whether to enable UI elements that accept user completion. Subclasses of Task that automate completion (e.g., SubmitOperation when RunStyle is set to Once) can override this method to prevent users from explicitly marking completion. The default implementation returns true when the task state is completable or completed.

Reimplemented in smtk::task::SubmitOperation.

◆ getViewData()

bool smtk::task::Task::getViewData ( smtk::common::TypeContainer & configuration ) const

virtual

Populate a type-container with view-related data for configuration.

Subclasses should override this method. Generally, views will want access to a resource and potentially components in the resource that are the subject of the view. Other view configuration will come from view style() (see above) or smtk::common::Managers.

This method will return true when the configuration was modified and false otherwise.

Reimplemented in smtk::task::FillOutAttributes.

◆ managers()

std::shared_ptr< smtk::common::Managers > smtk::task::Task::managers ( ) const

Return the application-state container.

This will return null if the task has no task::Manager.

◆ markCompleted()

bool smtk::task::Task::markCompleted ( bool completed )

virtual

This public method allows user-interface components to indicate when the user marks a task complete (or unmarks it).

This method has no effect and returns false if the task's current state is unavailable or incomplete. Returns true if the task's current state changes (from Completable to Completed if completed is true or Completed to Completable if completed is false). If true is returned, this method invoked its observers.

Be aware that if this task transitions from State::Completed to State::Incomplete or State::Unavailable, m_completed will be reset to false and this method must be invoked again.

Reimplemented in smtk::task::SubmitOperation.

◆ portData()

std::shared_ptr< PortData > smtk::task::Task::portData ( const Port * port ) const

virtual

Given a port owned by this task, return data to be transmitted over the port.

Subclasses that own ports must override this method in order to produce port-data.

Reimplemented in smtk::task::FillOutAttributes.

◆ portDataUpdated()

void smtk::task::Task::portDataUpdated ( const Port * port )

virtual

Accept notification that data on the given port has been updated.

This function will be called when processing operation results. There is no guarantee that resources other than the project owning this task is locked; if you need to modify other resources as a result of this notification, you should launch an operation so that those resources are properly locked.

If port is one of the task's input ports (i.e., port->direction() == In), then each agent of the task is called with the port. If port is one of the task's output ports (i.e., port->direction() == Out), then each downstream task of port has its portDataUpdated() method with the connected port.

Because this function will be called on the user-interface thread, it is acceptable to take actions affecting the user interface, including changing the state of this task.

Reimplemented in smtk::task::FillOutAttributes.

◆ removeDependencies()

template<typename Container >

bool smtk::task::Task::removeDependencies ( const Container & tasks )

Remove a container of task-pointers as dependencies.

Returns true if all dependencies were removed, false otherwise. This method will invoke observers if removing the dependencies changes this task's state.

◆ removeDependency()

bool smtk::task::Task::removeDependency ( const std::shared_ptr< Task > & dependency )

Remove a dependency.

Returns true if the dependency was removed, false if not. This method will invoke observers if removing the dependency changes this task's state.

◆ resource()

const std::shared_ptr< resource::Resource > smtk::task::Task::resource ( ) const

overridevirtual

Components are required to return their owning resource (if any).

Components may not have an owning resource at some points in their lifecycle, so be sure to verify the returned value is non-null.

Implements smtk::resource::Component.

◆ setId()

bool smtk::task::Task::setId ( const common::UUID & myID )

overridevirtual

Assign an ID to this object (used by readers; not for arbitrary reuse).

TODO: care must be taken to modify the recorded ID in all links that connect to this object (see Resource::setId and its treatment of manager registration for reference).

Implements smtk::resource::PersistentObject.

◆ setTitle()

void smtk::task::Task::setTitle ( const std::string & title )

inline

Set the title of the task to be presented to users.

This is not intended to be a unique identifier.

◆ state()

State smtk::task::Task::state ( ) const

virtual

Get the state.

This state is a composition of m_agentState (he combined state of all of the task's agents), m_childrenState (the combined state of all the task's children) – and m_dependencyState (the state of any dependencies).

Since the task as no agents by default, m_agentState is initialized to State::Completable. Similarly, since the task has no children by default, m_childrenState is initialized to State::Irrelevant. Therefore the default behavior is to become Completable once all dependencies are met (i.e., Completable or Completed) and Completed only if dependencies are met and markCompleted(true) has been called.

In terms of expected values, m_dependnecyState can have the following values:

Irrelevant : There are no dependencies or all of their states are Irrelevant.
Unavailable : At least one of the relevant dependencies' states is less than Completable or all are Completable but strict dependency observance has been requested.
Completable : All of the relevant dependencies' states are at least Completable but all are not Completed and strict dependency observance has not been requested.
Completed : All of the relevant dependencies' states are Completed.

In terms of expected values, m_agentState can have the following values:

Irrelevant : There are no agents or all of their states are Irrelevant
Unavailable : All relevant agents are Unavailable.
Completable : All relevant agents are Completable.
Incomplete : The states of the agents are different and .

In terms of expected values, m_childrenState can have the following values:

Irrelevant : There are no children or all of their states are Irrelevant
Unavailable : The minimum state of all relevant children is Unavailable.
Incomplete : The minimum state of all relevant children is Incomplete.
Completable : The minimum state of all relevant children is Completable.
Completed : All relevant children are Completed.

In terms of calculating the state of the task itself :

DependencyState	AgentState	ChildrenState	TaskState
Unavailable	Any	Any	Unavailable
Irrelevant Completable Completed	Irrelevant	Irrelevant	Irrelevant
		Incomplete	Incomplete
		Completable	Incomplete
		Completed	Completable (if m_complete is false) Completed (if m_complete is true)
	Unavailable	Irrelevant	Unavailable
	Incomplete		Incomplete
	Completable		Completable (if m_complete is false) Completed (if m_complete is true)
	Unavailable	Unavailable	Unavailable
	Unavailable	> Unavailable	Incomplete
	> Unavailable	Unavailable
	Incomplete	Any
	Any	Incomplete
	Completable	Completable
	Completable	Completed	Completable (if m_complete is false) Completed (if m_complete is true)

◆ style()

const std::set<smtk::string::Token>& smtk::task::Task::style ( ) const

inline

Set/get style classes for the task.

A style class specifies how applications should present the task (e.g., what type of view to provide the user, what rendering mode to use, what objects to list or exclude).

◆ updateAgentState()

bool smtk::task::Task::updateAgentState	(	const Agent *	agent,
		State	prev,
		State	next,
		bool	signal = `true`
	)

virtual

Updates the state of the task based on the change of an agent.

Will return true if the task's state has changed. If this results in the task's state changing, observers are invoked if signal is true (the default).

The signal parameter exists so that agents that wish to change their parent task's m_agentState without forcing the final state of the task to change may do so. This can happen, for instance, when a dependency causes the task's final state to become Unavailable but a task's state to transition from Completable to Incomplete. Since Incomplete > Unavailable, the overall task state should not be modified by the agent. However, the task's agent-state also needs to be modified from within Task::changeState.

If you are writing an agent and next is less than your agent's internal state, pass false to signal.

Reimplemented in smtk::task::AgentlessTask.

◆ updateChildrenState()

bool smtk::task::Task::updateChildrenState	(	const Task *	child,
		State	prev,
		State	next
	)

protectedvirtual

Updates the state of the task based on the change of a child task.

Will return true if the task's state has changed. If this results in the

◆ updateDependencyState()

bool smtk::task::Task::updateDependencyState	(	Task &	dependency,
		State	prev,
		State	next
	)

protectedvirtual

Update our state because a dependent task has changed state or a subclass has marked the internal state as changed.

Returns true if this task's state changed and false otherwise. This method will invoke observers if it returns true.

◆ visit()

smtk::common::Visit smtk::task::Task::visit	(	RelatedTasks	relation,
		Visitor	visitor
	)		const

virtual

Visit children.

If hasChildren returns false, this will return immediately.

For the signature taking a Visitor, this method returns smtk::common::Visit::Halt if iteration was terminated.

Subclasses that override hasChildren should override these methods.

Friends And Related Function Documentation

◆ workflowsOfTask

SMTKCORE_EXPORT void workflowsOfTask	(	Task *	,
		std::set< smtk::task::Task * > &	,
		std::set< smtk::task::Task * > &
	)

friend

Free functions that populate a set of workflow "head" tasks for an input task (this is the set of tasks that task ultimately depends on but are not themselves dependent on any task).

The variant that accepts visited can be used to efficiently accumulate workflows across several tasks (by pruning visited nodes from its traversal).

Member Data Documentation

◆ m_dependents

std::set<WeakPtr, std::owner_less<WeakPtr> > smtk::task::Task::m_dependents

protected

Tasks upon which this task depends.

This set is maintained by other Task instances when addDependency/removeDependency is called.

◆ m_parent

Task* smtk::task::Task::m_parent = nullptr

protected

If this task is the child of another task, this pointer references its parent.

The parent is responsible for updating this pointer as needed. m_parent is not a weak pointer because it must be initialized in the child during the parent's construction (when no shared pointer may exist).

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

/home/docs/checkouts/readthedocs.org/user_builds/smtk/checkouts/latest/smtk/task/Task.h
/home/docs/checkouts/readthedocs.org/user_builds/smtk/checkouts/latest/smtk/task/Task.cxx

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Enumeration Documentation

◆ RelatedTasks

Member Function Documentation

◆ addDependencies()

◆ addDependency()

◆ agents()

◆ areDependenciesStrict()

◆ canAddDependency()

◆ changePortName()

◆ changeState()

◆ computeDependencyState()

◆ configure()

◆ dependencies()

◆ editableCompletion()

◆ getViewData()

◆ managers()

◆ markCompleted()

◆ portData()

◆ portDataUpdated()

◆ removeDependencies()

◆ removeDependency()

◆ resource()

◆ setId()

◆ setTitle()

◆ state()

◆ style()

◆ updateAgentState()

◆ updateChildrenState()

◆ updateDependencyState()

◆ visit()

Friends And Related Function Documentation

◆ workflowsOfTask

Member Data Documentation

◆ m_dependents

◆ m_parent