Migration guide

During the development it was important to minimize the changes in the API functions and types. Each API method removal or chang is described below providing a before and after code example. For more information on the current API methods please check the API reference document.

Short list of removed/renamed headers, types, functions, and macros

Removed legacy headers

Renamed headers

jerry-api.h to jerryscript.h
jerry-port.h to jerryscript-port.h

Removed API types

jerry_char_ptr_t usage replaced with jerry_char_t *
jerry_object_free_callback_t replaced by jerry_object_native_free_callback_t

Removed API methods

jerry_get_memory_limits
jerry_get_object_native_handle replaced by jerry_get_object_native_pointer
jerry_set_object_native_handle replaced by jerry_set_object_native_pointer
jerry_value_set_abort_flag replaced by jerry_create_abort_from_value
jerry_value_has_abort_flag replaced by jerry_value_is_abort
jerry_value_set_error_flag replaced by jerry_create_error_from_value
jerry_value_has_error_flag replaced by jerry_value_is_error
jerry_value_clear_error_flag replaced by jerry_get_value_from_error
jerry_get_value_without_error_flag replaced by jerry_get_value_from_error
jerry_parse_and_save_snapshot replaced by jerry_generate_snapshot
jerry_parse_and_save_function_snapshot replaced by jerry_generate_function_snapshot

Removed unused configuration macros

CONFIG_MEM_DATA_LIMIT_MINUS_HEAP_SIZE
CONFIG_MEM_STACK_LIMIT
CONFIG_VM_STACK_FRAME_INLINED_VALUES_NUMBER
CONFIG_ECMA_GLOBAL_ENVIRONMENT_DECLARATIVE
All CONFIG_.. macros have been renamed to use the JERRY_ prefix format.

Modified API functions

The most important changes in the API are releated to error handling and manipulation.

This function was replaced with . Take note of the second argument of the new jerry_create_abort_from_value function which controls if the first argument should be usable after the call or not.

Before

After

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

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

jerry_value_has_abort_flag

This function was renamed to .

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);
}

jerry_value_set_error_flag

This function was replaced with . Take note of the second argument of the new jerry_create_error_from_value function which controls if the first argument should be usable after the call or not.

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);
}

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

This function was renamed to jerry_value_is_error.

Before

After

{
  jerry_value_t value;
  // create or acquire value
  // ...
  if (jerry_value_is_error (value))
  {
    // ...
  }
  jerry_release_value (value);

jerry_value_clear_error_flag AND jerry_get_value_without_error_flag

These functions were merged into jerry_get_value_from_error. Please note the second argument of the new function which controls if the first argument passed should be released or not.

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

Other functions changed

jerry_register_magic_strings

In case of the jerry_register_magic_strings function the change is that the first argument’s base type jerry_char_ptr_t was changed to jerry_char_t*. For more details see: .

In the following code parts please take note of the type used for the magic_string_items array.

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);
}

Snapshot generating API

This function was replaced with . The function returns an error object if there was any problem during snapshot generation and if there was no problem the return value is a number value containing the snapshot size in bytes.

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);
}

jerry_parse_and_save_function_snapshot

Before

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)
}

Garbage collection

jerry_gc

The jerry_gc function was modified to handle an argument which represents the pressure for the garbage collector. For more information checkout the reference.

Before

{
  jerry_gc ();
}

After

{
  jerry_gc (JERRY_GC_PRESSURE_LOW);
}

The third argument of jerry_eval has been changed from bool to .

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

Port API

The port API of handling timezones has been changed. The previous interface did not allow timezones to be handled correctly, even if the host system was up to the task. Check for more details.

The new port API function name is [jerry_port_get_local_time_zone_adjustment](05.PORT-API.md#date-1].

Below is the default implementations for both versions:

bool jerry_port_get_time_zone (jerry_time_zone_t *tz_p)
{
  struct timeval tv;
  /* 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

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 */

Native pointers

The assignment of native pointers (previously called handles) have been changed since v1.0. In the previous version only one native pointer could be assigned to a jerry_value_t. Now it is allowed to register multiple native infos, which can be accessed with the corresponding . The old functions were removed and replaced by new ones.

jerry_object_free_callback_t callback type is replaced by jerry_object_native_info_t
jerry_get_object_native_handle is replaced by jerry_get_object_native_pointer
jerry_set_object_native_handle is replaced by

Before

After

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"
  }
}