Runtime service that is used by operators. More...

#include <RuntimeServices.h>

Classes
class	ProfilerGuard
	Helper class to ensure all profiler events have matching begin/end calls. More...

Public Types
using	LogCallback = void()(RuntimeMessageCategory category, Amino::StringView const &message, void clientData)

Public Member Functions
AMINO_CORE_SHARED_DECL	RuntimeServices (LogCallback cb, void *clientData, RuntimeMessageCategory logLevel=RuntimeMessageCategory::kInfo, bool allowConcurrentCalls=false)
	Constructs a RuntimeServices that calls the given callback when messages are logged. More...

AMINO_CORE_SHARED_DECL	~RuntimeServices ()
	Destructor. More...

AMINO_CORE_SHARED_DECL bool	isLogEnabled (RuntimeMessageCategory cat) const
	Check if logging is enabled for a specific category. More...

bool	isLogInfoEnabled () const
	Short-hand for isLogEnabled(RuntimeMessageCategory::kInfo) More...

bool	isLogWarningEnabled () const
	Short-hand for isLogEnabled(RuntimeMessageCategory::kWarning) More...

bool	isLogErrorEnabled () const
	Short-hand for isLogEnabled(RuntimeMessageCategory::kError) More...

template<typename Msg >
AMINO_INTERNAL_FORCEINLINE void	logInfo (Msg const &msg) const
	Short-hand for log(RuntimeMessageCategory::kInfo, msg) More...

template<typename Msg >
AMINO_INTERNAL_FORCEINLINE void	logWarning (Msg const &msg) const
	Short-hand for log(RuntimeMessageCategory::kWarning, msg) More...

template<typename Msg >
AMINO_INTERNAL_FORCEINLINE enable_if_functor< Msg >	logError (Msg const &msg) const
	Short-hand for log(RuntimeMessageCategory::kError, msg) More...

AMINO_CORE_SHARED_DECL void	logError (StringView msg) const
	Log the given error message if logging of errors is enabled. More...

AMINO_CORE_SHARED_DECL int	profilerEventBegin () const
	Notify profiler about beginning of a new named event. More...

AMINO_CORE_SHARED_DECL int	profilerEventBegin (const char *eventName) const
	Notify profiler about beginning of a new named event. More...

AMINO_CORE_SHARED_DECL void	profilerEventEnd (int startEventID) const
	Notify profiler about end of an event. More...


template<typename OStream >
AMINO_INTERNAL_FORCEINLINE	RuntimeServices (OStream *os)
	Constructs a RuntimeServices that logs messages to the given output stream when messages are logged. More...

template<typename OStream >
AMINO_INTERNAL_FORCEINLINE	RuntimeServices (OStream *os, RuntimeMessageCategory logLevel)
	Constructs a RuntimeServices that logs messages to the given output stream when messages are logged. More...


	RuntimeServices (const RuntimeServices &rhs)=delete
	Copying and moving RuntimeServices is prohibited. More...

	RuntimeServices (RuntimeServices &&rhs) noexcept=delete
	Copying and moving RuntimeServices is prohibited. More...

RuntimeServices &	operator= (const RuntimeServices &rhs)=delete
	Copying and moving RuntimeServices is prohibited. More...

RuntimeServices &	operator= (RuntimeServices &&rhs) noexcept=delete
	Copying and moving RuntimeServices is prohibited. More...


template<typename MsgFunc >
AMINO_INTERNAL_FORCEINLINE enable_if_functor< MsgFunc >	log (RuntimeMessageCategory category, MsgFunc const &msgFunc) const
	Log a message with a specific category. More...

void	log (RuntimeMessageCategory category, StringView const &message) const
	Log a message with a specific category. More...

Static Public Member Functions
static AMINO_CORE_SHARED_DECL RuntimeServices const &	getDisabled ()
	Get reference to a "disabled" runtime services. More...

Detailed Description

Runtime service that is used by operators.

The runtime service object is used by a job to capture messages generated by its operators at runtime. Operators can call the logging functions of the RuntimeServices object to generate error, warning or info messages. They can do so either by passing logging functions a functor that will lazily be called only if logging is enabled for the given message category, or by passing a StringView directly. In the latter case, except for RuntimeServices::logError, it is up to the caller to ensure that logging is enabled for the given category (logging messages when logging is disabled will trigger an assertion).

The RuntimeServices can also be used to profile the operator's execution time by creating named profiling events.

Calls to all logging and profiling functions are thread-safe.

This RuntimeServices parameter must be a const reference. For example:

In header file:

float average(
    const FloatData& data,
    RuntimeServices const& runtimeServices);

In cpp file:

float average(const FloatData& data, RuntimeServices const& runtimeServices)
{
    using namespace Amino::StringViewLiterals;
    size_t size = data.size();
    if ( size == 0 ) {
        runtimeServices.logError("No data to average!"_asv);
    } else if ( size == 1 ) {
        if (runtimeServices.isLogWarningEnabled())
           runtimeServices.logWarning("Averaging a single value!"_asv);
    } else {
        runtimeServices.logInfo([size]() {
            std::string msg = "Averaging ";
            msg += std::to_string(size);
            msg += " floats";
            return msg;
        });
    }
    // ...
}

It is not necessary to specify the RuntimeServices parameter on the operator if logging/profiling is not required. The header parser will detect the presence of the RuntimeServices and generate the state required for the operator to be called with this parameter.

Warning: The RuntimeServices mechanism must only be used to log runtime messages and profiling events. It must never influence the output values of an external operator. For example, the operator should always produce the same output values, regardless if logging is enabled of not.

Definition at line 103 of file RuntimeServices.h.

Member Typedef Documentation

◆ LogCallback

using Amino::RuntimeServices::LogCallback = void (*)( RuntimeMessageCategory category, Amino::StringView const& message, void* clientData)

Definition at line 112 of file RuntimeServices.h.

Constructor & Destructor Documentation

◆ RuntimeServices() [1/5]

template<typename OStream >

AMINO_INTERNAL_FORCEINLINE Amino::RuntimeServices::RuntimeServices ( OStream * os )

inlineexplicit

Constructs a RuntimeServices that logs messages to the given output stream when messages are logged.

Definition at line 136 of file RuntimeServices.h.

References Amino::kInfo.

◆ RuntimeServices() [2/5]

template<typename OStream >

AMINO_INTERNAL_FORCEINLINE Amino::RuntimeServices::RuntimeServices	(	OStream *	os,
		RuntimeMessageCategory	logLevel
	)

inline

Constructs a RuntimeServices that logs messages to the given output stream when messages are logged.

Definition at line 140 of file RuntimeServices.h.

◆ RuntimeServices() [3/5]

AMINO_CORE_SHARED_DECL Amino::RuntimeServices::RuntimeServices	(	LogCallback	cb,
		void *	clientData,
		RuntimeMessageCategory	logLevel = `RuntimeMessageCategory::kInfo`,
		bool	allowConcurrentCalls = `false`
	)

Constructs a RuntimeServices that calls the given callback when messages are logged.

◆ RuntimeServices() [4/5]

Amino::RuntimeServices::RuntimeServices ( const RuntimeServices & rhs )

delete

Copying and moving RuntimeServices is prohibited.

◆ RuntimeServices() [5/5]

Amino::RuntimeServices::RuntimeServices ( RuntimeServices && rhs )

deletenoexcept

Copying and moving RuntimeServices is prohibited.

◆ ~RuntimeServices()

AMINO_CORE_SHARED_DECL Amino::RuntimeServices::~RuntimeServices ( )

Destructor.

Member Function Documentation

◆ getDisabled()

static AMINO_CORE_SHARED_DECL RuntimeServices const & Amino::RuntimeServices::getDisabled ( )

static

Get reference to a "disabled" runtime services.

This RuntimeServices instance does not have logging enabled and has no profilers callbacks. It can be used by C++ library author to create operators that take a RuntimeServices job port and want to write tests for such operators directly (without creating an Amino::Job that would pass said RuntimeServices to the operator).

◆ isLogEnabled()

AMINO_CORE_SHARED_DECL bool Amino::RuntimeServices::isLogEnabled ( RuntimeMessageCategory cat ) const

Check if logging is enabled for a specific category.

Referenced by isLogErrorEnabled(), isLogInfoEnabled(), isLogWarningEnabled(), and log().

◆ isLogErrorEnabled()

bool Amino::RuntimeServices::isLogErrorEnabled ( ) const

inline

Short-hand for isLogEnabled(RuntimeMessageCategory::kError)

Definition at line 178 of file RuntimeServices.h.

References isLogEnabled(), and Amino::kError.

◆ isLogInfoEnabled()

bool Amino::RuntimeServices::isLogInfoEnabled ( ) const

inline

Short-hand for isLogEnabled(RuntimeMessageCategory::kInfo)

Definition at line 168 of file RuntimeServices.h.

References isLogEnabled(), and Amino::kInfo.

◆ isLogWarningEnabled()

bool Amino::RuntimeServices::isLogWarningEnabled ( ) const

inline

Short-hand for isLogEnabled(RuntimeMessageCategory::kWarning)

Definition at line 173 of file RuntimeServices.h.

References isLogEnabled(), and Amino::kWarning.

◆ log() [1/2]

template<typename MsgFunc >

