LibXR::Thread Class Reference

线程管理类，封装 POSIX 线程创建和调度 Thread management class encapsulating POSIX thread creation and scheduling More...

#include <thread.hpp>

Public Types
enum class	Priority : uint8_t {   IDLE , LOW , MEDIUM , HIGH ,   REALTIME , NUMBER }
	线程优先级枚举 Enumeration for thread priorities More...

Public Member Functions
	Thread ()
	默认构造函数，初始化空线程 Default constructor initializing an empty thread
	Thread (libxr_thread_handle handle)
	通过 POSIX 线程句柄创建线程对象 Constructor to create a thread object from a POSIX thread handle
template<typename ArgType >
void	Create (ArgType arg, void(*function)(ArgType arg), const char *name, size_t stack_depth, Thread::Priority priority)
	创建新线程 Creates a new thread
ErrorCode	Join ()
	Waits for this POSIX thread to terminate and releases its resources.
	operator libxr_thread_handle ()
	线程对象转换为 POSIX 线程句柄 Converts the thread object to a POSIX thread handle

Static Public Member Functions
static Thread	Current (void)
	获取当前线程对象 Gets the current thread object
static uint32_t	GetTime ()
	获取当前系统时间（毫秒） Gets the current system time in milliseconds
static void	Sleep (uint32_t milliseconds)
	让线程进入休眠状态 Puts the thread to sleep
static void	SleepUntil (MillisecondTimestamp &last_waskup_time, uint32_t time_to_sleep)
	让线程休眠直到指定时间点 Puts the thread to sleep until a specified time
static void	Yield ()
	让出 CPU 以执行其他线程 Yields CPU execution to allow other threads to run

Static Private Member Functions
static void	ConfigureAttributes (pthread_attr_t &attr, size_t stack_depth, Thread::Priority priority)
static void	ConfigureScheduling (pthread_attr_t &attr, Thread::Priority priority)

Private Attributes
libxr_thread_handle	thread_handle_
	POSIX 线程句柄 POSIX thread handle.

Detailed Description

线程管理类，封装 POSIX 线程创建和调度 Thread management class encapsulating POSIX thread creation and scheduling

Definition at line 17 of file thread.hpp.

Member Enumeration Documentation

Priority

enum class LibXR::Thread::Priority : uint8_t

strong

线程优先级枚举 Enumeration for thread priorities

Enumerator
IDLE	空闲优先级 Idle priority
LOW	低优先级 Low priority
MEDIUM	中等优先级 Medium priority
HIGH	高优先级 High priority
REALTIME	实时优先级 Realtime priority
NUMBER	优先级数量 Number of priority levels

Definition at line 24 of file thread.hpp.

  {
    IDLE,      
    LOW,       
    MEDIUM,    
    HIGH,      
    REALTIME,  
    NUMBER,    
  };

Constructor & Destructor Documentation

Thread() [1/2]

LibXR::Thread::Thread ( )

inline

默认构造函数，初始化空线程 Default constructor initializing an empty thread

Definition at line 38 of file thread.hpp.

{};

Thread() [2/2]

LibXR::Thread::Thread ( libxr_thread_handle handle )

inline

通过 POSIX 线程句柄创建线程对象 Constructor to create a thread object from a POSIX thread handle

Parameters

handle

POSIX 线程句柄 POSIX thread handle

Definition at line 45 of file thread.hpp.

: thread_handle_(handle) {};

Member Function Documentation

ConfigureAttributes()

static void LibXR::Thread::ConfigureAttributes ( pthread_attr_t & attr, size_t stack_depth, Thread::Priority priority )

inlinestaticprivate

Definition at line 197 of file thread.hpp.

  {
    const size_t stack_size =
        LibXR::max(static_cast<size_t>(PTHREAD_STACK_MIN), stack_depth);
    pthread_attr_setstacksize(&attr, stack_size);
    ConfigureScheduling(attr, priority);
  }

ConfigureScheduling()

static void LibXR::Thread::ConfigureScheduling ( pthread_attr_t & attr, Thread::Priority priority )

inlinestaticprivate

Definition at line 206 of file thread.hpp.

  {
    const int min_priority = sched_get_priority_min(SCHED_FIFO);
    const int max_priority = sched_get_priority_max(SCHED_FIFO);
    if (max_priority - min_priority < static_cast<int>(Priority::REALTIME))
    {
      XR_LOG_WARN(
          "SCHED_FIFO not supported or insufficient range. Using default policy.");
      pthread_attr_setinheritsched(&attr, PTHREAD_INHERIT_SCHED);
      return;
    }
 
    pthread_attr_setinheritsched(&attr, PTHREAD_EXPLICIT_SCHED);
    pthread_attr_setschedpolicy(&attr, SCHED_FIFO);
 
    struct sched_param sp;
    Memory::FastSet(&sp, 0, sizeof(sp));
    sp.sched_priority = min_priority + static_cast<int>(priority);
 
    if (pthread_attr_setschedparam(&attr, &sp) == 0)
    {
      return;
    }
 
    XR_LOG_WARN("Failed to set thread priority. Falling back to default policy.");
    pthread_attr_setschedpolicy(&attr, SCHED_OTHER);
    pthread_attr_setinheritsched(&attr, PTHREAD_INHERIT_SCHED);
  }

Create()

template<typename ArgType >

void LibXR::Thread::Create ( ArgType arg, void(* function )(ArgType arg), const char * name, size_t stack_depth, Thread::Priority priority )

inline

创建新线程 Creates a new thread

Template Parameters

ArgType

线程函数的参数类型 The type of argument for the thread function

Parameters

arg	线程函数的参数 Argument for the thread function
function	线程执行的函数 Function executed by the thread
name	线程名称 Thread name
stack_depth	线程栈大小（字节） Stack size of the thread (bytes)
priority	线程优先级 Thread priority

