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

#include <itransaction.h>

Inheritance diagram for mi::neuraylib::ITransaction:

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

virtual void	abort ()=0
	This operation is not supported. More...

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

virtual base::IInterface *	create (const char type_name, Uint32 argc=0, const base::IInterface argv[]=0)=0
	Creates an object of the type `type_name`. More...

template<class T>
T *	create (const char type_name, Uint32 argc=0, const base::IInterface argv[]=0)
	Creates an object of the type `type_name`. More...

template<class T>
T *	create ()
	Creates an object of the type `T`. More...

virtual Sint32	store (base::IInterface db_element, const char name, Uint8 privacy=LOCAL_SCOPE)=0
	Stores the element `db_element` in the database under the name `name` and with the privacy level `privacy`. More...

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

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

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

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

virtual Sint32	copy (const char source, const char target, Uint8 privacy=LOCAL_SCOPE)=0
	Creates a copy of a database element. More...

virtual Sint32	remove (const char *name, bool only_localized=false)=0
	Removes the element with the name `name` from the database. More...

virtual const char *	name_of (const base::IInterface *db_element) const =0
	Returns the name of a database element. More...

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

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

virtual bool	has_changed_since_time_stamp (const char element, 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 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 IArray *	list_elements (const char root_element, const char name_pattern=0, const IArray *type_names=0) const =0
	Returns scene elements of a subgraph originating at a given scene element. More...

virtual Sint32	get_privacy_level (const char *name) const =0
	Returns the privacy level of the element with the name `name`. 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< 0x6ca1f0c2, ... >
typedef Interface_declare< id1, ... >	Self
	Own type. More...

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

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

Static Public Member Functions inherited from mi::base::Interface_declare< 0x6ca1f0c2, ... >
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().

Transactions are not thread-safe. If you use a particular transaction from multiple threads, then you have to serialize all transaction uses. This does not only apply to methods of mi::neuraylib::ITransaction, but all methods that implicitly use the transaction. For example, such a use can happen by methods of DB elements returned from access() or edit() calls, or by objects returned from factories taking the transaction as an argument, like mi::neuraylib::IMdl_factory::create_module_builder().

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: The interface pointer returned from access() reflects the changes as they are done to the interface pointer returned from the last edit() call.
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.

: Note that these semantics do not only apply to access() and edit() calls. They also apply to other API methods that access other database elements, e.g., mi::IRef::get_reference(), which internally calls access().

Note: The MDL SDK currently supports only one transaction at a time.

Member Function Documentation

^◆ abort()

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

pure virtual

This operation is not supported.

^◆ access() [1/2]

template<class T>

const T * mi::neuraylib::ITransaction::access ( const char * name )

inline

Retrieves an element from the database.

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

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 Uuid&) on the returned pointer, since the return type already is a const pointer to the type T specified as template parameter.

Parameters

name	The name of the element to retrieve.

Template Parameters

T	The interface type of the element to retrieve.

Returns: The requested element from the database, or NULL if name is invalid, no DB element with that name exists, the transaction is already closed, or the element is not of type T.

^◆ access() [2/2]

virtual const base::IInterface * mi::neuraylib::ITransaction::access ( const char * name )

pure virtual

Retrieves an element from the database.

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

Parameters

name	The name of the element to retrieve.

Returns: The requested element from the database, or NULL if name is invalid, no DB element with that name exists, or the transaction is already closed.

^◆ commit()

virtual Sint32 mi::neuraylib::ITransaction::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.

^◆ copy()

virtual Sint32 mi::neuraylib::ITransaction::copy	(	const char *	source,
		const char *	target,
		Uint8	privacy = `LOCAL_SCOPE`
	)

pure virtual

Creates a copy of a database element.

Note that DB elements of type mi::neuraylib::IModule and mi::neuraylib::IFunction_definition can not be copied.

Parameters

source	The name of the element to be copied.
target	The desired name of the copy.
privacy	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 (NULL pointer).
-3: The transaction is not open.
-4: There is no DB element named source visible in this transaction.
-5: Invalid privacy level.
-6: DB elements of this type cannot be copied.
-9: There is already an element of name name and overwriting elements of that type is not supported. This applies to elements of type mi::neuraylib::IModule and mi::neuraylib::IFunction_definition. It also applies to elements of type mi::neuraylib::IFunction_call that are used as defaults in an mi::neuraylib::IFunction_definition.

