IApp#

Fully qualified name: omni::kit::IApp

class IApp#

Main Kit Application plugin.

It runs all Kit extensions and contains necessary pieces to make them work together: settings, events, python, update loop. Generally an application will bootstrap omni.kit.app by doing the following steps:

Initialize the Carbonite carb::Framework
Load the omni.kit.app plugin with carb::Framework::loadPlugin()
Call IApp::run() which will not return until the application shuts down
Shut down the Carbonite carb::Framework

The kit executable is provided by Carbonite for this purpose. It is a thin bootstrap executable around starting omni.kit.app.

This interface can be acquired from Carbonite with carb::Framework::acquireInterface().

Public Functions

virtual void startup(const AppDesc &desc) = 0#

Starts up the application.

Note

Typically this function is not called directly. Instead use run().

Parameters:: desc – the AppDesc that describes the application

virtual void update() = 0#: Performs one application update loop.

Note

Typically this function is not called directly. Instead use run().

virtual bool isRunning() = 0#

Checks whether the application is still running.

Return values:

true – The application is still running
false – The application has requested to quit and has shut down

virtual int shutdown() = 0#

Shuts down the application.

This function should be called once isRunning() returns false.

Returns:: The application exit code (0 indicates success)

inline int run(const AppDesc &desc)#

A helper function that starts, continually updates, and shuts down the application.

This function essentially performs:

startup(desc);
while (isRunning())
    update();
return shutdown()

Parameters:: desc – the AppDesc that describes the application
Returns:: The application exit code (0 indicates success)

virtual void postQuit(int returnCode = 0) = 0#

Requests application exit.

Note

This does not immediately exit the application. The next call to update() will evaluate the shutdown process.

Note

This shutdown request is cancellable by calling tryCancelShutdown().

Parameters:: returnCode – The requested return code that will be returned by shutdown() once the application exits.

virtual carb::events::IEventStream *getLogEventStream() = 0#

Access the log event stream.

Accesses a carb::events::IEventStream that receives every “error” (or higher) message.

Event Arguments

Event ID is always 0
”source” - The log source, typically plugin name (string)
”level” - The Log Levels (integer)
”filename” - The source file name, such as by __FILE__ (string)
”lineNumber” - The line in the source file, such as by __LINE__ (integer)
”functionName” - The name of the function doing the logging, such as by CARB_PRETTY_FUNCTION (string)
”message” - The log message

Returns:: a carb::events::IEventStream that receives every error (or higher) log message

virtual void toggleLogMessageRecording( bool logMessageRecordingEnabled, ) = 0#

Toggles log message recording.

By default, startup() enables log message recording. Recorded log messages can be replayed on a carb::logging::Logger2 with replayLogMessages().

Parameters:: logMessageRecordingEnabled – if true, future log messages are recorded; if false the log messages are not recorded

virtual RunLoop *getRunLoop(const char *name) = 0#

Access and/or creates a Run Loop by name.

Parameters:: name – The Run Loop to create or find; nullptr is interpreted as kRunLoopDefault
Returns:: the specified RunLoop instance

virtual bool isRunLoopAlive(const char *name) = 0#

Tests whether the specified run loop exists.

Parameters:

name – The Run Loop to find; nullptr is interpreted as kRunLoopDefault

Return values:

true – The specified name has a valid RunLoop
false – The specified name does not have a valid RunLoop

virtual void terminateRunLoop(const char *name, bool block) = 0#

Requests the run loop to terminate.

Note

This calls IRunLoopRunner::onRemoveRunLoop() but the RunLoop itself is not actually removed.

Parameters:

name – The Run Loop to find; nullptr is interpreted as kRunLoopDefault
block – Passed to IRunLoopRunner::onRemoveRunLoop()

inline carb::events::IEventStream *getPreUpdateEventStream( const char *runLoopName = kRunLoopDefault, )#

Helper function to access a Run Loop event stream.

See also

RunLoop

Note

This function calls getRunLoop(), which will create the Runloop if it is not already created.

Warning

This function is deprecated. See Kit Kernel Event System for a reference on converting.

Parameters:: runLoopName – The name of the Run Loop; nullptr is interpreted as kRunLoopDefault
Returns:: A carb::events::IEventStream instance

