microPython的源码解析之 objgenerator.c

MicroPython 是一种适用于微控制器和其他受限环境的 Python 编程语言的实现。它旨在提供与 Python 3 语言的紧密兼容，同时考虑到内存和计算资源的限制。MicroPython 库是这门语言的核心组成部分，提供了一系列的模块和函数，使得开发者能够在硬件上执行各种任务。
下面将通过系列文章,逐一解读microPython,以便让读者了解掌握microPython的整个核心逻辑.,以便读者可以透过这个Python的最小内核,掌握Python解析器的核心实现逻辑,学习世界上最优秀的源码设计之一.

microPython Python最小内核源码解析
这段代码是MicroPython中生成器(Generator)的实现部分。生成器是一种特殊的迭代器，可以在执行过程中暂停和恢复。
代码中定义了生成器的包装器结构体、调用函数、实例方法（如send、throw、close等），以及生成器实例的类型。
生成器在Python中用于创建复杂的迭代逻辑，可以在执行到yield语句时暂停，保留当前状态，并在之后从停止的地方继续执行。

#include <stdlib.h>
#include <assert.h>

#include "py/runtime.h"
#include "py/bc.h"
#include "py/objstr.h"
#include "py/objgenerator.h"
#include "py/objfun.h"
#include "py/stackctrl.h"

// 生成器退出异常的实例 - 生成器关闭时需要
const mp_obj_exception_t mp_const_GeneratorExit_obj = {
   
    {
   &mp_type_GeneratorExit}, // 类型指向GeneratorExit
    0, // 未使用的字段
    0, // 未使用的字段
    NULL, // 未使用的字段
    (mp_obj_tuple_t *)&mp_const_empty_tuple_obj // 指向空元组的指针
};

/******************************************************************************/
/* 生成器包装器                                                          */

// 生成器对象的结构体定义
typedef struct _mp_obj_gen_instance_t {
   
    mp_obj_base_t base; // 基础对象结构
    // pend_exc: 异常状态，mp_const_none表示未运行且没有异常，MP_OBJ_NULL表示正在运行且没有异常，其他值表示未运行且有待处理的异常
    mp_obj_t pend_exc;
    // code_state: 代码状态结构体，存储生成器执行时的上下文信息
    mp_code_state_t code_state;
} mp_obj_gen_instance_t;

// 生成器包装器的调用函数实现
static mp_obj_t gen_wrap_call(mp_obj_t self_in, size_t n_args, size_t n_kw, const mp_obj_t *args) {
   
    // self_in: 传入的生成器包装器对象
    mp_obj_fun_bc_t *self_fun = MP_OBJ_TO_PTR(self_in); // 将对象转换为函数指针

    // 获取字节码前缀，包括状态大小和异常堆栈大小
    const uint8_t *ip = self_fun->bytecode;
    MP_BC_PRELUDE_SIG_DECODE(ip);

    // 分配生成器对象内存，包括局部堆栈和异常堆栈
    mp_obj_gen_instance_t *o = mp_obj_malloc_var(
        mp_obj_gen_instance_t, // 分配对象类型
        code_state.state, // 状态大小
        byte, // 每个状态的大小
        n_state * sizeof(mp_obj_t) + n_exc_stack * sizeof(mp_exc_stack_t), // 需要分配的总内存
        &mp_type_gen_instance // 对象类型
    );

    // 初始化异常状态和代码状态
    o->pend_exc = mp_const_none;
    o->code_state.fun_bc = self_fun;
    o->code_state.n_state = n_state;
    // 设置代码状态，包括参数等
    mp_setup_code_state(&o->code_state, n_args, n_kw, args);
    return MP_OBJ_FROM_PTR(o); // 返回生成器对象
}

// 根据编译选项定义生成器包装器的类型属性
#if MICROPY_PY_FUNCTION_ATTRS
#define GEN_WRAP_TYPE_ATTR attr, mp_obj_fun_bc_attr,
#else
#define GEN_WRAP_TYPE_ATTR
#endif

