233 lines
7.1 KiB
C++
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)
|