inline carb::events::IEventStream *getUpdateEventStream( const char *runLoopName = kRunLoopDefault, )#

Helper function to access a Run Loop event stream.

See also

RunLoop

Note

This function calls getRunLoop(), which will create the Runloop if it is not already created.

Warning

This function is deprecated. See Kit Kernel Event System for a reference on converting.

Parameters:: runLoopName – The name of the Run Loop; nullptr is interpreted as kRunLoopDefault
Returns:: A carb::events::IEventStream instance

inline carb::events::IEventStream *getPostUpdateEventStream( const char *runLoopName = kRunLoopDefault, )#

Helper function to access a Run Loop event stream.

See also

RunLoop

Note

This function calls getRunLoop(), which will create the Runloop if it is not already created.

Warning

This function is deprecated. See Kit Kernel Event System for a reference on converting.

Parameters:: runLoopName – The name of the Run Loop; nullptr is interpreted as kRunLoopDefault
Returns:: A carb::events::IEventStream instance

inline carb::events::IEventStream *getMessageBusEventStream( const char *runLoopName = kRunLoopDefault, )#

Helper function to access a Run Loop event stream.

See also

RunLoop

Note

This function calls getRunLoop(), which will create the Runloop if it is not already created.

Warning

This function is deprecated. See Kit Kernel Event System for a reference on converting.

Parameters:: runLoopName – The name of the Run Loop; nullptr is interpreted as kRunLoopDefault
Returns:: A carb::events::IEventStream instance

virtual void setRunLoopRunner(IRunLoopRunner *runner) = 0#

Set particular Run Loop runner implementation.

This function must be called only once during app startup. If no IRunLoopRunner was set application will quit. If IRunLoopRunner is set it becomes responsible for spinning run loops. Application will call in functions on IRunLoopRunner interface to communicate the intent. Sets the current Run Loop Runner instance

See also

RunLoop, IRunLoopRunner

Note

The IRunLoopRunner instance is retained by *this until destruction when the plugin is unloaded. To un-set the IRunLoopRunner instance, call this function with nullptr.

Parameters:: runner – The IRunLoopRunner instance that will receive notifications about Run Loop events; nullptr to un-set the IRunLoopRunner instance.

virtual omni::ext::ExtensionManager *getExtensionManager() = 0#

Accesses the Extension Manager.

Returns:: a pointer to the omni::ext::ExtensionManager instance

virtual IAppScripting *getPythonScripting() = 0#

Accesses the Application Scripting Interface.

Returns:: a pointer to the IAppScripting instance

virtual const char *getBuildVersion() = 0#

Access the build version string.

This is effectively getBuildInfo().kitVersion.c_str().

See also

getBuildInfo(), BuildInfo

Returns:: The build version string

virtual bool isDebugBuild() = 0#

Reports whether the application is running ‘debug’ configuration.

A debug configuration is one where CARB_DEBUG was non-zero at compile time.

Note

This is based on whether the plugin exporting the IApp interface (typically omni.kit.app.plugin) that is currently running was built as a debug configuration.

Return values:

true – CARB_DEBUG was non-zero at compile-time
false – CARB_DEBUG was zero at compile-time (release build)

virtual PlatformInfo getPlatformInfo() = 0#

Retrieves information about the currently running platform.

Returns:: a PlatformInfo struct describing the currently running platform.

virtual double getTimeSinceStart( carb::extras::Timer::Scale timeScale = carb::extras::Timer::Scale::eMilliseconds, ) = 0#

Returns the time elapsed since startup.

This function returns the fractional time that has elapsed since startup() was called, in the requested scale units.

Parameters:: timeScale – Desired time scale for the returned time interval (seconds, milliseconds, etc.)
Returns:: time passed since startup() was most recently called

virtual double getLastUpdateTime() = 0#

Returns the time elapsed since update.

This function returns the fractional time that has elapsed since update() was called (or if update() has not yet been called, since startup() was called), in milliseconds.

Returns:: time passed since update() or startup() (whichever is lower) in milliseconds

virtual uint32_t getUpdateNumber() = 0#

Returns the current update number.

This value is initialized to zero at startup(). Every time the kRunLoopDefault RunLoop::postUpdate carb::events::IEventStream is pumped, this value is incremented by one.