^◆ create() [1/3]

template<class T>

T * mi::neuraylib::ITransaction::create ( )

inline

Creates an object of the type T.

Objects created with this method are typically Types and Scene elements. Note that most types can also be created via the API component mi::neuraylib::IFactory which does not require the context of a transaction.

This method can not be used to create MDL modules, definitions, or function calls. To create instances of mi::neuraylib::IFunction_call, use the method mi::neuraylib::IFunction_definition::create_function_call().

The created object will be initialized in a manner dependent upon the passed type name. Each class has its own policy on initialization. So, one should not make any assumptions on the values of the various class members.

Note that there are two versions of this templated member function, one that takes no arguments, and another one that takes one or three arguments (the type name, and two optional arguments passed to the constructor or factory). The version with no arguments can only be used to create a subset of supported types derived from mi::IData: it supports only those types where the type name can be deduced from the template parameter, i.e., it does not support arrays, structures, maps, and pointers. The version with one or three arguments can be used to create any type (but requires the type name as parameter, which is redundant for many types). Attempts to use the version with no arguments with a template parameter where the type name can not be deduced results in compiler errors.

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 Uuid&) on the returned pointer, since the return type already is a pointer to the type T specified as template parameter.

Template Parameters

T	The interface type of the class to create.

Returns: A pointer to the created object.

^◆ create() [2/3]

template<class T>

T * mi::neuraylib::ITransaction::create	(	const char *	type_name,
		Uint32	argc = `0`,
		const base::IInterface *	argv[] = `0`
	)

inline

Creates an object of the type type_name.

Objects created with this method are typically Types and Scene elements. Note that most types can also be created via the API component mi::neuraylib::IFactory which does not require the context of a transaction.

This method can not be used to create MDL modules, definitions, or function calls. To create instances of mi::neuraylib::IFunction_call, use the method mi::neuraylib::IFunction_definition::create_function_call().

The created object will be initialized in a manner dependent upon the passed type name. Each class has its own policy on initialization. So, one should not make any assumptions on the values of the various class members.

Note that there are two versions of this templated member function, one that takes no arguments, and another one that takes one or three arguments (the type name, and two optional arguments passed to the constructor or factory). The version with no arguments can only be used to create a subset of supported types derived from mi::IData: it supports only those types where the type name can be deduced from the template parameter, i.e., it does not support arrays, structures, maps, and pointers. The version with one or three arguments can be used to create any type (but requires the type name as parameter, which is redundant for many types). Attempts to use the version with no arguments with a template parameter where the type name can not be deduced results in compiler errors.

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 Uuid&) on the returned pointer, since the return type already is a pointer to the type T specified as template parameter.

Parameters

type_name	The type name of the object to create. See Types for possible type names. In addition, Scene elements can be created by passing the name of the requested interfaces without namespace qualifiers and the leading `"I"`, e.g., `"Image"` for mi::neuraylib::IImage. Note that you can not create instances of mi::neuraylib::IAttribute_set or mi::neuraylib::IScene_element, only instances of the derived interfaces.
argc	The number of elements in `argv`. Passed to the constructor of factory of the object to create.
argv	The array of arguments passed to the constructor. Passed to the constructor of factory of the object to create.

Template Parameters

T	The interface type of the class to create.

Returns: A pointer to the created object, or NULL if type_name is invalid (NULL pointer), not a valid type name, or does not create an object of type T.

^◆ create() [3/3]

virtual base::IInterface * mi::neuraylib::ITransaction::create	(	const char *	type_name,
		Uint32	argc = `0`,
		const base::IInterface *	argv[] = `0`
	)

pure virtual

Creates an object of the type type_name.

Objects created with this method are typically Types and Scene elements. Note that most types can also be created via the API component mi::neuraylib::IFactory which does not require the context of a transaction.

This method can not be used to create MDL modules, definitions, or function calls. To create instances of mi::neuraylib::IFunction_call, use the method mi::neuraylib::IFunction_definition::create_function_call().

The created object will be initialized in a manner dependent upon the passed type name. Each class has its own policy on initialization. So, one should not make any assumptions on the values of the various class members.

