AccessedObjectsCallback Class Reference

#include <c4d_accessedobjects.h>

Detailed Description

An AccessedObjectsCallback is passed to BaseList2D::GetAccessedObjects so that an implementation of BaseList2D can tell which data it will access within methods like ModifyObject or GetVirtualObjects. This is used to parallelize the execution of those methods as much as possible.

Public Member Functions
MAXON_METHOD maxon::Result< maxon::GenericData >	IgnoreWrite (const BaseObject *obj, Bool withChildren)
MAXON_METHOD maxon::Result< Bool >	MayAccess2 (const BaseList2D *object, ACCESSED_OBJECTS_MASK readMask, ACCESSED_OBJECTS_MASK writeMask)
MAXON_METHOD GET_ACCESSED_OBJECTS_FLAGS	AddFlags (GET_ACCESSED_OBJECTS_FLAGS newFlags)
MAXON_METHOD void	RestoreFlags (GET_ACCESSED_OBJECTS_FLAGS prevFlags)
MAXON_METHOD Bool	TestFlags (GET_ACCESSED_OBJECTS_FLAGS mask) const
MAXON_METHOD maxon::Result< Bool >	MarkVisited (const BaseList2D *object)
MAXON_METHOD Bool	IsReadable (const BaseList2D *object, ACCESSED_OBJECTS_MASK readMask)
MAXON_METHOD maxon::Result< void >	EnsureReadable (const BaseList2D *object, ACCESSED_OBJECTS_MASK readMask)
MAXON_METHOD maxon::Result< Bool >	MayAccessDeprecated (const BaseList2D *object, ACCESSED_OBJECTS_MASK readMask, ACCESSED_OBJECTS_MASK writeMask)
MAXON_METHOD maxon::Result< Bool >	MayAccessAnything ()
MAXON_METHOD const BaseDocument *	GetDocument ()
MAXON_METHOD BUILDFLAGS	GetBuildFlags ()

Private Member Functions
	MAXON_INTERFACE_SIMPLE_VIRTUAL (AccessedObjectsCallback, MAXON_REFERENCE_NONE)

Member Function Documentation

MAXON_INTERFACE_SIMPLE_VIRTUAL()

MAXON_INTERFACE_SIMPLE_VIRTUAL ( AccessedObjectsCallback  , MAXON_REFERENCE_NONE    )

private

IgnoreWrite()

MAXON_METHOD maxon::Result<maxon::GenericData> IgnoreWrite	(	const BaseObject *	obj,
		Bool	withChildren
	)

