An abstraction of concrete container implementations. More...

#include <softwarecontainer.h>

Inheritance diagram for softwarecontainer::SoftwareContainer:

Collaboration diagram for softwarecontainer::SoftwareContainer:

Public Member Functions
	LOG_DECLARE_CLASS_CONTEXT ("PCL","SoftwareContainer library")

	SoftwareContainer (const ContainerID id, std::unique_ptr< const SoftwareContainerConfig > config)
	Creates a new SoftwareContainer instance. More...

bool	startGateways (const GatewayConfiguration &configs)
	Starts the Gateways by setting the gateway configurations and activating the configured gateway. More...

std::shared_ptr< FunctionJob >	createFunctionJob (const std::function< int()> fun)
	Create a job that can run a function in a container. More...

std::shared_ptr< CommandJob >	createCommandJob (const std::string &command)
	Create a job that can run a command in a container. More...

void	shutdown ()
	Shut down the container. More...

void	shutdown (unsigned int timeout)
	Shot down the container with an explicit timeout. More...

void	suspend ()
	Suspend the container. More...

void	resume ()
	Resume a suspended container. More...

bool	bindMount (const std::string &pathOnHost, const std::string &pathInContainer, bool readonly=true)
	Should only be called on containers in state 'READY'. More...

ObservableProperty< ContainerState > &	getContainerState ()
	Get the state of this container instance. More...

bool	previouslyConfigured ()
	Indicates if gateways have been configured previously. More...

Private Member Functions
bool	bindMount (const std::string &src, const std::string &dst, const std::string &tmpContainerRoot, bool readOnly, bool writeBufferEnabled=false)
	bindMount Bind mount a src directory to another position dst. More...

bool	tmpfsMount (const std::string dst, const int maxSize)
	tmpfsMount Mount a tmpfs in the dst path and limit size of the tmpfs to maxSize More...

bool	writeToFile (const std::string &path, const std::string &content)

void	markFileForDeletion (const std::string &path)

bool	overlayMount (const std::string &lower, const std::string &upper, const std::string &work, const std::string &dst)
	overlayMount Mount a directory with an overlay on top of it. More...

bool	syncOverlayMount (const std::string &lower, const std::string &upper)
	syncOverlayMount Copy the directory structure from upper layer to the lower layer More...

bool	createSharedMountPoint (const std::string &path)
	createSharedMountPoint Make the mount point shared, ie new mount points created in one bind mount will also be created in the other mount point. More...

bool	pathInList (const std::string path)
	checks whether given path is already added to clean up handlers or not More...

Private Attributes
std::vector< std::unique_ptr< CleanUpHandler > >	m_cleanupHandlers
	m_cleanupHandlers A vector of cleanupHandlers added during the lifetime of the FileToolKitWithUndo that will be run from the destructor. More...

std::vector< std::unique_ptr< CreateDir > >	m_createDirList
	m_createDirList A vector of CreateDir classes. More...

Detailed Description

An abstraction of concrete container implementations.

SoftwareContainer (SC) can be in various states. Some method calls are only valid when SC is in a particular state.

States:

READY
SUSPENDED
TERMINATED
INVALID

When SC is in state 'READY', all relevant gateways are added and the underlying container implementation is created and initialized. In this state, the following methods are allowed to be called:

suspend() - successful call triggers transition to SUSPENDED
shutdown() - successful call triggers trasition to TERMINATED
bindMount()
startGateways()
createFunctionJob()
createCommandJob()

When SC is in state 'SUSPENDED', the following method calls are allowed to be called:

shutdown() - successful call triggers a transition to TERMINATED
resume() - successful call triggers a transition to READY

When SC is in state 'INVALID', something has gone wrong in the underlying container implementation and the container should be considered to be in a broken state from which it cannot recover.

The following methods are allowed to be called in every state:

getContainerState()

If a call is made when SC is in an inappropriate state, the InvalidOperationError exception is thrown. This error does not mean that the intended operation was erroneous, since the operation can't even be performed in the current state.

It is an error to call a method on a state which would be the result of the operation, e.g. calling suspend on a suspended container is an invalid operation. The reason for this is that the interface should be clear that there can't be any side effects or other changes when making a call which is redundant.

Definition at line 165 of file softwarecontainer.h.

Constructor & Destructor Documentation

softwarecontainer::SoftwareContainer::SoftwareContainer	(	const ContainerID	id,
		std::unique_ptr< const SoftwareContainerConfig >	config
	)

Creates a new SoftwareContainer instance.

On successful creation, the state will be 'READY'.

Parameters

id	The containerID to use.
config	An object holding all needed settings for the container

Exceptions

SoftwareContainerError If unable to set up the needed directories or network settings for this container, or if anything goes wrong when creating and initializing the underlying container implementation.

Definition at line 58 of file softwarecontainer.cpp.