Parameters

type_name	The type name of the object to create. See Types for possible type names. In addition, Scene elements can be created by passing the name of the requested interfaces without namespace qualifiers and the leading `"I"`, e.g., `"Image"` for mi::neuraylib::IImage. Note that you can not create instances of mi::neuraylib::IAttribute_set or mi::neuraylib::IScene_element, only instances of the derived interfaces.
argc	The number of elements in `argv`. Passed to the constructor of factory of the object to create.
argv	The array of arguments passed to the constructor. Passed to the constructor of factory of the object to create.

Returns: A pointer to the created object, or NULL if type_name is invalid (NULL pointer) or not a valid type name.

^◆ edit() [1/2]

template<class T>

T * mi::neuraylib::ITransaction::edit ( const char * name )

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. It will then make a copy of that version and return the copy. The edited DB element will be committed to the database automatically, when the obtained interface is released. It is neither necessary nor possible to store the edited element manually in the database using the store() method.

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 Uuid&) on the returned pointer, since the return type already is a pointer to the type T specified as template parameter.

Parameters

name	The name of the element to retrieve.

Template Parameters

T	The interface type of the element to retrieve.

Returns: The requested element from the database, or NULL if name is invalid, no DB element with that name exists, the transaction is already closed, or the element is not of type T.

^◆ edit() [2/2]

virtual base::IInterface * mi::neuraylib::ITransaction::edit ( const char * name )

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 DB element visible for the current transaction. It will then make a copy of that version and return the copy. The edited DB element will be committed to the database automatically, when the obtained interface is released. It is neither necessary nor possible to store the edited element manually in the database using the store() method.

Parameters

name	The name of the element to retrieve.

Returns: The requested element from the database, or NULL if name is invalid, no DB element with that name exists, or the transaction is already closed.

^◆ get_id()

virtual const char * mi::neuraylib::ITransaction::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::ITransaction::get_privacy_level ( const char * name ) const

pure virtual

Returns the privacy level of the element with the name name.

Parameters

name	The name of the element.

Returns

>= 0: Success. The privacy level of the element (in the range 0-255).
-2: Invalid parameters (NULL pointer).
-3: The transaction is not open.
-4: There is no DB element named name visible in this transaction.

^◆ get_scope()

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

pure virtual

Returns the scope of this transaction.

^◆ get_time_stamp() [1/2]

virtual const char * mi::neuraylib::ITransaction::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 MDL SDK instance. It should not be put into external storage and re-used for different or later MDL SDK 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(const char*)const

^◆ get_time_stamp() [2/2]

