Wrapper around an IpcService object that provides simpler method calls to the dobby daemon. More...

#include <DobbyProxy.h>

Inheritance diagram for DobbyProxy:

[legend]

Collaboration diagram for DobbyProxy:

[legend]

Classes
struct	StateChangeEvent

Public Member Functions
	DobbyProxy (const std::shared_ptr< AI_IPC::IIpcService > &ipcService, const std::string &serviceName, const std::string &objectName)
	Registers the signal handlers and sets up a threaded dispatcher for started / stopped events.

	~DobbyProxy () final
	Unregisters the signal listeners and flushes the ipc connection.

bool	shutdown () const override
	Asks the daemon to shut itself down.

bool	ping () const override
	Asks the daemon to send back a pong message.

bool	isAlive (const std::chrono::milliseconds &timeout) const override
	Checks if the daemon is alive.

bool	setLogMethod (uint32_t method, int pipeFd) const override
	Sets the logging method used by the daemon.

bool	setLogLevel (int level) const override
	Simply sets the log level in the daemon.

bool	setAIDbusAddress (bool privateBus, const std::string &address) const override
	Sets the AI dbus address for use by the containeriser.

int32_t	startContainerFromSpec (const std::string &id, const std::string &jsonSpec, const std::list< int > &files, const std::string &command="", const std::string &displaySocket="", const std::vector< std::string > &envVars=std::vector< std::string >()) const override
	Starts a container with the given id, json spec file and the list of files.

int32_t	startContainerFromBundle (const std::string &id, const std::string &bundlePath, const std::list< int > &files, const std::string &command="", const std::string &displaySocket="", const std::vector< std::string > &envVars=std::vector< std::string >()) const override
	Starts a container with the given id, bundle path and the list of files.

bool	stopContainer (int32_t cd, bool withPrejudice) const override
	Stops the container with the descriptor (container integer id)

bool	pauseContainer (int32_t cd) const override
	Pauses the container with the descriptor (container integer id)

bool	resumeContainer (int32_t cd) const override
	Resumes the container with the descriptor (container integer id)

bool	hibernateContainer (int32_t descriptor, const std::string &options) const override
	Checkpoints the container with the descriptor (container integer id)

bool	wakeupContainer (int32_t descriptor) const override
	Restores previously checkpointed container with the given id.

bool	addContainerMount (int32_t descriptor, const std::string &source, const std::string &destination, const std::vector< std::string > &mountFlags, const std::string &mountData) const override
	mounts a new host directory/device inside container

bool	addAnnotation (int32_t cd, const std::string &key, const std::string &value) const override
	adds a key value pair to the container annotation

bool	removeAnnotation (int32_t cd, const std::string &key) const override
	removes a key value pair from the container annotation

bool	removeContainerMount (int32_t descriptor, const std::string &source) const override
	unmounts a directory/device inside the container

bool	execInContainer (int32_t cd, const std::string &options, const std::string &command) const override
	Executes a command in the given container.

int	getContainerState (int32_t cd) const override
	Returns the current state of a container.

int	registerListener (const StateChangeListener &listener, const void *cbParams) override
	Installs a callback 'listener' to be notified of changes to the state of the containers.

void	unregisterListener (int tag) override
	Unregisters a listener previously registered.

std::string	getContainerInfo (int32_t descriptor) const override
	Gets the stats / info for the given container.

std::list< std::pair< int32_t, std::string > >	listContainers () const override
	Returns a list of containers.

bool	createBundle (const std::string &id, const std::string &jsonSpec) const override
	Debugging utility that can be used to create a bundle based on a dobby spec file.

std::string	getSpec (int32_t descriptor) const override
	Debugging utility to retrieve the original spec file for a running container (i.e. like the 'virsh dumpxml' command).

std::string	getOCIConfig (int32_t descriptor) const override
	Debugging utility to retrieve the config.json file for a running container (i.e. like the 'virsh dumpxml' command).

