#include <vtkMarshalContext.h>

Detailed Description

Shared context used by vtkSerializer and vtkDeserializer

This class is capable of tracking dependencies among VTK objects, their states and preventing recursion when the VTK serialization classes are used.

It also provides centralized storage and tracking of objects in a weak object map, recording ownership of objects using a strong object map, hashing the contents of blobs to minimize data redundancies in the state and finally an API to coordinate the registration and removal of states, objects and blobs.

Tests:: vtkMarshalContext (Tests)

Definition at line 40 of file vtkMarshalContext.h.

Inheritance diagram for vtkMarshalContext:

[legend]

Collaboration diagram for vtkMarshalContext:

[legend]

Classes
class	ScopedParentTracker
	Convenient to push a parent as the 'active' identifier and add children to that parent when (de)serializing sub-states or sub-objects. More...

Public Types
typedef vtkObject	Superclass

using	WeakObjectStore = std::map<vtkTypeUInt32, vtkWeakPointer<vtkObjectBase>>

using	StrongObjectStore = std::map<std::string, std::set<vtkSmartPointer<vtkObjectBase>>>

Public Member Functions
virtual vtkTypeBool	IsA (const char *type)
	Return 1 if this class is the same type of (or a subclass of) the named class.

vtkMarshalContext *	NewInstance () const

void	PrintSelf (ostream &os, vtkIndent indent) override
	Methods invoked by print to print information about the object including superclasses.

const nlohmann::json &	Blobs () const
	Get blobs.

const nlohmann::json &	States () const
	Get states.

const WeakObjectStore &	WeakObjects () const
	Get map of weak objects.

const StrongObjectStore &	StrongObjects () const
	Get map of strong objects.

void	KeepAlive (const std::string &owner, vtkObjectBase *objectBase)
	This method creates a record of ownership between `owner` and `objectBase`.

void	Retire (const std::string &owner, vtkObjectBase *objectBase)
	Release the strong reference kept by `owner` to the given `objectBase`.

bool	RegisterState (nlohmann::json state)
	Add a `state`.

bool	UnRegisterState (vtkTypeUInt32 identifier)
	Removes a `state`.

nlohmann::json &	GetState (vtkTypeUInt32 identifier) const
	Find and get the `state` registered at `identifier`.

bool	RegisterObject (vtkObjectBase *objectBase, vtkTypeUInt32 &identifier)
	Add an `objectBase` into the weak object store associated with `identifier`.

bool	UnRegisterObject (vtkTypeUInt32 identifier)
	Removes an `objectBase` registered at `identifier` from the weak object store.

vtkSmartPointer< vtkObjectBase >	GetObjectAtId (vtkTypeUInt32 identifier) const
	Find and get the `objectBase` registered at `identifier`.

vtkTypeUInt32	GetId (vtkObjectBase *objectBase) const
	Get the `identifier` associated with `objectBase`.

bool	RegisterBlob (vtkSmartPointer< vtkTypeUInt8Array > blob, std::string &hash)
	Add a `blob` into the blob store associated with `hash`.

bool	UnRegisterBlob (const std::string &hash)
	Removes a `blob` registered at `hash` from the blob store.

vtkSmartPointer< vtkTypeUInt8Array >	GetBlob (const std::string &hash, bool copy=true)
	Find and get the `blob` registered at `hash`.

std::vector< vtkTypeUInt32 >	GetDirectDependencies (vtkTypeUInt32 identifier) const
	Return all direct dependencies of the object/state registered at `identifier`.

void	ResetDirectDependencies ()
	Reset the dependency cache.

void	ResetDirectDependenciesForNode (vtkTypeUInt32 identifier)
	Reset the dependency cache for the given `identifier`

vtkTypeUInt32	MakeId ()
	Make a new `identifier`.

void	PushParent (vtkTypeUInt32 identifier)
	Make `identifier` the active identifier.

void	PopParent ()
	Adds the 'active' identifier into the genealogy.


void	SetAllocateIdsDescending (bool allocateIdsDescending)
	When enabled, `MakeId` hands out identifiers counting down from the maximum value of `vtkTypeUInt32` instead of counting up from 0.

