This interface represents the base class for all database jobs. More...

#include <dice.h>

Inheritance diagram for mi::neuraylib::IJob:

[legend]

Public Member Functions
virtual IJob *	copy () const =0
	Creates a copy of the database job. More...

virtual const char *	get_class_name () const =0
	Returns a human readable identifier for the class this database job belongs to. More...

virtual Size	get_size () const =0
	Returns the size of the database job in bytes. More...

virtual IElement *	execute (IDice_transaction *transaction) const =0
	Executes the database job and returns the resulting database element. More...

virtual bool	is_shared () const =0
	Indicates whether the database job is shared between transactions. More...

virtual bool	is_local_only () const =0
	Indicates whether the database job shall be executed on the local host only. More...

virtual bool	is_parent () const =0
	Indicates whether the database job creates and stores database elements and/or database jobs. More...

virtual Float32	get_cpu_load () const =0
	Returns the CPU load of the database job. More...

virtual Float32	get_gpu_load () const =0
	Returns the GPU load of the database job. More...

Public Member Functions inherited from mi::neuraylib::ISerializable
virtual base::Uuid	get_class_id () const =0
	Returns the class ID of the object. More...

virtual void	serialize (ISerializer *serializer) const =0
	Serializes the object to the given `serializer`. More...

virtual void	deserialize (IDeserializer *deserializer)=0
	Deserializes the object from the given `deserializer`. 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...

Additional Inherited Members
Public Types inherited from mi::base::Interface_declare< 0x0edda67e, ... >
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::Interface_declare< 0x7a70f2fb, ... >
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< 0x0edda67e, ... >
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::Interface_declare< 0x7a70f2fb, ... >
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 represents the base class for all database jobs.

Each database job must be derived from this interface.

Database jobs generate database elements that result from on-demand computing. Similar to database elements, database jobs are identified by a tag and are stored in the database. In contrast to database elements, database jobs get executed when accessing the tag by mi::neuraylib::IDice_transaction::access(), and then provide a database element representing the result of the job execution, that is, a job can be considered a kind of procedural database element. Subsequent accesses to the tag will not necessarily re-execute the job but the database might immediately return the previously computed job result (see is_shared, is_local_only).

Not every procedurally generated data must be created by means of database jobs. Sometimes, some member function of the database element represents an even better place to compute the required data. As a rule of thumb, a database job should be introduced if:

the creation of the resulting data is not trivial and takes some time,
the creation of the data shall be done on demand and only if actually required, and
some task can be divided into smaller subtasks (individual jobs), which are independent from one another.

In addition to triggering on-demand execution of database jobs by accessing the associated tag it also possible to advise a database jobs for lazy execution (see mi::neuraylib::IDice_transaction::advise()).

The database has a mechanism to ensure that a job gets up-to-date information when being executed. The guarantee given is: All changes done or seen on a host before doing an mi::neuraylib::IDice_transaction::advise() or mi::neuraylib::IDice_transaction::access() on a job are visible during job execution. This is also ensured if the job is executed on a remotely on a different host in a cluster. This guarantee is also transitive for jobs executed by other jobs.

Note: Fragmented jobs represent a way to achieve parallelism and distributed computing. See mi::neuraylib::IFragmented_job for details.

See also: The mixin mi::neuraylib::Job can be useful as a starting point for your own implementation of this abstract interface.

Member Function Documentation

^◆ copy()

virtual IJob * mi::neuraylib::IJob::copy ( ) const

pure virtual

Creates a copy of the database job.

Duplicating a database job is used by the database when it needs to create a new version of the given job, e.g., when someone edits an existing job. This member function must create and return a full copy of the job.

Returns: A newly allocated instance of the database job. The pointer represents a complete replica of the database job on which the member function was called.

^◆ execute()

virtual IElement * mi::neuraylib::IJob::execute ( IDice_transaction * transaction ) const

pure virtual

Executes the database job and returns the resulting database element.

Executing the database job returns a newly allocated database element. The type of the database element class returned by the database job may be arbitrary but must correspond to the class that is expected by code accessing the database job's result.

Note that the database will execute that database job at most once in each transaction (see also is_shared()).

Parameters

transaction The transaction in which the job is executed. It may be used to access required database elements and other database jobs during the execution of the job. The transaction may not be used to edit or create new tags.

Returns: The created database element.

^◆ get_class_name()

virtual const char * mi::neuraylib::IJob::get_class_name ( ) const

pure virtual

Returns a human readable identifier for the class this database job belongs to.

This name is not required for proper operation, but can be useful for debugging. For example, the name is used to display the class name in the tag table of the HTTP administration console.

Returns: The class name. The string has to be valid at all times while instances of this class are stored in the database.

^◆ get_cpu_load()

virtual Float32 mi::neuraylib::IJob::get_cpu_load ( ) const

pure virtual

Returns the CPU load of the database job.

Typically 1.0 for CPU jobs and 0.0 for GPU jobs. A value larger than 1.0 might be used for jobs that concurrently use multiple threads, e.g., if OpenMP or MPI is used.

Note: This value must never change for a given instance of the database job.

^◆ get_gpu_load()

virtual Float32 mi::neuraylib::IJob::get_gpu_load ( ) const

pure virtual

Returns the GPU load of the database job.

Typically 0.0 for CPU jobs and 1.0 for GPU jobs. A value larger than 1.0 might be used for jobs that concurrently use multiple GPUs.

Note: This value must never change for a given instance of the database job.

^◆ get_size()

virtual Size mi::neuraylib::IJob::get_size ( ) const

pure virtual

Returns the size of the database job in bytes.

The value includes all memory that directly or indirectly belongs exclusively to this database job. For simple classes,

sizeof(*this)

works.

A correct implementation of this method is required if memory limits are configured.

See also: mi::neuraylib::IDatabase_configuration::set_memory_limits(), mi::neuraylib::IDatabase_configuration::get_memory_limits()

^◆ is_local_only()

virtual bool mi::neuraylib::IJob::is_local_only ( ) const

pure virtual

Indicates whether the database job shall be executed on the local host only.

A database job that is supposed to be executed locally cannot be delegated to other hosts in the cluster. In consequence, the database job must be executed on each host that accesses the associated tag.

Typically, database jobs are executed locally if the inputs and/or the results too large to be transmitted over the network, or if the job is trivial enough to be executed on the fly and does not require distributed execution.

Returns: true if the job shall be executed on the local host only, or false otherwise.

^◆ is_parent()

virtual bool mi::neuraylib::IJob::is_parent ( ) const

pure virtual

Indicates whether the database job creates and stores database elements and/or database jobs.

Returns: true if the job creates and stores database elements, or false otherwise.

^◆ is_shared()

virtual bool mi::neuraylib::IJob::is_shared ( ) const

pure virtual

Indicates whether the database job is shared between transactions.

A shared job is not automatically re-executed per transaction but only if

it has never been executed before or
it is explicitly invalidated by calling mi::neuraylib::IDice_transaction::invalidate_job_results(). In contrast, a non-shared database job is done (at most) once per transaction when accessing the associated tag the first time.

Returns: true if the database job is shared between transactions, or false otherwise.

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ copy()

◆ execute()

◆ get_class_name()

◆ get_cpu_load()

◆ get_gpu_load()

◆ get_size()

◆ is_local_only()

◆ is_parent()

◆ is_shared()

^◆ copy()

^◆ execute()

^◆ get_class_name()

^◆ get_cpu_load()

^◆ get_gpu_load()

^◆ get_size()

^◆ is_local_only()

^◆ is_parent()

^◆ is_shared()