Files
externals/linux/include/ActivMiddleware/ActivBase/Process.h
T

291 lines
8.6 KiB
C++

/**
* @file include/ActivMiddleware/ActivBase/Process.h
*
* @brief Header file for the process class.
*/
#if (!defined ACTIV_BASE_PROCESS_H)
#define ACTIV_BASE_PROCESS_H
#include "ActivMiddleware/ActivBase/External.h"
#include "ActivMiddleware/ActivBase/Environment.h"
#include "ActivMiddleware/ActivBase/ProcessorAffinity.h"
#include "ActivMiddleware/CxxYZ/map.h"
#include "ActivMiddleware/CxxYZ/set.h"
#include <vector>
//! Activ namespace.
namespace Activ
{
class BinaryArray;
/**
* @brief Process class.
*
* Provides OS-abstractions for common process-level operations.
*/
class Process
{
public:
#if (defined ACTIV_PLATFORM_WINDOWS)
typedef TypeToIntegralType<DWORD>::Type Id; ///< Process id type for Windows.
#elif (defined ACTIV_PLATFORM_POSIX)
typedef TypeToIntegralType<pid_t>::Type Id; ///< Process id type for Posix.
#else
#error Configure for this platform
#endif
//! Attributes class. Attributes passed to Process::Start.
class Attributes
{
public:
//! Default constructor.
ACTIV_BASE_API Attributes();
/**
* @brief Parse attributes.
*
* @param attributes
*
* @throw Exception
* @throw std::exception
*/
ACTIV_BASE_API void Parse(const String &attributes);
//! String representation of attributes for the UI.
ACTIV_BASE_API String ToString() const;
ProcessorAffinity m_processorAffinity; ///< Processor affinity to assign the process.
bool m_shouldPoll; ///< For ACTIV processes will configure threads to run CPU busy.
bool m_shouldOnload; ///< Should prefix m_command with 'onload' (linux only).
String m_cpuSet; ///< cpuset to execute the process in (linux only).
Environment::EnvironmentMap m_setEnvironmentMap; ///< Additional environment variables to configure for the process.
CxxYZ::set<String> m_unSetEnvironmentList; ///< Environment variables that should be removed from the environment.
};
/**
* @brief Run a command to completion and return any stdout output of the process.
*
* @param command the command (and arguments) to run.
* @param output any output from command is appended to output (output is not cleared).
* @param timeoutPeriod maximum time in ms to wait for all output.
*
* @return STATUS_CODE_SUCCESS or an error explaining why the command could not be run.
* @retval ...
*/
ACTIV_BASE_API static StatusCode Run(const String &command, String &output, const TimeoutPeriod timeoutPeriod = 30000);
/**
* @brief Replace the current process image with a new process image.
*
* Note on Windows, this call launches a new process and exits the calling process if the new
* process was started successfully.
*
* @param command the command (and arguments) to run.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_FAILURE
* @retval STATUS_CODE_HEAP_EMPTY
* @retval STATUS_CODE_INVALID_FORMAT @a command is incorrectly formatted
* @retval STATUS_CODE_NOT_FOUND @a command not found
*/
ACTIV_BASE_API static StatusCode Exec(const String &command);
/**
* @brief Launch a process in the background.
*
* @param command the command (and arguments) to run.
* @param id reference to an @a Id variable to receive the process id of the new process.
* @param attributes the attributes containing the affinity and environment etc.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_FAILURE
* @retval STATUS_CODE_HEAP_EMPTY
* @retval STATUS_CODE_INVALID_FORMAT @a command is incorrectly formatted
* @retval STATUS_CODE_NOT_FOUND @a command not found
*/
ACTIV_BASE_API static StatusCode Start(const String &command, Id &id, const Attributes &attributes = Attributes());
/**
* @brief Kill a process.
*
* @param id the process id to kill.
*
* @return STATUS_CODE_SUCCESS or an error explaining why the process could not be killed.
*/
ACTIV_BASE_API static StatusCode Kill(const Id id);
/**
* @brief Wait for a process to exit.
*
* @param id the process id to wait for.
* @param timeoutPeriod the timeout period to wait, in ms.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_TIMEOUT
* @retval STATUS_CODE_FAILURE
*/
ACTIV_BASE_API static StatusCode WaitForCompletion(const Id id,
const TimeoutPeriod timeoutPeriod = ACTIV_WAIT_INFINITE);
/**
* @brief Does a process exist?
*
* @param id the process id to check for.
*
* @return true if the process exists.
*/
ACTIV_BASE_API static bool DoesExist(const Id id);
/**
* @brief Get the current process id.
*
* @return The current running process id.
*/
ACTIV_BASE_API static Id GetCurrentId();
/**
* @brief Set the processors this process can be scheduled on.
*
* @param processorAffinity the processor affinity for the process to be assigned to. If the processor affinity is not
* initialized, the process will be set to have no affinity to particular processors.
* @param id id of the process to set the affinity of (default current process).
*
* @retval STATUS_CODE_SUCCESS
* @retval ...
*/
ACTIV_BASE_API static StatusCode SetProcessorAffinity(const ProcessorAffinity &processorAffinity, const Id id = GetCurrentId());
/**
* @brief Get the processors the defined process can be scheduled on.
*
* @param processorAffinity the processor affinity for the process.
* @param id id of the process to retrieve the affinity for (default current process).
*
* @retval STATUS_CODE_SUCCESS
* @retval ...
*/
ACTIV_BASE_API static StatusCode GetProcessorAffinity(ProcessorAffinity &processorAffinity, const Id id = GetCurrentId());
#if (defined ACTIV_PLATFORM_LINUX)
/**
* @brief Get the cpuset root path.
*
* @return the cpuset root path
*/
ACTIV_BASE_API static const String &GetCpuSetRootPath();
/**
* @brief Assign a process to a cpuset.
*
* @param cpuSet the cpuset to assign the process to.
* @param id the process id to assign to a cpuset (default current process).
*
* @retval STATUS_CODE_SUCCESS
* @retval ...
*/
ACTIV_BASE_API static StatusCode AssignCpuSet(const String &cpuSet, const Id id = GetCurrentId());
/**
* @brief Get the cpuset a process is assigned to.
*
* @param cpuSet the cpuset assigned to the process.
* @param id the process id to retrieve the cpuset for (default current process).
*
* @retval STATUS_CODE_SUCCESS
* @retval ...
*/
ACTIV_BASE_API static StatusCode GetCpuSet(String &cpuSet, const Id id = GetCurrentId());
#endif
#if (defined ACTIV_PLATFORM_POSIX)
/**
* @brief Switch to another user.
*
* @param userName
*
* This call will attempt to set the following environment variables to values appropriate for the new user:
*
* USER
* HOME
* SHELL
* EUID
* EGID
*
* It will set the current effective user and group ids to that of the new user.
*
* On Linux, the real user & group ids are also set along with UID and GID environment variables. If the function was
* called with an initial real user id of root, the following capabilities are available to the new user:
*
* CAP_DAC_OVERRIDE
* CAP_NET_ADMIN
* CAP_NET_BIND_SERVICE
* CAP_NET_RAW
* CAP_SYS_NICE
* CAP_SYS_TIME
*
* @throw Exception unknown user, or failed to set environment.
*/
ACTIV_BASE_API static void SwitchToUser(const String &userName);
#endif
/**
* @brief Get the name of the executable for a particular process id.
*
* @param id
* @param executableName
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_NOT_SUPPORTED
* @retval ...
*/
ACTIV_BASE_API static StatusCode GetExecutableName(const Id id, String &executableName);
/**
* @brief Get the name and directory of the executable for a particular process id.
*
* @param id
* @param directoryName
* @param executableName
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_NOT_SUPPORTED
* @retval ...
*/
ACTIV_BASE_API static StatusCode GetExecutableName(const Id id, String &directoryName, String &executableName);
/**
* @brief Was this process launched via a debugger?
*
* This is potentially useful in catch blocks in order to ensure exceptions are passed to the the debugger. For example:
*
* catch (const std::exception &e)
* {
* ACTIV_DEBUG_ONLY(if (Process::WasStartedViaDebugger()) throw;)
*
* ...
* }
*
* Code should not rely on this being 100% accurate; it should be considered a hint and used in non-critical code as above.
*
* @return Boolean.
*/
ACTIV_BASE_API static bool WasStartedViaDebugger();
/**
* @brief Calculate a sha1 hash of the running executable.
*
* @param sha1 BinaryArray to receive the 20 byte SHA1 hash.
*
* @return STATUS_CODE_SUCCESS or an error status.
*/
ACTIV_BASE_API static StatusCode GetSha1(BinaryArray &sha1);
};
} // namespace Activ
#endif // (!defined ACTIV_BASE_PROCESS_H)