microPython的源码解析之 objexcept.c

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

microPython Python最小内核源码解析
这段代码是MicroPython异常处理的一部分，它定义了异常对象的创建、打印、属性操作以及跟踪回溯信息的处理。代码中包含了对内存分配、类型检查、字符串处理等多个方面的操作，以及对紧急情况下内存分配失败的处理策略。这些函数和结构体是MicroPython运行时异常处理机制的核心组成部分。

#include <string.h> // 字符串操作函数
#include <stdarg.h> // 可变参数列表处理
#include <assert.h>  // 断言检查
#include <stdio.h>   // 标准输入输出函数

// 包含MicroPython的特定头文件
#include "py/objlist.h" // 列表对象处理
#include "py/objstr.h"  // 字符串对象处理
#include "py/objtuple.h" // 元组对象处理
#include "py/objtype.h"  // 对象类型处理
#include "py/runtime.h" // 运行时环境设置
#include "py/gc.h"      // 垃圾回收机制
#include "py/mperrno.h"  // 错误码定义

#if MICROPY_ROM_TEXT_COMPRESSION && !defined(NO_QSTR)
// 如果启用了ROM文本压缩并且不是在QSTR提取过程中
// 从"genhdr/compressed.data.h"提取MP_MAX_UNCOMPRESSED_TEXT_LEN宏
#define MP_MATCH_COMPRESSED(...) // 忽略
#define MP_COMPRESSED_DATA(...) // 忽略
#include "genhdr/compressed.data.h"
#undef MP_MATCH_COMPRESSED
#undef MP_COMPRESSED_DATA
#endif

// 跟踪回溯条目的长度（文件、行、块）
#define TRACEBACK_ENTRY_LEN (3)

// 可选分配的缓冲区，用于存储一些跟踪回溯信息、元组参数、可能的字符串对象和数据，
// 当堆被锁定时使用。
#if MICROPY_ENABLE_EMERGENCY_EXCEPTION_BUF

// 当使用时，紧急异常缓冲区的布局如下：
//  - 跟踪回溯条目（文件、行、块）
//  - 跟踪回溯条目（文件、行、块）
//  - mp_obj_tuple_t对象
//  - n_args * mp_obj_t，用于元组
//  - mp_obj_str_t对象
//  - 字符串数据
#define EMG_BUF_TRACEBACK_OFFSET    (0)
#define EMG_BUF_TRACEBACK_SIZE      (2 * TRACEBACK_ENTRY_LEN * sizeof(size_t))
#define EMG_BUF_TUPLE_OFFSET        (EMG_BUF_TRACEBACK_OFFSET + EMG_BUF_TRACEBACK_SIZE)
#define EMG_BUF_TUPLE_SIZE(n_args)  (sizeof(mp_obj_tuple_t) + n_args * sizeof(mp_obj_t))
#define EMG_BUF_STR_OFFSET          (EMG_BUF_TUPLE_OFFSET + EMG_BUF_TUPLE_SIZE(1))
#define EMG_BUF_STR_BUF_OFFSET      (EMG_BUF_STR_OFFSET + sizeof(mp_obj_str_t))

#if MICROPY_EMERGENCY_EXCEPTION_BUF_SIZE > 0
#define mp_emergency_exception_buf_size MICROPY_EMERGENCY_EXCEPTION_BUF_SIZE

// 初始化紧急异常缓冲区
void mp_init_emergency_exception_buf(void) {
   
    // 由于缓冲区是静态声明的，这里不需要做任何事情。我们在这里提供这个函数定义，
    // 以便调用代码无论其配置如何都可以调用这个函数（使得调用代码稍微简洁一些）。
}

#else
#define mp_emergency_exception_buf_size MP_STATE_VM(mp_emergency_exception_buf_size)

// 包含MicroPython的硬件抽象层头文件，用于原子操作
#include "py/mphal.h" // for MICROPY_BEGIN_ATOMIC_SECTION/MICROPY_END_ATOMIC_SECTION

// 初始化紧急异常缓冲区
void mp_init_emergency_exception_buf(void) {
   
    mp_emergency_exception_buf_size = 0;
    MP_STATE_VM(mp_emergency_exception_buf) = NULL;
}

