A transaction provides a consistent view on the database. More...

#include <dice.h>

Inheritance diagram for mi::neuraylib::IDice_transaction:

Public Member Functions
virtual Sint32	commit ()=0
	Commits the transaction. More...

virtual void	abort ()=0
	Aborts the transaction. More...

virtual bool	is_open ()=0
	Indicates whether the transaction is open. More...

virtual Tag_struct	store (IElement element, Tag_struct tag=NULL_TAG, const char name=nullptr, Privacy_level privacy_level=LOCAL_SCOPE)=0
	Stores a new database element in the database. More...

virtual Tag_struct	store (IJob job, Tag_struct tag=NULL_TAG, const char name=nullptr, Privacy_level privacy_level=LOCAL_SCOPE)=0
	Stores a new database job in the database. More...

virtual Tag_struct	store_for_reference_counting (IElement element, Tag_struct tag=NULL_TAG, const char name=nullptr, Privacy_level privacy_level=LOCAL_SCOPE)=0
	Stores a new database element in the database (for reference counting). More...

virtual Tag_struct	store_for_reference_counting (IJob job, Tag_struct tag=NULL_TAG, const char name=nullptr, Privacy_level privacy_level=LOCAL_SCOPE)=0
	Stores a new database job in the database (for reference counting). More...

virtual const base::IInterface *	access (Tag_struct tag)=0
	Retrieves an element from the database. More...

template<class T>
const T *	access (Tag_struct tag)
	Retrieves an element from the database. More...

virtual base::IInterface *	edit (Tag_struct tag)=0
	Retrieves an element from the database and returns it ready for editing. More...

template<class T>
T *	edit (Tag_struct tag)
	Retrieves an element from the database and returns it ready for editing. More...

virtual Sint32	localize (Tag_struct tag, Privacy_level privacy_level)=0
	Localizes a tag to the given privacy level. More...

virtual Sint32	remove (Tag_struct tag, bool only_localized=false)=0
	Marks a tag for removal from the database. More...

virtual const char *	get_time_stamp () const =0
	Returns the time stamp describing the current "time". More...

virtual const char *	get_time_stamp (Tag_struct tag) const =0
	Returns the time stamp of the last change of a database element. More...

virtual bool	has_changed_since_time_stamp (Tag_struct tag, const char *time_stamp) const =0
	Checks whether an element has been stored or changed in the database since a given time stamp. More...

virtual const ITag_set *	get_changed_elements_since_time_stamp (const char *time_stamp) const =0
	Returns all elements (of type mi::neuraylib::IElement) that have been stored or changed in the database since a given time stamp. More...

virtual const char *	get_id () const =0
	Returns the ID of this transaction. More...

virtual IScope *	get_scope () const =0
	Returns the scope of this transaction. More...

virtual Sint32	get_privacy_level (Tag_struct tag) const =0
	Returns the privacy level of the element with a given tag. More...

virtual void	advise (Tag_struct tag)=0
	Advises the database that a given tag is required soon. More...

virtual Tag_struct	reserve_tag ()=0
	Reserves a tag. More...

virtual const char *	tag_to_name (Tag_struct tag)=0
	Returns the name associated with a tag in the database. More...

virtual Tag_struct	name_to_tag (const char *name)=0
	Returns the tag associated with a name in the database. More...

virtual Sint32	execute_fragmented (IFragmented_job *job, Size count)=0
	Executes a fragmented job synchronously. More...

virtual Sint32	execute_fragmented_async (IFragmented_job job, Size count, IExecution_listener listener)=0
	Executes a fragmented job asynchronously. More...

virtual void	invalidate_job_results (Tag_struct tag)=0
	Invalidates the results of a database job. More...

Public Member Functions inherited from mi::base::IInterface
virtual Uint32	retain () const =0
	Increments the reference count. More...

virtual Uint32	release () const =0
	Decrements the reference count. More...

virtual const IInterface *	get_interface (const Uuid &interface_id) const =0
	Acquires a const interface from another. More...

template<class T>
const T *	get_interface () const
	Acquires a const interface from another. More...