bool	GetAllocateIdsDescending () const
	When enabled, `MakeId` hands out identifiers counting down from the maximum value of `vtkTypeUInt32` instead of counting up from 0.

Public Member Functions inherited from vtkObject
	vtkBaseTypeMacro (vtkObject, vtkObjectBase)

virtual void	DebugOn ()
	Turn debugging output on.

virtual void	DebugOff ()
	Turn debugging output off.

bool	GetDebug ()
	Get the value of the debug flag.

void	SetDebug (bool debugFlag)
	Set the value of the debug flag.

virtual void	Modified ()
	Update the modification time for this object.

virtual vtkMTimeType	GetMTime ()
	Return this object's modified time.

void	PrintSelf (ostream &os, vtkIndent indent) override
	Methods invoked by print to print information about the object including superclasses.

void	RemoveObserver (unsigned long tag)

void	RemoveObservers (unsigned long event)

void	RemoveObservers (const char *event)

void	RemoveAllObservers ()

vtkTypeBool	HasObserver (unsigned long event)

vtkTypeBool	HasObserver (const char *event)

vtkTypeBool	InvokeEvent (unsigned long event)

vtkTypeBool	InvokeEvent (const char *event)

std::string	GetObjectDescription () const override
	The object description printed in messages and PrintSelf output.

unsigned long	AddObserver (unsigned long event, vtkCommand *, float priority=0.0f)
	Allow people to add/remove/invoke observers (callbacks) to any VTK object.

unsigned long	AddObserver (const char event, vtkCommand , float priority=0.0f)
	Allow people to add/remove/invoke observers (callbacks) to any VTK object.

vtkCommand *	GetCommand (unsigned long tag)
	Allow people to add/remove/invoke observers (callbacks) to any VTK object.

void	RemoveObserver (vtkCommand *)
	Allow people to add/remove/invoke observers (callbacks) to any VTK object.

void	RemoveObservers (unsigned long event, vtkCommand *)
	Allow people to add/remove/invoke observers (callbacks) to any VTK object.

void	RemoveObservers (const char event, vtkCommand )
	Allow people to add/remove/invoke observers (callbacks) to any VTK object.

vtkTypeBool	HasObserver (unsigned long event, vtkCommand *)
	Allow people to add/remove/invoke observers (callbacks) to any VTK object.

vtkTypeBool	HasObserver (const char event, vtkCommand )
	Allow people to add/remove/invoke observers (callbacks) to any VTK object.

template<class U, class T>
unsigned long	AddObserver (unsigned long event, U observer, void(T::*callback)(), float priority=0.0f)
	Overloads to AddObserver that allow developers to add class member functions as callbacks for events.

template<class U, class T>
unsigned long	AddObserver (unsigned long event, U observer, void(T::callback)(vtkObject , unsigned long, void *), float priority=0.0f)
	Overloads to AddObserver that allow developers to add class member functions as callbacks for events.

template<class U, class T>
unsigned long	AddObserver (unsigned long event, U observer, bool(T::callback)(vtkObject , unsigned long, void *), float priority=0.0f)
	Allow user to set the AbortFlagOn() with the return value of the callback method.

vtkTypeBool	InvokeEvent (unsigned long event, void *callData)
	This method invokes an event and return whether the event was aborted or not.

vtkTypeBool	InvokeEvent (const char event, void callData)
	This method invokes an event and return whether the event was aborted or not.

virtual void	SetObjectName (const std::string &objectName)
	Set/get the name of this object for reporting purposes.

virtual std::string	GetObjectName () const
	Set/get the name of this object for reporting purposes.

Public Member Functions inherited from vtkObjectBase
const char *	GetClassName () const
	Return the class name as a string.

virtual vtkIdType	GetNumberOfGenerationsFromBase (const char *name)
	Given the name of a base class of this class type, return the distance of inheritance between this class type and the named class (how many generations of inheritance are there between this class and the named class).

virtual void	Delete ()
	Delete a VTK object.

virtual void	FastDelete ()
	Delete a reference to this object.

void	InitializeObjectBase ()

void	Print (ostream &os)
	Print an object to an ostream.

void	Register (vtkObjectBase *o)
	Increase the reference count (mark as used by another object).

