单任务异步执行器 / Single-job asynchronous executor. More...

#include <async.hpp>

Collaboration diagram for LibXR::ASync:

Public Types
enum class	Status : uint32_t { READY = 0 , BUSY = 1 , DONE = UINT32_MAX }
	异步任务的状态枚举。 Enumeration of asynchronous task statuses. More...

using	Job = LibXR::Callback<ASync*>

Public Member Functions
	ASync (size_t stack_depth, Thread::Priority priority)
	构造 `ASync` 并初始化线程或软件 Timer。 Constructs an `ASync` and initializes its worker or software Timer.

Status	GetStatus ()
	获取当前异步任务的状态。 Retrieves the current status of the asynchronous task.

ErrorCode	AssignJob (Job job)
	提交任务 / Submit a job.

ErrorCode	AssignJobFromCallback (Job job, bool in_isr)
	从回调上下文提交任务 / Submit a job from callback context.

Static Public Member Functions
static void	ThreadFun (ASync *async)
	任务线程函数，等待信号量并执行任务。 Task thread function that waits for a semaphore and executes the assigned job.

Public Attributes
std::atomic< Status >	status_ = Status::READY
	当前异步任务状态

Job	job_
	存储分配的异步任务回调 / Stores the assigned asynchronous job callback.

Semaphore	sem_
	控制任务执行的信号量 / Semaphore controlling task execution.

Thread	thread_handle_
	处理异步任务的线程 / Thread handling asynchronous tasks.

Detailed Description

单任务异步执行器 / Single-job asynchronous executor.

有线程时由工作线程执行；无多线程支持时，由软件 Timer 推进。任务完成后保持 DONE，GetStatus 取走完成状态后恢复 READY。

Threaded systems use a worker; cooperative systems use a software Timer. Completion stays DONE until GetStatus acknowledges it and restores READY.

对象保留到工作线程退出或系统复位；回调数据保留到任务完成，任务不得抛异常。

Keep the object until its worker exits or the system resets. Keep callback data until completion. Jobs must not throw.

裸机从普通上下文推进 Timer；长任务会拖延其他回调，也不能等待同一 Timer 的其他任务。

Drive a bare-metal Timer in normal context. Long jobs delay other callbacks and cannot wait for work on the same Timer.

Definition at line 32 of file async.hpp.

Member Typedef Documentation

◆ Job

using LibXR::ASync::Job = LibXR::Callback<ASync*>

Definition at line 103 of file async.hpp.

Member Enumeration Documentation

◆ Status

enum class LibXR::ASync::Status : uint32_t

strong

异步任务的状态枚举。 Enumeration of asynchronous task statuses.

Enumerator
READY	任务已准备就绪 / Task is ready.
BUSY	任务已接收或正在执行 / Job accepted or running.
DONE	任务已完成，尚未取走状态 / Completed, awaiting acknowledgment.

Definition at line 39 of file async.hpp.

  {
    READY = 0,         
    BUSY = 1,          
    DONE = UINT32_MAX  
  };

Constructor & Destructor Documentation

◆ ASync()

ASync::ASync	(	size_t	stack_depth,
		Thread::Priority	priority )

构造 ASync 并初始化线程或软件 Timer。 Constructs an ASync and initializes its worker or software Timer.

Parameters

stack_depth	线程栈深度，无线程后端忽略。 Worker stack depth; ignored by cooperative backends.
priority	线程优先级，无线程后端忽略。 Worker priority; ignored by cooperative backends.

Definition at line 7 of file async.cpp.

{
#ifdef LIBXR_NOT_SUPPORT_MUTI_THREAD
  UNUSED(stack_depth);
  UNUSED(priority);
  auto timer = Timer::CreateTask<ASync*>(
      [](ASync* async)
      {
        if (async->pending_.exchange(0U, std::memory_order_acquire) != 0U)
        {
          async->RunJob();
        }
      },
      this, 1);
  Timer::Start(timer);
  Timer::Add(timer);
#else
  thread_handle_.Create(this, ThreadFun, "async_job", stack_depth, priority);
#endif
}

Member Function Documentation

◆ AssignJob()

ErrorCode ASync::AssignJob ( Job job )

提交任务 / Submit a job.

Parameters

job	预先创建的任务回调 / Previously created job callback.

Returns: READY 时接收并返回 OK，否则返回 BUSY，保留原任务和完成状态。 OK if READY; otherwise BUSY, preserving the existing job and completion.

Note: 成功表示已接收，任务可能在本调用返回前完成。提交不会同步调用任务。 Success means admission; execution may finish before this call returns. Submission does not invoke the job inline.