virtual IInterface *	get_interface (const Uuid &interface_id)=0
	Acquires a mutable interface from another. More...

template<class T>
T *	get_interface ()
	Acquires a mutable interface from another. More...

virtual Uuid	get_iid () const =0
	Returns the interface ID of the most derived interface. More...

Static Public Attributes
static const mi::Uint8	LOCAL_SCOPE = 255
	Symbolic privacy level for the privacy level of the scope of this transaction. More...

Additional Inherited Members
Public Types inherited from mi::base::Interface_declare< 0x1885cbec, ... >
using	Self = Interface_declare< id1, ... >
	Own type. More...

using	IID = Uuid_t< id1, ... >
	Declares the interface ID (IID) of this interface. More...

Public Types inherited from mi::base::IInterface
using	IID = Uuid_t<0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0>
	Declares the interface ID (IID) of this interface. More...

Static Public Member Functions inherited from mi::base::Interface_declare< 0x1885cbec, ... >
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface and of its ancestors. More...

Static Public Member Functions inherited from mi::base::IInterface
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface. More...

Detailed Description

A transaction provides a consistent view on the database.

This view on the database is isolated from changes by other (parallel) transactions. Eventually, each transaction must be either committed or aborted, i.e., all changes become either atomically visible to transactions started afterwards, or not at all.

Transactions are associated with a scope of the database and can be created with mi::neuraylib::IScope::create_transaction<mi::neuraylib::IDice_transaction>().

Concurrent accesses to database elements within a transaction

Access to database elements is provided by access() (read-only) and edit() (for modification). The interface pointers returned by these methods must be released when you are done, in particular before the transaction is committed or aborted. Releasing the last interface pointer obtained from edit() makes the changes also visible to later edit() calls for the same database element.

Note that it is possible to access the same database element concurrently in the same transaction. Concurrently means that the interface pointer obtained from an earlier access() or edit() call has not yet been released and the same database element is accessed once more using access() or edit(). It is advisable to avoid such concurrent accesses since it can easily lead to difficult to understand effects. The semantics are as follows:

multiple access() calls: Since all obtained interface pointers are const there is no way to modify the database elements.
access() call after edit() calls: This use case is not supported.
edit() call after access() calls: The changes done to the interface pointer returned from edit() are not observable through any interface pointer returned from the access() calls.
multiple edit() calls: The changes done to the individual interface pointers are not observable through the other interface pointers. The changes from the interface pointer from the last edit() call survive, independent of the order in which the pointers are released.

Concurrent transactions

If the same database element is edited in multiple overlapping transactions, the changes from the transaction created last survive, independent of the order in which the transactions are committed. If needed, the lifetime of transactions can be serialized across hosts (see mi::neuraylib::IDatabase::lock() for details).

Member Function Documentation

^◆ abort()

virtual void mi::neuraylib::IDice_transaction::abort ( )

pure virtual

Aborts the transaction.

Note that an abort() implicitly closes the transaction. A closed transaction does not allow any future operations and needs to be released.

^◆ access() [1/2]

template<class T>

const T * mi::neuraylib::IDice_transaction::access ( Tag_struct tag )

inline

Retrieves an element from the database.

The database searches for the most recent version of the named database element visible for the current transaction. That version will be returned.

If the tag identifies a database job the database ensures that the job has been executed and returns the result of the job.

This templated member function is a wrapper of the non-template variant for the user's convenience. It eliminates the need to call mi::base::IInterface::get_interface(const base::Uuid&) on the returned pointer, since the return type already is a const handle of the type T specified as template parameter.

Parameters

tag	The tag that identifies the requested database element.

Template Parameters

T	The interface type of the element to retrieve.

Returns: The requested element in the database, or nullptr if the transaction is already closed, or the element is not of type T.

^◆ access() [2/2]

virtual const base::IInterface * mi::neuraylib::IDice_transaction::access ( Tag_struct tag )

pure virtual

Retrieves an element from the database.

The database searches for the most recent version of the named database element visible for the current transaction. That version will be returned.

If the tag identifies a database job the database ensures that the job has been executed and returns the result of the job.

Parameters

tag	The tag that identifies the requested database element.

