/** * @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 //! 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::Type Id; ///< Process id type for Windows. #elif (defined ACTIV_PLATFORM_POSIX) typedef TypeToIntegralType::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 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)