virtual void	UnRegister (vtkObjectBase *o)
	Decrease the reference count (release by another object).

int	GetReferenceCount ()
	Return the current reference count of this object.

void	SetReferenceCount (int)
	Sets the reference count.

bool	GetIsInMemkind () const
	A local state flag that remembers whether this object lives in the normal or extended memory space.

virtual void	PrintHeader (ostream &os, vtkIndent indent)
	Methods invoked by print to print information about the object including superclasses.

virtual void	PrintTrailer (ostream &os, vtkIndent indent)
	Methods invoked by print to print information about the object including superclasses.

virtual bool	UsesGarbageCollector () const
	Indicate whether the class uses `vtkGarbageCollector` or not.

Static Public Member Functions
static vtkTypeBool	IsTypeOf (const char *type)

static vtkMarshalContext *	SafeDownCast (vtkObjectBase *o)

static vtkMarshalContext *	New ()

static void	AddRegistrar (vtkMarshalContextRegistrarFunc registrar)
	Add a serialization registrar to the static vector.

static bool	CallRegistrars (void ser, void deser, void invoker, const char *error)
	Call all registrars with the given arguments.

Static Public Member Functions inherited from vtkObject
static vtkObject *	New ()
	Create an object with Debug turned off, modified time initialized to zero, and reference counting on.

static void	BreakOnError ()
	This method is called when vtkErrorMacro executes.

static void	SetGlobalWarningDisplay (vtkTypeBool val)
	This is a global flag that controls whether any debug, warning or error messages are displayed.

static void	GlobalWarningDisplayOn ()
	This is a global flag that controls whether any debug, warning or error messages are displayed.

static void	GlobalWarningDisplayOff ()
	This is a global flag that controls whether any debug, warning or error messages are displayed.

static vtkTypeBool	GetGlobalWarningDisplay ()
	This is a global flag that controls whether any debug, warning or error messages are displayed.

Static Public Member Functions inherited from vtkObjectBase
static vtkTypeBool	IsTypeOf (const char *name)
	Return 1 if this class type is the same type of (or a subclass of) the named class.

static vtkIdType	GetNumberOfGenerationsFromBaseType (const char *name)
	Given a the name of a base class of this class type, return the distance of inheritance between this class type and the named class (how many generations of inheritance are there between this class and the named class).

static vtkObjectBase *	New ()
	Create an object with Debug turned off, modified time initialized to zero, and reference counting on.

static void	SetMemkindDirectory (const char *directoryname)
	The name of a directory, ideally mounted -o dax, to memory map an extended memory space within.

static bool	GetUsingMemkind ()
	A global state flag that controls whether vtkObjects are constructed in the usual way (the default) or within the extended memory space.

Protected Member Functions
virtual vtkObjectBase *	NewInstanceInternal () const

	vtkMarshalContext ()

	~vtkMarshalContext () override

bool	HasId (vtkObjectBase *objectBase, vtkTypeUInt32 &identifier)
	Return `true` if `objectBase` exists in the weak object store, `false` otherwise If the `objectBase` exists, it's id will be stored in `identifier`.

bool	IsProcessing (vtkTypeUInt32 identifier)
	Return `true` if `identifier` has been through `PushParent`, but not yet been through `PopParent`, false otherwise.

bool	IsProcessed (vtkTypeUInt32 identifier)
	Returns`true` if `identifier` exists in the genealogy of object(s)/state(s), false otherwise.

void	AddChild (vtkTypeUInt32 identifier)
	Records `identifier` in the list of children of the 'active' identifier.

Protected Member Functions inherited from vtkObject
	vtkObject ()

	~vtkObject () override

void	RegisterInternal (vtkObjectBase *, vtkTypeBool check) override

void	UnRegisterInternal (vtkObjectBase *, vtkTypeBool check) override

void	InternalGrabFocus (vtkCommand mouseEvents, vtkCommand keypressEvents=nullptr)
	These methods allow a command to exclusively grab all events.

void	InternalReleaseFocus ()
	These methods allow a command to exclusively grab all events.

Protected Member Functions inherited from vtkObjectBase
	vtkObjectBase ()

virtual	~vtkObjectBase ()

virtual void	ReportReferences (vtkGarbageCollector *)

	vtkObjectBase (const vtkObjectBase &)

