ContainerInterface Class

An interface for custom container instances. More...

Header: #include <ContainerInterface>
Inherits: QObject

Public Types

enum ExitStatus { NormalExit, CrashExit, ForcedExit }
enum ProcessError { }
enum RunState { NotRunning, StartingUp, Running, ShuttingDown }

Public Functions

virtual bool attachApplication(const QVariantMap &application) = 0
virtual QString controlGroup() const = 0
virtual bool isReady() const = 0
virtual void kill() = 0
virtual QString mapContainerPathToHost(const QString &containerPath) const = 0
virtual QString mapHostPathToContainer(const QString &hostPath) const = 0
virtual qint64 processId() const = 0
virtual void setBaseDirectory(const QString &baseDirectory) = 0
virtual bool setControlGroup(const QString &groupName) = 0
virtual bool setProgram(const QString &program) = 0
virtual bool start(const QStringList &arguments, const QMap<QString, QString> &runtimeEnvironment, const QVariantMap &amConfig) = 0
virtual ContainerInterface::RunState state() const = 0
virtual void terminate() = 0

Signals

void errorOccured(ContainerInterface::ProcessError processError)
void finished(int exitCode, ContainerInterface::ExitStatus exitStatus)
void ready()
void started()
void stateChanged(ContainerInterface::RunState state)

Detailed Description

A pointer to this interface should be returned from a successful call to ContainerManagerInterface::create()

Each instance of this class corresponds to a single application or - if supported - a single quick-launcher instance.

The interface is closely modelled after QProcess and even reuses many of QProcess' enums.

Member Type Documentation

enum ContainerInterface::ExitStatus

This enum describes the different exit statuses of an application.

ConstantValueDescription
ContainerInterface::NormalExit0The application exited normally.
ContainerInterface::CrashExit1The application crashed.
ContainerInterface::ForcedExit2The application was killed by the application manager, since it ignored the quit request originating from a call to ApplicationManager::stopApplication.

See also ApplicationObject::lastExitStatus and QProcess::ExitStatus.

enum ContainerInterface::ProcessError

This enum describes the different types of errors that are reported by an application.

Its names and values are an exact copy of QProcess::ProcessError.

enum ContainerInterface::RunState

This enum describes the different run states of an application.

ConstantValueDescription
ContainerInterface::NotRunning0The application has not been started yet.
ContainerInterface::StartingUp1The application has been started and is initializing.
ContainerInterface::Running2The application is running.
ContainerInterface::ShuttingDown3The application has been stopped and is cleaning up (in multi-process mode this state is only reached if the application is terminating gracefully).

See also ApplicationObject::runState and QProcess::ProcessState.

Member Function Documentation

[pure virtual] bool ContainerInterface::attachApplication(const QVariantMap &application)

The application manager calls this function, when an application has to be attached to this container instance: the application map closely corresponds to the application's meta-data returned from the ApplicationManager::get() method:

These fields are not available for this function:

Name
isRunning
isStartingUp
isShuttingDown
isLocked
isUpdating
isRemovable
updateProgress
application
lastExitCode
lastExitStatus

These fields are added on top of what ApplicationManager::get() provides:

NameDescription
codeDirThe directory where the application's code is located.
manifestDirThe directory where the application's manifest (info.yaml) is located.
applicationPropertiesA map with all application properties as seen in the manifest.

[pure virtual] QString ContainerInterface::controlGroup() const

This function needs to return which control group the application's container is in. The control group name returned by this function is not the low-level name used by the operating system, but an abstraction. See the container documentation for more details on how to setup this mapping.

Note: If your custom container solution does not support cgroups, then simply return an empty QString here.

See also setControlGroup().

[signal] void ContainerInterface::errorOccured(ContainerInterface::ProcessError processError)

This signal needs to be emitted when an error occurs with the process within the container. The specified processError describes the type of error that occurred.

See also QProcess::errorOccurred().

[signal] void ContainerInterface::finished(int exitCode, ContainerInterface::ExitStatus exitStatus)

This signal has to be emitted when the process within the container finishes. The exitStatus parameter gives an indication why the process exited - in case of a normal exit, the exitCode will be the return value of the process' main() function.

See also QProcess::finished().

[pure virtual] bool ContainerInterface::isReady() const

Needs to return true if the container is ready for starting the application's program or false otherwise.

See also ready().

[pure virtual] void ContainerInterface::kill()

Called by the application manager, if it wants to kill the current process within the container, causing it to exit immediately.

On Unix, the equivalent would be sending a SIGKILL signal.

See also terminate().

[pure virtual] QString ContainerInterface::mapContainerPathToHost(const QString &containerPath) const

The application manager will call this function whenever paths have to be mapped between the filesystem namespace of the application's container and the application manager.

You can simply return containerPath, if both are running in the same namespace.

[pure virtual] QString ContainerInterface::mapHostPathToContainer(const QString &hostPath) const

The application manager will call this function whenever paths have to be mapped between the filesystem namespace of the application manager and the application's container.

You can simply return hostPath, if both are running in the same namespace.

[pure virtual] qint64 ContainerInterface::processId() const

