291 lines
8.6 KiB
C++
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)
|