// 分配紧急异常缓冲区
mp_obj_t mp_alloc_emergency_exception_buf(mp_obj_t size_in) {
   
    mp_int_t size = mp_obj_get_int(size_in);
    void *buf = NULL;
    if (size > 0) {
   
        buf = m_new(byte, size);
    }

    int old_size = mp_emergency_exception_buf_size;
    void *old_buf = MP_STATE_VM(mp_emergency_exception_buf);

    // 原子性地更新这两个变量，以便中断不会在赋值之间发生。
    mp_uint_t atomic_state = MICROPY_BEGIN_ATOMIC_SECTION();
    mp_emergency_exception_buf_size = size;
    MP_STATE_VM(mp_emergency_exception_buf) = buf;
    MICROPY_END_ATOMIC_SECTION(atomic_state);

    if (old_buf != NULL) {
   
        m_del(byte, old_buf, old_size);
    }
    return mp_const_none;
}
#endif
#endif  // MICROPY_ENABLE_EMERGENCY_EXCEPTION_BUF

// 判断对象是否为原生异常实例
bool mp_obj_is_native_exception_instance(mp_obj_t self_in) {
   
    return MP_OBJ_TYPE_GET_SLOT_OR_NULL(mp_obj_get_type(self_in), make_new) == mp_obj_exception_make_new;
}

// 获取原生异常对象
static mp_obj_exception_t *get_native_exception(mp_obj_t self_in) {
   
    assert(mp_obj_is_exception_instance(self_in));
    if (mp_obj_is_native_exception_instance(self_in)) {
   
        return MP_OBJ_TO_PTR(self_in);
    } else {
   
        return MP_OBJ_TO_PTR(((mp_obj_instance_t *)MP_OBJ_TO_PTR(self_in))->subobj[0]);
    }
}

// 可能的话解压错误文本
static void decompress_error_text_maybe(mp_obj_exception_t *o) {
   
    #if MICROPY_ROM_TEXT_COMPRESSION
    if (o->args->len == 1 && mp_obj_is_exact_type(o->args->items[0], &mp_type_str)) {
   
        mp_obj_str_t *o_str = MP_OBJ_TO_PTR(o->args->items[0]);
        if (MP_IS_COMPRESSED_ROM_STRING(o_str->data)) {
   
            byte *buf = m_new_maybe(byte, MP_MAX_UNCOMPRESSED_TEXT_LEN + 1);
            if (!buf) {
   
                #if MICROPY_ENABLE_EMERGENCY_EXCEPTION_BUF
                // 如果没有足够的空间，尝试使用紧急异常缓冲区。
                buf = (byte *)((uint8_t *)MP_STATE_VM(mp_emergency_exception_buf) + EMG_BUF_STR_BUF_OFFSET);
                size_t avail = (uint8_t *)MP_STATE_VM(mp_emergency_exception_buf) + mp_emergency_exception_buf_size - buf;
                if (avail < MP_MAX_UNCOMPRESSED_TEXT_LEN + 1) {
   
                    // 无法解压，回退到没有消息文本。
                    o->args = (mp_obj_tuple_t *)&mp_const_empty_tuple_obj;
                    return;
                }
                #else
                o->args = (mp_obj_tuple_t *)&mp_const_empty_tuple_obj;
                return;
                #endif
            }
            mp_decompress_rom_string(buf, (mp_rom_error_text_t)o_str->data);
            o_str->data = buf;
            o_str->len = strlen((const char *)buf);
            o_str->hash = 0;
        }
        // 延迟计算字符串哈希。
        if (o_str->hash == 0) {
   
            o_str->hash = qstr_compute_hash(o_str->data, o_str->len);
        }
    }
    #endif
}

// 打印异常对象
void mp_obj_exception_print(const mp_print_t *print, mp_obj_t o_in, mp_print_kind_t kind) {
   
    mp_obj_exception_t *o = MP_OBJ_TO_PTR(o_in);
    mp_print_kind_t k = kind & ~PRINT_EXC_SUBCLASS;
    bool is_subclass = kind & PRINT_EXC_SUBCLASS;