Public Member Functions inherited from IDobbyProxy
bool	isAlive () const

int32_t	setLogMethod (uint32_t method) const

int32_t	startContainerFromSpec (const std::string &id, const std::string &jsonSpec) const

int32_t	startContainerFromBundle (const std::string &id, const std::string &bundlePath) const

bool	stopContainer (int32_t descriptor) const

Public Member Functions inherited from AICommon::Notifier< IDobbyProxyEvents >
void	addObserver (const std::shared_ptr< IDobbyProxyEvents > &observer)
	Register interest in receiving updates.

void	removeObserver (const std::shared_ptr< IDobbyProxyEvents > &observer)
	Unregister from updates.

void	setDispatcher (const std::shared_ptr< IDispatcher > &dispatcher_)

Private Member Functions
void	onContainerStartedEvent (const AI_IPC::VariantList &args)
	Called when a org.rdk.dobby.ctrl1.Started event is received from the Dobby 'hypervisor' daemon.

void	onContainerStoppedEvent (const AI_IPC::VariantList &args)
	Called when a org.rdk.dobby.ctrl1.Stopped event is received from the Dobby 'hypervisor' daemon.

void	onContainerHibernatedEvent (const AI_IPC::VariantList &args)
	Called when a org.rdk.dobby.ctrl1.Hibernated event is received from the Dobby 'hypervisor' daemon.

void	onContainerAwokenEvent (const AI_IPC::VariantList &args)
	Called when a org.rdk.dobby.ctrl1.Awoken event is received from the Dobby 'hypervisor' daemon.

bool	invokeMethod (const char interface_, const char method_, const AI_IPC::VariantList &params_, AI_IPC::VariantList &returns_) const
	Invokes a dbus method on the daemon.

void	containerStateChangeThread ()
	Thread function that receives notifications on container state changes and then calls the install handler(s).

Private Attributes
const std::shared_ptr< AI_IPC::IIpcService >	mIpcService

const std::string	mServiceName

const std::string	mObjectName

std::string	mContainerStartedSignal

std::string	mContainerStoppedSignal

std::thread	mStateChangeThread

std::mutex	mStateChangeLock

std::condition_variable	mStateChangeCond

std::deque< StateChangeEvent >	mStateChangeQueue

std::mutex	mListenersLock

AICommon::IDGenerator< 8 >	mListenerIdGen

std::map< int, std::pair< StateChangeListener, const void * > >	mListeners

Additional Inherited Members
Public Types inherited from IDobbyProxy
typedef std::function< void(int32_t, const std::string &, IDobbyProxyEvents::ContainerState, const void *)>	StateChangeListener

Protected Member Functions inherited from AICommon::Notifier< IDobbyProxyEvents >
void	notify (F f, Args &&... args)

void	notify (F f)

Protected Attributes inherited from AICommon::Notifier< IDobbyProxyEvents >
std::shared_ptr< IDispatcher >	dispatcher

Detailed Description

Wrapper around an IpcService object that provides simpler method calls to the dobby daemon.

Member Function Documentation

◆ addAnnotation()

bool DobbyProxy::addAnnotation	(	int32_t	cd,
		const std::string &	key,
		const std::string &	value
	)		const

overridevirtual

adds a key value pair to the container annotation

Parameters

[in]	cd	The container descriptor.
[in]	key	The key string
[in]	value	The value string

Returns: true on success, false on failure.

Implements IDobbyProxy.

◆ addContainerMount()

bool DobbyProxy::addContainerMount	(	int32_t	cd,
		const std::string &	source,
		const std::string &	destination,
		const std::vector< std::string > &	mountFlags,
		const std::string &	mountData
	)		const

overridevirtual

mounts a new host directory/device inside container

Parameters

