Update jerry_run_all_enqueued_jobs() function and documentation (#4283)

Make sure it always returns an error or an undefined value.

JerryScript-DCO-1.0-Signed-off-by: Daniel Balla dballa@inf.u-szeged.hu

docs/02.API-REFERENCE.md

@@ -1364,6 +1364,9 @@ jerry_eval (const jerry_char_t *source_p,
 
 Run enqueued Promise jobs until the first thrown error or until all get executed.
 
+*Important Note*: The job queue is not guaranteed to be empty, after the function call has returned a value.
+Therefore, this function is best used in a while loop, handling each error it returns, until the job queue is empty.
+
 *Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
 is no longer needed.
 
@@ -1394,7 +1397,27 @@ main (void)
 
   jerry_value_t parsed_code = jerry_parse (NULL, 0, script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS);
   jerry_value_t script_value = jerry_run (parsed_code);
-  jerry_value_t job_value = jerry_run_all_enqueued_jobs ();
+
+  jerry_value_t job_value;
+  while (true)
+  {
+    job_value = jerry_run_all_enqueued_jobs ();
+
+    if (jerry_value_is_error (job_value))
+    {
+      if (jerry_value_is_abort (job_value))
+      {
+        // Terminate the engine
+      }
+
+      // Handle the error here
+    }
+    else
+    {
+      // The queue should be empty now
+      break;
+    }
+  }
 
   jerry_release_value (job_value);
   jerry_release_value (script_value);

jerry-core/ecma/operations/ecma-jobqueue.c

@@ -498,7 +498,7 @@ ecma_process_all_enqueued_jobs (void)
 {
   ecma_value_t ret = ECMA_VALUE_UNDEFINED;
 
-  while (JERRY_CONTEXT (job_queue_head_p) != NULL && !ECMA_IS_VALUE_ERROR (ret))
+  while (JERRY_CONTEXT (job_queue_head_p) != NULL)
   {
     ecma_job_queue_item_t *job_p = JERRY_CONTEXT (job_queue_head_p);
     JERRY_CONTEXT (job_queue_head_p) = ecma_job_queue_get_next (job_p);
@@ -531,9 +531,15 @@ ecma_process_all_enqueued_jobs (void)
         break;
       }
     }
+
+    if (ECMA_IS_VALUE_ERROR (ret))
+    {
+      return ret;
+    }
   }
 
-  return ret;
+  ecma_free_value (ret);
+  return ECMA_VALUE_UNDEFINED;
 } /* ecma_process_all_enqueued_jobs */
 
 /**