Replace jerry_value_set_abort_flag with jerry_create_abort_from_value (#2411)

Replaced the function, added some tests for it. Also changed the functions order to
alphabetical.

JerryScript-DCO-1.0-Signed-off-by: Istvan Miklos imiklos2@inf.u-szeged.hu

docs/02.API-REFERENCE.md

@@ -1696,6 +1696,125 @@ jerry_is_feature_enabled (const jerry_feature_t feature);
 
 # Error manipulation functions
 
+## jerry_create_abort_from_value
+
+**Summary**
+
+Create (api) abort from a value.
+
+This function creates an API abort value from an API value. The second argument defines
+whether the input value must be released or not. If it is set to `true`,
+then a [`jerry_release_value`](#jerry_release_value) function will be called
+for the first argument, so the api value won't be available after the call of
+`jerry_create_abort_from_value`. The second argument should be false if both value
+and created abort value are needed.
+
+**Prototype**
+
+```c
+jerry_value_t
+jerry_create_abort_from_value (jerry_value_t value, bool release);
+```
+
+- `value` - api value
+- `release` - raw boolean, defines whether input value must be released
+- return value - abort (api) value
+
+**Example 1**
+
+```c
+{
+  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);
+}
+```
+
+**Example 2**
+
+```c
+{
+  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);
+}
+```
+
+**See also**
+
+- [jerry_value_t](#jerry_value_t)
+- [jerry_get_value_from_error](#jerry_get_value_from_error)
+- [jerry_create_error_from_value](#jerry_create_error_from_value)
+
+## jerry_create_error_from_value
+
+**Summary**
+
+Create (api) error from a value.
+
+This function creates an API error value from an API value. The second argument defines
+whether the input value must be released or not. If it is set to `true`,
+then a [`jerry_release_value`](#jerry_release_value) function will be called
+for the first argument, so the api value won't be available after the call of
+`jerry_create_error_from_value`. The second argument should be false if both value
+and created error value are needed.
+
+**Prototype**
+
+```c
+jerry_value_t
+jerry_create_error_from_value (jerry_value_t value, bool release);
+```
+
+- `value` - api value
+- `release` - raw boolean, defines whether input value must be released
+- return value - error (api) value
+
+**Example 1**
+
+```c
+{
+  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);
+}
+```
+
+**Example 2**
+
+```c
+{
+  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);
+}
+```
+
+**See also**
+
+- [jerry_value_t](#jerry_value_t)
+- [jerry_get_value_from_error](#jerry_get_value_from_error)
+- [jerry_create_abort_from_value](#jerry_create_abort_from_value
+
 ## jerry_get_error_type
 
 **Summary**
@@ -1802,103 +1921,7 @@ jerry_get_value_from_error (jerry_value_t value, bool release)
 
 - [jerry_value_t](#jerry_value_t)
 - [jerry_create_error_from_value](#jerry_create_error_from_value)
-- [jerry_value_set_abort_flag](#jerry_value_set_abort_flag)
-
-## jerry_create_error_from_value
-
-**Summary**
-
-Create (api) error from a value.
-
-This function creates an API error value from an API value. The second argument defines
-whether the input value must be released or not. If it is set to `true`,
-then a [`jerry_release_value`](#jerry_release_value) function will be called
-for the first argument, so the api value won't be available after the call of
-`jerry_create_error_from_value`. The second argument should be false if both value
-and created error value are needed.
-
-**Prototype**
-
-```c
-jerry_value_t
-jerry_create_error_from_value (jerry_value_t value, bool release);
-```
-
-- `value` - api value
-- `release` - raw boolean, defines whether input value must be released
-- return value - error (api) value
-
-**Example 1**
-
-```c
-{
-  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);
-}
-```
-
-**Example 2**
-
-```c
-{
-  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);
-}
-```
-
-**See also**
-
-- [jerry_value_t](#jerry_value_t)
-- [jerry_get_value_from_error](#jerry_get_value_from_error)
-- [jerry_value_set_abort_flag](#jerry_value_set_abort_flag)
-
-
-## jerry_value_set_abort_flag
-
-**Summary**
-
-Set both the error and abort flags.
-
-**Prototype**
-
-```c
-void
-jerry_value_set_abort_flag (jerry_value_t *value_p);
-```
-
-- `value_p` - pointer to an api value
-
-**Example**
-
-```c
-{
-  jerry_value_t value;
-  ... // create or acquire value
-
-  jerry_value_set_abort_flag (&value);
-
-  jerry_release_value (value);
-}
-```
-
-**See also**
-
-- [jerry_value_t](#jerry_value_t)
-- [jerry_get_value_from_error](#jerry_get_value_from_error)
-- [jerry_create_error_from_value](#jerry_create_error_from_value)
-
+- [jerry_create_abort_from_value](#jerry_create_abort_from_value)
 
 # Getter functions of 'jerry_value_t'
 

jerry-core/api/jerry.c

@@ -904,35 +904,39 @@ jerry_is_feature_enabled (const jerry_feature_t feature) /**< feature to check *
 } /* jerry_is_feature_enabled */
 
 /**
- * Get the value from an error value.
+ * Create abort from an api value.
  *
- * Extract the api value from an error. If the second argument is true
- * it will release the input error value.
+ * Create abort value from an api value. If the second argument is true
+ * it will release the input api value.
  *
- * Note:
- *      returned value must be freed with jerry_release_value, when it is no longer needed.
- *
- * @return jerry_value_t value
+ * @return api abort value
  */
 jerry_value_t
-jerry_get_value_from_error (jerry_value_t value, /**< api value */
-                            bool release) /**< release api value */
+jerry_create_abort_from_value (jerry_value_t value, /**< api value */
+                               bool release) /**< release api value */
 {
   jerry_assert_api_available ();
 
-  if (!ecma_is_value_error_reference (value))
+  if (JERRY_UNLIKELY (ecma_is_value_error_reference (value)))
   {
-    return release ? value : ecma_copy_value (value);
+    /* This is a rare case so it is optimized for
+     * binary size rather than performance. */
+    if (jerry_value_is_abort (value))
+    {
+      return release ? value : jerry_acquire_value (value);
+    }
+
+    value = jerry_get_value_from_error (value, release);
+    release = true;
   }
 
-  jerry_value_t ret_val = jerry_acquire_value (ecma_get_error_reference_from_value (value)->value);
-
-  if (release)
+  if (!release)
   {
-    jerry_release_value (value);
+    value = ecma_copy_value (value);
   }
-  return ret_val;
-} /* jerry_get_value_from_error */
+
+  return ecma_create_error_reference (value, false);
+} /* jerry_create_abort_from_value */
 
 /**
  * Create error from an api value.
@@ -970,26 +974,35 @@ jerry_create_error_from_value (jerry_value_t value, /**< api value */
 } /* jerry_create_error_from_value */
 
 /**
- * Set both the abort and error flags if the value is not an error reference.
+ * Get the value from an error value.
+ *
+ * Extract the api value from an error. If the second argument is true
+ * it will release the input error value.
+ *
+ * Note:
+ *      returned value must be freed with jerry_release_value, when it is no longer needed.
+ *
+ * @return jerry_value_t value
  */
-void
-jerry_value_set_abort_flag (jerry_value_t *value_p) /**< api value */
+jerry_value_t
+jerry_get_value_from_error (jerry_value_t value, /**< api value */
+                            bool release) /**< release api value */
 {
   jerry_assert_api_available ();
 
-  if (JERRY_UNLIKELY (ecma_is_value_error_reference (*value_p)))
+  if (!ecma_is_value_error_reference (value))
   {
-    /* This is a rare case so it is optimized for
-     * binary size rather than performance. */
-    if (jerry_value_is_abort (*value_p))
-    {
-      return;
-    }
-    *value_p = ecma_clear_error_reference (*value_p, false);
+    return release ? value : ecma_copy_value (value);
   }
 
-  *value_p = ecma_create_error_reference (*value_p, false);
-} /* jerry_value_set_abort_flag */
+  jerry_value_t ret_val = jerry_acquire_value (ecma_get_error_reference_from_value (value)->value);
+
+  if (release)
+  {
+    jerry_release_value (value);
+  }
+  return ret_val;
+} /* jerry_get_value_from_error */
 
 /**
  * Return the type of the Error object if possible.

jerry-core/include/jerryscript-core.h

@@ -379,9 +379,9 @@ bool jerry_is_feature_enabled (const jerry_feature_t feature);
 /**
  * Error manipulation functions.
  */
-jerry_value_t jerry_get_value_from_error (jerry_value_t value, bool release);
+jerry_value_t jerry_create_abort_from_value (jerry_value_t value, bool release);
 jerry_value_t jerry_create_error_from_value (jerry_value_t value, bool release);
-void jerry_value_set_abort_flag (jerry_value_t *value_p);
+jerry_value_t jerry_get_value_from_error (jerry_value_t value, bool release);
 
 /**
  * Error object function(s).

tests/unit-core/test-abort.c

@@ -30,7 +30,7 @@ callback_func (const jerry_value_t function_obj,
   JERRY_UNUSED (args_count);
 
   jerry_value_t value = jerry_create_string ((jerry_char_t *) "Abort run!");
-  jerry_value_set_abort_flag (&value);
+  value = jerry_create_abort_from_value (value, true);
   return value;
 } /* callback_func */
 
@@ -114,7 +114,7 @@ main (void)
   TEST_ASSERT (!jerry_value_is_abort (value));
   TEST_ASSERT (!jerry_value_is_error (value));
 
-  jerry_value_set_abort_flag (&value);
+  value = jerry_create_abort_from_value (value, true);
   TEST_ASSERT (jerry_value_is_abort (value));
   TEST_ASSERT (jerry_value_is_error (value));
 
@@ -122,7 +122,7 @@ main (void)
   TEST_ASSERT (!jerry_value_is_abort (value));
   TEST_ASSERT (jerry_value_is_error (value));
 
-  jerry_value_set_abort_flag (&value);
+  value = jerry_create_abort_from_value (value, true);
   TEST_ASSERT (jerry_value_is_abort (value));
   TEST_ASSERT (jerry_value_is_error (value));
 

tests/unit-core/test-api-set-and-clear-error-flag.c

@@ -61,6 +61,40 @@ main (void)
   compare_str (str, pterodactylus_p, pterodactylus_size);
   jerry_release_value (str);
 
+  str = jerry_create_string ((jerry_char_t *) pterodactylus_p);
+  error = jerry_create_abort_from_value (str, true);
+  str = jerry_get_value_from_error (error, true);
+
+  compare_str (str, pterodactylus_p, pterodactylus_size);
+  jerry_release_value (str);
+
+  str = jerry_create_string ((jerry_char_t *) pterodactylus_p);
+  error = jerry_create_abort_from_value (str, false);
+  jerry_release_value (str);
+  str = jerry_get_value_from_error (error, true);
+
+  compare_str (str, pterodactylus_p, pterodactylus_size);
+  jerry_release_value (str);
+
+  str = jerry_create_string ((jerry_char_t *) pterodactylus_p);
+  error = jerry_create_error_from_value (str, true);
+  error = jerry_create_abort_from_value (error, true);
+  JERRY_ASSERT (jerry_value_is_abort (error));
+  str = jerry_get_value_from_error (error, true);
+
+  compare_str (str, pterodactylus_p, pterodactylus_size);
+  jerry_release_value (str);
+
+  str = jerry_create_string ((jerry_char_t *) pterodactylus_p);
+  error = jerry_create_error_from_value (str, true);
+  jerry_value_t error2 = jerry_create_abort_from_value (error, false);
+  JERRY_ASSERT (jerry_value_is_abort (error2));
+  jerry_release_value (error);
+  str = jerry_get_value_from_error (error2, true);
+
+  compare_str (str, pterodactylus_p, pterodactylus_size);
+  jerry_release_value (str);
+
   double test_num = 3.1415926;
   jerry_value_t num = jerry_create_number (test_num);
   jerry_value_t num2 = jerry_create_error_from_value (num, false);
@@ -98,19 +132,40 @@ main (void)
   jerry_release_value (num2);
 
   num = jerry_create_number (test_num);
-  jerry_value_set_abort_flag (&num);
-  JERRY_ASSERT (jerry_value_is_abort (num));
-  num2 = jerry_create_error_from_value (num, true);
+  error = jerry_create_abort_from_value (num, true);
+  JERRY_ASSERT (jerry_value_is_abort (error));
+  num2 = jerry_create_error_from_value (error, true);
   JERRY_ASSERT (jerry_value_is_error (num2));
   num = jerry_get_value_from_error (num2, true);
   JERRY_ASSERT (jerry_get_number_value (num) == test_num);
   jerry_release_value (num);
 
   num = jerry_create_number (test_num);
-  jerry_value_set_abort_flag (&num);
-  JERRY_ASSERT (jerry_value_is_abort (num));
-  num2 = jerry_create_error_from_value (num, false);
+  error = jerry_create_abort_from_value (num, false);
   jerry_release_value (num);
+  JERRY_ASSERT (jerry_value_is_abort (error));
+  num2 = jerry_create_error_from_value (error, true);
+  JERRY_ASSERT (jerry_value_is_error (num2));
+  num = jerry_get_value_from_error (num2, true);
+  JERRY_ASSERT (jerry_get_number_value (num) == test_num);
+  jerry_release_value (num);
+
+  num = jerry_create_number (test_num);
+  error = jerry_create_abort_from_value (num, true);
+  JERRY_ASSERT (jerry_value_is_abort (error));
+  num2 = jerry_create_error_from_value (error, false);
+  jerry_release_value (error);
+  JERRY_ASSERT (jerry_value_is_error (num2));
+  num = jerry_get_value_from_error (num2, true);
+  JERRY_ASSERT (jerry_get_number_value (num) == test_num);
+  jerry_release_value (num);
+
+  num = jerry_create_number (test_num);
+  error = jerry_create_abort_from_value (num, false);
+  jerry_release_value (num);
+  JERRY_ASSERT (jerry_value_is_abort (error));
+  num2 = jerry_create_error_from_value (error, false);
+  jerry_release_value (error);
   JERRY_ASSERT (jerry_value_is_error (num2));
   num = jerry_get_value_from_error (num2, true);
   JERRY_ASSERT (jerry_get_number_value (num) == test_num);
@@ -130,9 +185,20 @@ main (void)
   error = jerry_create_error_from_value (error, true);
   jerry_release_value (error);
 
+  value = jerry_create_number (42);
+  error = jerry_create_abort_from_value (value, true);
+  error = jerry_create_abort_from_value (error, true);
+  jerry_release_value (error);
+
   value = jerry_create_number (42);
   error = jerry_create_error_from_value (value, true);
-  jerry_value_t error2 = jerry_create_error_from_value (error, false);
+  error2 = jerry_create_error_from_value (error, false);
+  jerry_release_value (error);
+  jerry_release_value (error2);
+
+  value = jerry_create_number (42);
+  error = jerry_create_abort_from_value (value, true);
+  error2 = jerry_create_abort_from_value (error, false);
   jerry_release_value (error);
   jerry_release_value (error2);