Returns:: the current update number (number of times that the kRunLoopDefault RunLoop has updated)

virtual void printAndLog(const char *message) = 0#

Formats and prints a log message.

The given log message is prepended with the time since start (as via getTimeSinceStart()) and first sent to CARB_LOG_INFO(), and then outputted to stdout if /app/enableStdoutOutput is true (defaults to true).

Parameters:: message – The message to log and print to stdout

virtual carb::events::IEventStream *getShutdownEventStream() = 0#

Accesses the shutdown event stream.

Warning

This function is deprecated in favor of Events 2.0 using carb.eventdispatcher.plugin with named events.

Returns:: The carb::events::IEventStream that contains shutdown events

virtual bool tryCancelShutdown(const char *reason) = 0#

Attempts to cancel a shutdown in progress.

Parameters:

reason – The reason to interrupt shutdown; nullptr is interpreted as an empty string

Return values:

true – The shutdown process was interrupted successfully
false – A noncancellable shutdown is in progress and cannot be interrupted

virtual void postUncancellableQuit(int returnCode) = 0#

Requests application exit that cannot be cancelled.

Note

This does not immediately exit the application. The next call to update() will evaluate the shutdown process.

Note

This shutdown request is not cancellable by calling tryCancelShutdown().

Parameters:: returnCode – The requested return code that will be returned by shutdown() once the application exits.

virtual carb::events::IEventStream *getStartupEventStream() = 0#

Accesses the startup event stream.

Warning

This function is deprecated in favor of Events 2.0 using carb.eventdispatcher.plugin with named events.

Returns:: The carb::events::IEventStream that contains startup events

virtual bool isAppReady() = 0#

Checks whether the app is in a ready state.

Return values:

true – The app is in a ready state; kGlobalEventAppReady has been previously dispatched
false – The app is not yet ready

virtual void delayAppReady(const char *requesterName) = 0#

Instructs the app to delay setting the ready state.

Every update() call resets the delay request; therefore to continue delaying the ready state this function must be called during every update cycle.

Note

This function is only useful prior to achieving the ready state. Calling it after isAppReady() reports true has no effect.

Parameters:: requesterName – (required) The requester who is delaying the ready state, used for logging

virtual const BuildInfo &getBuildInfo() = 0#

Access information about how the plugin was built.

Returns:: A reference to BuildInfo describing version and hash information

virtual const AppInfo &getAppInfo() = 0#

Access information about the running application.

Returns:: A reference to AppInfo describing how the application was started and configured

virtual void restart( const char *const *args = nullptr, size_t argCount = 0, RestartArgsPolicy argsPolicy = RestartArgsPolicy::eAppend, bool uncancellable = false, ) = 0#

Restarts the application.

Quits the current process and starts a new process. The command line arguments can be inherited, appended or replaced.

To quit a regular postQuit() is used, unless uncancellable is set to true in which case postUncancellableQuit() is called.

Parameters:

args – Array of command line arguments for a new process; may be nullptr
argCount – Number of command line arguments in args
argsPolicy – A RestartArgsPolicy value that controls replacing existing args with args, or appending args to the existing args
uncancellable – If true postUncancellableQuit() is used to quit the current process; false will instead of postQuit().

virtual void reportAlive() = 0#

Reports to the hang detector that the app is still working on a task.

Remark

When the hang detector is enabled, it must be ‘ticked’ periodically to avoid detecting a hang. This is done automatically any time a log message is written out or the main loop runs. If anything takes focus away from the main loop for an extended period to perform work though, it must still report to the hang detector that the process is still alive and doing work in order to avoid a hang being detected.

virtual void replayLogMessages(carb::logging::Logger2 *target) = 0#

Replays recorded log messages for the specified target.

This function will call carb::logging::Logger2::handleMessage() for each log message that has been retained.

Parameters:: target – The carb::logging::Logger2 instance to replay messages for

Public Static Functions

static inline constexpr carb::InterfaceDesc getInterfaceDesc( ) noexcept#

Returns information about this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns:: The carb::InterfaceDesc struct with information about this interface.

static inline constexpr carb::InterfaceDesc getLatestInterfaceDesc( ) noexcept#

Returns information about the latest version of this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns:: The carb::InterfaceDesc struct with information about the latest version of this interface.