Member Functions

virtual IScope* mi::​neuraylib::​IDatabase::create_or_get_named_scope( const char* name, IScope* parent = 0, Uint8 privacy_level = 0) [pure virtual]

Creates or retrieves a new named scope at the given privacy level with the given parent scope ID.

Parameters

name

A name which can be used to lookup the scope. If a scope with the same name exists already then it will be returned if the parent and privacy level are identical. Otherwise creating the scope will fail.

parent

The parent scope for this scope. If the value is NULL the created scope will be a child of the global scope.

privacy_level

The privacy level of the scope. This must be higher than the privacy level of the parent scope. The privacy level of the global scope is 0 (and the global scope is the only scope with privacy level 0). The default value of 0 indicates the privacy level of the parent scope plus 1.

Returns

The created scope or NULL if something went wrong.

virtual IScope* mi::​neuraylib::​IDatabase::create_scope( IScope* parent, Uint8 privacy_level = 0, bool temp = false) [pure virtual]

Creates a new optionally temporary scope at the given privacy level with the given parent scope ID.

Note:

A scope continues to exist if the pointer returned by this method is released. Use remove_scope() to remove a scope.

Parameters

parent

The parent scope for this scope. If the value is NULL the created scope will be a child of the global scope.

privacy_level

The privacy level of the scope. This must be higher than the privacy level of the parent scope. The privacy level of the global scope is 0 (and the global scope is the only scope with privacy level 0). The default value of 0 indicates the privacy level of the parent scope plus 1.

temp

A bool indicating if the scope is temporary. If the scope is temporary, then when the host that created the scope is removed from the cluster the scope and all data contained in the scope will be removed. If the scope is not temporary, the default, then when the creating host is removed from the cluster the scope and all contained data will remain in the database.

Returns

The created scope or NULL if something went wrong.

virtual void mi::​neuraylib::​IDatabase::garbage_collection() [pure virtual]

Triggers a synchronous garbage collection run. The method sweeps through the entire database and removes all database elements which have been marked for removal and are no longer referenced. Note that it is not possible to remove database elements if there are open transactions in which such an element is still referenced.

To mark an element for removal use mi::neuraylib::IDice_transaction::remove() or mi::neuraylib::IDice_transaction::store_for_reference_counting().

virtual IScope* mi::​neuraylib::​IDatabase::get_global_scope() const [pure virtual]

Returns the global scope which is the root of a tree of scopes.

Returns

The global scope which is guaranteed to exist after startup of the system.

virtual IScope* mi::​neuraylib::​IDatabase::get_named_scope( const char* name) const [pure virtual]

Looks up and returns a scope with a given name.

Parameters

name

The name of the scope

Returns

The found scope or NULL if no such scope exists.

virtual IScope* mi::​neuraylib::​IDatabase::get_scope( const char* id) const [pure virtual]

Looks up and returns a scope with a given ID.

Parameters

id

The ID of the scope as returned by mi::neuraylib::IScope::get_id().

Returns

The found scope or NULL if no such scope exists.

virtual void mi::​neuraylib::​IDatabase::lock( Uint32 lock_id) [pure virtual]

Acquires a DB lock. The method blocks until the requested lock has been obtained. Recursively locking the same lock from within the same thread on the same host is supported.

If the host holding a lock leaves the cluster, the lock is automatically released.

Note:

• The locking mechanism is kind of a co-operative locking mechanism: The lock does not prevent other threads from accessing or editing the DB. It only prevents other threads from obtaining the same lock.

• DB locks are not restricted to threads on a single host, they apply to all threads on all hosts in the cluster.

• DB locks are an expensive operation and should only be used when absolutely necessary.

Parameters

lock_id

The lock to acquire.

virtual Sint32 mi::​neuraylib::​IDatabase::remove_scope( const char* id) const [pure virtual]

Removes a scope with the specified ID. Note that scopes are reference counted. The actual removal will not happen before all elements referencing the scope have been released (e.g., child scopes, transactions, database elements).

It is not possible to remove the global scope.

Parameters

id

The ID of the scope as returned by mi::neuraylib::IScope::get_id().

Returns

0, in case of success, -1 in case of failure.

virtual Sint32 mi::​neuraylib::​IDatabase::unlock( Uint32 lock_id) [pure virtual]

Releases a previously obtained DB lock. If the lock has been locked several times from within the same thread on the same host, it simply decrements the lock count. If the lock count reaches zero, the lock is released.

Parameters

lock_id

The lock to release.

Returns

0, in case of success, -1 in case of failure, i.e, the lock is not held by this thread on this host