Returns: The requested element in the database, or nullptr if the transaction is already closed.

^◆ advise()

virtual void mi::neuraylib::IDice_transaction::advise ( Tag_struct tag )

pure virtual

Advises the database that a given tag is required soon.

If tag identifies a database job its execution will be triggered. If tag identifies a plain database element then fetching the data from other hosts or reading from disk will be triggered (if necessary).

In both cases the method does not block, but returns immediately, only later accesses via access() or edit() might block. Thus, this method can be used, for instance, to trigger parallel execution of jobs.

^◆ commit()

virtual Sint32 mi::neuraylib::IDice_transaction::commit ( )

pure virtual

Commits the transaction.

Note that a commit() implicitly closes the transaction. A closed transaction does not allow any future operations and needs to be released.

Returns

0: Success.
-1: Unspecified failure.
-3: The transaction is not open.

^◆ edit() [1/2]

template<class T>

T * mi::neuraylib::IDice_transaction::edit ( Tag_struct tag )

inline

Retrieves an element from the database and returns it ready for editing.

The database searches for the most recent version of the named database element visible for the current transaction. The database creates a local copy which is used in this transaction (and replaces the old version when the transaction is committed).

Note that database jobs including their resulting database elements cannot be edited.

This templated member function is a wrapper of the non-template variant for the user's convenience. It eliminates the need to call mi::base::IInterface::get_interface(const base::Uuid&) on the returned pointer, since the return type already is a const handle of the type T specified as template parameter.

Parameters

tag	The tag that identifies the requested database element.

Template Parameters

T	The interface type of the element to retrieve.

Returns: The requested element in the database, or nullptr if the transaction is already closed, or the element is not of type T.

^◆ edit() [2/2]

virtual base::IInterface * mi::neuraylib::IDice_transaction::edit ( Tag_struct tag )

pure virtual

Retrieves an element from the database and returns it ready for editing.

The database searches for the most recent version of the named database element visible for the current transaction. The database creates a local copy which is used in this transaction (and replaces the old version when the transaction is committed).

Note that database jobs including their resulting database elements cannot be edited.

Parameters

tag	The tag that identifies the requested database element.

Returns: The requested element in the database, or nullptr if the transaction is already closed.

^◆ execute_fragmented()

virtual Sint32 mi::neuraylib::IDice_transaction::execute_fragmented	(	IFragmented_job *	job,
		Size	count
	)

pure virtual

Executes a fragmented job synchronously.

The fragmented job is conceptually split into count fragments. Each fragment is executed exactly once in the cluster environment, either locally or remotely. The method returns when all fragments have been executed.

The fragments are executed independently by any number of threads and possibly on any number of hosts in parallel (see mi::neuraylib::IFragmented_job::get_scheduling_mode()). The number of fragments does not imply any specific parallel execution scheme. In principle, the DiCE job scheduling system may execute all fragments in parallel at the same time or all in serial order one after the other or anything in between. It is only guaranteed that each fragment is executed exactly once.

Parameters

job The fragmented job to be executed. All fragments executed on the initiating host operate on the given instance of the fragmented job. The fragments executed on different hosts in the cluster operate on a replicas of the given instance. The replicas result from serializing the instance given here and later restoring an instance of the same class by deserializing it on the remote host. That is, changes to the fragmented job instance applied during job execution never become visible during remote execution and, thus, should be avoided, unless these changes are intentional (results) or not relevant (host local caches).

count The number of fragments into which the job is split. This value needs to be greater than zero unless the scheduling mode is mi::neuraylib::IFragmented_job::ONCE_PER_HOST. In that case a value of zero means "as many fragments as remote hosts in the cluster".

Returns

0: Success.
-1: Invalid parameters (job is nullptr or count is zero but the scheduling mode is not mi::neuraylib::IFragmented_job::ONCE_PER_HOST).
-3: Invalid job priority (negative value).

See also: mi::neuraylib::IScheduler::execute_fragmented() for a variant without transaction

^◆ execute_fragmented_async()

virtual Sint32 mi::neuraylib::IDice_transaction::execute_fragmented_async	(	IFragmented_job *	job,
		Size	count,
		IExecution_listener *	listener
	)