void	operator= (const vtkObjectBase &)

Friends
class	vtkDeserializer

class	vtkSerializer

Additional Inherited Members
Static Protected Member Functions inherited from vtkObjectBase
static vtkMallocingFunction	GetCurrentMallocFunction ()

static vtkReallocingFunction	GetCurrentReallocFunction ()

static vtkFreeingFunction	GetCurrentFreeFunction ()

static vtkFreeingFunction	GetAlternateFreeFunction ()

Protected Attributes inherited from vtkObject
bool	Debug

vtkTimeStamp	MTime

vtkSubjectHelper *	SubjectHelper

std::string	ObjectName

Protected Attributes inherited from vtkObjectBase
std::atomic< int32_t >	ReferenceCount

vtkWeakPointerBase **	WeakPointers

Member Typedef Documentation

◆ Superclass

typedef vtkObject vtkMarshalContext::Superclass

Definition at line 43 of file vtkMarshalContext.h.

◆ WeakObjectStore

using vtkMarshalContext::WeakObjectStore = std::map<vtkTypeUInt32, vtkWeakPointer<vtkObjectBase>>

Definition at line 47 of file vtkMarshalContext.h.

◆ StrongObjectStore

using vtkMarshalContext::StrongObjectStore = std::map<std::string, std::set<vtkSmartPointer<vtkObjectBase>>>

Definition at line 48 of file vtkMarshalContext.h.

Constructor & Destructor Documentation

◆ vtkMarshalContext()

vtkMarshalContext::vtkMarshalContext ( )

protected

◆ ~vtkMarshalContext()

vtkMarshalContext::~vtkMarshalContext ( )

overrideprotected

Member Function Documentation

◆ IsTypeOf()

static vtkTypeBool vtkMarshalContext::IsTypeOf ( const char * type )

static

◆ IsA()

virtual vtkTypeBool vtkMarshalContext::IsA ( const char * name )

virtual

Return 1 if this class is the same type of (or a subclass of) the named class.

Returns 0 otherwise. This method works in combination with vtkTypeMacro found in vtkSetGet.h.

Reimplemented from vtkObjectBase.

◆ SafeDownCast()

static vtkMarshalContext * vtkMarshalContext::SafeDownCast ( vtkObjectBase * o )

static

◆ NewInstanceInternal()

virtual vtkObjectBase * vtkMarshalContext::NewInstanceInternal ( ) const

protectedvirtual

◆ NewInstance()

vtkMarshalContext * vtkMarshalContext::NewInstance ( ) const

◆ New()

static vtkMarshalContext * vtkMarshalContext::New ( )

static

◆ PrintSelf()

void vtkMarshalContext::PrintSelf	(	ostream &	os,
		vtkIndent	indent )

overridevirtual

Methods invoked by print to print information about the object including superclasses.

Typically not called by the user (use Print() instead) but used in the hierarchical print process to combine the output of several classes.

Reimplemented from vtkObjectBase.

◆ AddRegistrar()

static void vtkMarshalContext::AddRegistrar ( vtkMarshalContextRegistrarFunc registrar )

static

Add a serialization registrar to the static vector.

◆ CallRegistrars()

static bool vtkMarshalContext::CallRegistrars	(	void *	ser,
		void *	deser,
		void *	invoker,
		const char **	error )

static

Call all registrars with the given arguments.

◆ Blobs()

const nlohmann::json & vtkMarshalContext::Blobs ( ) const

Get blobs.

◆ States()

const nlohmann::json & vtkMarshalContext::States ( ) const

Get states.

◆ WeakObjects()

const WeakObjectStore & vtkMarshalContext::WeakObjects ( ) const

Get map of weak objects.

◆ StrongObjects()

const StrongObjectStore & vtkMarshalContext::StrongObjects ( ) const

Get map of strong objects.

◆ KeepAlive()

void vtkMarshalContext::KeepAlive	(	const std::string &	owner,
		vtkObjectBase *	objectBase )

This method creates a record of ownership between owner and objectBase.

◆ Retire()

void vtkMarshalContext::Retire	(	const std::string &	owner,
		vtkObjectBase *	objectBase )