该方法基于 POSIX pthread_create() 创建新线程，执行 function 并传递 arg 作为参数。 线程栈大小 stack_depth 需要进行调整以符合 POSIX 线程的栈管理方式。 如果系统支持 SCHED_RR 调度策略，则设置线程优先级。

This method creates a new thread using POSIX pthread_create(), executing function with arg as the argument. The stack_depth needs adjustment for POSIX thread stack management. If the system supports SCHED_RR scheduling, thread priority is set accordingly.

线程数据封装类 Thread data encapsulation class

构造函数，存储线程相关数据 Constructor to store thread-related data

Parameters

fun	线程执行的函数 Function executed by the thread
arg	线程参数 Thread argument
name	线程名称 Thread name

线程入口函数，执行用户定义的线程函数 Thread entry function that executes the user-defined function

Parameters

arg	线程参数 Thread argument

Returns

返回值始终为 nullptr The return value is always nullptr

< 线程执行的函数 Function executed by the thread

< 线程函数的参数 Argument passed to the thread function

< 线程名称 Thread name

Definition at line 68 of file thread.hpp.

  {
    pthread_attr_t attr;
    pthread_attr_init(&attr);
    ConfigureAttributes(attr, stack_depth, priority);
 
    class ThreadBlock
    {
     public:
      ThreadBlock(decltype(function) fun, ArgType arg, const char* name)
          : fun_(fun), arg_(arg)
      {
        std::memset(name_, 0, sizeof(name_));
        if (name != nullptr)
        {
          std::strncpy(name_, name, sizeof(name_) - 1);
        }
      }
 
      static void* Port(void* arg)
      {
        ThreadBlock* block = static_cast<ThreadBlock*>(arg);
 
        if (block->name_[0] != '\0')
        {
          pthread_setname_np(pthread_self(), block->name_);
        }
 
        block->fun_(block->arg_);
        delete block;
        return static_cast<void*>(nullptr);
      }
 
      decltype(function) fun_;  
      ArgType arg_;             
      char name_[16];           
    };
 
    auto block = new ThreadBlock(function, arg, name);
 
    // 创建线程
    int ans = pthread_create(&this->thread_handle_, &attr, ThreadBlock::Port, block);
 
    if (ans != 0)
    {
      XR_LOG_WARN("Failed to create thread: %s (%s), retrying with default attributes.",
                  name, strerror(ans));
 
      // 完全使用系统默认属性（attr = nullptr）
      ans = pthread_create(&this->thread_handle_, nullptr, ThreadBlock::Port, block);
 
      if (ans != 0)
      {
        XR_LOG_ERROR("Failed to create thread: %s (%s)", name, strerror(ans));
        delete block;
      }
    }
 
    pthread_attr_destroy(&attr);
  }

Current()

Thread Thread::Current ( void )

static

获取当前线程对象 Gets the current thread object

Returns

当前线程对象 The current thread object

Definition at line 13 of file thread.cpp.

{ return Thread(pthread_self()); }

GetTime()

uint32_t Thread::GetTime ( )

static

获取当前系统时间（毫秒） Gets the current system time in milliseconds

Returns

当前时间（毫秒） Current time in milliseconds

Definition at line 35 of file thread.cpp.

{ return Timebase::GetMilliseconds(); }

Join()

ErrorCode Thread::Join

(

)

Waits for this POSIX thread to terminate and releases its resources.

Returns

OK on success, otherwise FAILED.

Definition at line 39 of file thread.cpp.

{
  return pthread_join(thread_handle_, nullptr) == 0 ? ErrorCode::OK : ErrorCode::FAILED;
}

operator libxr_thread_handle()

LibXR::Thread::operator libxr_thread_handle ( )

inline

线程对象转换为 POSIX 线程句柄 Converts the thread object to a POSIX thread handle

Returns

POSIX 线程句柄 POSIX thread handle

Definition at line 194 of file thread.hpp.

{ return thread_handle_; }

Sleep()

void Thread::Sleep ( uint32_t milliseconds )

static

让线程进入休眠状态 Puts the thread to sleep

Parameters

milliseconds

休眠时间（毫秒） Sleep duration in milliseconds

Definition at line 15 of file thread.cpp.

{
  timespec ts = MonotonicTime::RelativeFromMilliseconds(milliseconds);
  while (clock_nanosleep(CLOCK_MONOTONIC, 0, &ts, &ts) == EINTR)
  {
  }
}

SleepUntil()

void Thread::SleepUntil ( MillisecondTimestamp & last_waskup_time, uint32_t time_to_sleep )

static

让线程休眠直到指定时间点 Puts the thread to sleep until a specified time

Parameters

last_waskup_time	上次唤醒时间 Last wake-up time
time_to_sleep	休眠时长（毫秒） Sleep duration in milliseconds

Definition at line 23 of file thread.cpp.

{
  last_waskup_time = last_waskup_time + time_to_sleep;
 
  const timespec ts =
      MonotonicTime::AddMilliseconds(libxr_linux_start_time_spec, last_waskup_time);
 
  while (clock_nanosleep(CLOCK_MONOTONIC, TIMER_ABSTIME, &ts, nullptr) == EINTR)
  {
  }
}

Yield()

void Thread::Yield ( )

static

让出 CPU 以执行其他线程 Yields CPU execution to allow other threads to run

Definition at line 37 of file thread.cpp.

{ sched_yield(); }

Field Documentation

thread_handle_

libxr_thread_handle LibXR::Thread::thread_handle_

private

POSIX 线程句柄 POSIX thread handle.

Definition at line 235 of file thread.hpp.

---

The documentation for this class was generated from the following files:

• system/linux/thread.hpp
• system/linux/thread.cpp