pure virtual

Executes a fragmented job asynchronously.

This method is similar to execute_fragmented() except that the execution happens asynchronously. A callback is used to signal the completion of the job.

Note: Currently, this method is restricted to local jobs (see mi::neuraylib::IFragmented_job::get_scheduling_mode()).

Parameters

job	The fragmented job to be executed.
count	The number of fragments into which the job is split. This value needs to be greater than zero unless the scheduling mode is mi::neuraylib::IFragmented_job::ONCE_PER_HOST. In that case a value of zero means "as many fragments as remote hosts in the cluster".
listener	The `job_finished()` method of this callback is called when the job has been completed (might be `nullptr`).

Returns

0: Success.
-1: Invalid parameters (job is nullptr or count is zero).
-2: Invalid scheduling mode (asynchronous execution is restricted to local jobs).
-3: Invalid job priority (negative value).

See also: mi::neuraylib::IScheduler::execute_fragmented() for a variant without transaction

^◆ get_changed_elements_since_time_stamp()

virtual const ITag_set * mi::neuraylib::IDice_transaction::get_changed_elements_since_time_stamp ( const char * time_stamp ) const

pure virtual

Returns all elements (of type mi::neuraylib::IElement) that have been stored or changed in the database since a given time stamp.

Note: time_stamp should not stem from another concurrent transaction. Such changes will never be visible in this transaction, but the method might still return true depending on the start order of the two transactions.

See also: get_time_stamp(), get_time_stamp(mi::neuraylib::Tag_struct)const

Parameters

time_stamp The time stamp obtained from get_time_stamp() or get_time_stamp(mi::neuraylib::Tag_struct)const.

Returns: The set of elements that have been changed since the time stamp, or nullptr in case of failure, i.e., the time stamp is invalid or there have been too many changes since the given time stamp.

^◆ get_id()

virtual const char * mi::neuraylib::IDice_transaction::get_id ( ) const

pure virtual

Returns the ID of this transaction.

The transaction ID is of most use when debugging an application as the value returned allows one to correlate log messages and admin HTTP server output with the API actions.

Returns: The ID of the transaction.

^◆ get_privacy_level()

virtual Sint32 mi::neuraylib::IDice_transaction::get_privacy_level ( Tag_struct tag ) const

pure virtual

Returns the privacy level of the element with a given tag.

Parameters

tag	The tag of the element.

Returns

>= 0: Success. The privacy level of the element (in the range 0-255).
-3: The transaction is not open.

^◆ get_scope()

virtual IScope * mi::neuraylib::IDice_transaction::get_scope ( ) const

pure virtual

Returns the scope of this transaction.

^◆ get_time_stamp() [1/2]

virtual const char * mi::neuraylib::IDice_transaction::get_time_stamp ( ) const

pure virtual

Returns the time stamp describing the current "time".

Note: The time stamp is not related to time in the classical meaning. It rather relates to the current transaction and the number of database changes since the start of the transaction.; The time stamp is only meaningful for the current DiCE instance. It should not be put into external storage and re-used for different or later DiCE instances.; The return value of this method is only valid until the next call of this method (or one of its overloads) on this instance.

See also: has_changed_since_time_stamp(), get_time_stamp(mi::neuraylib::Tag_struct)const

^◆ get_time_stamp() [2/2]

virtual const char * mi::neuraylib::IDice_transaction::get_time_stamp ( Tag_struct tag ) const

pure virtual

Returns the time stamp of the last change of a database element.

Note: The time stamp is not related to time in the classical meaning. It rather relates to the transaction and the number of database changes since the start of the transaction when the database element was changed last.; The time stamp is only meaningful for the current DiCE instance. It should not be put into external storage and re-used for different or later DiCE instances.; The return value of this method is only valid until the next call of this method (or one of its overloads) on this instance.

See also: has_changed_since_time_stamp(), get_time_stamp()

^◆ has_changed_since_time_stamp()

virtual bool mi::neuraylib::IDice_transaction::has_changed_since_time_stamp	(	Tag_struct	tag,
		const char *	time_stamp
	)		const

