A helper for serializing task configurations. More...

#include <Helper.h>

Collaboration diagram for smtk::task::json::Helper:

Public Types
using	SwizzleId = Configurator< Task >::SwizzleId
	Swizzle IDs are serializable substitutes for pointers.

using	json = nlohmann::json
	JSON data type.

Public Member Functions
	~Helper ()
	Destructor is public, but you shouldn't use it.

void	setMapUUIDs (bool shouldMap)
	Turn on/off mapping of JSON UUIDs to new, random UUIDs. More...

bool	mapUUIDs () const

Manager &	taskManager ()

Configurator< Task > &	tasks ()
	Return an object for registering task classes and serialization helpers.

Configurator< Port > &	ports ()
	Return an object for registering port classes and serialization helpers.

Configurator< Adaptor > &	adaptors ()
	Return an object for registering adaptor classes and serialization helpers.

void	setManagers (const smtk::common::Managers::Ptr &managers)
	Set/get the managers to use when serializing/deserializing. More...

smtk::common::Managers::Ptr	managers ()

void	clear ()
	Reset the helper's state. More...

void	currentTasks (std::vector< Task * > &tasks)
	Populate tasks with the set of current tasks.

void	currentPorts (std::vector< Port * > &ports)
	Populate ports with the set of current ports.

void	currentAdaptors (std::vector< Adaptor * > &adaptors)
	Populate adaptors with the set of current adaptors.

json	swizzleDependencies (const Task::PassedDependencies &deps)
	Return a serialization of task-references that is consistent within the scope of serializing a set of tasks.

Task::PassedDependencies	unswizzleDependencies (const json &ids) const
	Return a deserialization of de-swizzled task-references.

bool	topLevel () const
	Returns true if the helper is for deserializing top-level or child tasks.

void	setAdaptorTaskIds (SwizzleId fromId, SwizzleId toId)
	Set/clear a pair of task IDs used when deserializing a single adaptor. More...

void	setAdaptorTaskIds (const smtk::common::UUID &fromId, const smtk::common::UUID &toId)

void	clearAdaptorTaskIds ()

std::pair< Task , Task >	getAdaptorTasks ()
	Get task-pointers based on the IDs set earlier.

void	setActiveSerializedTask (Task *task)
	Set the current helper's active task and all parents which shared the same task manager. More...

Task *	activeSerializedTask () const

smtk::resource::PersistentObject *	objectFromJSONSpec (const json &spec, smtk::string::Token objType="task")
	Return a pointer to a persistent object given a JSON spec. More...

template<typename T >
T *	objectFromJSONSpecAs (const json &spec, smtk::string::Token objType="task")

Static Public Member Functions
static Helper &	instance ()
	Return the helper "singleton". More...

static Helper &	pushInstance (smtk::task::Manager &taskManager, const smtk::common::Managers::Ptr &otherManagers)
	Push a new top-level helper instance on the local thread's stack. More...

static Helper &	pushInstance (smtk::task::Task *parent)
	Push a new (non-top-level) helper instance on the local thread's stack. More...

static void	popInstance ()
	Pop a helper instance off the local thread's stack.

static std::size_t	nestingDepth ()
	Return the nesting level (i.e., the number of helper instances in the stack). More...

Protected Member Functions
	Helper (Manager *)

Protected Attributes
Manager *	m_taskManager { nullptr }

Configurator< Task >	m_tasks

Configurator< Port >	m_ports

Configurator< Adaptor >	m_adaptors

Task *	m_activeSerializedTask { nullptr }

smtk::common::Managers::Ptr	m_managers

SwizzleId	m_adaptorFromId = ~static_cast<SwizzleId>(0)

SwizzleId	m_adaptorToId = ~static_cast<SwizzleId>(0)

smtk::common::UUID	m_adaptorFromUID

smtk::common::UUID	m_adaptorToUID

bool	m_topLevel { true }
	m_topLevel indicates whether pushInstance() (false) or instance() (true) was used to create this helper. More...

bool	m_mapUUIDs { false }
	m_mapUUIDs is true when deserializing worklet JSON. More...

Detailed Description

A helper for serializing task configurations.

This is needed in order to serialize dependencies among tasks which are stored as pointers that could, in theory, form a cycle.

Member Function Documentation

◆ clear()

void smtk::task::json::Helper::clear ( )

Reset the helper's state.