Release the strong reference kept by owner to the given objectBase.

This method does nothing if the records show that owner doesn't own objectBase.

◆ RegisterState()

bool vtkMarshalContext::RegisterState ( nlohmann::json state )

Add a state.

Returns true if the state was registered, false otherwise.

Note: The state is successfully registered only if a key named "Id" exists in state and it's value is an unsigned integer.

◆ UnRegisterState()

bool vtkMarshalContext::UnRegisterState ( vtkTypeUInt32 identifier )

Removes a state.

Returns true if a state exists at identifier and it was removed, false otherwise.

◆ GetState()

nlohmann::json & vtkMarshalContext::GetState ( vtkTypeUInt32 identifier ) const

Find and get the state registered at identifier.

Returns an empty json object if there is no state registered at identifier.

◆ RegisterObject()

bool vtkMarshalContext::RegisterObject	(	vtkObjectBase *	objectBase,
		vtkTypeUInt32 &	identifier )

Add an objectBase into the weak object store associated with identifier.

If identifier is 0, a new identifier will be created. Returns true if the objectBase was registered, false otherwise.

Note: The objectBase is successfully registered only if it is non-null.

◆ UnRegisterObject()

bool vtkMarshalContext::UnRegisterObject ( vtkTypeUInt32 identifier )

Removes an objectBase registered at identifier from the weak object store.

Returns true if a objectBase exists at identifier and it was removed, false otherwise.

◆ GetObjectAtId()

vtkSmartPointer< vtkObjectBase > vtkMarshalContext::GetObjectAtId ( vtkTypeUInt32 identifier ) const

Find and get the objectBase registered at identifier.

◆ GetId()

vtkTypeUInt32 vtkMarshalContext::GetId ( vtkObjectBase * objectBase ) const

Get the identifier associated with objectBase.

◆ RegisterBlob()

bool vtkMarshalContext::RegisterBlob	(	vtkSmartPointer< vtkTypeUInt8Array >	blob,
		std::string &	hash )

Add a blob into the blob store associated with hash.

If hash is an empty string, the contents of blob will be hashed and the result of the hashing algorithm stored in hash. Returns true if the blob was registered, false otherwise.

Note: The blob is successfully registered only if it is non-null. This method accepts empty blobs.

◆ UnRegisterBlob()

bool vtkMarshalContext::UnRegisterBlob ( const std::string & hash )

Removes a blob registered at hash from the blob store.

Returns true if a blob exists at hash and it was removed, false otherwise.

◆ GetBlob()

vtkSmartPointer< vtkTypeUInt8Array > vtkMarshalContext::GetBlob	(	const std::string &	hash,
		bool	copy = true )

Find and get the blob registered at hash.

If copy is true (the default), a copy of the blob is returned and the caller owns it independently of this context. If copy is false, the returned array aliases the context-owned buffer via vtkTypeUInt8Array::SetArray with the save flag set to 1; it does not take ownership. The caller must stop using the returned array once the blob is unregistered, this context is destroyed, or Blobs is otherwise mutated, any of which leaves the array dangling.

◆ GetDirectDependencies()

std::vector< vtkTypeUInt32 > vtkMarshalContext::GetDirectDependencies ( vtkTypeUInt32 identifier ) const

Return all direct dependencies of the object/state registered at identifier.

Note: This method doesn't compute the dependencies on demand. Instead it relies upon the vtkSerializer/vtkDeserializer correctly using the ScopedParentTracker API to record the genealogy of object(s)/state(s) serialized/deserialized.

Technically, it's not a strict genealogy as it is possible to have circular dependencies.

◆ ResetDirectDependencies()

void vtkMarshalContext::ResetDirectDependencies ( )

Reset the dependency cache.

◆ ResetDirectDependenciesForNode()

void vtkMarshalContext::ResetDirectDependenciesForNode ( vtkTypeUInt32 identifier )

Reset the dependency cache for the given identifier

◆ MakeId()

vtkTypeUInt32 vtkMarshalContext::MakeId ( )

Make a new identifier.

◆ SetAllocateIdsDescending()

void vtkMarshalContext::SetAllocateIdsDescending ( bool allocateIdsDescending )

