QPC 框架深度解析: Active Object 与层次状态机的嵌入式实践

// 传统方式: 多个线程共享数据，需要锁保护
static SensorData g_sensorData;  // 全局共享
static pthread_mutex_t g_mutex;

void sensor_thread(void *arg) {
    while (1) {
        pthread_mutex_lock(&g_mutex);    // 获取锁
        g_sensorData = read_sensor();     // 写共享数据
        pthread_mutex_unlock(&g_mutex);   // 释放锁
        usleep(1000);
    }
}

void display_thread(void *arg) {
    while (1) {
        pthread_mutex_lock(&g_mutex);    // 获取锁
        show(g_sensorData);               // 读共享数据
        pthread_mutex_unlock(&g_mutex);   // 释放锁
        usleep(100000);
    }
}

// AO 方式: 通过事件传递数据，无共享状态
typedef struct {
    QEvt    super;
    int32_t temperature;
} SensorEvt;

// 传感器 AO: 只负责采集，通过事件发布数据
static QState Sensor_active(SensorAO *me, QEvt const *e) {
    switch (e->sig) {
    case SAMPLE_SIG: {
        SensorEvt *evt = Q_NEW(SensorEvt, SENSOR_DATA_SIG);
        evt->temperature = read_sensor();
        QF_publish(&evt->super, me);  // 发布，不关心谁消费
        return Q_HANDLED();
    }
    }
    return Q_SUPER(&QHsm_top);
}

// 显示 AO: 只负责显示，订阅感兴趣的事件
static QState Display_active(DisplayAO *me, QEvt const *e) {
    switch (e->sig) {
    case SENSOR_DATA_SIG: {
        SensorEvt const *se = (SensorEvt const *)e;
        show(se->temperature);  // 直接使用，无需加锁
        return Q_HANDLED();
    }
    }
    return Q_SUPER(&QHsm_top);
}

// 平面 FSM: 状态组合呈指数增长
enum {
    STATE_IDLE_NORMAL,
    STATE_IDLE_ERROR,
    STATE_WORKING_NORMAL,
    STATE_WORKING_ERROR,
    STATE_SLEEP_NORMAL,
    STATE_SLEEP_ERROR,
    // ... 每增加一个维度，状态数翻倍
};

typedef struct QMState {
    struct QMState const *superstate;    // 父状态指针 (编译期绑定)
    QStateHandler const   stateHandler;  // 状态处理函数
    QActionHandler const  entryAction;   // ENTRY 动作
    QActionHandler const  exitAction;    // EXIT  动作
    QActionHandler const  initAction;    // INIT  动作 (初始转移)
} QMState;

void QMsm_dispatch_(QHsm * const me, QEvt const * const e) {
    QMState const *t = me->state.obj;  // 当前状态
    QState r;

    // 从当前状态开始，沿 superstate 链向上冒泡
    do {
        r = (*t->stateHandler)(me, e);   // 调用状态处理函数
        if (r == Q_RET_UNHANDLED) {
            t = t->superstate;           // 未处理 → 委托给父状态
        }
    } while (r == Q_RET_UNHANDLED && t != NULL);

    // 如果需要状态转换，执行预生成的 Entry/Exit/Init 序列
    if (r >= Q_RET_TRAN) {
        QMsm_execTatbl_(me, me->temp.tatbl);
    }
}

// 父状态: 处理通用事件
static QState Parent_state(MyAO *me, QEvt const *e) {
    switch (e->sig) {
    case COMMON_SIG:
        handle_common();     // 所有子状态共享的默认行为
        return Q_HANDLED();
    }
    return Q_SUPER(&QHsm_top);
}

// 子状态: 覆盖特定事件，其余自动委托给父状态
static QState Child_state(MyAO *me, QEvt const *e) {
    switch (e->sig) {
    case SPECIFIC_SIG:
        handle_specific();   // 子状态专属处理
        return Q_HANDLED();
    case COMMON_SIG:
        handle_override();   // 覆盖父状态的默认行为
        return Q_HANDLED();
    }
    return Q_SUPER(&Parent_state);  // 其余事件冒泡到父状态
}