pure virtual

Checks whether an element has been stored or changed in the database since a given time stamp.

Note: time_stamp should not stem from another concurrent transaction. Such changes will never be visible in this transaction, but the method might still return true depending on the start order of the two transactions.; In case of multiple overlapping transactions the returned answer may not list all changes due to the isolation of the transactions. If accurate results are required, transactions changing elements should be committed before transactions querying the journal for such changes are started.

See also: get_time_stamp(), get_time_stamp(mi::neuraylib::Tag_struct)const

Parameters

tag	The tag that identifies the database element.
time_stamp	The time stamp obtained from get_time_stamp() or get_time_stamp(mi::neuraylib::Tag_struct)const.

Returns: true if the element has been stored or changed since the time stamp (or if tag or time_stamp is invalid), false otherwise.

^◆ invalidate_job_results()

virtual void mi::neuraylib::IDice_transaction::invalidate_job_results ( Tag_struct tag )

pure virtual

Invalidates the results of a database job.

If the result of a database is invalidated the next access to that tag will trigger re-execution of the job. Re-execution of a database job might become necessary when database elements used as input for the job have changed.

Note: Non-shared database jobs (see mi::neuraylib::IJob::is_shared()) are automatically invalidated for each transaction, i.e., their results are not shared beyond multiple transactions.

^◆ is_open()

virtual bool mi::neuraylib::IDice_transaction::is_open ( )

pure virtual

Indicates whether the transaction is open.

The ability to check whether the transaction is still open is particularly important for advised jobs, which shall be able to abort their operation if their results become irrelevant to the database in the meantime.

Returns: true if the transaction is still open, or false if the transaction is closed, i.e., it has been committed or aborted.

^◆ localize()

virtual Sint32 mi::neuraylib::IDice_transaction::localize	(	Tag_struct	tag,
		Privacy_level	privacy_level
	)

pure virtual

Localizes a tag to the given privacy level.

Creates a copy of the identified database element and stores that copy in the given privacy level.

Parameters

tag	The tag that identifies the database element to be localized.
privacy_level	The desired privacy level of the copy (in the range from 0 to the privacy level of the scope of this transaction). In addition, the constant LOCAL_SCOPE can be used as a shortcut to indicate the privacy level of the scope of this transaction without supplying the actual value itself.

Returns

0: Success.
-2: Invalid parameters (tag is invalid).
-5: Invalid privacy level.

^◆ name_to_tag()

virtual Tag_struct mi::neuraylib::IDice_transaction::name_to_tag ( const char * name )

pure virtual

Returns the tag associated with a name in the database.

Note: A name can be associated with different tags in different scopes.

Returns: The tag (or one tag) associated with name, or NULL_TAG if there is no tag associated with name.

^◆ remove()

virtual Sint32 mi::neuraylib::IDice_transaction::remove	(	Tag_struct	tag,
		bool	only_localized = `false`
	)

pure virtual

Marks a tag for removal from the database.

Global removals

The purpose of global removals is to mark all versions of a tag for garbage collection. Such a marker has no effect while the tag is still referenced (in any scope) by other database elements or while the transaction where the removal request was made is still open. When these conditions do no longer apply, the tag becomes eligible for garbage collection and must no longer be used in any way. There is no guarantee when the garbage collection will actually remove the tag.

This implies that a remove() call might actually remove an element that was stored later under the same tag. This can potentially lead to invalid tag accesses. Those cases can be avoided by using mi::neuraylib::IDatabase::garbage_collection() after a transaction was committed and before starting the next one to force garbage collection of all possible elements.

Local removals

The purpose of local removals is to undo the effects of an earlier localization via mi::neuraylib::IDice_transaction::localize(). A local removal request requires that a tag version exists in the scope of the transaction, and at least one more tag version exists in one of the parent scopes. The effect of a local removal request is to immediately hide the tag version in the scope of the transaction (the local copy), and to make the next tag version in one of the parent scopes accessible from the very same transaction. The hidden local copy will be lazily removed by the garbage collection of the database. There is no guarantee when this will happen.

Parameters