Definition at line 28 of file async.cpp.

28{ return AssignJobFromCallback(job, false); }

LibXR::ASync::AssignJobFromCallback

ErrorCode AssignJobFromCallback(Job job, bool in_isr)

从回调上下文提交任务 / Submit a job from callback context.

Definition async.cpp:30

◆ AssignJobFromCallback()

ErrorCode ASync::AssignJobFromCallback	(	Job	job,
		bool	in_isr )

从回调上下文提交任务 / Submit a job from callback context.

Parameters

job	预先创建的任务回调 / Previously created job callback.
in_isr	当前是否处于 ISR；线程后端据此选择通知方式。 Whether the caller is in an ISR; selects the worker notification path.

Returns: 与 AssignJob 相同：OK 表示接收，BUSY 表示原任务尚未释放。 Same as AssignJob: OK admits the job; BUSY leaves the existing job intact.

Note: 任务由工作线程或软件 Timer 执行，任务回调收到的 in_isr 为 false。 The worker or software Timer executes the job with in_isr=false.

Definition at line 30 of file async.cpp.

{
  Status expected = Status::READY;
  if (!status_.compare_exchange_strong(expected, Status::BUSY, std::memory_order_acquire,
                                       std::memory_order_relaxed))
  {
    return ErrorCode::BUSY;
  }
 
  job_ = job;
#ifdef LIBXR_NOT_SUPPORT_MUTI_THREAD
  UNUSED(in_isr);
  pending_.store(1U, std::memory_order_release);
#else
  sem_.PostFromCallback(in_isr);
#endif
  return ErrorCode::OK;
}

◆ GetStatus()

Status LibXR::ASync::GetStatus ( )

inlinenodiscard

获取当前异步任务的状态。 Retrieves the current status of the asynchronous task.

如果任务尚未完成，则返回当前 status_。如果任务已完成，则返回 DONE 并重置状态为 READY。 If the task is not yet completed, it returns the current status_. If the task is completed, it returns DONE and resets the status to READY.

Returns: 返回当前任务状态。 Returns the current task status.

Definition at line 86 of file async.hpp.

  {
    Status cur = status_.load(std::memory_order_acquire);
    if (cur != Status::DONE)
    {
      return cur;
    }
    // 只允许一个观察者取走 DONE；迟到的观察者不能覆盖下一次提交的 BUSY。
    // Consume DONE once; a late observer must not overwrite the next submission's BUSY.
    if (status_.compare_exchange_strong(cur, Status::READY, std::memory_order_acq_rel,
                                        std::memory_order_acquire))
    {
      return Status::DONE;
    }
    return cur;
  }

◆ ThreadFun()

void ASync::ThreadFun ( ASync * async )

static

任务线程函数，等待信号量并执行任务。 Task thread function that waits for a semaphore and executes the assigned job.

该函数作为 ASync 任务的主线程，持续等待 sem_ 释放后执行任务，执行完成后更新 status_ 状态。 This function serves as the main thread for ASync, continuously waiting for sem_ to be released before executing a job, and updating status_ upon completion.

Parameters

async 指向 ASync 实例的指针。 Pointer to the ASync instance.

Definition at line 55 of file async.cpp.

{
  while (true)
  {
    if (async->sem_.Wait() == ErrorCode::OK)
    {
      async->RunJob();
    }
  }
}

Member Data Documentation

◆ job_

Job LibXR::ASync::job_

存储分配的异步任务回调 / Stores the assigned asynchronous job callback.

Definition at line 128 of file async.hpp.

◆ sem_

Semaphore LibXR::ASync::sem_

控制任务执行的信号量 / Semaphore controlling task execution.

Definition at line 129 of file async.hpp.

◆ status_

std::atomic<Status> LibXR::ASync::status_ = Status::READY

当前异步任务状态

Definition at line 72 of file async.hpp.

◆ thread_handle_

Thread LibXR::ASync::thread_handle_

处理异步任务的线程 / Thread handling asynchronous tasks.

Definition at line 131 of file async.hpp.

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

src/system/async.hpp
src/system/async.cpp

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Member Typedef Documentation

◆ Job

Member Enumeration Documentation

◆ Status

Constructor & Destructor Documentation

◆ ASync()

Member Function Documentation

◆ AssignJob()

◆ AssignJobFromCallback()

◆ GetStatus()

◆ ThreadFun()

Member Data Documentation

◆ job_

◆ sem_

◆ status_

◆ thread_handle_