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

This interface is used for configuring the logging for the DiCE library. More...

#include <ilogging_configuration.h>

Inheritance diagram for mi::neuraylib::ILogging_configuration:

Public Member Functions

virtual void set_receiving_logger (base::ILogger *logger)=0
 Sets the receiving logger. More...
 
virtual base::ILoggerget_receiving_logger () const =0
 Returns the receiving logger. More...
 
virtual base::ILoggerget_forwarding_logger () const =0
 Returns the forwarding logger. More...
 
virtual Sint32 set_log_level (base::Message_severity level)=0
 Sets the overall logging level of this host. More...
 
virtual base::Message_severity get_log_level () const =0
 Returns the overall logging level of this host. More...
 
virtual Sint32 set_log_level_by_category (const char *category, base::Message_severity level)=0
 Sets the logging level of this host for a particular message category. More...
 
virtual base::Message_severity get_log_level_by_category (const char *category) const =0
 Returns the logging level of this host for a particular message category. More...
 
virtual Sint32 set_log_priority (Sint32 priority)=0
 Sets the logging priority of this host. More...
 
virtual Sint32 get_log_priority () const =0
 Returns the logging priority of this host. More...
 
virtual void set_log_prefix (Uint32 prefix)=0
 Sets the log message prefix. More...
 
virtual Uint32 get_log_prefix () const =0
 Returns the log message prefix. More...
 
virtual Sint32 set_log_locally (bool value)=0
 Enables or disables local logging. More...
 
virtual bool get_log_locally () const =0
 Indicates whether local logging is enabled or not. 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

- Public Types inherited from mi::base::Interface_declare< 0xaf42fbf7, ... >
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< 0xaf42fbf7, ... >
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 for configuring the logging for the DiCE library.

The DiCE API allows to configure the logging in several ways. You can control the logging by providing an own logger object that implements the mi::base::ILogger interface. By default, all messages are written to stderr.

There are two types of loggers, forwarding and receiving loggers. From an application point of view the flow of a log message is as follows: The application sends the message to the forwarding logger which forwards it to the DiCE library. The message is processed, and if not discarded, sent to the logging host (if distinct from the local host), and passed to the receiving logger. Both types of loggers use the same interface mi::base::ILogger. The receiving logger can be set by the application, the forwarding logger cannot be controlled and is provided by the DiCE library.

The amount of messages can be controlled via log levels. There are two different kinds of log levels, one overall log level, and log levels for individual message categories. These log levels act as independent filters; only messages passing both log level settings are reported.

Note that setting a particular log level implies all higher log levels, e.g., mi::base::details::MESSAGE_SEVERITY_WARNING includes mi::base::details::MESSAGE_SEVERITY_ERROR and mi::base::details::MESSAGE_SEVERITY_FATAL.

In a cluster setup only one host, the logging host, receives the log messages of all hosts. The selection of the logging host is controlled via log priorities (see set_log_priority()). Forwarding of log messages to the logging host can be disabled (see set_log_locally()).

See also
mi::base::ILogger for a list of supported message categories

Member Function Documentation

 get_forwarding_logger()

virtual base::ILogger * mi::neuraylib::ILogging_configuration::get_forwarding_logger ( ) const
pure virtual

Returns the forwarding logger.

The forwarding logger should be used to pass log messages to the DiCE library.

 get_log_level()

virtual base::Message_severity mi::neuraylib::ILogging_configuration::get_log_level ( ) const
pure virtual

Returns the overall logging level of this host.

See also
get_log_level_by_category()
Returns
The configured logging level.

 get_log_level_by_category()

virtual base::Message_severity mi::neuraylib::ILogging_configuration::get_log_level_by_category ( const char *  category) const
pure virtual

Returns the logging level of this host for a particular message category.

See also
mi::base::ILogger for supported categories
get_log_level() for a filter level independent of categories
Parameters
categoryThe message category.
Returns
The logging level, in case of success, -1 in case of failure.

 get_log_locally()