virtual const char * mi::neuraylib::ITransaction::get_time_stamp ( const char * element ) 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 MDL SDK instance. It should not be put into external storage and re-used for different or later MDL SDK 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::ITransaction::has_changed_since_time_stamp	(	const char *	element,
		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(const char*)const

Parameters

element	The name of the element.
time_stamp	The time stamp obtained from get_time_stamp() or get_time_stamp(const char*)const.

Returns: true if the element has been stored or changed since the time stamp (or if element or time_stamp is invalid, or there is no element with that name), false otherwise.

^◆ is_open()

virtual bool mi::neuraylib::ITransaction::is_open ( ) const

pure virtual

Indicates whether the transaction is open.

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

^◆ list_elements()

virtual IArray * mi::neuraylib::ITransaction::list_elements	(	const char *	root_element,
		const char *	name_pattern = `0`,
		const IArray *	type_names = `0`
	)		const

pure virtual

Returns scene elements of a subgraph originating at a given scene element.

The method iterates over all elements of a subgraph originating at the given scene element and returns their names. Optionally, the results can be filtered by a regular expression for the element names and a list for type names.

Note that the runtime of the method depends on the number of elements in the subgraph. It might be expensive to call this method for large subgraphs.

The returned scene elements are in such an order that all elements referenced by a given element are listed before that element ("before" in the sense of "using smaller array indices").

Parameters

root_element	The root of the subgraph to traverse.
name_pattern	An extended regular expression that acts as filter on the names of returned scene elements (see [OGBS7]). The regular expression is matched to any part of the scene element name, not just to the entire scene element name. The value `NULL` is handled as `".*"`.
type_names	A list of type names that acts as filter on the names of returned scene elements. Only scene elements with a matching type name pass the filter. The value `NULL` lets all scene elements pass the filter irrespective of their type name.

Returns: A list of name of scene elements in the subgraph matching the given regular expression and type name filter, or NULL in case of an invalid root element name or an invalid regular expression.

^◆ name_of()

virtual const char * mi::neuraylib::ITransaction::name_of ( const base::IInterface * db_element ) const

pure virtual

Returns the name of a database element.

Parameters

db_element The DB element.

Returns: The name of the DB element, or NULL if db_element is invalid (NULL pointer), the object is not in the database, or the transaction is already closed.

^◆ remove()

virtual Sint32 mi::neuraylib::ITransaction::remove	(	const char *	name,
		bool	only_localized = `false`
	)

pure virtual

Removes the element with the name name from the database.

Note that the element continues to be stored in the database as long as it is referenced by other elements. If it is no longer referenced, and the last transaction were it was referenced has been committed, it will be lazily removed by the garbage collection of the DB. There is no guarantee when this will happen.

This implies that a remove() call might actually remove an element that was stored later under the same name. 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.

Parameters

name	The name of the element in the database to remove.
only_localized	Unused.

Returns

0: Success.
-1: There is no DB element named name visible in this transaction (only_localize is false) or there is no DB element named name in the scope of this transaction (only_localized is true).
-2: Invalid parameters (NULL pointer).
-3: The transaction is not open.

^◆ store()

virtual Sint32 mi::neuraylib::ITransaction::store	(	base::IInterface *	db_element,
		const char *	name,
		Uint8	privacy = `LOCAL_SCOPE`
	)

pure virtual

Stores the element db_element in the database under the name name and with the privacy level privacy.

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.

Note: Overwriting vs editing of existing DB elements
While it is possible to overwrite existing DB elements, for performance reasons it is often better to edit the already existing DB element instead. Editing a DB element allows the DB to keep track of the type of changes which might help render modes to update their data structures more efficiently. When overwriting an existing DB element such information is not available and pessimistic assumptions have to be made which may result in lower performance.

Parameters

db_element	The mi::base::IInterface to store.
name	The name under which to store `db_element`. If there exists already a DB element with that name then it will be overwritten
privacy	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

0: Success.
-1: Unspecified failure.
-2: Invalid parameters (NULL pointer).
-3: The transaction is not open.
-4: db_element is not a DB element.
-5: Invalid privacy level.
-6: db_element has already been stored previously.
-7: The element is to be stored in a transaction different from the one that was used to create it.
-8: The element is a user-defined class that has not been registered.

-9: There is already an element of name name and overwriting elements of that type is not supported. This applies to elements of type mi::neuraylib::IModule and mi::neuraylib::IFunction_definition. It also applies to elements of type mi::neuraylib::IFunction_call that are used as defaults in an mi::neuraylib::IFunction_definition.

Member Data Documentation

^◆ LOCAL_SCOPE

const mi::Uint8 mi::neuraylib::ITransaction::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() and copy() to indicate the privacy level of the scope of this transaction. It has the same affect 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]

◆ commit()

◆ copy()

◆ create() [1/3]

◆ create() [2/3]

◆ create() [3/3]

◆ edit() [1/2]

◆ edit() [2/2]

◆ get_id()

◆ get_privacy_level()

◆ get_scope()

◆ get_time_stamp() [1/2]

◆ get_time_stamp() [2/2]

◆ has_changed_since_time_stamp()

◆ is_open()

◆ list_elements()

◆ name_of()

◆ remove()

◆ store()

Member Data Documentation

◆ LOCAL_SCOPE

^◆ abort()

^◆ access() [1/2]

^◆ access() [2/2]

^◆ commit()

^◆ copy()

^◆ create() [1/3]

^◆ create() [2/3]

^◆ create() [3/3]

^◆ edit() [1/2]

^◆ edit() [2/2]

^◆ get_id()

^◆ get_privacy_level()

^◆ get_scope()

^◆ get_time_stamp() [1/2]

^◆ get_time_stamp() [2/2]

^◆ has_changed_since_time_stamp()

^◆ is_open()

^◆ list_elements()

^◆ name_of()

^◆ remove()

^◆ store()

^◆ LOCAL_SCOPE