Files
externals/linux/include/ActivMiddleware/ActivBase/ThreadUtils.h
T
2023-12-15 13:15:08 -05:00

233 lines
7.1 KiB
C++

/**
* @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)