// 定义生成器包装器的类型
MP_DEFINE_CONST_OBJ_TYPE(
    mp_type_gen_wrap,
    MP_QSTR_generator, // 类型名称
    MP_TYPE_FLAG_BINDS_SELF, // 类型标志
    GEN_WRAP_TYPE_ATTR // 类型属性
    call, gen_wrap_call // 调用函数
    );

/******************************************************************************/
// 原生生成器包装器

#if MICROPY_EMIT_NATIVE

// 原生生成器对象的结构体定义
typedef struct _mp_obj_gen_instance_native_t {
   
    mp_obj_base_t base; // 基础对象结构
    mp_obj_t pend_exc; // 待处理的异常
    mp_code_state_native_t code_state; // 原生代码状态
} mp_obj_gen_instance_native_t;

// 原生生成器包装器的调用函数实现
static mp_obj_t native_gen_wrap_call(mp_obj_t self_in, size_t n_args, size_t n_kw, const mp_obj_t *args) {
   
    // self_in: 传入的原生生成器包装器对象
    mp_obj_fun_bc_t *self_fun = MP_OBJ_TO_PTR(self_in); // 将对象转换为函数指针

    // 获取原生函数的前缀指针
    const uint8_t *prelude_ptr = mp_obj_fun_native_get_prelude_ptr(self_fun);

    // 从前缀中提取状态大小
    const uint8_t *ip = prelude_ptr;
    MP_BC_PRELUDE_SIG_DECODE(ip);

    // 分配原生生成器对象内存，包括局部堆栈（不需要异常堆栈）
    mp_obj_gen_instance_native_t *o = mp_obj_malloc_var(
        mp_obj_gen_instance_native_t, // 分配对象类型
        code_state.state, // 状态大小
        byte, // 每个状态的大小
        n_state * sizeof(mp_obj_t), // 需要分配的总内存
        &mp_type_gen_instance // 对象类型
    );

    // 设置代码状态
    o->pend_exc = mp_const_none;
    o->code_state.fun_bc = self_fun;
    o->code_state.n_state = n_state;
    // 设置原生代码状态，包括参数等
    mp_setup_code_state_native(&o->code_state, n_args, n_kw, args);

    // 标记为原生函数，不使用此变量
    o->code_state.exc_sp_idx = MP_CODE_STATE_EXC_SP_IDX_SENTINEL;

    // 准备生成器实例以供执行
    o->code_state.ip = mp_obj_fun_native_get_generator_start(self_fun);

    return MP_OBJ_FROM_PTR(o); // 返回生成器对象
}

// 根据编译选项定义原生生成器包装器的类型属性
#if MICROPY_PY_FUNCTION_ATTRS
#define NATIVE_GEN_WRAP_TYPE_ATTR , attr, mp_obj_fun_bc_attr
#else
#define NATIVE_GEN_WRAP_TYPE_ATTR
#endif

// 定义原生生成器包装器的类型
MP_DEFINE_CONST_OBJ_TYPE(
    mp_type_native_gen_wrap,
    MP_QSTR_generator, // 类型名称
    MP_TYPE_FLAG_BINDS_SELF, // 类型标志
    call, native_gen_wrap_call // 调用函数
    NATIVE_GEN_WRAP_TYPE_ATTR
    );

#endif // MICROPY_EMIT_NATIVE

/******************************************************************************/
/* 生成器实例                                                          */

// 生成器实例的打印函数实现
static void gen_instance_print(const mp_print_t *print, mp_obj_t self_in, mp_print_kind_t kind) {
   
    (void)kind; // 忽略kind参数
    mp_obj_gen_instance_t *self = MP_OBJ_TO_PTR(self_in); // 将对象转换为生成器实例指针
    // 打印生成器对象的信息
    mp_printf(print, "<generator object '%q' at %p>", mp_obj_fun_get_name(MP_OBJ_FROM_PTR(self->code_state.fun_bc)), self);