Reference counting in JerryScript

In JerryScript all jerry_value_t values are independent references to internal objects. Values returned by JerryScript API functions are always live references and must be released by jerry_release_value.

  1.   jerry_value_t global = jerry_get_global_object ();
  3.   /* The value stored in the 'global' variable contains a live
  4.    * reference to the global object. The system also keeps its
  5.    * own live reference to the global object. These two references
  6.    * are independent, and both must be destroyed before the global
  7.    * object can be freed. */
  9.   jerry_release_value (global);
  11.   /* Without jerry_release_value() the global object will not
  12.    * be freed even by jerry_cleanup(). After the reference
  13.    * is released it becomes a dead reference and cannot be
  14.    * used anymore. */

Multiple references might refer to the same internal object even though their jerry_value_t representation might be different.

  1.   jerry_value_t pi_ref1 = jerry_create_number (3.14);
  2.   jerry_value_t pi_ref2 = jerry_acquire_value (pi_ref1);
  4.   /* Both pi_ref1 and pi_ref2 refer to the same 3.14 value
  5.    * although they might not be equal in C (pi_ref1 != pi_ref2). */
  7.   /* Both references must be released. */
  8.   jerry_release_value (pi_ref1);
  9.   jerry_release_value (pi_ref2);

Releasing the same jerry_value_t twice to release two live references is not allowed and it might cause crashes. Hence the following code is an INCORRECT WAY of releasing the 3.14 value.

  1.   jerry_release_value (pi_ref1);
  2.   jerry_release_value (pi_ref1);

JerryScript API functions returning with a jerry_value_t always return with a new live reference. Passing a jerry_value_t to an API function never releases its reference (unless explicitly stated in the documentation). The next example shows this behaviour through property getting and setting.

  1.   jerry_value_t prop_value = jerry_get_property (...);
  3.   /* The prop_value must be released later because both the base
  4.    * object and the prop_value have an independent reference to
  5.    * the same JavaScript value. When the operation fails, the
  6.    * prop_value contains a live reference to an error object.
  7.    * This reference must be released as well. */
  9.   if (jerry_value_is_error (prop_value))
  10.   {
  11.     /* Errors can be handled here. */
  12.   }
  13.   else
  14.   {
  15.     /* The application has a live reference to the property
  16.      * value even if the base object is freed by the garbage
  17.      * collector. */
  18.   }
  20.   /* The prop_value must be released. */
  21.   jerry_release_value (prop_value);
  23.   /* Property setting is the same. */
  25.   jerry_value_t new_prop_value = jerry_create_number (2.718);
  26.   jerry_value_t result = jerry_set_property (..., new_prop_value);
  28.   /* If the property set is successful, a new reference is created
  29.    * for the value referenced by new_prop_value. The new_prop_value
  30.    * reference must be released regardless of whether the operation
  31.    * is successful. */
  33.   /* The new_prop_value can be passed to other JerryScript API
  34.    * functions before the jerry_release_value () call. */
  36.   jerry_release_value (new_prop_value);
  38.   /* The reference stored in the 'result' variable is live whether
  39.    * the operation is successful or not, and must also be freed. */
  41.   if (jerry_value_is_error (result))
  42.   {
  43.     /* Errors can be handled here. */
  44.   }
  45.   else
  46.   {
  47.     /* A reference to a true primitive value is returned. */
  48.   }
  50.   jerry_release_value (result);

The simplest form of setting a property without error checking is the following:

  1.   /* There are no 'ifs' in this snippet. */
  2.   jerry_release_value (jerry_set_property (..., new_prop_value));
  3.   jerry_release_value (new_prop_value);

The reference returned by a jerry_external_handler_t callback transfers the ownership of the live reference. Otherwise the referenced object could be freed by the garbage collector.

  1. jerry_value_t my_external_handler (const jerry_value_t function_obj,
  2.                                    const jerry_value_t this_val,
  3.                                    const jerry_value_t args_p[],
  4.                                    const jerry_length_t args_count
  5. {
  6.   /* Do not release function_obj, this_val, and args_p because
  7.    * these references are automatically released after the handler
  8.    * is returned. This approach reduces code size which is useful
  9.    * on embedded systems. However you can create other references
  10.    * to them by calling jerry_acquire_value () if needed. */
  12.   /* Since the ownership of the reference is transferred to the
  13.    * caller the following snippet is valid. */
  15.   /* If the value to be returned is needed for other purposes the
  16.    * jerry_acquire_value () can be used to create new references. */
  17.   return jerry_create_string (...);
  18. }

Duplicating a jerry_value_t in C does not create another live reference.

  1.   jerry_value_t undef = jerry_create_undefined ();
  2.   jerry_value_t undef2 = undef;
  4.   /* Releasing either undef or undef2 is valid but not both.
  5.    * After the release both references become dead (invalid). */
  6.   jerry_release_value (undef2);
  8.   /* Dead references can be reassigned again. */
  9.   undef = jerry_create_boolean (true);

References can be duplicated in C as long as only one of them is freed.

  1.   jerry_value_t a = jerry_create_boolean (true);
  3.   jerry_value_t b = a;
  4.   jerry_value_t c = a;
  6.   /* A new reference is assigned to 'a'. */
  7.   a = jerry_create_boolean (false);
  9.   [...]
  11.   jerry_release_value (a);
  12.   /* The 'a' (boolean false) reference becomes dead (invalid). */
  14.   jerry_release_value (c);
  15.   /* Both 'b' and 'c' (boolean true) references become dead. */
  17.   /* Since all references are released, no memory leak occurs. */