[in]	cd	The container descriptor.
[in]	source	path of the mount device on the host
[in]	destination	path of the mount on the container
[in]	mountFlags	The mount flags is a vector of srings containing the mount optiosn e.g. "rbind,ro" it should include "bind"
[in]	mountData	string containing the mount data

Returns: true on success, false on failure.

Implements IDobbyProxy.

◆ containerStateChangeThread()

void DobbyProxy::containerStateChangeThread ( )

private

Thread function that receives notifications on container state changes and then calls the install handler(s).

We use a separate thread to notify of container changes because we don't want to block the IpcService thread for long periods of time while code does stuff based on container state change.

◆ createBundle()

bool DobbyProxy::createBundle	(	const std::string &	id,
		const std::string &	jsonSpec
	)		const

overridevirtual

Debugging utility that can be used to create a bundle based on a dobby spec file.

This can be useful for debugging container issues, as it allows the daemon to create the bundle but not actually run it, and therefore it can be run manually from the command line.

Parameters

[in]	id	The name of the bundle to create.
[in]	jsonSpec	The json spec for the bundle.

Returns: true on success, false on failure.

Implements IDobbyProxy.

◆ execInContainer()

bool DobbyProxy::execInContainer	(	int32_t	cd,
		const std::string &	options,
		const std::string &	command
	)		const

overridevirtual

Executes a command in the given container.

Parameters

[in]	cd	The container descriptor.
[in]	options	The options to execute the command with.
[in]	command	The command to execute.

Returns: true on success, false on failure.

Implements IDobbyProxy.

◆ getContainerInfo()

std::string DobbyProxy::getContainerInfo ( int32_t cd ) const

overridevirtual

Gets the stats / info for the given container.

This method returns a string containing info / stats on the given container in json format. The json should look something like the following

{
    "id": "blah",
    "pids": [ 2046, 2064 ],
    "cpu": {
        "usage": {
            "total":734236982,
            "percpu":[348134887,386102095]
        }
    },
    "memory":{
        "user": {
            "limit":41943040,
            "usage":356352,
            "max":524288,
            "failcnt":0
        }
    }
    "gpu":{
        "memory": {
            "limit":41943040,
            "usage":356352,
            "max":524288,
            "failcnt":0
        }
    }
    ...
}

But be warned it may change over time.

Parameters

[in] cd The container descriptor, which is the value returned by startContainer call.

Returns: the json string on success, on failure an empty string.

Implements IDobbyProxy.

◆ getContainerState()

int DobbyProxy::getContainerState ( int32_t cd ) const

overridevirtual

Returns the current state of a container.

The container state will be one of the following values CONTAINER_STATE_INVALID CONTAINER_STATE_STARTING CONTAINER_STATE_RUNNING CONTAINER_STATE_STOPPING CONTAINER_STATE_PAUSED

Parameters

[in] cd The container descriptor, which is the value returned by startContainer call.

Returns: on success a positive state value, on failure -1.

Implements IDobbyProxy.

◆ getOCIConfig()

std::string DobbyProxy::getOCIConfig ( int32_t cd ) const

overridevirtual

Debugging utility to retrieve the config.json file for a running container (i.e. like the 'virsh dumpxml' command).

Parameters

[in] cd The container descriptor, which is the value returned by startContainer call.

Returns: a string containing the config.json, on failure an empty string.

Implements IDobbyProxy.

◆ getSpec()

std::string DobbyProxy::getSpec ( int32_t cd ) const

overridevirtual

Debugging utility to retrieve the original spec file for a running container (i.e. like the 'virsh dumpxml' command).

Parameters

[in] cd The container descriptor, which is the value returned by startContainer call.

Returns: a string containing the spec json, on failure an empty string.

Implements IDobbyProxy.

◆ hibernateContainer()

bool DobbyProxy::hibernateContainer	(	int32_t	cd,
		const std::string &	options
	)		const

overridevirtual

Checkpoints the container with the descriptor (container integer id)

Parameters

[in] cd The container descriptor, which is the value returned by startContainer call.