AMINO_INTERNAL_FORCEINLINE enable_if_functor< MsgFunc > Amino::RuntimeServices::log	(	RuntimeMessageCategory	category,
		MsgFunc const &	msgFunc
	)		const

inline

Log a message with a specific category.

Warning: The message should only be generated if logging is enabled.

Can either be called with a functor that generates the message which will be called only if logging is enabled, or with a StringView (in which case it's up to the caller to ensure that logging is enabled with isLogEnabled).

Definition at line 193 of file RuntimeServices.h.

References isLogEnabled().

Referenced by logError(), logInfo(), and logWarning().

◆ log() [2/2]

void Amino::RuntimeServices::log	(	RuntimeMessageCategory	category,
		StringView const &	message
	)		const

inline

Log a message with a specific category.

Warning: The message should only be generated if logging is enabled.

Can either be called with a functor that generates the message which will be called only if logging is enabled, or with a StringView (in which case it's up to the caller to ensure that logging is enabled with isLogEnabled).

Definition at line 203 of file RuntimeServices.h.

References isLogEnabled().

◆ logError() [1/2]

template<typename Msg >

AMINO_INTERNAL_FORCEINLINE enable_if_functor< Msg > Amino::RuntimeServices::logError ( Msg const & msg ) const

inline

Short-hand for log(RuntimeMessageCategory::kError, msg)

Definition at line 224 of file RuntimeServices.h.

References Amino::kError, and log().

◆ logError() [2/2]

AMINO_CORE_SHARED_DECL void Amino::RuntimeServices::logError ( StringView msg ) const

Log the given error message if logging of errors is enabled.

Note: Unlike the other log functions (which should only be called if logging is enabled), logError can be called unconditionally. If logging of error is disabled, it will just be a no-op. The reasonning for this exception is that typically logging of errors should always be enabled, but even if it's not, the performance hit of maybe creating a unused error message string is never a situation where performance would matter.

◆ logInfo()

template<typename Msg >

AMINO_INTERNAL_FORCEINLINE void Amino::RuntimeServices::logInfo ( Msg const & msg ) const

inline

Short-hand for log(RuntimeMessageCategory::kInfo, msg)

Definition at line 212 of file RuntimeServices.h.

References Amino::kInfo, and log().

◆ logWarning()

template<typename Msg >

AMINO_INTERNAL_FORCEINLINE void Amino::RuntimeServices::logWarning ( Msg const & msg ) const

inline

Short-hand for log(RuntimeMessageCategory::kWarning, msg)

Definition at line 218 of file RuntimeServices.h.

References Amino::kWarning, and log().

◆ operator=() [1/2]

RuntimeServices & Amino::RuntimeServices::operator= ( const RuntimeServices & rhs )

delete

Copying and moving RuntimeServices is prohibited.

◆ operator=() [2/2]

RuntimeServices & Amino::RuntimeServices::operator= ( RuntimeServices && rhs )

deletenoexcept

Copying and moving RuntimeServices is prohibited.

◆ profilerEventBegin() [1/2]

AMINO_CORE_SHARED_DECL int Amino::RuntimeServices::profilerEventBegin ( ) const

Notify profiler about beginning of a new named event.

Parameters

eventName The name to associate with profiler event.

Returns: Event ID which started a new profiling block. This event should later be passed to profilerEventEnd method in order to close profiling block.

◆ profilerEventBegin() [2/2]

AMINO_CORE_SHARED_DECL int Amino::RuntimeServices::profilerEventBegin ( const char * eventName ) const

Notify profiler about beginning of a new named event.

Parameters

eventName The name to associate with profiler event.

Returns: Event ID which started a new profiling block. This event should later be passed to profilerEventEnd method in order to close profiling block.

◆ profilerEventEnd()

AMINO_CORE_SHARED_DECL void Amino::RuntimeServices::profilerEventEnd ( int startEventID ) const

Notify profiler about end of an event.

Parameters

startEventID Link to an event ID which started profiling block.

Referenced by Amino::RuntimeServices::ProfilerGuard::~ProfilerGuard().

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ LogCallback

Constructor & Destructor Documentation

◆ RuntimeServices() [1/5]

◆ RuntimeServices() [2/5]

◆ RuntimeServices() [3/5]

◆ RuntimeServices() [4/5]

◆ RuntimeServices() [5/5]

◆ ~RuntimeServices()

Member Function Documentation

◆ getDisabled()

◆ isLogEnabled()

◆ isLogErrorEnabled()

◆ isLogInfoEnabled()

◆ isLogWarningEnabled()

◆ log() [1/2]

◆ log() [2/2]

◆ logError() [1/2]

◆ logError() [2/2]

◆ logInfo()

◆ logWarning()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ profilerEventBegin() [1/2]

◆ profilerEventBegin() [2/2]

◆ profilerEventEnd()