References softwarecontainer::FileToolkitWithUndo::tmpfsMount().

                                                                                          :
     m_containerID(id),
     m_config(std::move(config)),
     m_previouslyConfigured(false)
 {
     m_containerRoot = buildPath(m_config->sharedMountsDir(), "SC-" + std::to_string(id));
     m_tmpfsSize = 100485760;
     checkContainerRoot(m_containerRoot);
     if (m_config->writeBufferEnabled()) {
         if (m_config->temporaryFileSystemWriteBufferEnableds()) {
             m_tmpfsSize = m_config->temporaryFileSystemSize();
         }
         tmpfsMount(m_containerRoot, m_tmpfsSize);
     }
 
 #ifdef ENABLE_NETWORKGATEWAY
     checkNetworkSettings();
 #endif // ENABLE_NETWORKGATEWAY
 
     m_container = std::shared_ptr<ContainerAbstractInterface>(
         new Container("SC-" + std::to_string(id),
                       m_config->containerConfigPath(),
                       m_containerRoot,
                       m_config->writeBufferEnabled(),
                       m_config->containerShutdownTimeout()));
 
     if(!init()) {
         throw SoftwareContainerError("Could not initialize SoftwareContainer, container ID: "
                                      + std::to_string(id));
     }
 
     m_containerState.setValueNotify(ContainerState::READY);
 }

Here is the call graph for this function:

Member Function Documentation

bool softwarecontainer::SoftwareContainer::startGateways ( const GatewayConfiguration & configs )

virtual

Starts the Gateways by setting the gateway configurations and activating the configured gateway.

This should only be called on containers in state 'READY'

Returns: true If configuration and activation was successful; false If configuration or activation encountered a non-fatal error

Exceptions

GatewayError	If configuration or activation of any gateway encountered a fatal error.
InvalidOperationError	If called when state is not 'READY'
InvalidContainerError	If the container is in state 'INVALID'

Implements softwarecontainer::SoftwareContainerAbstractInterface.

Definition at line 174 of file softwarecontainer.cpp.

 {
     assertValidState();
 
     if (m_containerState != ContainerState::READY) {
         std::string message = "Invalid to start gateways on non ready container " +
                               std::string(m_container->id());
         log_error() << message;
         throw InvalidOperationError(message);
     }
 
     if (!configureGateways(gwConfig)) {
         log_error() << "Could not configure Gateways";
         return false;
     }
 
     if (!activateGateways()) {
         log_error() << "Could not activate Gateways";
         return false;
     }
 
     // Keep track of if user has called this method at least once
     m_previouslyConfigured = true;
 
     return true;
 }

std::shared_ptr< FunctionJob > softwarecontainer::SoftwareContainer::createFunctionJob ( const std::function< int()> fun )

Create a job that can run a function in a container.

This should only be called on containers in state 'READY'

Exceptions

InvalidOperationError	If called when state is not 'READY'
InvalidContainerError	If the container is in state 'INVALID'

Definition at line 391 of file softwarecontainer.cpp.

 {
     assertValidState();
 
     if (m_containerState != ContainerState::READY) {
         std::string message = "Invalid to execute code in non ready container " +
                               std::string(m_container->id());
         log_error() << message;
         throw InvalidOperationError(message);
     }
 
     return std::make_shared<FunctionJob>(m_container, fun);
 }

std::shared_ptr< CommandJob > softwarecontainer::SoftwareContainer::createCommandJob ( const std::string & command )

virtual

Create a job that can run a command in a container.

This should only be called on containers in state 'READY'

Exceptions

InvalidOperationError	If called when state is not 'READY'
InvalidContainerError	If the container is in state 'INVALID'

Implements softwarecontainer::SoftwareContainerAbstractInterface.

Definition at line 405 of file softwarecontainer.cpp.

 {
     assertValidState();
 
     if (m_containerState != ContainerState::READY) {
         std::string message = "Invalid to execute code in non ready container " +
                               std::string(m_container->id());
         log_error() << message;
         throw InvalidOperationError(message);
     }
 
     return std::make_shared<CommandJob>(m_container, command);
 }

void softwarecontainer::SoftwareContainer::shutdown ( )

Shut down the container.

A successful call to this method triggers a transition to state 'TERMINATED'.

This shoud only be called on containers in state 'READY' or 'SUSPENDED'

If the operation is not successful, the container state will be set to 'INVALID'. This means that this container instance should be considered broken.

Exceptions

ContainerError	If operation was unsucessful InvalidOperationError If called when state is not 'READY' or 'SUSPENDED'
InvalidContainerError	If the container is in state 'INVALID'

Definition at line 277 of file softwarecontainer.cpp.

 {
     return shutdown(m_config->containerShutdownTimeout());
 }

void softwarecontainer::SoftwareContainer::shutdown ( unsigned int timeout )

virtual

Shot down the container with an explicit timeout.

Same as the shutdown() method, but the value passed will override any timeout value in the main configuration.

Parameters

timeout Seconds to use for timeout

Implements softwarecontainer::SoftwareContainerAbstractInterface.