Returns: true on success, false on failure.

Implements IDobbyProxy.

◆ invokeMethod()

bool DobbyProxy::invokeMethod	(	const char *	interface_,
		const char *	method_,
		const AI_IPC::VariantList &	params_,
		AI_IPC::VariantList &	returns_
	)		const

private

Invokes a dbus method on the daemon.

The method is invoked with the service name and object name that was set in the constructor.

Parameters

[in]	interface_	The dbus interface name of the method
[in]	method_	The dbus method name to invoke
[in]	params_	The list of args to apply
[in]	returns_	Reference variable that the results will be put in on success.

Returns: true on success, false on failure.

◆ isAlive()

bool DobbyProxy::isAlive ( const std::chrono::milliseconds & timeout ) const

overridevirtual

Checks if the daemon is alive.

This function just polls on the service becoming available on the bus, the poll period is 20ms and it will keep polling until either the service is present or the timeout is exceeded.

Parameters

[in] timeout The number of milliseconds to wait for the service.

Returns: true on success, false on failure.

Implements IDobbyProxy.

◆ listContainers()

std::list< std::pair< int32_t, std::string > > DobbyProxy::listContainers ( ) const

overridevirtual

Returns a list of containers.

Each element in the returned list is a pair of container descriptor (integer) and the string id of the container.

This returns a list of containers the daemon knows about, this is not necessarily only running containers, it will include containers that are in the starting and stopping states. To determine the state of a container use the DobbyProxy::getContainerState method.

Returns: a list of all known containers.

Implements IDobbyProxy.

◆ onContainerAwokenEvent()

void DobbyProxy::onContainerAwokenEvent ( const AI_IPC::VariantList & args )

private

Called when a org.rdk.dobby.ctrl1.Awoken event is received from the Dobby 'hypervisor' daemon.

We parse the event data and if it makes sense we bounce this event up to any listeners using the Notifier / Observer pattern.

Parameters

[in] args The args sent with the event.

◆ onContainerHibernatedEvent()

void DobbyProxy::onContainerHibernatedEvent ( const AI_IPC::VariantList & args )

private

Called when a org.rdk.dobby.ctrl1.Hibernated event is received from the Dobby 'hypervisor' daemon.

We parse the event data and if it makes sense we bounce this event up to any listeners using the Notifier / Observer pattern.

Parameters

[in] args The args sent with the event.

◆ onContainerStartedEvent()

void DobbyProxy::onContainerStartedEvent ( const AI_IPC::VariantList & args )

private

Called when a org.rdk.dobby.ctrl1.Started event is received from the Dobby 'hypervisor' daemon.

We parse the event data and if it makes sense we bounce this event up to any listeners using the Notifier / Observer pattern.

Parameters

[in] args The args sent with the event.

◆ onContainerStoppedEvent()

void DobbyProxy::onContainerStoppedEvent ( const AI_IPC::VariantList & args )

private

Called when a org.rdk.dobby.ctrl1.Stopped event is received from the Dobby 'hypervisor' daemon.

We parse the event data and if it makes sense we bounce this event up to any listeners using the Notifier / Observer pattern.

Parameters

[in] args The args sent with the event.

◆ pauseContainer()

bool DobbyProxy::pauseContainer ( int32_t cd ) const

overridevirtual

Pauses the container with the descriptor (container integer id)

Warning: A positive response doesn't mean the container has paused, rather it means the container has successfully been asked to pause. To determine when a container has paused you need to observe the container status events.

Parameters

[in] cd The container descriptor, which is the value returned by startContainer call.

Returns: true on success, false on failure.

Implements IDobbyProxy.

◆ ping()

bool DobbyProxy::ping ( ) const

overridevirtual

Asks the daemon to send back a pong message.

Returns: true on success, false on failure.

Implements IDobbyProxy.

◆ registerListener()

