DiCE API nvidia_logo_transpbg.gif Up
mi::neuraylib::IDatabase Class Referenceabstract

This interface is used to interact with the distributed database. More...

#include <idatabase.h>

Inheritance diagram for mi::neuraylib::IDatabase:

Public Types

enum  Garbage_collection_priority {
  PRIORITY_LOW = 0 ,
  PRIORITY_MEDIUM = 1 ,
  PRIORITY_HIGH = 2 ,
  PRIORITY_FORCE_32_BIT = 0xffffffffU
}
 Priorities for synchronous garbage collection runs. More...
 
- Public Types inherited from mi::base::Interface_declare< 0x814ae637, ... >
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...
 

Public Member Functions

virtual IScopeget_global_scope () const =0
 Returns the global scope which is the root of a tree of scopes. More...
 
virtual IScopecreate_scope (IScope *parent, Uint8 privacy_level=0, bool temp=false)=0
 Creates a new optionally temporary scope at the given privacy level with the given parent scope ID. More...
 
virtual IScopeget_scope (const char *id) const =0
 Looks up and returns a scope with a given ID. More...
 
virtual Sint32 remove_scope (const char *id) const =0
 Removes a scope with the specified ID. More...
 
virtual void lock (Uint32 lock_id)=0
 Acquires a DB lock. More...
 
virtual Sint32 unlock (Uint32 lock_id)=0
 Releases a previously obtained DB lock. More...
 
virtual IScopecreate_or_get_named_scope (const char *name, IScope *parent=0, Uint8 privacy_level=0)=0
 Creates or retrieves a new named scope at the given privacy level with the given parent scope ID. More...
 
virtual IScopeget_named_scope (const char *name) const =0
 Looks up and returns a scope with a given name. More...
 
virtual void garbage_collection (Garbage_collection_priority priority=PRIORITY_MEDIUM)=0
 Triggers a synchronous garbage collection run. 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 IInterfaceget_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 IInterfaceget_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...
 

Additional Inherited Members

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

This interface is used to interact with the distributed database.

Member Enumeration Documentation

 Garbage_collection_priority

Priorities for synchronous garbage collection runs.

Enumerator
PRIORITY_LOW 

Low priority for synchronous garbage collection runs.

Use this priority if the performance of other concurrent DB operations is more important than a fast synchronous garbage collection.

PRIORITY_MEDIUM 

Medium priority for synchronous garbage collection runs.

This priority attempts to maintain a balance between the synchronous garbage collection and other concurrent DB operations.

PRIORITY_HIGH 

High priority for synchronous garbage collection runs.

Other concurrent DB operations will experience a large performance drop. Therefore, this priority should not be used in multi-user settings.

Member Function Documentation

 create_or_get_named_scope()

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
nameA 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.
parentThe parent scope for this scope. If the value is NULL the created scope will be a child of the global scope.
privacy_levelThe 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.

 create_scope()

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
parentThe parent scope for this scope. If the value is NULL the created scope will be a child of the global scope.
privacy_levelThe 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.
tempA 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.

 garbage_collection()

virtual void mi::neuraylib::IDatabase::garbage_collection ( Garbage_collection_priority  priority = PRIORITY_MEDIUM)
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().

Parameters
priorityThe intended priority of the synchronous garbage collection run.

 get_global_scope()

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.

 get_named_scope()

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
nameThe name of the scope
Returns
The found scope or NULL if no such scope exists.

 get_scope()

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

Looks up and returns a scope with a given ID.

Parameters
idThe ID of the scope as returned by mi::neuraylib::IScope::get_id().
Returns
The found scope or NULL if no such scope exists.

 lock()

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.

Parameters
lock_idThe lock to acquire.
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.

 remove_scope()

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, including handles to the scope itself. Even when all these conditions are met, scope removal might actually happen at a later point in time, depending on the timing of past and current transactions, even in unrelated scopes.

It is not possible to remove the global scope.

Parameters
idThe ID of the scope as returned by mi::neuraylib::IScope::get_id().
Returns
0, in case of success, -1 in case of failure.

 unlock()

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_idThe 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