// QMsm 的转换动作表在编译期由 QM 工具生成
// 不需要运行时查找 LCA，直接执行预定义的 Exit/Entry 序列
static QMTranActTable const tatbl_s11_to_s21 = {
    &QMsm_s2_s21,  // 目标状态
    {
        Q_ACTION_CAST(&s11_exit),   // Exit S1.1
        Q_ACTION_CAST(&s1_exit),    // Exit S1
        Q_ACTION_CAST(&s2_entry),   // Entry S2
        Q_ACTION_CAST(&s21_entry),  // Entry S2.1
        Q_ACTION_NULL               // 终止标记
    }
};

// QEQueue 内部结构 (简化)
typedef struct {
    QEvt const * volatile frontEvt;  // 最新事件的快速缓存
    QEvt const **ring;               // 环形缓冲数组
    QEQueueCtr   end;                // 数组长度
    QEQueueCtr   head;               // 写入位置
    QEQueueCtr   tail;               // 读取位置
    QEQueueCtr   nFree;              // 空闲槽数
} QEQueue;

// 事件投递 (简化)
bool QActive_post_(QActive *me, QEvt const *e, uint_fast16_t margin) {
    QF_CRIT_ENTRY();  // 进入临界区 (关中断)

    if (me->eQueue.frontEvt == NULL) {
        // 快速路径: 队列为空，直接放入 frontEvt
        me->eQueue.frontEvt = e;
        // 唤醒 AO 线程
        rt_thread_resume(me->thread);
    } else {
        // 普通路径: 放入环形缓冲
        me->eQueue.ring[me->eQueue.head] = e;
        if (me->eQueue.head == 0U) {
            me->eQueue.head = me->eQueue.end;
        }
        --me->eQueue.head;
        --me->eQueue.nFree;
    }

    QF_CRIT_EXIT();   // 退出临界区
    return true;
}

QEvt const *QActive_get_(QActive *me) {
    QF_CRIT_ENTRY();

    if (me->eQueue.frontEvt == NULL) {
        // 队列为空，挂起线程等待事件
        rt_thread_suspend(rt_thread_self());
        QF_CRIT_EXIT();
        rt_schedule();        // 让出 CPU
        QF_CRIT_ENTRY();     // 被唤醒后重新进入临界区
    }

    QEvt const *e = me->eQueue.frontEvt;

    if (me->eQueue.nFree < me->eQueue.end) {
        // 环形缓冲中还有事件，提升到 frontEvt
        me->eQueue.frontEvt = me->eQueue.ring[me->eQueue.tail];
        if (me->eQueue.tail == 0U) {
            me->eQueue.tail = me->eQueue.end;
        }
        --me->eQueue.tail;
        ++me->eQueue.nFree;
    } else {
        me->eQueue.frontEvt = NULL;  // 队列已空
    }

    QF_CRIT_EXIT();
    return e;
}

typedef struct {
    QEvt    super;     // 基类
    int32_t value;     // 直接内嵌 payload
} DataEvt;

// 生产者
DataEvt *e = Q_NEW(DataEvt, DATA_SIG);
e->value = 42;
QACTIVE_POST(&receiver->super, &e->super, 0);

// 消费者
DataEvt const *de = (DataEvt const *)e;
process(de->value);  // 直接使用，零拷贝

static uint8_t bigBuf[10240];  // 外部大缓冲

typedef struct {
    QEvt     super;
    uint8_t *dataPtr;     // 指向外部缓冲
    uint32_t length;
} BigEvt;

BigEvt *e = Q_NEW(BigEvt, BIG_SIG);
e->dataPtr = bigBuf;
e->length  = sizeof(bigBuf);
// 入队仅写入 BigEvt 指针 (几字节)，不拷贝 10KB 数据
QACTIVE_POST(&consumer->super, &e->super, 0);