int DobbyProxy::registerListener	(	const StateChangeListener &	listener,
		const void *	cbParams
	)

overridevirtual

Installs a callback 'listener' to be notified of changes to the state of the containers.

On success a positive id value will be returned for the listener, this should then be passed to unregisterListener(...) to release the listener.

Parameters

[in]	listener	The callback to install.
[in]	cbParams	Pointer to custom parameters.

Implements IDobbyProxy.

◆ removeAnnotation()

bool DobbyProxy::removeAnnotation	(	int32_t	cd,
		const std::string &	key
	)		const

overridevirtual

removes a key value pair from the container annotation

Parameters

[in]	cd	The container descriptor.
[in]	key	The key string

Returns: true on success, false on failure.

Implements IDobbyProxy.

◆ removeContainerMount()

bool DobbyProxy::removeContainerMount	(	int32_t	cd,
		const std::string &	source
	)		const

overridevirtual

unmounts a directory/device inside the container

Parameters

[in]	cd	The container descriptor.
[in]	source	path of the mount device on the host

Returns: true on success, false on failure.

Implements IDobbyProxy.

◆ resumeContainer()

bool DobbyProxy::resumeContainer ( int32_t cd ) const

overridevirtual

Resumes the container with the descriptor (container integer id)

Parameters

[in] cd The container descriptor, which is the value returned by startContainer call.

Returns: true on success, false on failure.

Implements IDobbyProxy.

◆ setAIDbusAddress()

bool DobbyProxy::setAIDbusAddress	(	bool	privateBus,
		const std::string &	address
	)		const

overridevirtual

Sets the AI dbus address for use by the containeriser.

The dobby daemon itself doesn't use the AI dbuses, rather it stores them and provides the addresses to any plugins and any container that requested them in it's spec file.

Parameters

[in]	privateBus	true if the address is for the AI private bus, otherwise the AI public bus.
[in]	address	The dbus address to set.

Returns: true on success, false on failure.

Implements IDobbyProxy.

◆ setLogLevel()

bool DobbyProxy::setLogLevel ( int level ) const

overridevirtual

Simply sets the log level in the daemon.

The value should be one of the constants from the Logging.h header, i.e.

AI_DEBUG_LEVEL_FATAL
AI_DEBUG_LEVEL_ERROR
AI_DEBUG_LEVEL_WARNING
AI_DEBUG_LEVEL_MILESTONE
AI_DEBUG_LEVEL_INFO
AI_DEBUG_LEVEL_DEBUG

Parameters

[in] level The log level to set

Returns: true on success, false on failure.

Implements IDobbyProxy.

◆ setLogMethod()

bool DobbyProxy::setLogMethod	(	uint32_t	method,
		int	pipeFd
	)		const

overridevirtual

Sets the logging method used by the daemon.

By default the dobby daemon logs to syslog, by sending a valid pipe fd to the daemon it will switch to routing all it's logs via the supplied pipe.

This is typically called by DobbyFactory right after the daemon is launched.

The log method should be one of the following values:

DOBBY_LOG_NULL     : disable all diag based log output
DOBBY_LOG_SYSLOG   : route diag logging to syslog
DOBBY_LOG_ETHANLOG : route diag logging to the supplied pipe

Parameters

[in]	method	The log method to use.
[in]	pipeFd	The write fd of the pipe.

Returns: true on success, false on failure.

Implements IDobbyProxy.

◆ shutdown()

bool DobbyProxy::shutdown ( ) const

overridevirtual

Asks the daemon to shut itself down.

The daemon is expected to reply with a value before shutting down.

Returns: true on success, false on failure.

Implements IDobbyProxy.

◆ startContainerFromBundle()

int32_t DobbyProxy::startContainerFromBundle	(	const std::string &	id,
		const std::string &	bundlePath,
		const std::list< int > &	files,
		const std::string &	command = `""`,
		const std::string &	displaySocket = `""`,
		const std::vector< std::string > &	envVars = `std::vector<std::string>()`
	)		const

