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值。

立即学习“Java免费学习笔记（深入）”；

// 定义实际的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: %fn", 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: %sn", 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嵌入式开发中不可或缺的技能。