virtual bool mi::neuraylib::ILogging_configuration::get_log_locally ( ) const
pure virtual

Indicates whether local logging is enabled or not.

 get_log_prefix()

virtual Uint32 mi::neuraylib::ILogging_configuration::get_log_prefix ( ) const
pure virtual

Returns the log message prefix.

Returns
A bitmask of the enabled log message components (see mi::neuraylib::Log_prefix).

 get_log_priority()

virtual Sint32 mi::neuraylib::ILogging_configuration::get_log_priority ( ) const
pure virtual

Returns the logging priority of this host.

 get_receiving_logger()

virtual base::ILogger * mi::neuraylib::ILogging_configuration::get_receiving_logger ( ) const
pure virtual

Returns the receiving logger.

Note that if no receiving logger has been set, this method returns NULL and logging is done using a default logger that is internal to this library. This default logger simply writes to stderr.

Note that log messages directly passed to the receiving logger will not be processed by the DiCE library. Use the forwarding logger instead.

 set_log_level()

virtual Sint32 mi::neuraylib::ILogging_configuration::set_log_level ( base::Message_severity  level)
pure virtual

Sets the overall logging level of this host.

Any messages below the given level will be discarded.

See also
set_log_level_by_category()
Parameters
levelThe logging level.
Returns
0, in case of success, -1 in case of failure.

 set_log_level_by_category()

virtual Sint32 mi::neuraylib::ILogging_configuration::set_log_level_by_category ( const char *  category,
base::Message_severity  level 
)
pure virtual

Sets the logging level of this host for a particular message category.

Any messages of that category below the given level will be discarded.

See also
mi::base::ILogger for supported categories
set_log_level() for a filter level independent of categories
Parameters
categoryThe message category. The special value "ALL" is supported to set the logging level of all categories.
levelThe logging level.
Returns
0, in case of success, -1 in case of failure.

 set_log_locally()

virtual Sint32 mi::neuraylib::ILogging_configuration::set_log_locally ( bool  value)
pure virtual

Enables or disables local logging.

If local logging is enabled, all log messages from this host are sent to the local logger. Otherwise, they are sent to the logger of the logging host (see set_log_priority()).

This can only be configured before DiCE has been started.

Parameters
valuetrue to enable the local logging, false to disable it (the default).
Returns
0, in case of success, -1 in case of failure.

 set_log_prefix()

virtual void mi::neuraylib::ILogging_configuration::set_log_prefix ( Uint32  prefix)
pure virtual

Sets the log message prefix.

The log message prefix consists of several optional components that provide context for the log message. Each of these components can be enabled or disabled.

Parameters
prefixA bitmask of the to-be-enabled log message components (see mi::neuraylib::Log_prefix).

 set_log_priority()

virtual Sint32 mi::neuraylib::ILogging_configuration::set_log_priority ( Sint32  priority)
pure virtual

Sets the logging priority of this host.

The log priority determines which host becomes the logging host. The preferred logging host should have the highest number, and fallbacks in case of problems should have lower numbers, in the preferred order of fallbacks. Hosts with the highest logging priority will take over from designated logging hosts that have failed. The default logging priority is 0.

This can only be configured before DiCE has been started.

Parameters
priorityThe logging priority
Returns
0, in case of success, -1 in case of failure.

 set_receiving_logger()

virtual void mi::neuraylib::ILogging_configuration::set_receiving_logger ( base::ILogger logger)
pure virtual

Sets the receiving logger.

Note that in a cluster setup only the logging host will receive messages from the DiCE library. An exception are fatal log messages because due to kind of nature of these messages there is no guarantee that they will reach the logging host. In addition, very few log messages might be received during startup before the host has joined the cluster.

Parameters
loggerThe receiving logger. It is valid to pass NULL in which case logging is reset to be done to stderr.