Пособие по миграции

Это руководство предназначено для описания основных изменений между версиями JerryScript 1.0 и 2.0. Кроме того, оно разработано для предоставления руководства по изменению кода версии 1.0 на код, соответствующий версии 2.0.

Во время разработки было важно минимизировать изменения в функциях и типах API. Каждое удаление или изменение API метода описано ниже, предоставляя примеры кода до и после. Для получения дополнительной информации о текущих методах API, пожалуйста, проверьте документ API reference.

Краткий список удаленных/переименованных заголовков, типов, функций и макросов

Удаленные устаревшие заголовки

jerry-internal.h

Переименованные заголовки

jerry-api.h в jerryscript.h
jerry-port.h в jerryscript-port.h

Удаленные типы API

Использование jerry_char_ptr_t заменено на jerry_char_t *
jerry_object_free_callback_t заменено на jerry_object_native_free_callback_t

Удаленные методы API

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Удаленные неиспользуемые макросы конфигурации
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_.

Измененные функции API

Функции манипулирования ошибками

Наиболее важные изменения в API связаны с обработкой и манипулированием ошибками.

jerry_value_set_abort_flag

Эта функция была заменена на jerry_create_abort_from_value. Обратите внимание на второй аргумент новой функции jerry_create_abort_from_value, который контролирует, может ли первый аргумент быть использован после вызова или нет.

jerry_value_has_abort_flag

Эта функция была переименована в jerry_value_is_abort.

До

{
  jerry_value_t value;
  // создание или получение значения
  // ...

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

  jerry_release_value (value);
}

После

{
  jerry_value_t value;
  // создание или получение значения
  // ...

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

  jerry_release_value (value);
}

jerry_value_set_error_flag

Эта функция была заменена на jerry_create_error_from_value. Обратите внимание на второй аргумент новой функции jerry_create_error_from_value, который контролирует, можно ли использовать первый аргумент после вызова или нет.

До

