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

    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.   }
    21.   jerry_release_value (prop_value);
    22.   /* Property setting is the same. */
    24.   jerry_value_t new_prop_value = jerry_create_number (2.718);
    25.   jerry_value_t result = jerry_set_property (..., new_prop_value);
    27.   /* If the property set is successful, a new reference is created
    28.    * for the value referenced by new_prop_value. The new_prop_value
    29.    * reference must be released regardless of whether the operation
    30.    * is successful. */
    32.   /* The new_prop_value can be passed to other JerryScript API
    33.    * functions before the jerry_release_value () call. */
    35.   jerry_release_value (new_prop_value);
    37.   /* The reference stored in the 'result' variable is live whether
    38.    * the operation is successful or not, and must also be freed. */
    40.   if (jerry_value_is_error (result))
    41.   {
    42.     /* Errors can be handled here. */
    43.   }
    44.   else
    45.   {
    46.     /* A reference to a true primitive value is returned. */
    47.   }
    49.   jerry_release_value (result);

    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_length_t args_count
    4. {
    5.   /* Do not release function_obj, this_val, and args_p because
    6.    * these references are automatically released after the handler
    7.    * is returned. This approach reduces code size which is useful
    8.    * on embedded systems. However you can create other references
    9.    * to them by calling jerry_acquire_value () if needed. */
    11.   /* Since the ownership of the reference is transferred to the
    12.    * caller the following snippet is valid. */
    14.   /* If the value to be returned is needed for other purposes the
    15.    * jerry_acquire_value () can be used to create new references. */
    16.   return jerry_create_string (...);
    17. }

    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. */
    16.   /* Since all references are released, no memory leak occurs. */