/** * @file include/ActivMiddleware/ActivBase/ThreadUtils.h * * @brief Header file for the thread utilities class. */ #if (!defined ACTIV_BASE_THREAD_UTILS_H) #define ACTIV_BASE_THREAD_UTILS_H #include "ActivMiddleware/ActivBase/External.h" #include "ActivMiddleware/ActivBase/ProcessorAffinity.h" //! Activ namespace. namespace Activ { /** * @brief Thread utilities class. */ class ThreadUtils { public: #if (defined ACTIV_PLATFORM_WINDOWS) typedef DWORD Id; ///< Thread id type for Windows. typedef Id OsId; #elif (defined ACTIV_PLATFORM_POSIX) typedef pthread_t Id; ///< Thread id type for Posix. #if (defined ACTIV_PLATFORM_LINUX) typedef pid_t OsId; #elif (defined ACTIV_PLATFORM_SOLARIS) typedef id_t OsId; #else typedef Id OsId; #endif #else #error Configure for this platform #endif /** * @brief Get the current thread id. * * @return The id of the calling thread. */ ACTIV_BASE_API static Id GetCurrentId(); /** * @brief Get the priority of any thread. * * @param priority thread priority. * @param id id of the thread to get the priority for, default the calling thread. * * @retval STATUS_CODE_SUCCESS * @retval ... */ ACTIV_BASE_API static StatusCode GetThreadPriority(uint32_t &priority, const Id id = GetCurrentId()); /** * @brief Set the priority of any thread. * * @param priority new thread priority. * @param id id of the thread to set the priority for, default the calling thread. * * @retval STATUS_CODE_SUCCESS * @retval ... */ ACTIV_BASE_API static StatusCode SetThreadPriority(const uint32_t priority, const Id id = GetCurrentId()); /** * @brief Convert string to thread priority. Valid priority strings are 'Idle', 'Lowest', 'BelowNormal', 'Normal', * 'AboveNormal', 'Highest' and 'TimeCritical'. * * @param str string to convert. Note case is ignored. * @param priority converted thread priority. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_FAILURE */ ACTIV_BASE_API static StatusCode StringToPriority(const String &str, uint32_t &priority); /** * @brief Get a pretty-printed string containing the available priority levels. * * @return Pretty-printed string containing the available priority levels. */ ACTIV_BASE_API static const String PrioritiesToString(); /** * @brief Set the processors a thread can be scheduled on. * * @param processorAffinity the processor affinity for this thread to be assigned to. if the processor affinity is not * initialized the thread will be set to have the same affinity as the starting process. Under windows threads are * limited to the parent process processor affinity list, this is not the case with linux. * @param id id of the thread to set the affinities for, default the calling thread. * * @retval STATUS_CODE_SUCCESS * @retval ... */ ACTIV_BASE_API static StatusCode SetProcessorAffinity(const ProcessorAffinity &processorAffinity, const Id id = GetCurrentId()); #if (defined ACTIV_PLATFORM_LINUX) /** * @brief Get the processors the defined thread can be scheduled on. * * @param processorAffinity the processor affinity for the process. * @param osId id of the thread to retrieve the affinity for. * * @retval STATUS_CODE_SUCCESS * @retval ... */ ACTIV_BASE_API static StatusCode GetProcessorAffinity(ProcessorAffinity &processorAffinity, const OsId osId); /** * @brief Assign a thread to a cpuset. * * @param cpuSet the cpuset to assign the thread to. * @param osId the thread id to assign to a cpuset (result of ::gettid not the pthread id). * * @retval STATUS_CODE_SUCCESS * @retval ... */ ACTIV_BASE_API static StatusCode AssignCpuSet(const String &cpuSet, const OsId osId); /** * @brief Get the cpuset a thread is assigned to. * * @param cpuSet the cpuset assigned to the process. * @param osId the thread id to retrieve the cpuset for (result of ::gettid not the pthread id). * * @retval STATUS_CODE_SUCCESS * @retval ... */ ACTIV_BASE_API static StatusCode GetCpuSet(String &cpuSet, const OsId osId); /** * @brief Get the OS thread name. * * @param name the thread name as seen by the OS. * @param osId the thread id to retrieve the name for (result of ::gettid not the pthread id). * * @retval STATUS_CODE_SUCCESS * @retval ... */ ACTIV_BASE_API static StatusCode GetOsName(String &name, const OsId osId); #elif (defined ACTIV_PLATFORM_SOLARIS) /** * @brief Get the processors the defined thread can be scheduled on. * * @param processorAffinity the processor affinity for the process. * @param pid id of the process that contains the thread. * @param lwpId id of the thread to retrieve the affinity for. * * @retval STATUS_CODE_SUCCESS * @retval ... */ ACTIV_BASE_API static StatusCode GetProcessorAffinity(ProcessorAffinity &processorAffinity, const OsId pid, const Id lwpId); /** * @brief Get whether the thread is stopped. * * @param pid id of the process that contains the thread. * @param lwpId id to check the status of. * * @return true if the thread has stopped. */ ACTIV_BASE_API static bool IsStopped(const OsId pid, const Id lwpId); /** * @brief Get the OS thread name. * * @param name the thread name as seen by the OS. * @param pid id of the process that contains the thread. * @param lwpId id to retrieve the name for. * * @retval STATUS_CODE_SUCCESS * @retval ... */ ACTIV_BASE_API static StatusCode GetOsName(String &name, const OsId pid, const Id lwpId); #endif /** * @brief Suspend the execution of the current thread for the specified interval. * * Note this is a wrapper over the platform's native thread sleep function, and depending on the platform, * may return before the period has expired. * * @param period the period to sleep for, in ms. */ ACTIV_BASE_API static void Suspend(const TimeoutPeriod period); /** * @brief Suspend the execution of the current thread for the specified interval. * * This is a more accurate wait than provided by Suspend(). It is guaranteed not to return before @a period * milliseconds have expired. Use with caution as it may incur noticable CPU cost. * * @param period the period to sleep for, in ms. */ ACTIV_BASE_API static void AccurateSuspend(const TimeoutPeriod period); /** * @brief Suspend the execution of the current thread for the specified interval in microseconds. * * Note this is a wrapper over the platform's native thread sleep function, and depending on the platform, * may return before the period has expired. * * @param period the period to sleep for, in us. * * @retval STATUS_CODE_TIMEOUT */ ACTIV_BASE_API static StatusCode MicrosecondSuspend(const uint64_t period); /** * @brief Get the name of the calling thread. * * @return Name of the thread, or string representation of the thread id if a name isn't available (no SetName() called). */ ACTIV_BASE_API static const String &GetName(); /** * @brief Set the name of the calling thread. * * @param threadName the name to give the thread. */ ACTIV_BASE_API static void SetName(const String &threadName); }; } // namespace Activ #endif // (!defined ACTIV_BASE_THREAD_UTILS_H)