tag	The tag to be marked for removal.
only_localized	`false` for global removals (the default) or `true` for local removals. The flag is ignored in favor of global removals if the transaction belongs to the global scope.

Returns

0: Success (including subsequent global removals on elements already marked for global removal).
-1: For global removals: there is no database element with tag tag visible in this transaction. For local removals: there is no database element with tag tag in the scope of this transaction or there is no version of that database element in one of the parent scopes.
-2: Invalid parameters (tag is invalid).
-3: The transaction is not open.

^◆ reserve_tag()

virtual Tag_struct mi::neuraylib::IDice_transaction::reserve_tag ( )

pure virtual

Reserves a tag.

When storing a database element or database job a new tag is automatically assigned and returned. Alternatively, one can reserve a tag upfront and pass it later explicitly to the various store() method.

Returns: The reserved tag.

^◆ store() [1/2]

virtual Tag_struct mi::neuraylib::IDice_transaction::store	(	IElement *	element,
		Tag_struct	tag = `NULL_TAG`,
		const char *	name = `nullptr`,
		Privacy_level	privacy_level = `LOCAL_SCOPE`
	)

pure virtual

Stores a new database element in the database.

After a successful store operation the passed interface pointer must no longer be used, except for releasing it. This is due to the fact that after a store() the database retains ownership of the stored data. You can obtain the stored version from the database using the access() or edit() methods.

Parameters

element	The database element to be stored in the database.
tag	An optional tag used to identify the database element in the database. The tag must be NULL_TAG (the default) or must have been obtained from previous calls to store(), store_for_reference_counting(), name_to_tag(), or reserve_tag(). An existing database element/job associated with this tag will be replaced. See also the documentation of the return value and the note below.
name	An optional name used to identify the database element in the database. An existing database element/job associated with this name will be replaced. The empty string is not a valid name.
privacy_level	The privacy level under which to store `db_element` (in the range from 0 to the privacy level of the scope of this transaction). In addition, the constant LOCAL_SCOPE can be used as a shortcut to indicate the privacy level of the scope of this transaction without supplying the actual value itself.

Returns

The tag that identifies the stored database element, or NULL_TAG in case of errors. Possible reasons for errors are:

The class ID of the element has not been registered (see mi::neuraylib::IDice_configuration::register_serializable_class()).
The privacy level is invalid.
The element is already stored in the database.

Note that the returned tag might differ from tag or name_to_tag() applied to name if there is already a database element/job associated with that tag, that database element/job is to be removed, and no other database element/job is referencing it anymore.

Note: The parameter tag is ignored if name is given and there is a database element/job with that name. The tag of that database element/job is used instead of tag.

^◆ store() [2/2]

virtual Tag_struct mi::neuraylib::IDice_transaction::store	(	IJob *	job,
		Tag_struct	tag = `NULL_TAG`,
		const char *	name = `nullptr`,
		Privacy_level	privacy_level = `LOCAL_SCOPE`
	)

pure virtual

Stores a new database job in the database.

After a successful store operation the passed interface pointer must no longer be used, except for releasing it. This is due to the fact that after a store() the database retains ownership of the stored data.

Parameters

job	The database job to be stored in the database.
tag	An optional tag used to identify the database job in the database. The tag must be NULL_TAG (the default) or must have been obtained from previous calls to store(), store_for_reference_counting(), name_to_tag(), or reserve_tag(). An existing database element/job associated with this tag will be replaced. See also the documentation of the return value and the note below.
name	An optional name used to identify the database job in the database. An existing database element/job associated with this name will be replaced. The empty string is not a valid name.
privacy_level	The privacy level under which to store `job` (in the range from 0 to the privacy level of the scope of this transaction). In addition, the constant LOCAL_SCOPE can be used as a shortcut to indicate the privacy level of the scope of this transaction without supplying the actual value itself.

Returns

The tag that identifies the stored database job, or NULL_TAG in case of errors. Possible reasons for errors are:

The class ID of the job has not been registered (see mi::neuraylib::IDice_configuration::register_serializable_class()).
The privacy level is invalid.
The job is already stored in the database.