This should be called before beginning serialization or deserialization. Additionally, calling it after each of these tasks is recommended since it will free memory.

◆ instance()

Helper & smtk::task::json::Helper::instance ( )

static

Return the helper "singleton".

The object returned is a per-thread instance at the top of a stack that may be altered using the pushInstance() and popInstance() methods. This allows nested deserializers to each have their own context that appears to be globally available.

◆ nestingDepth()

std::size_t smtk::task::json::Helper::nestingDepth ( )

static

Return the nesting level (i.e., the number of helper instances in the stack).

The outermost helper will return 1 (assuming you have called instance() first).

◆ objectFromJSONSpec()

smtk::resource::PersistentObject * smtk::task::json::Helper::objectFromJSONSpec	(	const json &	spec,
		smtk::string::Token	objType = `"task"`
	)

Return a pointer to a persistent object given a JSON spec.

Because workflow designers may provide worklets whose objects (tasks/ports/adaptors) do not have UUIDs, we need a way for worklet state to reference these objects. We must also handle cases where UUIDs are provided. This method is used by deserialization code to fetch the relevant object given a variety of input JSON that uniquely specifies objects in different ways.

The spec may be:

a JSON array holding a pair of UUIDs: a resource UUID and a component UUID. If the resource UUID is null, the component UUID is assumed to belong to the current project.
a single integer: the swizzle ID of a task, port, or adaptor (as indicated by the optional objType argument.
a JSON array holding a string and an integer: the string indicates the type of component (one of "task", "port", or "adaptor") and the integer represents a swizzle ID.

◆ pushInstance() [1/2]

Helper & smtk::task::json::Helper::pushInstance	(	smtk::task::Manager &	taskManager,
		const smtk::common::Managers::Ptr &	otherManagers
	)

static

Push a new top-level helper instance on the local thread's stack.

The returned Helper will have:

The same managers as the previous (if any) helper.
The parent task is assigned the ID 0.

◆ pushInstance() [2/2]

Helper & smtk::task::json::Helper::pushInstance ( smtk::task::Task * parent )

static

Push a new (non-top-level) helper instance on the local thread's stack.

The returned Helper will have:

The same taskManager as the previous helper.
The same managers as the previous (if any) helper.
The parent task is assigned the ID 0.

◆ setActiveSerializedTask()

void smtk::task::json::Helper::setActiveSerializedTask ( Task * task )

Set the current helper's active task and all parents which shared the same task manager.

You may pass (or expect) a null task.

◆ setAdaptorTaskIds()

void smtk::task::json::Helper::setAdaptorTaskIds	(	SwizzleId	fromId,
		SwizzleId	toId
	)

Set/clear a pair of task IDs used when deserializing a single adaptor.

Storing these IDs as state in the helper allows from_json() to be "stateless" (i.e., taking no additional parameters and using the Helper as a side effect).

◆ setManagers()

void smtk::task::json::Helper::setManagers ( const smtk::common::Managers::Ptr & managers )

Set/get the managers to use when serializing/deserializing.

Call setManagers() with an instance of all your application's managers before attempting to serialize/deserialize as helpers are allowed to use managers as needed.

◆ setMapUUIDs()

void smtk::task::json::Helper::setMapUUIDs ( bool shouldMap )

Turn on/off mapping of JSON UUIDs to new, random UUIDs.

This is used by EmplaceWorklet. Do not call this after any tasks/ports/adaptors have been swizzled by any of this helper's configurators.

Member Data Documentation

◆ m_mapUUIDs

bool smtk::task::json::Helper::m_mapUUIDs { false }

protected

m_mapUUIDs is true when deserializing worklet JSON.

This causes all persistent objects in the JSON to have their UUIDs remapped.

◆ m_topLevel

bool smtk::task::json::Helper::m_topLevel { true }

protected

m_topLevel indicates whether pushInstance() (false) or instance() (true) was used to create this helper.

If m_topLevel is false, the parent task is assigned swizzle ID 1.

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

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

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Function Documentation

◆ clear()

◆ instance()

◆ nestingDepth()

◆ objectFromJSONSpec()

◆ pushInstance() [1/2]

◆ pushInstance() [2/2]

◆ setActiveSerializedTask()

◆ setAdaptorTaskIds()

◆ setManagers()

◆ setMapUUIDs()

Member Data Documentation

◆ m_mapUUIDs

◆ m_topLevel