{
  jerry_value_t value;
  // создание или получение значения
  // ...```markdown
### jerry_value_set_error_flag и jerry_value_clear_error_flag

Эти функции были объединены в [`jerry_get_value_from_error`](02.API-REFERENCE.md#jerry_get_value_from_error).
Обратите внимание на второй аргумент новой функции, который контролирует, следует ли освободить первый аргумент или нет.

**До**

```c
{
  jerry_value_t value;
  // создание или получение значения
  // ...

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

  jerry_release_value (value);
  jerry_release_value (real_value);
}

После

{
  jerry_value_t value;
  // создание или получение значения
  // ...

  jerry_value_t error = jerry_get_value_from_error (value, false);
  // как 'error', так и 'value' могут быть использованы и должны быть освобождены, когда они больше не нужны

  jerry_release_value (error);
  jerry_release_value (value);
}

{
  jerry_value_t 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);
}
```

## Измененные другие функции

### jerry_register_magic_strings

В случае функции `jerry_register_magic_strings` базовый тип первого аргумента `jerry_char_ptr_t` был изменен на `jerry_char_t*`.
Для более подробной информации см.: [`jerry_register_magic_strings`](02.API-REFERENCE.md#jerry_register_magic_strings).

В следующих частях кода обратите внимание на тип, используемый для массива `magic_string_items`.

**До**

```c
{
  // должен быть статическим, так как 'jerry_register_magic_strings' не копирует
  // элементы должны быть отсортированы по размеру, а затем лексикографически
  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));
}
```

## API для генерации снимков

### jerry_parse_and_save_snapshot

Эта функция была заменена на [`jerry_generate_snapshot`](02.API-REFERENCE.md#jerry_generate_snapshot).
Функция возвращает объект ошибки, если возникли какие-либо проблемы во время генерации снимка,
и если проблем не было, то возвращаемое значение — это числовое значение, содержащее размер снимка в байтах.**До**

```c
{
  static uint32_t global_mode_snapshot_buffer[256];
  const jerry_char_t *code_to_snapshot_p = (const jerry_char_t *) "(function () { return 'строка из снимка'; }) ();";

  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));
  // использовать "global_mode_snapshot_buffer"
}
```

**После**

```c
{
  static uint32_t global_mode_snapshot_buffer[256];
  const jerry_char_t *code_to_snapshot_p = (const jerry_char_t *) "(function () { return 'строка из снимка'; }) ();";
``````md
  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))
  {
    // Произошла ошибка во время создания снимка, например, возникла ошибка синтаксиса.
    // Используйте "generate_result", чтобы проверить ошибку.
  }
  else
  {
    size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
    // используйте "global_mode_snapshot_buffer"
  }
  jerry_release_value (generate_result);
}
```

### jerry_parse_and_save_function_snapshot

Эта функция была заменена на [`jerry_generate_function_snapshot`](02.API-REFERENCE.md#jerry_parse_and_save_function_snapshot).
Функция возвращает объект ошибки, если произошла какая-либо проблема во время создания снимка, и если проблем не было, то возвращаемое значение — это числовое значение, содержащее размер снимка в байтах.```c
{
  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;";
}
```

```markdown
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))
{
  // Произошла ошибка во время создания снимка, например, возникла ошибка синтаксиса.
  // Используйте "generate_result", чтобы проверить ошибку.
}
else
{
  size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
  // используйте "func_snapshot_buffer"
}
jerry_release_value (generate_result);
}
```

## Сборка мусора

### jerry_gc
Функция [`jerry_gc`](02.API-REFERENCE.md#jerry_gc) была изменена для обработки аргумента, представляющего пороговое значение давления для сборщика мусора.
Для получения дополнительной информации см. ссылку на [`jerry_gc_mode_t`](02.API-REFERENCE.md#jerry_gc_mode_t).**До**

```c
{
  jerry_gc ();
}
```

**После**

```c
{
  jerry_gc (JERRY_GC_PRESSURE_LOW);
}
```

## jerry_eval

Третий аргумент функции [`jerry_eval`](02.API-REFERENCE.md#jerry_eval) был изменен
с `bool` на [`jerry_parse_opts_t`](02.API-REFERENCE.md#jerry_parse_opts_t).

**До**

```c
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);
```

**После**

```c
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);
```

## API порта

### jerry_port_get_time_zone

API порта для обработки часовых поясов был изменен. Предыдущий интерфейс не позволял корректно обрабатывать часовые пояса, даже если система была способна это делать.
Для получения дополнительной информации см. [соответствующую задачу](https://github.com/jerryscript-project/jerryscript/issues/1661).

Новое имя функции API порта — [jerry_port_get_local_time_zone_adjustment](05.PORT-API.md#date-1).

Ниже приведены стандартные реализации для обеих версий:

**До**

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

  /* gettimeofday может не заполнить tz, поэтому инициализируем нулями */
  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 */
```

**После**```c
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 */
```
## Локальные часовые поясаПрисваивание локальных указателей (ранее называвшихся обработчиками) было изменено с версии v1.0. В предыдущей версии можно было назначить только один локальный указатель к `jerry_value_t`. Теперь разрешено регистрировать несколько локальных данных, которые можно получить с помощью соответствующего
[`jerry_object_native_info_t`](02.API-REFERENCE.md#jerry_object_native_info_t).
Старые функции были удалены и заменены новыми.

- Тип обратного вызова `jerry_object_free_callback_t` заменен на `jerry_object_native_info_t`
- `jerry_get_object_native_handle` заменен на [`jerry_get_object_native_pointer`](02.API-REFERENCE.md#jerry_get_object_native_pointer)
- `jerry_set_object_native_handle` заменен на [`jerry_set_object_native_pointer`](02.API-REFERENCE.md#jerry_set_object_native_pointer)

**До**

```c
struct
{
  int data;
} my_info;

static void
handler_construct_freecb (uintptr_t native_p)
{
  // Вызывается при освобождении JS объекта и необходимости освободить
  // локальные данные.

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

void
demo (void)
{
  jerry_value_t this_val;
  // создание или получение this_val
  // ...

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

  // установка локального обработчика
  jerry_set_object_native_handle (this_val,
                                  (uintptr_t) info,
                                  handler_construct_freecb);
  // ...
  // чтение локального обработчика
  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;
    // использовать obj_info
  }
}
```


**После**

```c
struct
{
  int data;
} my_info;

static void
handler_construct_freecb (void *native_p)
{
  // Вызывается при освобождении JS объекта и необходимости освободить
  // локальные данные.
}
```  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;
  // создание или получение this_val
  // ...

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

# Новые API-функции

В этом разделе перечислены новые API-функции.

## Встроенные объекты

***ArrayBuffer***

- [`jerry_create_arraybuffer`](02.API-REFERENCE.md#jerry_create_arraybuffer)
- [`jerry_create_arraybuffer_external`](02.API-REFERENCE.md#jerry_create_arraybuffer_external)
- [`jerry_get_arraybuffer_pointer`](02.API-REFERENCE.md#jerry_get_arraybuffer_pointer)

***DataView***

- [`jerry_create_dataview`](02.API-REFERENCE.md#jerry_create_dataview)
- [`jerry_value_is_dataview`](02.API-REFERENCE.md#jerry_value_is_dataview)
- [`jerry_get_dataview_buffer`](02.API-REFERENCE.md#jerry_get_dataview_buffer)

***JSON***

- [`jerry_json_parse`](02.API-REFERENCE.md#jerry_json_parse)
- [`jerry_json_stringify`](02.API-REFERENCE.md#jerry_json_stringify)

***Number***

- [`jerry_create_number_infinity`](02.API-REFERENCE.md#jerry_create_number_infinity)
- [`jerry_create_number_nan`](02.API-REFERENCE.md#jerry_create_number_nan)

***Promise***

- [`jerry_run_all_enqueued_jobs`](02.API-REFERENCE.md#jerry_run_all_enqueued_jobs)
- [`jerry_create_promise`](02.API-REFERENCE.md#jerry_create_promise)
- [`jerry_resolve_or_reject_promise`](02.API-REFERENCE.md#jerry_resolve_or_reject_promise)
- [`jerry_value_is_promise`](02.API-REFERENCE.md#jerry_value_is_promise)

***RegExp***

- [`jerry_create_regexp`](02.API-REFERENCE.md#jerry_create_regexp)
- [`jerry_create_regexp_sz`](02.API-REFERENCE.md#jerry_create_regexp_sz)

***String***

- [`jerry_substring_to_utf8_char_buffer`](02.API-REFERENCE.md#jerry_substring_to_utf8_char_buffer)
- [`jerry_get_utf8_string_size`](02.API-REFERENCE.md#jerry_get_utf8_string_size)
- [`jerry_get_utf8_string_length`](02.API-REFERENCE.md#jerry_get_utf8_string_length)
- [`jerry_create_string_from_utf8`](02.API-REFERENCE.md#jerry_create_string_from_utf8)
- [`jerry_create_string_sz_from_utf8`](02.API-REFERENCE.md#jerry_create_string_sz_from_utf8)

***Symbol***

- [`jerry_create_symbol`](02.API-REFERENCE.md#jerry_create_symbol)
- [`jerry_value_is_symbol`](02.API-REFERENCE.md#jerry_value_is_symbol)- [`jerry_create_symbol`](02.API-REFERENCE.md#jerry_create_symbol)
- [`jerry_get_symbol_descriptive_string`](02.API-REFERENCE.md#jerry_get_symbol_descriptive_string)
- [`jerry_value_is_symbol`](02.API-REFERENCE.md#jerry_value_is_symbol)

***Типизированные массивы***

- [`jerry_create_typedarray`](02.API-REFERENCE.md#jerry_create_typedarray)
- [`jerry_create_typedarray_for_arraybuffer`](02.API-REFERENCE.md#jerry_create_typedarray_for_arraybuffer)
- [`jerry_create_typedarray_for_arraybuffer_sz`](02.API-REFERENCE.md#jerry_create_typedarray_for_arraybuffer_sz)
- [`jerry_get_typedarray_type`](02.API-REFERENCE.md#jerry_get_typedarray_type)
- [`jerry_get_typedarray_length`](02.API-REFERENCE.md#jerry_get_typedarray_length)
- [`jerry_get_typedarray_buffer`](02.API-REFERENCE.md#jerry_get_typedarray_buffer)
- [`jerry_value_is_typedarray`](02.API-REFERENCE.md#jerry_value_is_typedarray)


## Экземпляры и управление памятью

***Экземпляры JerryScript***

- [`jerry_create_context`](02.API-REFERENCE.md#jerry_create_context)
- [`jerry_get_context_data`](02.API-REFERENCE.md#jerry_get_context_data)

***Управление памятью***

- [`jerry_heap_alloc`](02.API-REFERENCE.md#jerry_heap_alloc)
- [`jerry_heap_free`](02.API-REFERENCE.md#jerry_heap_free)


## Операции с значениями JavaScript

***Бинарные операции***

- [`jerry_binary_operation`](02.API-REFERENCE.md#jerry_binary_operation)

***Манипуляции с ошибками***

- [`jerry_get_error_type`](02.API-REFERENCE.md#jerry_get_error_type)
- [`jerry_get_backtrace`](02.API-REFERENCE.md#jerry_get_backtrace)

***Интерфейсы нативных указателей***

- [`jerry_delete_object_native_pointer`](02.API-REFERENCE.md#jerry_delete_object_native_pointer)
- [`jerry_objects_foreach_by_native_info`](02.API-REFERENCE.md#jerry_objects_foreach_by_native_info)

***Свойства***

- [`jerry_delete_property_by_index`](02.API-REFERENCE.md#jerry_delete_property_by_index)
- [`jerry_objects_foreach`](02.API-REFERENCE.md#jerry_objects_foreach)## Отладчик
- [`jerry_debugger_is_connected`](07.DEBUGGER.md#jerry_debugger_is_connected)
- [`jerry_debugger_stop`](07.DEBUGGER.md#jerry_debugger_stop)
- [`jerry_debugger_continue`](07.DEBUGGER.md#jerry_debugger_continue)
- [`jerry_debugger_stop_at_breakpoint`](07.DEBUGGER.md#jerry_debugger_stop_at_breakpoint)
- [`jerry_debugger_wait_for_client_source`](07.DEBUGGER.md#jerry_debugger_wait_for_client_source)
- [`jerry_debugger_send_output`](07.DEBUGGER.md#jerry_debugger_send_output)
- [`jerry_debugger_send_log`](07.DEBUGGER.md#jerry_debugger_send_log)

## Другое- [`jerry_is_feature_enabled`](02.API-REFERENCE.md#jerry_is_feature_enabled)
- [`jerry_parse_and_save_literals`](02.API-REFERENCE.md#jerry_parse_and_save_literals)
- [`jerry_set_vm_exec_stop_callback`](02.API-REFERENCE.md#jerry_set_vm_exec_stop_callback)


## Функции порта

- [`jerry_port_normalize_path`](05.PORT-API.md#jerry_port_normalize_path)
- [`jerry_port_read_source`](05.PORT-API.md#jerry_port_read_source)
- [`jerry_port_release_source`](05.PORT-API.md#jerry_port_release_source)
- [`jerry_port_print_char`](05.PORT-API.md#jerry_port_print_char)
- [`jerry_port_get_current_context`](05.PORT-API.md#jerry_port_get_current_context)
- [`jerry_port_fatal`](05.PORT-API.md#jerry_port_fatal)
- [`jerry_port_sleep`](05.PORT-API.md#jerry_port_sleep)

OSCHINA-MIRROR/openharmony-third_party_jerryscript

Пособие по миграции

Краткий список удаленных/переименованных заголовков, типов, функций и макросов

Измененные функции API

Функции манипулирования ошибками

jerry_value_set_abort_flag

jerry_value_has_abort_flag

jerry_value_set_error_flag

Опубликовать ( 0 )

Введение

Обновления (1)

Участники

Недавние действия

OSCHINA-MIRROR/openharmony-third_party_jerryscript .gitee-modal { min-width: 500px !important; } .gitee-modal .close { right: 0.6rem !important; }

Пособие по миграции

Краткий список удаленных/переименованных заголовков, типов, функций и макросов

Измененные функции API

Функции манипулирования ошибками

jerry_value_set_abort_flag

jerry_value_has_abort_flag

jerry_value_set_error_flag

Опубликовать ( 0 )

Введение

Обновления (1)

Участники

Недавние действия

OSCHINA-MIRROR/openharmony-third_party_jerryscript