When enabled, MakeId hands out identifiers counting down from the maximum value of vtkTypeUInt32 instead of counting up from 0.

A mirror context (e.g. a WebAssembly remote session that deserializes states produced by a server-side context) must not allocate identifiers from the same range as its remote counterpart. Otherwise, locally registered objects would occupy identifiers the remote context hands out later for new objects, and incoming states would then be applied to unrelated local objects. Default is off.

◆ GetAllocateIdsDescending()

bool vtkMarshalContext::GetAllocateIdsDescending ( ) const

When enabled, MakeId hands out identifiers counting down from the maximum value of vtkTypeUInt32 instead of counting up from 0.

A mirror context (e.g. a WebAssembly remote session that deserializes states produced by a server-side context) must not allocate identifiers from the same range as its remote counterpart. Otherwise, locally registered objects would occupy identifiers the remote context hands out later for new objects, and incoming states would then be applied to unrelated local objects. Default is off.

◆ PushParent()

void vtkMarshalContext::PushParent ( vtkTypeUInt32 identifier )

Make identifier the active identifier.

All subsequent AddChild(child) will add child into the list of children for identifier until PopParent gets invoked.

◆ PopParent()

void vtkMarshalContext::PopParent ( )

Adds the 'active' identifier into the genealogy.

It's children are populated using the recorded children of the 'active' identifier using AddChild The active parent is reset to the previous identifier.

◆ HasId()

bool vtkMarshalContext::HasId	(	vtkObjectBase *	objectBase,
		vtkTypeUInt32 &	identifier )

protected

Return true if objectBase exists in the weak object store, false otherwise If the objectBase exists, it's id will be stored in identifier.

Note: This is just a convenient method that wraps around GetId.

◆ IsProcessing()

bool vtkMarshalContext::IsProcessing ( vtkTypeUInt32 identifier )

protected

Return true if identifier has been through PushParent, but not yet been through PopParent, false otherwise.

◆ IsProcessed()

bool vtkMarshalContext::IsProcessed ( vtkTypeUInt32 identifier )

protected

Returnstrue if identifier exists in the genealogy of object(s)/state(s), false otherwise.

◆ AddChild()

void vtkMarshalContext::AddChild ( vtkTypeUInt32 identifier )

protected

Records identifier in the list of children of the 'active' identifier.

Note

This parent-child relationship is not committed into the genealogy until PopParent is invoked.
This method does nothing if there is no 'active' identifier, i.e, when PushParent(identifier) was never called.

Friends And Related Symbol Documentation

◆ vtkDeserializer

friend class vtkDeserializer

friend

Definition at line 309 of file vtkMarshalContext.h.

◆ vtkSerializer

friend class vtkSerializer

friend

Definition at line 310 of file vtkMarshalContext.h.

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

Common/Core/vtkMarshalContext.h

Detailed Description

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Additional Inherited Members

Member Typedef Documentation

◆ Superclass

◆ WeakObjectStore

◆ StrongObjectStore

Constructor & Destructor Documentation

◆ vtkMarshalContext()

◆ ~vtkMarshalContext()

Member Function Documentation

◆ IsTypeOf()

◆ IsA()

◆ SafeDownCast()

◆ NewInstanceInternal()

◆ NewInstance()

◆ New()

◆ PrintSelf()

◆ AddRegistrar()

◆ CallRegistrars()

◆ Blobs()

◆ States()

◆ WeakObjects()

◆ StrongObjects()

◆ KeepAlive()

◆ Retire()

◆ RegisterState()

◆ UnRegisterState()

◆ GetState()

◆ RegisterObject()

◆ UnRegisterObject()

◆ GetObjectAtId()

◆ GetId()

◆ RegisterBlob()

◆ UnRegisterBlob()

◆ GetBlob()

◆ GetDirectDependencies()

◆ ResetDirectDependencies()

◆ ResetDirectDependenciesForNode()

◆ MakeId()

◆ SetAllocateIdsDescending()

◆ GetAllocateIdsDescending()

◆ PushParent()

◆ PopParent()

◆ HasId()

◆ IsProcessing()

◆ IsProcessed()

◆ AddChild()

Friends And Related Symbol Documentation

◆ vtkDeserializer

◆ vtkSerializer