QuickJS-NG 中的函数与不透明指针关联技术解析

在 QuickJS-NG 项目中，开发者经常需要将 C 函数与特定指针数据关联起来，以便在 JavaScript 调用时能够访问这些数据。本文将深入探讨这一技术需求及其解决方案。

需求背景

在 QuickJS-NG 这样的嵌入式 JavaScript 引擎中，有时需要让一个 C 函数出现在多个不同的 JSContext 上下文中，并且每次调用时能够针对不同的外部对象执行操作。理想情况下，我们希望直接将数据指针与函数关联，而不是通过额外的映射表来维护这种关系。

现有机制分析

QuickJS-NG 提供了几种数据关联机制：

1. Magic 整数：可以关联一个整数到函数，但空间有限（不足以存储64位指针）
2. JS 数据：可以关联任意 JS 类型数据，但不适合直接存储原始指针
3. 类的不透明数据：支持存储指针，但普通函数对象默认不支持

解决方案

1. 使用类模拟函数

通过创建一个自定义类并实现 call 方法，可以实现函数与指针的关联：

typedef JSValue JSCFunctionOpaque(JSContext *ctx, JSValue this_val, 
                                int argc, JSValue *argv, void *opaque);

struct my_tuple {
    JSCFunctionOpaque *fun;
    void *opaque;
};

JSValue call_opaque(JSContext *ctx, JSValue fun, JSValue this, 
                   int argc, JSValue *argv, int magic) {
    struct my_tuple *tup = JS_GetOpaque(fun, JS_GetClassID(fun));
    return tup->fun(ctx, this, argc, argv, tup->opaque);
}

这种方法的关键点：

• 定义包含函数指针和数据指针的结构体
• 实现类的 call 方法作为代理
• 通过 JS_GetOpaque 获取关联数据

2. 使用上下文不透明指针

如果数据是按上下文而非按函数区分的，可以使用内置的上下文不透明指针机制：

void *opaque = JS_GetContextOpaque(ctx);

这种方法更简单，但适用范围有限。

3. 使用 BigInt 间接存储指针

通过 JS_NewCFunctionData 结合 BigInt 可以间接存储指针：

JSValue aux = JS_NewBigUint64(ctx, (uint64_t)(uintptr_t)opaque);
JS_NewCFunctionData(ctx, func, length, magic, 1, &aux);

在回调函数中通过 JS_ToBigUint64 转换回指针。这种方法虽然巧妙，但存在类型安全问题。

技术对比

方法	优点	缺点
类模拟函数	类型安全，直接支持指针	实现较复杂
上下文指针	简单直接	仅支持每个上下文一个指针
BigInt 转换	不需要额外类定义	类型不安全，依赖特定实现

最佳实践建议

对于大多数情况，推荐使用类模拟函数的方法，因为：

1. 类型安全，不会意外解释错误的数据
2. 内存管理明确，有明确的析构点
3. 扩展性强，可以添加更多元数据

实现示例

以下是完整的类模拟函数实现示例：

#include <stdlib.h>
#include "quickjs.h"

// 定义函数类型
typedef JSValue JSCFunctionOpaque(JSContext *ctx, JSValue this_val, 
                                int argc, JSValue *argv, void *opaque);

// 存储函数和指针的结构体
struct my_tuple {
    JSCFunctionOpaque *fun;
    void *opaque;
};

// 类的call方法实现
JSValue call_opaque(JSContext *ctx, JSValue fun, JSValue this, 
                   int argc, JSValue *argv, int magic) {
    struct my_tuple *tup = JS_GetOpaque(fun, JS_GetClassID(fun));
    return tup->fun(ctx, this, argc, argv, tup->opaque);
}

// 类的析构函数
void finalize_opaque(JSRuntime *rt, JSValue val) {
    free(JS_GetOpaque(val, JS_GetClassID(val)));
}

// 类定义
JSClassDef def = { 
    "Function", 
    .call = call_opaque, 
    .finalizer = finalize_opaque 
};

// 创建不透明函数
JSValue new_c_function_opaque(JSContext *ctx, JSCFunctionOpaque *cfun, 
                            void *opaque) {
    JSValue fun, proto;
    struct my_tuple *tup;

    proto = JS_GetFunctionProto(ctx);
    fun = JS_NewObjectProtoClass(ctx, proto, id);
    JS_FreeValue(ctx, proto);
    if (JS_IsException(fun))
        return fun;
    tup = malloc(sizeof(*tup));
    tup->fun = cfun;
    tup->opaque = opaque;
    JS_SetOpaque(fun, tup);
    return fun;
}

总结

QuickJS-NG 提供了多种方式来实现 C 函数与指针数据的关联，开发者可以根据具体需求选择最适合的方案。类模拟函数的方法虽然实现稍复杂，但提供了最好的类型安全性和扩展性，是大多数场景下的推荐选择。理解这些技术细节有助于开发者更好地利用 QuickJS-NG 的强大功能，构建高效的 JavaScript 扩展。