// 初始化: 预分配事件池
static uint8_t poolSto[20 * sizeof(DataEvt)];
QF_poolInit(poolSto, sizeof(poolSto), sizeof(DataEvt));

// 分配: O(1) 从池中弹出
DataEvt *e = Q_NEW(DataEvt, SENSOR_SIG);

// 回收: O(1) 归还到池中
// QF_gc(e) 在事件循环中自动调用

// 1. AO 实例和资源 (全部静态分配)
static BlinkyAO  l_blinky;
static QEvt const *blinkyQSto[8];     // 事件队列缓冲
static uint8_t    blinkyStk[256];      // 线程栈

// 2. 构造
void BlinkyAO_ctor(void) {
    QActive_ctor(&l_blinky.super, Q_STATE_CAST(&Blinky_initial));
}

// 3. 启动
void BlinkyAO_start(void) {
    BlinkyAO_ctor();
    QACTIVE_START(&l_blinky.super,
                  BLINKY_PRIO,                     // 优先级
                  blinkyQSto, Q_DIM(blinkyQSto),   // 事件队列
                  blinkyStk, sizeof(blinkyStk),     // 线程栈
                  (void *)0);                       // 初始事件参数
}

static void qf_thread_function(void *arg) {
    QActive *me = (QActive *)arg;
    for (;;) {
        QEvt const *e = QActive_get_(me);     // 阻塞等待事件
        QHSM_DISPATCH(&me->super, e);         // 派发给状态机
        QF_gc(e);                              // 回收动态事件
    }
}

// 在 ISR 中发布事件
static QEvt const sigX_evt = { SIG_X, 0U };

// ISR 版本: 最短路径，几十条指令
QACTIVE_POST_FROM_ISR(&myAO->super, &sigX_evt);
// 内部: 写队列指针 + rt_thread_resume()
// 调度器在 rt_interrupt_leave() 中统一触发

// 在 AO 构造函数中创建周期性定时事件
QTimeEvt_ctorX(&me->sampleEvt, &me->super, SAMPLE_SIG, 0U);

// 在状态机初始化时启动: 首次 1 tick 延迟，周期 1 tick
QTimeEvt_armX(&me->sampleEvt, 1U, 1U);

// 停止定时器
QTimeEvt_disarm(&me->sampleEvt);

void SysTick_Handler(void) {
    rt_interrupt_enter();
    rt_tick_increase();       // RT-Thread 系统节拍
    QF_TICK_X(0U, (void *)0); // QP/C 时间事件驱动
    rt_interrupt_leave();
}

void sensor_thread_entry(void *p) {
    while (1) {
        rt_thread_mdelay(1);   // 每次循环: 阻塞→调度→唤醒→调度
        data = read_sensor();
        process_data(data);
    }
}

typedef struct {
    QActive   super;
    QTimeEvt  sampleEvt;     // 内置定时器
} SensorAO;

static SensorAO   l_sensor;
static QEvt const *sensorQSto[8];
static uint8_t     sensorStk[256];

enum { SAMPLE_SIG = Q_USER_SIG };

// 构造
void SensorAO_ctor(void) {
    QActive_ctor(&l_sensor.super, Q_STATE_CAST(&Sensor_initial));
    QTimeEvt_ctorX(&l_sensor.sampleEvt, &l_sensor.super, SAMPLE_SIG, 0U);
}

// 状态机
static QState Sensor_initial(SensorAO *me, QEvt const *e) {
    (void)e;
    QTimeEvt_armX(&me->sampleEvt, 1U, 1U);  // 周期 1ms (假设 1kHz tick)
    return Q_TRAN(&Sensor_active);
}

static QState Sensor_active(SensorAO *me, QEvt const *e) {
    switch (e->sig) {
    case SAMPLE_SIG: {
        uint16_t data = BSP_readADC();
        BSP_processData(data);
        return Q_HANDLED();
    }
    }
    return Q_SUPER(&QHsm_top);
}