overridevirtual

Starts a container with the given id, bundle path and the list of files.

Parameters

[in]	id	The string id of the container, this should not have any spaces and only container alphanumeric characters plus '.' and '-'.
[in]	bundlePath	Path to the container bundle.
[in]	files	An array of file descriptors to pass into the container construction, can be empty.
[in]	command	Custom command to run inside the container, overriding the args in the config file
[in]	displaySocket	Path to the westeros display socket to mount into the container

Returns: on success a container descriptor which is a number greater than 0, on failure a negative error code.

Implements IDobbyProxy.

◆ startContainerFromSpec()

int32_t DobbyProxy::startContainerFromSpec	(	const std::string &	id,
		const std::string &	jsonSpec,
		const std::list< int > &	files,
		const std::string &	command = `""`,
		const std::string &	displaySocket = `""`,
		const std::vector< std::string > &	envVars = `std::vector<std::string>()`
	)		const

overridevirtual

Starts a container with the given id, json spec file and the list of files.

Parameters

[in]	id	The string id of the container, this should not have any spaces and only container alphanumeric characters plus '.' and '-'.
[in]	jsonSpec	The (large) string containing the json formatted container spec.
[in]	files	An array of file descriptors to pass into the container construction, can be empty.
[in]	command	Custom command to run inside the container, overriding the args in the config file
[in]	displaySocket	Path to the westeros display socket to mount into the container

Returns: on success a container descriptor which is a number greater than 0, on failure a negative error code.

Implements IDobbyProxy.

◆ stopContainer()

bool DobbyProxy::stopContainer	(	int32_t	cd,
		bool	withPrejudice
	)		const

overridevirtual

Stops the container with the descriptor (container integer id)

Warning: A positive response doesn't mean the container has stopped, rather it means the container has successfully been asked to stop. To determine when a container has stopped you need to observe the container status events.

Parameters

[in]	cd	The container descriptor, which is the value returned by startContainer call.
[in]	withPrejudice	If true the container is terminated using a SIGKILL, the default is false in which case the container is asked to close with a SIGTERM.

Returns: true on success, false on failure.

Implements IDobbyProxy.

◆ unregisterListener()

void DobbyProxy::unregisterListener ( int id )

overridevirtual

Unregisters a listener previously registered.

Do no call this from the context of a listener callback.

Parameters

[in] id The id of the listener returned by registerListener.

Implements IDobbyProxy.

◆ wakeupContainer()

bool DobbyProxy::wakeupContainer ( int32_t cd ) const

overridevirtual

Restores previously checkpointed container with the given id.

Parameters

[in] id The string id of the container, this should not have any spaces and only container alphanumeric characters plus '.' and '-'.

Returns: true on success, false on failure.

Implements IDobbyProxy.

The documentation for this class was generated from the following files:

client/lib/include/DobbyProxy.h
client/lib/source/DobbyProxy.cpp

Classes

Public Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ addAnnotation()

◆ addContainerMount()

◆ containerStateChangeThread()

◆ createBundle()

◆ execInContainer()

◆ getContainerInfo()

◆ getContainerState()

◆ getOCIConfig()

◆ getSpec()

◆ hibernateContainer()

◆ invokeMethod()

◆ isAlive()

◆ listContainers()

◆ onContainerAwokenEvent()

◆ onContainerHibernatedEvent()

◆ onContainerStartedEvent()

◆ onContainerStoppedEvent()

◆ pauseContainer()

◆ ping()

◆ registerListener()

◆ removeAnnotation()

◆ removeContainerMount()

◆ resumeContainer()

◆ setAIDbusAddress()

◆ setLogLevel()

◆ setLogMethod()

◆ shutdown()

◆ startContainerFromBundle()

◆ startContainerFromSpec()

◆ stopContainer()

◆ unregisterListener()

◆ wakeupContainer()