Definition at line 282 of file softwarecontainer.cpp.

 {
     assertValidState();
 
     log_debug() << "shutdown called";
 
     if (m_containerState != ContainerState::READY
         && m_containerState != ContainerState::SUSPENDED)
     {
         std::string message = "Invalid to shut down container which is not ready or suspended " +
                               std::string(m_container->id());
         log_error() << message;
         throw InvalidOperationError(message);
     }
 
     if(!shutdownGateways()) {
         log_error() << "Could not shut down all gateways cleanly, check the log";
     }
 
     if(!m_container->destroy(timeout)) {
         std::string message = "Could not destroy the container during shutdown " +
                               std::string(m_container->id());
         log_error() << message;
         m_containerState.setValueNotify(ContainerState::INVALID);
         throw ContainerError(message);
     }
 
     m_containerState.setValueNotify(ContainerState::TERMINATED);
 }

void softwarecontainer::SoftwareContainer::suspend ( )

virtual

Suspend the container.

This suspends any execution inside the container until resume is called. A successful call to this method triggers a transition to state 'SUSPENDED'.

If the operation is not successful, the container state will be set to 'INVALID'. This means that this container instance should be considered broken.

Exceptions

ContainerError	If operation was unsuccessful
InvalidOperationError	If called when state is not 'READY'
InvalidContainerError	If the container is in state 'INVALID'

Implements softwarecontainer::SoftwareContainerAbstractInterface.

Definition at line 312 of file softwarecontainer.cpp.

 {
     assertValidState();
 
     std::string id = std::string(m_container->id());
 
     if (m_containerState != ContainerState::READY) {
         std::string message = "Invalid to suspend non ready container " + id;
         log_error() << message;
         throw InvalidOperationError(message);
     }
 
     if (!m_container->suspend()) {
         std::string message =  "Failed to suspend container " + id;
         log_error() << message;
         m_containerState.setValueNotify(ContainerState::INVALID);
         throw ContainerError(message);
     }
 
     log_debug() << "Suspended container " << id;
     m_containerState.setValueNotify(ContainerState::SUSPENDED);
 }

void softwarecontainer::SoftwareContainer::resume ( )

virtual

Resume a suspended container.

This resumes execution of a container that was suspended. A successful call to this method will trigger a transition to state 'READY'.

If the operation is not successful, the container state will be set to 'INVALID'. This means that this container instance should be considered broken.

Exceptions

ContainerError	If operation was unsucessful
InvalidOperationError	If called when state is not 'SUSPENDED'
InvalidContainerError	If the container is in state 'INVALID'

Implements softwarecontainer::SoftwareContainerAbstractInterface.

Definition at line 335 of file softwarecontainer.cpp.

 {
     assertValidState();
     std::string id = std::string(m_container->id());
 
     if (m_containerState != ContainerState::SUSPENDED) {
         std::string message =  "Invalid to resume non suspended container " + id;
         log_error() << message;
         throw InvalidOperationError(message);
     }
 
     if (!m_container->resume()) {
         std::string message = "Failed to resume container " + id;
         log_error() << message;
         m_containerState.setValueNotify(ContainerState::INVALID);
         throw ContainerError(message);
     }
 
     log_debug() << "Resumed container " << id;
     m_containerState.setValueNotify(ContainerState::READY);
 }

bool softwarecontainer::SoftwareContainer::bindMount	(	const std::string &	pathOnHost,
		const std::string &	pathInContainer,
		bool	readonly = `true`
	)

virtual

Should only be called on containers in state 'READY'.

Exceptions

InvalidOperationError	If called when state is not 'READY'
InvalidContainerError	If the container is in state 'INVALID'

Implements softwarecontainer::SoftwareContainerAbstractInterface.

Definition at line 419 of file softwarecontainer.cpp.

 {
     assertValidState();
 
     std::string id = std::string(m_container->id());
 
     if (m_containerState != ContainerState::READY) {
         std::string message = "Invalid to bind mount in non ready container " + id;
         log_error() << message;
         throw InvalidOperationError(message);
     }
 
     return m_container->bindMountInContainer(pathOnHost, pathInContainer, readonly);
 }

ObservableProperty< ContainerState > & softwarecontainer::SoftwareContainer::getContainerState ( )

Get the state of this container instance.

Returns: ContainerState representing the current state

Definition at line 386 of file softwarecontainer.cpp.

 {
     return m_containerState;
 }

bool softwarecontainer::SoftwareContainer::previouslyConfigured ( )

virtual

Indicates if gateways have been configured previously.

The user should use this method to check if startGateways have been called previously.

TODO: This should be removed when quick-launch is implemented

Returns: true if startGateways has been called previously, false if not

Implements softwarecontainer::SoftwareContainerAbstractInterface.

Definition at line 445 of file softwarecontainer.cpp.

References softwarecontainer::isDirectory(), softwarecontainer::isDirectoryEmpty(), and softwarecontainer::FileToolkitWithUndo::m_createDirList.

 {
     return m_previouslyConfigured;
 }

Here is the call graph for this function:

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

libsoftwarecontainer/include/softwarecontainer.h
libsoftwarecontainer/src/softwarecontainer.cpp

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation