JerryScript 迁移指南:从 1.0 到 2.0/3.0 的 API 升级实战

原创2026-09-27 19:47:251,751 阅读
文章标签:编程语言语言运行时解释器嵌入式物联网标准库

JerryScript 迁移指南:从 1.0 到 2.0/3.0 的 API 升级实战

本篇指南以 JerryScript 官方迁移文档(docs/16.MIGRATION-GUIDE.md)为主体,完整梳理从 1.0 到 2.0 版本间的 API 变更,包括被删除/重命名的头文件、类型、函数与配置宏,并为每一项变更提供 Before(1.0 写法) 与 After(2.0 写法) 的可直接编译对照代码。读者完成后将能够:识别并修复旧代码中的全部破坏性 API 调用、正确使用新的错误处理与原生指针(Native Pointer)机制、迁移快照生成与 GC 调用方式,并了解 2.x 到 3.x 的 API 大规模重命名背景。所有新 API 的完整签名可对照 docs/02.API-REFERENCE.md 查阅。

1. 迁移背景与总体思路

JerryScript 1.0 与 2.0 之间的主要变化集中在 API 函数的移除与签名调整 上。开发团队在设计 2.0 时遵循了一个重要原则:尽量最小化 API 函数与类型的变动。因此,绝大多数变更都是"一对一"的替换关系,每个被移除或修改的 API 方法都可以在本指南中找到对应的 before/after 代码示例,迁移成本被控制在可接受的范围内。

迁移工作的总思路可以概括为三步:

  1. 对照速查表:先使用第 2 节的"短列表"快速定位项目中用到了哪些已删除/已重命名的符号;
  2. 逐项替换:对每个符号按第 3~6 节的 before/after 示例进行替换;
  3. 处理新 API 与 Port API:根据需要补充实现新版本引入的功能(如 Promise、TypedArray、多原生指针),并更新移植层(Port API)的时区函数。

2. 删除/重命名清单速查

2.1 头文件变更

被删除的头文件:

  • jerry-internal.h —— 该内部头文件在 2.0 中不再对外暴露,相关内部实现被收纳进核心源码目录。

被重命名的头文件:

旧名称(1.0) 新名称(2.0)
jerry-api.h jerryscript.h
jerry-port.h jerryscript-port.h

在 2.0 中,主头文件为 jerry-core/include/jerryscript.h,它聚合了 jerryscript-core.h(核心 API)、jerryscript-snapshot.h(快照 API)等子头文件;移植层头文件为 jerryscript-port.h。

2.2 删除的 API 类型

旧类型(1.0) 替换方案(2.0)
jerry_char_ptr_t 直接使用 jerry_char_t *
jerry_object_free_callback_t jerry_object_native_info_t(结构化原生信息描述)

jerry_char_t 在 jerryscript-types.h 中定义为 uint8_t,其指针形式 jerry_char_t * 即取代了 1.0 中冗余的 jerry_char_ptr_t 别名。

2.3 删除的 API 方法(及替换目标)

被删除方法(1.0) 替换方法(2.0)
jerry_get_memory_limits 移除,内存信息获取方式改为通过上下文/配置管理
jerry_get_object_native_handle jerry_get_object_native_pointer
jerry_set_object_native_handle jerry_set_object_native_pointer
jerry_value_set_abort_flag jerry_create_abort_from_value
jerry_value_has_abort_flag jerry_value_is_abort
jerry_value_set_error_flag jerry_create_error_from_value
jerry_value_has_error_flag jerry_value_is_error
jerry_value_clear_error_flag jerry_get_value_from_error
jerry_get_value_without_error_flag jerry_get_value_from_error
jerry_parse_and_save_snapshot jerry_generate_snapshot
jerry_parse_and_save_function_snapshot jerry_generate_function_snapshot

2.4 删除的配置宏

以下配置宏在 2.0 中被移除:

  • CONFIG_MEM_DATA_LIMIT_MINUS_HEAP_SIZE
  • CONFIG_MEM_STACK_LIMIT
  • CONFIG_VM_STACK_FRAME_INLINED_VALUES_NUMBER
  • CONFIG_ECMA_GLOBAL_ENVIRONMENT_DECLARATIVE

同时,所有 CONFIG_.. 系列宏统一改名为 JERRY_ 前缀格式。当前版本的完整可配置宏清单可以在 jerry-core/config.h 中查看,例如内存上限 JERRY_MEM_HEAP_LIMIT、特性开关 JERRY_ESNEXT、JERRY_DEBUGGER 等。在 3.0 中这些宏进一步演进为 JERRY_BUILTIN_*、JERRY_GC_* 等细分命名。迁移时,凡是代码中出现的 CONFIG_ 前缀宏都需要改为对应的 JERRY_ 前缀形式。

3. 错误处理函数的迁移(重点)

错误处理是 1.0 → 2.0 中 最重要的 API 变更区域。1.0 时代通过"修改标志位"的方式在 jerry_value_t 上就地打上/清除错误与 abort 标记;2.0 改为显式构造错误/abort 值,返回值所有权语义更清晰。

3.1 jerry_value_set_abort_flag → jerry_create_abort_from_value

新函数 jerry_create_abort_from_value 的第二个参数(bool take_ownership)控制调用后第一个参数 value 是否仍然可用:

  • 传 true:调用后原 value 的所有权转移给新的 abort 值,原变量不得再使用,只需释放 abort;
  • 传 false:调用后 abort 与 value 都可用,两者都需要单独释放。

Before(1.0):

{
  jerry_value_t value;
  // create or acquire value
  // ...

  jerry_value_set_abort_flag (&value);

  jerry_release_value (value);
}

After(2.0,转移所有权):

{
  jerry_value_t value;
  // create or acquire value
  // ...

  jerry_value_t abort = jerry_create_abort_from_value (value, true);
  // using the 'value' variable after release is invalid

  jerry_release_value (abort);
}

After(2.0,保留原值):

{
  jerry_value_t value;
  ... // create or acquire value

  jerry_value_t abort = jerry_create_abort_from_value (value, false);
  // both 'abort' and 'value' can be used and must be released when they are no longer needed

  jerry_release_value (abort);
  jerry_release_value (value);
}

3.2 jerry_value_has_abort_flag → jerry_value_is_abort

仅改名为 jerry_value_is_abort,参数与返回值语义不变。该函数在 jerryscript-core.h 中声明为 bool jerry_value_is_abort (const jerry_value_t value);。

Before:

{
  jerry_value_t value;
  // create or acquire value
  // ...

  if (jerry_value_has_abort_flag (value))
  {
    // ...
  }

  jerry_release_value (value);
}

After:

{
  jerry_value_t value;
  // create or acquire value
  // ...

  if (jerry_value_is_abort (value))
  {
    // ...
  }

  jerry_release_value (value);
}

3.3 jerry_value_set_error_flag → jerry_create_error_from_value

替换逻辑与 jerry_create_abort_from_value 完全对称,第二个参数同样控制 value 的所有权转移。文档中该函数参考 API Reference。

Before:

{
  jerry_value_t value;
  // create or acquire value
  // ...

  jerry_value_set_error_flag (&value);

  jerry_release_value (value);
}

After(转移所有权):

{
  jerry_value_t value;
  // create or acquire value
  // ...

  jerry_value_t error = jerry_create_error_from_value (value, true);
  // using the 'value' variable after release is invalid

  jerry_release_value (error);
}

After(保留原值):

{
  jerry_value_t value;
  // create or acquire value
  // ...

  jerry_value_t error = jerry_create_error_from_value (value, false);
  // both 'error' and 'value' can be used and must be released when they are no longer needed

  jerry_release_value (error);
  jerry_release_value (value);
}

3.4 jerry_value_has_error_flag → jerry_value_is_error

同名替换,声明见 jerryscript-core.h:bool jerry_value_is_error (const jerry_value_t value);。

Before:

{
  jerry_value_t value;
  // create or acquire value
  // ...

  if (jerry_value_has_error_flag (value))
  {
    // ...
  }

  jerry_release_value (value);
}

After:

{
  jerry_value_t value;
  // create or acquire value
  // ...

  if (jerry_value_is_error (value))
  {
    // ...
  }

  jerry_release_value (value);
}

3.5 jerry_value_clear_error_flag 与 jerry_get_value_without_error_flag → jerry_get_value_from_error

这两个 1.0 函数在 2.0 中被合并为单一的 jerry_get_value_from_error。注意其第二个参数:控制是否在取出真实值的同时释放传入的错误值。

Before:

{
  jerry_value_t value;
  // create or acquire value
  // ...

  jerry_value_set_error_flag (&value);
  jerry_value_clear_error_flag (&value);
  // or
  jerry_value_t real_value = jerry_get_value_without_error_flag (value);

  jerry_release_value (value);
  jerry_release_value (real_value);
}

After:

{
  jerry_value_t value;
  // create or acquire value
  // ...

  jerry_value_t error = jerry_create_error_from_value (value, true);

  jerry_value_t real_value = jerry_get_value_from_error (error, true);

  jerry_release_value (real_value);
}

所有权小结:2.0 的错误处理 API 围绕 jerry_value_t 的所有权转移设计了统一的二参数模式。迁移时最容易出错的地方是"第二个参数传错导致双重释放或内存泄漏",建议在替换时逐条核对:true 表示调用方不再持有原值,false 表示双方都需要释放。

4. 其他被修改的函数

4.1 jerry_register_magic_strings:类型从 jerry_char_ptr_t 改为 jerry_char_t *

该函数用于注册"魔法字符串"(magic strings,即在源码中高频出现、被静态化存储以节省内存的字符串常量)。变更点是第一个参数的基础类型由 jerry_char_ptr_t 改为 jerry_char_t *。当前仓库中的声明为 jerryscript-core.h:

void jerry_register_magic_strings (const jerry_char_t *const *ext_strings_p,
                                   uint32_t count,
                                   const jerry_length_t *lengths_p);

注意两个前提条件(两个版本通用):

  • 数组必须是 static 的,因为该函数不会复制字符串内容;
  • 字符串条目必须先按长度升序排序,再按字典序排序。

Before:

{
  // must be static, because 'jerry_register_magic_strings' does not copy
  // the items must be sorted by size at first, then lexicographically
  static const jerry_char_ptr_t magic_string_items[] = {
                                                          (const jerry_char_ptr_t) "magicstring1",
                                                          (const jerry_char_ptr_t) "magicstring2",
                                                          (const jerry_char_ptr_t) "magicstring3"
                                                        };
  uint32_t num_magic_string_items = (uint32_t) (sizeof (magic_string_items) / sizeof (jerry_char_ptr_t));

  // must be static, because 'jerry_register_magic_strings' does not copy
  static const jerry_length_t magic_string_lengths[] = { 12, 12, 12 };
  jerry_register_magic_strings (magic_string_items, num_magic_string_items, magic_string_lengths);
}

After:

{
  // must be static, because 'jerry_register_magic_strings' does not copy
  // the items must be sorted by size at first, then lexicographically
  static const jerry_char_t *magic_string_items[] = {
                                                      (const jerry_char_t *) "magicstring1",
                                                      (const jerry_char_t *) "magicstring2",
                                                      (const jerry_char_t *) "magicstring3"
                                                    };
  uint32_t num_magic_string_items = (uint32_t) (sizeof (magic_string_items) / sizeof (jerry_char_t *));

  // must be static, because 'jerry_register_magic_strings' does not copy
  static const jerry_length_t magic_string_lengths[] = { 12, 12, 12 };
  jerry_register_magic_strings (magic_string_items, num_magic_string_items, magic_string_lengths);
}

4.2 jerry_parse_and_save_snapshot → jerry_generate_snapshot

快照(Snapshot)是 JerryScript 的核心特性之一:将源码预先编译为字节码缓冲,运行时直接加载,省去解析时间,非常适合物联网场景。2.0 的新函数 以返回值报告生成结果:若生成过程中出现问题(如语法错误)则返回错误对象;若成功则返回一个数字值,其数值即快照的字节数。底层实现在 jerry-snapshot.c 的 jerry_generate_snapshot 中,完整签名见 jerryscript-snapshot.h。

Before:

{
  static uint32_t global_mode_snapshot_buffer[256];
  const jerry_char_t *code_to_snapshot_p = (const jerry_char_t *) "(function () { return 'string from snapshot'; }) ();";

  size_t global_mode_snapshot_size =
    jerry_parse_and_save_snapshot (code_to_snapshot_p,
                                   strlen ((const char *) code_to_snapshot_p),
                                   true,
                                   false,
                                   global_mode_snapshot_buffer,
                                   sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t));
  // use "global_mode_snapshot_buffer"
}

After:

{
  static uint32_t global_mode_snapshot_buffer[256];
  const jerry_char_t *code_to_snapshot_p = (const jerry_char_t *) "(function () { return 'string from snapshot'; }) ();";

  jerry_value_t generate_result;
  generate_result = jerry_generate_snapshot (NULL,
                                             0,
                                             code_to_snapshot_p,
                                             strlen ((const char *) code_to_snapshot_p),
                                             global_mode_snapshot_buffer,
                                             sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t));
  if (jerry_value_is_error (generate_result))
  {
    // There was a problem during snapshot generation, for example there is a SyntaxError.
    // Use the "generate_result" to check the error.
  }
  else
  {
    size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
    // use "global_mode_snapshot_buffer"
  }
  jerry_release_value (generate_result);
}

新签名在开头多出的两个参数(NULL, 0)分别对应"预编译的代码值"与"生成选项",直接传 NULL, 0 表示传入的是原始源码而非预编译结果。

4.3 jerry_parse_and_save_function_snapshot → jerry_generate_function_snapshot

函数快照用于将单个函数(含参数列表)预编译为快照。与上一个函数相同的错误返回约定:错误对象表示失败,数字值表示快照字节数。

Before:

{
  static uint32_t func_snapshot_buffer[1024];

  const jerry_char_t *args_p = (const jerry_char_t *) "a, b";
  const jerry_char_t *src_p = (const jerry_char_t *) "return a + b;";

  size_t func_snapshot_size =
  jerry_parse_and_save_function_snapshot (src_p,
                                          strlen ((const char *) src_p),
                                          args_p,
                                          strlen ((const char *) args_p),
                                          false,
                                          func_snapshot_buffer,
                                          sizeof (func_snapshot_buffer) / sizeof (uint32_t));
  // check "function_snapshot_size" and use "func_snapshot_buffer"
}

After:

{
  static uint32_t func_snapshot_buffer[1024];

  const jerry_char_t *args_p = (const jerry_char_t *) "a, b";
  const jerry_char_t *src_p = (const jerry_char_t *) "return a + b;";

  jerry_value_t generate_result;
  generate_result = jerry_generate_function_snapshot (NULL,
                                                      0,
                                                      src_p,
                                                      strlen ((const char *) src_p),
                                                      args_p,
                                                      strlen ((const char *) args_p),
                                                      0,
                                                      func_snapshot_buffer,
                                                      sizeof (func_snapshot_buffer) / sizeof (uint32_t));
  if (jerry_value_is_error (generate_result))
  {
    // There was a problem during snapshot generation, for example there is a SyntaxError.
    // Use the "generate_result" to check the error.
  }
  else
  {
    size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
    // use "func_snapshot_buffer"
  }

  jerry_release_value (generate_result)
}

4.4 jerry_gc:新增压力参数 jerry_gc_mode_t

jerry_gc 被修改为接收一个表示 GC 压力(pressure) 的参数。当前仓库中该接口已演进为 jerryscript-core.h 的 void jerry_heap_gc (jerry_gc_mode_t mode);,压力枚举 jerry_gc_mode_t 定义在 jerryscript-types.h:

typedef enum
{
  JERRY_GC_PRESSURE_LOW,  /**< free unused objects, but keep memory */
  JERRY_GC_PRESSURE_HIGH  /**< free as much memory as possible */
} jerry_gc_mode_t;
  • JERRY_GC_PRESSURE_LOW:仅释放不再使用的对象,尽量保留内存以备复用(适合常规时机调用);
  • JERRY_GC_PRESSURE_HIGH:尽可能多地释放内存(适合内存告急时调用)。

Before:

{
  jerry_gc ();
}

After:

{
  jerry_gc (JERRY_GC_PRESSURE_LOW);
}

说明:jerry_gc_mode_t 的两个取值在 3.0 中被重命名为 JERRY_GC_PRESSURE_LOW/HIGH 的细分枚举(即上文 jerryscript-types.h 中展示的形式),2.0 时期对应为 JERRY_GC_PRESSURE_NONE 与 JERRY_GC_PRESSURE_HIGH 等命名,迁移时以当前头文件为准。

4.5 jerry_eval:第三个参数从 bool 改为 jerry_parse_opts_t

jerry_eval 的第三个参数由布尔值改为解析选项位掩码 jerry_parse_opts_t,以支持更丰富的解析行为(如 JERRY_PARSE_STRICT_MODE、JERRY_PARSE_MODULE 等)。当前声明为 jerryscript-core.h:

jerry_value_t jerry_eval (const jerry_char_t *source_p, size_t source_size, uint32_t flags);

其中 JERRY_PARSE_NO_OPTS = 0(无任何选项)定义在 jerryscript-types.h。

Before:

const jerry_char_t *str_to_eval = (const jerry_char_t *) "1 + 1";
jerry_value_t ret_val = jerry_eval (str_to_eval,
                                    strlen ((const char *) str_to_eval),
                                    false);

After:

const jerry_char_t *str_to_eval = (const jerry_char_t *) "1 + 1";
jerry_value_t ret_val = jerry_eval (str_to_eval,
                                    strlen ((const char *) str_to_eval),
                                    JERRY_PARSE_NO_OPTS);

原 false 对应的就是 JERRY_PARSE_NO_OPTS;若原来传 true(严格模式),则改为 JERRY_PARSE_STRICT_MODE。

5. Port API 迁移:时区处理

5.1 jerry_port_get_time_zone → jerry_port_get_local_time_zone_adjustment

1.0 的移植层时区接口存在设计缺陷:即使宿主系统具备完善的时区能力,旧接口也无法正确处理时区(问题背景见 JerryScript 官方 issue #1661)。2.0 将接口改为基于 Unix 毫秒时间戳计算本地时区偏移的新形式,新函数为 jerry_port_get_local_time_zone_adjustment,完整描述见 docs/05.PORT-API.md。当前仓库的 Unix 移植实现位于 jerry-port/unix/jerry-port-unix-date.c,Windows 实现位于 jerry-port/win/jerry-port-win-date.c。

下面是两个版本的默认实现对照:

Before(1.0):

bool jerry_port_get_time_zone (jerry_time_zone_t *tz_p)
{
  struct timeval tv;
  struct timezone tz;

  /* gettimeofday may not fill tz, so zero-initializing */
  tz.tz_minuteswest = 0;
  tz.tz_dsttime = 0;

  if (gettimeofday (&tv, &tz) != 0)
  {
    return false;
  }

  tz_p->offset = tz.tz_minuteswest;
  tz_p->daylight_saving_time = tz.tz_dsttime > 0 ? 1 : 0;

  return true;
} /* jerry_port_get_time_zone */

After(2.0):

double jerry_port_get_local_time_zone_adjustment (double unix_ms,
                                                  bool is_utc)
{
  struct tm tm;
  time_t now = (time_t) (unix_ms / 1000);
  localtime_r (&now, &tm);
  if (!is_utc)
  {
    now -= tm.tm_gmtoff;
    localtime_r (&now, &tm);
  }
  return ((double) tm.tm_gmtoff) * 1000;
} /* jerry_port_get_local_time_zone_adjustment */

新函数签名中:

  • unix_ms:Unix 毫秒时间戳;
  • is_utc:指示当前处理的日期时间是否以 UTC 表示,用于决定是否需要在计算前把本地时间先"还原"为 UTC 再求偏移;
  • 返回值:本地时区相对 UTC 的偏移量,单位为毫秒。

6. 原生指针(Native Pointer)机制迁移

1.0 中每个 jerry_value_t 对象只能关联一个原生句柄(native handle),且回调类型为简单的 jerry_object_free_callback_t。2.0 中该机制被重新设计:允许为同一个 JS 对象注册多个原生信息(native info),每个原生信息通过 jerry_object_native_info_t 结构体描述,并作为后续读写操作的"类型标签"进行区分。

涉及的三处替换:

旧(1.0) 新(2.0)
jerry_object_free_callback_t 回调类型 jerry_object_native_info_t 结构体(含 free_cb 成员)
jerry_get_object_native_handle jerry_get_object_native_pointer
jerry_set_object_native_handle jerry_set_object_native_pointer

当前仓库中 jerry_object_native_info_t 及相关操作(jerry_object_get_native_ptr、jerry_object_has_native_ptr、jerry_object_delete_native_ptr)声明见 jerryscript-core.h。

Before(1.0):

struct
{
  int data;
} my_info;

static void
handler_construct_freecb (uintptr_t native_p)
{
  // Invoked when the JS object is released and the
  // native data should be freed.

  struct my_info *info = (struct my_info *) native_p;
  free (info);
}

void
demo (void)
{
  jerry_value_t this_val;
  // create or acquire this_val
  // ...

  struct my_info *info = (struct my_info *) malloc (sizeof (struct my_info));
  info->data = 11;

  // setting the native handle
  jerry_set_object_native_handle (this_val,
                                  (uintptr_t) info,
                                  handler_construct_freecb);
  // ...
  // reading back the native handle
  uintptr_t ptr = (uintptr_t) NULL;
  bool is_ok = jerry_get_object_native_handle (this_val, &ptr);
  if (is_ok)
  {
    struct my_info *obj_info = (struct my_info *) ptr;
    // use "obj_info"
  }
}

After(2.0):

struct
{
  int data;
} my_info;

static void
handler_construct_freecb (void *native_p)
{
  // Invoked when the JS object is released and the
  // native data should be freed.

  struct my_info *info = (struct my_info *) native_p;
  free (info);
}

static const jerry_object_native_info_t my_info_type_info =
{
  .free_cb = handler_construct_freecb
};

void
demo (void)
{
  jerry_value_t this_val;
  // create or acquire this_val
  // ...

  struct my_info *info = (struct my_info *) malloc (sizeof (struct my_info));
  info->data = 11;

  // setting the native handle
  jerry_set_object_native_pointer (this_val,
                                   info,
                                   &my_info_type_info);
  // ...
  // reading back the native handle pointed by the "my_info_type_info" variable
  void *ptr = NULL;
  bool has_p = jerry_get_object_native_pointer (this_val, &ptr, &my_info_type_info);
  if (has_p)
  {
    struct my_info *obj_info = (struct my_info *) ptr;
    // use "obj_info"
  }
}

迁移要点:

  1. 回调签名:uintptr_t native_p 改为 void *native_p,不再需要整数与指针之间的强制转换;
  2. 类型信息:原来的裸回调改为 static const jerry_object_native_info_t 结构体({ .free_cb = ... }),该结构体同时充当该原生数据的"身份标识";
  3. 读写参数:set/get 都新增一个 &my_info_type_info 参数用于指定操作哪个原生信息,从而支持同一对象挂载多份不同类型原生数据。

7. 2.0 新增的 API 函数清单

2.0 同时引入了一批新 API,覆盖新的内置对象与能力。以下是迁移文档中的完整清单(各函数详细签名见 docs/02.API-REFERENCE.md 对应小节)。

7.1 内置对象相关

ArrayBuffer:

  • jerry_create_arraybuffer
  • jerry_create_arraybuffer_external(基于外部内存创建 ArrayBuffer,适合零拷贝场景)
  • jerry_get_arraybuffer_pointer

DataView:

  • jerry_create_dataview
  • jerry_value_is_dataview
  • jerry_get_dataview_buffer

JSON:

  • jerry_json_parse
  • jerry_json_stringify

Number:

  • jerry_create_number_infinity
  • jerry_create_number_nan

Promise:

  • jerry_run_all_enqueued_jobs(驱动 Promise 微任务队列,需在事件循环中调用)
  • jerry_create_promise
  • jerry_resolve_or_reject_promise
  • jerry_value_is_promise

RegExp:

  • jerry_create_regexp
  • jerry_create_regexp_sz

String(UTF-8 相关):

  • jerry_substring_to_utf8_char_buffer
  • jerry_get_utf8_string_size
  • jerry_get_utf8_string_length
  • jerry_create_string_from_utf8
  • jerry_create_string_sz_from_utf8

Symbol:

  • jerry_create_symbol
  • jerry_get_symbol_descriptive_string
  • jerry_value_is_symbol

TypedArray:

  • jerry_create_typedarray
  • jerry_create_typedarray_for_arraybuffer
  • jerry_create_typedarray_for_arraybuffer_sz
  • jerry_get_typedarray_type
  • jerry_get_typedarray_length
  • jerry_get_typedarray_buffer
  • jerry_value_is_typedarray

7.2 实例与内存管理

JerryScript 实例:

  • jerry_create_context(创建独立上下文,支持多实例隔离)
  • jerry_get_context_data(获取上下文私有数据)

内存管理:

  • jerry_heap_alloc
  • jerry_heap_free

多实例能力是 2.0 的重要架构升级:jerry_create_context 允许在一个进程内创建多个相互隔离的引擎实例。当前仓库的上下文实现可参考 jerry-core/jcontext/jcontext.c 与 jerry-core/jcontext/jcontext.h。

7.3 JavaScript 值操作

二元运算:

  • jerry_binary_operation

错误处理:

  • jerry_get_error_type
  • jerry_get_backtrace(获取当前错误/异常的调用栈回溯)

原生指针:

  • jerry_delete_object_native_pointer(删除对象上某个原生信息)
  • jerry_objects_foreach_by_native_info(遍历所有挂载了指定原生信息的对象)

属性操作:

  • jerry_delete_property_by_index
  • jerry_objects_foreach(遍历堆上所有对象)

7.4 调试器(Debugger)API

  • jerry_debugger_is_connected
  • jerry_debugger_stop
  • jerry_debugger_continue
  • jerry_debugger_stop_at_breakpoint
  • jerry_debugger_wait_for_client_source
  • jerry_debugger_send_output
  • jerry_debugger_send_log

这些函数需要开启 JERRY_DEBUGGER 特性并配合调试器客户端使用,协议说明见 docs/07.DEBUGGER.md,客户端参考实现位于 jerry-debugger/ 目录(如 jerry_client_main.py)。

7.5 其他新函数

  • jerry_is_feature_enabled(运行时查询某特性是否编译启用,可配合 docs/01.CONFIGURATION.md 中的特性开关使用)
  • jerry_parse_and_save_literals(保存解析过程中收集的字符串字面量,供魔法字符串注册使用)
  • jerry_set_vm_exec_stop_callback(设置 VM 执行停止回调,用于实现执行超时/中断控制)

7.6 新增 Port API 函数

  • jerry_port_normalize_path
  • jerry_port_read_source
  • jerry_port_release_source
  • jerry_port_print_char
  • jerry_port_get_current_context
  • jerry_port_fatal
  • jerry_port_sleep
  • jerry_port_print_byte

这些函数的默认实现分布在 jerry-port/common/(如 jerry-port-io.c、jerry-port-process.c、jerry-port-fs.c)与各平台目录(jerry-port/unix/、jerry-port/win/),详见 docs/05.PORT-API.md。

8. 从 2.x 迁移到 3.x 的补充说明

JerryScript 3.0 最显著的变化是一次更大规模的 API 重命名:绝大多数 API 函数在 3.0 中被改名,以统一命名风格(例如 jerry_get_global_object 等 2.x 函数在 3.0 中改名,原 2.x 名称仅在旧版本中有效)。API Reference 中为每个此类函数都标注了 "Renamed in version 3.0, it was previously known as xxx in earlier versions" 形式的迁移提示。

如果你同时需要从 1.0 迁移到 3.x,建议采用两步迁移策略:

  1. 先按本文第 2~6 节完成 1.0 → 2.0 的破坏性变更替换(错误处理、原生指针、快照、GC、eval、时区 Port API);
  2. 再对照 docs/02.API-REFERENCE.md 中的 "Renamed in version 3.0" 提示,将函数名批量更新到 3.x 命名。

这样每次只处理一类变更,出错时更容易定位。另外,由于配置宏在 1.0 → 2.0 经历了 CONFIG_ → JERRY_ 前缀统一,3.0 又对特性宏做了细分(如 JERRY_BUILTIN_* 系列),在迁移构建系统时请以 jerry-core/config.h 中的当前宏定义与默认值为准。

9. 迁移自检清单

完成迁移后,建议按以下清单逐项验证:

  • [ ] 头文件已更新为 #include "jerryscript.h" 与 #include "jerryscript-port.h",不再引用 jerry-api.h、jerry-port.h、jerry-internal.h;
  • [ ] 源码中不存在 jerry_char_ptr_t、jerry_object_free_callback_t 等旧类型;
  • [ ] 错误处理统一使用 jerry_create_abort_from_value / jerry_create_error_from_value / jerry_get_value_from_error,并核对每个调用的 take_ownership 参数;
  • [ ] 所有 CONFIG_ 前缀宏已改为 JERRY_ 前缀;
  • [ ] 快照生成调用已切换到 jerry_generate_snapshot / jerry_generate_function_snapshot,并检查返回值是否为错误对象;
  • [ ] jerry_gc 已传入 JERRY_GC_PRESSURE_LOW(或 HIGH)参数;
  • [ ] jerry_eval 的第三参数已由 bool 改为 jerry_parse_opts_t 枚举;
  • [ ] 移植层已实现 jerry_port_get_local_time_zone_adjustment,并删除旧 jerry_port_get_time_zone;
  • [ ] 原生数据读写已改用 jerry_object_native_info_t 与 jerry_(get|set)_object_native_pointer 三参数形式;
  • ] 编译通过且通过 tools/run-tests.py 运行单元测试([tests/unit-core/)验证引擎行为无回归。

完成以上步骤后,你的代码即与 2.0 及以上版本的 JerryScript API 兼容。若需要了解每个新 API 的完整参数与返回值语义,请继续阅读 docs/02.API-REFERENCE.md(API 参考)、docs/05.PORT-API.md(移植层参考)与 docs/04.INTERNALS.md(内部实现原理)。

登录后查看全文
jerryscript