Informs this AccessedObjectsCallback to ignore any writes to obj (and its nested objects if withChildren is set) in subsequent calls to MayAccess2 as long as the returned GenericData is alive. For example, this can be used for generators which clone other objects and then call GetVirtualObjects on them: Any write made by GetVirtualObjects on the cloned objects won't affect their originals. But the generator has to call GetAccessedObjects on the original objects because the clones don't exist yet, and this may report that there will be writes to those objects. With a surrounding IgnoreWrite, this can be avoided. The instance object makes use of this with the following code (where #found is the linked object):

{
  auto ignore = access.IgnoreWrite(found, true) iferr_return;
  return found->GetAccessedObjectsOfHierarchy(ACCESSED_OBJECTS_MASK::ALL, ACCESSED_OBJECTS_MASK::NONE, METHOD_ID::GET_VIRTUAL_OBJECTS_AND_MODIFY_OBJECT, access);
}

Parameters

[in]	obj	The object for which subsequent reports about write access shall be ignored.
[in]	withChildren	True if writes to (nested) children of the object shall be ignored as well, false otherwise.

Returns

The duration of the ignore order is controlled by the lifetime of the returned object.

MayAccess2()

MAXON_METHOD maxon::Result<Bool> MayAccess2	(	const BaseList2D *	object,
		ACCESSED_OBJECTS_MASK	readMask,
		ACCESSED_OBJECTS_MASK	writeMask
	)

Tells the callback that the current method may access object's data corresponding to readMask and writeMask. MayAccess2 is called in implementations of BaseList2D::GetAccessedObjects. A simple implementation for a generator could look like this:

class MyObject : public ObjectData
{
  INSTANCE(MyObject, ObjectData)
public:
  ...
  Result<Bool> GetAccessedObjects(const BaseList2D* node, METHOD_ID method, AccessedObjectsCallback& access) const override
  {
    switch (method)
    {
      case METHOD_ID::GET_VIRTUAL_OBJECTS:
      {
        return access.MayAccess2(node, ACCESSED_OBJECTS_MASK::DATA | ACCESSED_OBJECTS_MASK::ANY_TAG, ACCESSED_OBJECTS_MASK::CACHE);
      }
    }
    return SUPER::GetAccessedObjects(node, method, access);
  }
};

So when the object's GetVirtualObjects method is called, this may read from the BaseContainer and also from any tag, and it may write to the cache (namely, it writes the generated virtual object). If GetVirtualObjects reads from further objects (e.g., children or linked objects), this has to be matched by additional calls to MayAccess2.

If your implementation depends on the current time, you have to set the ACCESSED_OBJECTS_MASK::TIME flag in readMask for at least one of the calls to MayAccess2. If there's no dependency on any object, you can make a call to MayAccess2 with nullptr for the object parameter. Similarly, set ACCESSED_OBJECTS_MASK::CAMERA for a dependency on camera or ACCESSED_OBJECTS_MASK::EXTERNAL for a dependency on any other external state which isn't part of the object hierarchy. Dependencies on LOD level don't have to be taken into account.

Parameters

[in]	object	An object which the current method will access during execution.
[in]	readMask	The data identified by readMask will be read from object. In addition, you have to set the flags CAMERA, TIME or EXTERNAL if current camera, time or some external state like document settings are read.
[in]	writeMask	The data identified by writeMask will be written to object. This also allows to read the data.

Returns

If this returns false, the callback isn't interested in further calls to MayAccess2 and you can do an early exit.

AddFlags()

MAXON_METHOD GET_ACCESSED_OBJECTS_FLAGS AddFlags

(

GET_ACCESSED_OBJECTS_FLAGS

newFlags

)

RestoreFlags()

MAXON_METHOD void RestoreFlags

(

GET_ACCESSED_OBJECTS_FLAGS

prevFlags

)

TestFlags()

MAXON_METHOD Bool TestFlags

(

GET_ACCESSED_OBJECTS_FLAGS

mask

)

const

MarkVisited()

MAXON_METHOD maxon::Result<Bool> MarkVisited

(

const BaseList2D *

object

)

Marks object as visited to prevent endless recursion in implementations of BaseList2D::GetAccessedObjects.

Parameters

[in]

object

An object for which GetAccessedObjects is called.

Returns

True if the object hasn't been marked as visited before by a prior call to MarkVisited, false otherwise.

IsReadable()

MAXON_METHOD Bool IsReadable	(	const BaseList2D *	object,
		ACCESSED_OBJECTS_MASK	readMask
	)

Checks if the data corresponding to readMask is already readable from object. That's the case unless there's a pending job which will write to that data.

Parameters

[in]	object	An object.
[in]	readMask	The data mask for which readability shall be checked.

Returns

True if the data is readable, false otherwise.

EnsureReadable()

MAXON_METHOD maxon::Result<void> EnsureReadable	(	const BaseList2D *	object,
		ACCESSED_OBJECTS_MASK	readMask
	)

Waits if necessary until the data corresponding to readMask is readable from object. This method will wait as long as there are pending jobs which will write to that data.

Parameters

[in]	object	An object.
[in]	readMask	The data mask for which readability shall be checked.

MayAccessDeprecated()

MAXON_METHOD maxon::Result<Bool> MayAccessDeprecated	(	const BaseList2D *	object,
		ACCESSED_OBJECTS_MASK	readMask,
		ACCESSED_OBJECTS_MASK	writeMask
	)

This method is deprecated. Use MayAccess2 instead and make sure to pass the CAMERA, TIME or EXTERNAL flags of ACCESSED_OBJECTS_MASK to readMask if your implementation accesses camera, current time or something else outside of the object hierarchy.

Parameters

[in]	object	An object which the current method will access during execution.
[in]	readMask	The data identified by readMask will be read from object.
[in]	writeMask	The data identified by writeMask will be written to object. This also allows to read the data.

Returns

If this returns false, the callback isn't interested in further calls to MayAccessDeprecated and you can do an early exit.

MayAccessAnything()

MAXON_METHOD maxon::Result<Bool> MayAccessAnything

(

)

Tells the callback that the current method may access anything from the current document. You have to use this instead of MayAccess2 if it's unknown or too complex what the current method will actually do.

The default behaviour of BaseList2D::GetAccessedObjects is to call MayAccessAnything.

Returns

If this returns false, the callback isn't interested in further calls to MayAccess2 and you can do an early exit.

GetDocument()

MAXON_METHOD const BaseDocument* GetDocument

(

)

Returns the current document.

Returns

Current document.

GetBuildFlags()

MAXON_METHOD BUILDFLAGS GetBuildFlags

(

)

Returns the current build flags.

Returns

Current build flags. @MAXON_ANNOTATION{default=BUILDFLAGS(0)}