Note that the returned tag might differ from tag or name_to_tag() applied to name if there is already a database element/job associated with that tag, that database element/job is to be removed, and no other database element/job is referencing it anymore.

Note: The parameter tag is ignored if name is given and there is a database element/job with that name. The tag of that database element/job is used instead of tag.

^◆ store_for_reference_counting() [1/2]

virtual Tag_struct mi::neuraylib::IDice_transaction::store_for_reference_counting	(	IElement *	element,
		Tag_struct	tag = `NULL_TAG`,
		const char *	name = `nullptr`,
		Privacy_level	privacy_level = `LOCAL_SCOPE`
	)

pure virtual

Stores a new database element in the database (for reference counting).

This method is similar to store() except that the database element will only be kept in the database as long as other elements in the database exist that list it in their set of references returned by the mi::neuraylib::IElement::get_references() method. The same effect can be achieved by calling store() followed by a remove() call on the returned tag.

See also: store() for details

^◆ store_for_reference_counting() [2/2]

virtual Tag_struct mi::neuraylib::IDice_transaction::store_for_reference_counting	(	IJob *	job,
		Tag_struct	tag = `NULL_TAG`,
		const char *	name = `nullptr`,
		Privacy_level	privacy_level = `LOCAL_SCOPE`
	)

pure virtual

Stores a new database job in the database (for reference counting).

This method is similar to store() except that the database job will only be kept in the database as long as other elements in the database exist that list it in their set of references returned by the mi::neuraylib::IElement::get_references() method. The same effect can be achieved by calling store() followed by a remove() call on the returned tag.

See also: store() for details

^◆ tag_to_name()

virtual const char * mi::neuraylib::IDice_transaction::tag_to_name ( Tag_struct tag )

pure virtual

Returns the name associated with a tag in the database.

Note: A tag can be associated with different names in different scopes.

Returns: The name associated with tag, or nullptr if there is no name associated with tag.

Member Data Documentation

^◆ LOCAL_SCOPE

const mi::Uint8 mi::neuraylib::IDice_transaction::LOCAL_SCOPE = 255

static

Symbolic privacy level for the privacy level of the scope of this transaction.

This symbolic constant can be passed to store(), store_for_reference_counting(), and localize() to indicate the privacy level of the scope of this transaction. It has the same effect as passing the result of mi::neuraylib::IScope::get_privacy_level(), but is more convenient.

Public Member Functions

Static Public Attributes

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ abort()

◆ access() [1/2]

◆ access() [2/2]

◆ advise()

◆ commit()

◆ edit() [1/2]

◆ edit() [2/2]

◆ execute_fragmented()

◆ execute_fragmented_async()

◆ get_changed_elements_since_time_stamp()

◆ get_id()

◆ get_privacy_level()

◆ get_scope()

◆ get_time_stamp() [1/2]

◆ get_time_stamp() [2/2]

◆ has_changed_since_time_stamp()

◆ invalidate_job_results()

◆ is_open()

◆ localize()

◆ name_to_tag()

◆ remove()

◆ reserve_tag()

◆ store() [1/2]

◆ store() [2/2]

◆ store_for_reference_counting() [1/2]

◆ store_for_reference_counting() [2/2]

◆ tag_to_name()

Member Data Documentation

◆ LOCAL_SCOPE

^◆ abort()

^◆ access() [1/2]

^◆ access() [2/2]

^◆ advise()

^◆ commit()

^◆ edit() [1/2]

^◆ edit() [2/2]

^◆ execute_fragmented()

^◆ execute_fragmented_async()

^◆ get_changed_elements_since_time_stamp()

^◆ get_id()

^◆ get_privacy_level()

^◆ get_scope()

^◆ get_time_stamp() [1/2]

^◆ get_time_stamp() [2/2]

^◆ has_changed_since_time_stamp()

^◆ invalidate_job_results()

^◆ is_open()

^◆ localize()

^◆ name_to_tag()

^◆ remove()

^◆ reserve_tag()

^◆ store() [1/2]

^◆ store() [2/2]

^◆ store_for_reference_counting() [1/2]

^◆ store_for_reference_counting() [2/2]

^◆ tag_to_name()

^◆ LOCAL_SCOPE