Should return the native process identifier for the running process, if available. If no process is currently running, 0 is returned.

Note: The process identifier needs to be translated into the application manager's PID namespace, if the container solution is managing its own, private namespace.

Note: This identifier is needed to support security features within the application manager: Having a valid PID for every container is necessary (a) in order for Wayland windows to only be accepted when coming from known PIDs and (b) for system services to retrieve meta-data on applications via the D-Bus call ApplicationManager::identifyApplication(). If you need a quick workaround during development for Wayland to accept windows from any PID, then run the application manager with --no-security.

[signal] void ContainerInterface::ready()

If the container implementation needs to do potentially expensive initialization work in the background, it can tell the application manager to delay calling start() until it has emitted this signal.

In case this is not needed, then you never have to emit this signal, but you are expected to always return true from isReady().

See also isReady().

[pure virtual] void ContainerInterface::setBaseDirectory(const QString &baseDirectory)

Called by the application manager to set the initial working directory for the process within the container to baseDirectory.

[pure virtual] bool ContainerInterface::setControlGroup(const QString &groupName)

This function is expected to move the application's container into a control group. The groupName is not the low-level name used by the operating system, but an abstraction. See the container documentation for more details on how to setup this mapping. Returns true if the call was successful or false otherwise.

Note: If your custom container solution does not support cgroups, then simply return false here.

See also controlGroup().

[pure virtual] bool ContainerInterface::setProgram(const QString &program)

This function is called by the application manager in order to set the program to execute when starting the process. This function will be called before start(). Needs to return true if program is valid within this container or false otherwise.

See also start().

[pure virtual] bool ContainerInterface::start(const QStringList &arguments, const QMap<QString, QString> &runtimeEnvironment, const QVariantMap &amConfig)

This function will be called to asynchronously start the application's program (as set by setProgram()), with the additional command line arguments and with the additional environment variables from runtimeEnvironment.

The runtimeEnvironment is a string map for environment variables and their values. An empty value in this map means, that the environment variable denoted by its key shall be unset. The native runtime will define these variables by default:

NameDescription
QT_QPA_PLATFORMSet to wayland.
QT_IM_MODULEEmpty (unset), which results in applications using the default wayland text input method.
QT_SCALE_FACTOREmpty (unset), to prevent scaling of wayland clients relative to the compositor. Otherwise running the application manager on a 4K desktop with scaling would result in double-scaled applications within the application manager.
QT_WAYLAND_SHELL_INTEGRATIONSet to xdg-shell. This is the preferred wayland shell integration.
AM_CONFIGA YAML, UTF-8 string encoded version of the amConfig map (see below).
AM_NO_DLT_LOGGINGOnly set to 1, if DLT logging is to be switched off (otherwise not set at all). The same information is available via amConfig (see below), but some applications and launchers may need this information as early as possible.

The amConfig map is a collection of settings that are communicated to the program from the application manager. The same information is already string encoded in the AM_CONFIG environment variable within runtimeEnvironment, but it would be tedious to reparse that YAML fragment in the container plugin.

These are the currently defined fields in amConfig:

NameTypeDescription
baseDirstringThe base directory from where the application manager was started. Needed for relative import paths.
dbus/p2pstringThe D-Bus address for the peer-to-peer bus between the application manager and this application.
dbus/org.freedesktop.NotificationsstringThe D-Bus address for the notification interface. Can either be session (default), system or an actual D-Bus bus address.
logging/dltboolLogging should be done via DLT, if this is set to true.
logging/ruleslist<string>The Qt logging rules as set in the application manager's main config.
systemPropertiesobjectThe project specific system properties that were set via the application manager's main config file.
runtimeConfigurationobjectThe Runtime configuration used for this application.
ui/slowAnimationsboolSet to true, if animations should be slowed down.
ui/iconThemeNamestringIf set in the application manager, this will forward the icon theme name to the application (see QIcon::setThemeName()).
ui/iconThemeSearchPathsstringIf set in the application manager, this will forward the icon theme search paths to the application (see QIcon::setThemeSearchPaths()).
ui/openglobjectIf a specific OpenGL configuration is requested either globally for the application manager or just for this application (via its info.yaml manifest), this field will contain the required OpenGL configuration.

The application manager will only ever call this function once for any given instance.

This function should return true in case it succeeded or false otherwise. In case it returns true, the implementation needs to either emit the started() or errorOccurred() signal (can be delayed) in response to this call.

See also QProcess::start().

[signal] void ContainerInterface::started()

This signal has to be emitted when the process within the container has started and state() returns QProcess::Running.

See also QProcess::started().

[pure virtual] ContainerInterface::RunState ContainerInterface::state() const

This function needs to return the current state of the process within the container.

See also stateChanged(), errorOccured(), and QProcess::state().

[signal] void ContainerInterface::stateChanged(ContainerInterface::RunState state)

This signal needs to be emitted whenever the state of the process within the container changes.

[pure virtual] void ContainerInterface::terminate()

Called by the application manager, when attempting to terminate the process within the container.

The process may not exit as a result of calling this function. On Unix, the equivalent would be sending a SIGTERM signal.

See also kill().

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.