QuickJS嵌入式开发：C函数注册为JS回调

在QuickJS嵌入式开发中，将C函数注册为JavaScript回调方法是扩展JavaScript功能、实现C/C++宿主环境与JavaScript运行时交互的关键。本文详细介绍了注册C函数的步骤：首先，定义核心C函数处理业务逻辑，并创建适配QuickJS API的包装器。然后，通过`JS_NewCFunction`将C函数注册到QuickJS运行时，使其在JavaScript中可被调用。文章还强调了参数验证、错误处理和内存管理等重要考量，以及在编译时包含QuickJS头文件和链接库。掌握C函数注册机制，能有效构建高性能、功能丰富的嵌入式JavaScript应用。

本文详细介绍了在QuickJS嵌入式项目中，如何将C语言函数注册为JavaScript可调用的回调函数。通过定义C函数、创建包装器并利用QuickJS提供的API，实现C++宿主环境与JavaScript运行时之间的有效交互，从而扩展JavaScript的功能并处理复杂逻辑。

QuickJS中的C函数注册机制

在QuickJS嵌入式开发中，宿主应用程序（通常用C/C++编写）与JavaScript引擎之间的交互是核心。为了让JavaScript代码能够调用宿主环境提供的功能，我们需要将C/C++函数“暴露”给JavaScript运行时。这种机制使得C函数可以作为JavaScript中的普通函数被调用，实现了宿主环境对JavaScript能力的扩展。

当JavaScript代码需要执行一些复杂或底层操作时（例如访问硬件、调用操作系统API、执行高性能计算等），直接在JavaScript中实现效率不高或不可行。此时，将这些操作封装成C函数，并将其注册为JavaScript可调用的回调函数，成为一种高效且灵活的解决方案。

注册C函数为JavaScript回调的步骤

将C函数注册到QuickJS运行时，主要涉及以下几个步骤：

1. 定义核心C语言回调函数

首先，需要定义实际执行业务逻辑的C函数。这个函数将接收来自JavaScript的参数，并返回一个JavaScript值。

// 定义实际的C语言回调函数
static JSValue myCallback(JSContext *ctx, JSValueConst this_val, int argc, JSValueConst *argv) {
    // 在这里实现您的回调逻辑
    // 例如：
    // if (argc > 0 && JS_IsNumber(argv[0])) {
    //     double num;
    //     JS_ToFloat64(ctx, &num, argv[0]);
    //     printf("Received number from JS: %f\n", num);
    // }
    // return JS_NewString(ctx, "Hello from C!");
    return JS_UNDEFINED; // 如果没有返回值，通常返回JS_UNDEFINED
}

• JSContext *ctx: QuickJS上下文，用于执行各种操作，如创建JS值、抛出异常等。
• JSValueConst this_val: JavaScript中调用该函数时的this值。
• int argc: 传递给函数的参数数量。
• JSValueConst *argv: 参数数组，每个元素都是一个JSValueConst，代表一个JavaScript值。

2. 创建QuickJS兼容的C函数包装器

QuickJS的JS_NewCFunction函数需要一个特定签名的函数指针。为了适配这个签名，通常会创建一个简单的包装器函数，它直接调用我们定义的核心C函数。

// 创建一个C函数包装器，适配JS_NewCFunction所需的签名
static JSValue js_myCallback(JSContext *ctx, JSValueConst this_val, int argc, JSValueConst *argv) {
    // 直接调用上面定义的核心回调函数
    return myCallback(ctx, this_val, argc, argv);
}

这个包装器确保了函数签名与QuickJS API的要求一致。

3. 将C函数注册到QuickJS运行时

最后一步是将包装器函数注册到QuickJS的全局对象或其他JavaScript对象上，使其可以在JavaScript代码中被访问和调用。

// 获取QuickJS的全局对象
JSValue global_obj = JS_GetGlobalObject(ctx);

// 使用JS_NewCFunction创建JS函数对象，并将其命名为"myCallback"
// js_myCallback 是上面定义的包装器函数
// "myCallback" 是JavaScript中可见的函数名
// 0 是参数数量，如果不需要检查参数数量，可以设置为0
JS_SetPropertyStr(ctx, global_obj, "myCallback", JS_NewCFunction(ctx, js_myCallback, "myCallback", 0));

// 释放对全局对象的引用
JS_FreeValue(ctx, global_obj);

• JS_GetGlobalObject(ctx): 获取当前上下文的全局对象（通常是window或global）。
• JS_NewCFunction(ctx, js_myCallback, "myCallback", 0): 创建一个新的C函数对象。js_myCallback是实际的C函数指针，"myCallback"是该函数在JavaScript中暴露的名称，0表示该C函数不强制要求特定数量的参数（如果需要严格参数检查，可以指定预期的参数数量）。
• JS_SetPropertyStr(ctx, global_obj, "myCallback", ...): 将新创建的C函数对象作为属性添加到全局对象上，属性名为"myCallback"。
• JS_FreeValue(ctx, global_obj): 释放对全局对象的引用。JS_GetGlobalObject返回的JSValue需要在使用后通过JS_FreeValue释放。

完整示例代码

结合上述步骤，完整的注册代码如下：

#include "quickjs.h" // 确保包含QuickJS头文件

// 假设您已经有了一个QuickJS上下文 ctx
// JSContext *ctx = JS_NewContext(JS_NewRuntime());

// 定义实际的C语言回调函数
static JSValue myCallback(JSContext *ctx, JSValueConst this_val, int argc, JSValueConst *argv) {
    // 处理回调逻辑
    printf("myCallback from C has been called!\n");
    // 您可以在这里访问 argv 中的参数，例如：
    // if (argc > 0 && JS_IsString(argv[0])) {
    //     const char *str = JS_ToCString(ctx, argv[0]);
    //     printf("Argument from JS: %s\n", str);
    //     JS_FreeCString(ctx, str);
    // }
    return JS_UNDEFINED;
}

// 创建一个C函数包装器
static JSValue js_myCallback(JSContext *ctx, JSValueConst this_val, int argc, JSValueConst *argv) {
    return myCallback(ctx, this_val, argc, argv);
}

// 在您的QuickJS初始化代码中调用此函数来注册
void registerMyCallback(JSContext *ctx) {
    JSValue global_obj = JS_GetGlobalObject(ctx);
    JS_SetPropertyStr(ctx, global_obj, "myCallback", JS_NewCFunction(ctx, js_myCallback, "myCallback", 0));
    JS_FreeValue(ctx, global_obj);
}

// 示例用法 (在您的main函数或初始化逻辑中)
/*
int main() {
    JSRuntime *rt = JS_NewRuntime();
    JSContext *ctx = JS_NewContext(rt);

    // 注册回调函数
    registerMyCallback(ctx);

    // 执行一些JavaScript代码来调用回调
    const char *script = "myCallback(); console.log('Callback called from JS');";
    JS_Eval(ctx, script, strlen(script), "<eval>", JS_EVAL_GLOBAL);

    // 清理
    JS_FreeContext(ctx);
    JS_FreeRuntime(rt);
    return 0;
}
*/

在JavaScript中调用注册的C函数

一旦C函数被成功注册，它就可以在JavaScript代码中像普通的JavaScript函数一样被调用：

// 在JavaScript代码中调用C函数
myCallback(); // 这将执行C语言中的 myCallback 函数

// 也可以传递参数
// myCallback("Hello from JavaScript!", 123);

重要考量与最佳实践

1. 参数验证与类型检查: 当C函数接收JavaScript参数时，务必进行类型检查和验证。QuickJS提供了JS_IsNumber(), JS_IsString(), JS_IsFunction(), JS_ToInt32(), JS_ToCString()等一系列API来处理JS值的转换和验证。例如，在用户原始问题中提到的JS_IsFunction(ctx, argv[0])就是一个很好的参数验证实践。

   // 示例：检查第一个参数是否为函数
   if (argc == 0 || !JS_IsFunction(ctx, argv[0])) {
       return JS_ThrowTypeError(ctx, "Expected a function as argument");
   }

2. 错误处理: 在C函数中，如果发生错误，应该使用JS_Throw或JS_ThrowTypeError等函数向JavaScript运行时抛出异常，而不是直接返回错误码或终止程序。这使得JavaScript代码可以使用try...catch来捕获和处理这些错误。

3. 内存管理: QuickJS的JSValue是引用计数的。当从QuickJS API获取一个JSValue时（例如JS_GetGlobalObject），通常需要在使用完毕后通过JS_FreeValue释放它，除非该值被传递给另一个会增加其引用计数的API。对于传入C函数的JSValueConst *argv中的参数，通常不需要手动释放，因为它们是由QuickJS管理生命周期的。但如果需要长期持有某个JSValue（例如存储一个JavaScript回调函数到C++对象中），则必须使用JS_DupValue来增加其引用计数，并在不再需要时使用JS_FreeValue释放。

4. 上下文管理: 确保在正确的JSContext中执行操作。不同的JSContext之间是隔离的。

5. 编译与链接: 在编译您的嵌入式项目时，请确保包含QuickJS的头文件（如quickjs.h），并链接QuickJS库。

总结

通过上述方法，QuickJS嵌入式项目能够将C语言函数无缝地集成到JavaScript环境中，极大地增强了JavaScript的功能性和与宿主环境的交互能力。这种机制是构建高性能、功能丰富的嵌入式JavaScript应用的关键。理解并熟练运用C函数注册机制，是QuickJS嵌入式开发中不可或缺的技能。

今天关于《QuickJS嵌入式开发：C函数注册为JS回调》的内容就介绍到这里了，是不是学起来一目了然！想要了解更多关于的内容请关注golang学习网公众号！