Rework jerry_debugger_wait_for_client_source to use a callback.

The jerry_debugger_wait_and_run_client_source function is renamed to
jerry_debugger_wait_for_client_source and a callback is added which
is called when the source is received. Inside the callback the
application is free to do anything with the received source code.

JerryScript-DCO-1.0-Signed-off-by: Zoltan Herczeg zherczeg.u-szeged@partner.samsung.com

docs/07.DEBUGGER.md

@@ -83,6 +83,35 @@ debugger is disabled.
 The following section describes the debugger functions
 available for the host application.
 
+## JerryScript debugger types
+
+## jerry_debugger_wait_for_source_callback_t
+
+**Summary**
+
+This callback function is called by
+[jerry_debugger_wait_for_client_source](#jerry_debugger_wait_for_client_source)
+when a source code is received successfully.
+
+**Prototype**
+
+```c
+typedef jerry_value_t
+(*jerry_debugger_wait_for_source_callback_t) (const jerry_char_t *resource_name_p,
+                                              size_t resource_name_size,
+                                              const jerry_char_t *source_p,
+                                              size_t source_size, void *user_p);
+```
+
+- `resource_name_p` - resource (usually a file) name of the source code
+- `resource_name_size` - size of resource name
+- `source_p` - source code character data
+- `source_size` - size of source code
+- `user_p` - custom pointer passed to [jerry_debugger_wait_for_client_source](#jerry_debugger_wait_for_client_source)
+
+
+## JerryScript debugger functions
+
 ### jerry_debugger_init
 
 **Summary**
@@ -244,46 +273,86 @@ jerry_debugger_stop_at_breakpoint (bool enable_stop_at_breakpoint)
 }
 ```
 
-### jerry_debugger_wait_and_run_client_source
+### jerry_debugger_wait_for_client_source
 
 **Summary**
 
-Stops the engine and puts it into a waiting loop. If the client sends
-a source code and JerryScript receives that, then the function will
-run the source with the initialized options, after that the engine will
-wait for a new source until the client send a close signal.
+Asks the client to provide the next source code. The function
+waits until the whole source code is received. As a reply the
+the client may request a context reset or notify that no more
+source is available. These notifications are passed back as the
+return value of the function.
 
 **Prototype**
 
 ```c
-jerry_debugger_wait_and_run_type_t
-jerry_debugger_wait_and_run_client_source (jerry_value_t *return_value)
+jerry_debugger_wait_for_source_status_t
+jerry_debugger_wait_for_client_source (jerry_debugger_wait_for_source_callback_t callback_p,
+                                       void *user_p, jerry_value_t *return_value)
 ```
 
 **Example**
 
 ```c
-  jerry_init (JERRY_INIT_EMPTY);
-  jerry_debugger_init (5001);
+/**
+ * Runs the source code received by jerry_debugger_wait_for_client_source.
+ */
+static jerry_value_t
+wait_for_source_callback (const jerry_char_t *resource_name_p, /**< resource name */
+                          size_t resource_name_size, /**< size of resource name */
+                          const jerry_char_t *source_p, /**< source code */
+                          size_t source_size, /**< source code size */
+                          void *user_p __attribute__((unused))) /**< user pointer */
+{
+  jerry_value_t ret_val = jerry_parse_named_resource (resource_name_p,
+                                                      resource_name_size,
+                                                      source_p,
+                                                      source_size,
+                                                      false);
 
-  jerry_value_t run_result;
-  jerry_debugger_wait_and_run_type_t receive_status;
+  if (!jerry_value_has_error_flag (ret_val))
+  {
+    jerry_value_t func_val = ret_val;
+    ret_val = jerry_run (func_val);
+    jerry_release_value (func_val);
+  }
 
+  return ret_val;
+} /* wait_for_source_callback */
+
+int main ()
+{
   do
   {
-    receive_status = jerry_debugger_wait_and_run_client_source (&run_result);
+    /* Create a new JerryScript instance when a context reset is
+     * received. Applications usually registers their core bindings
+     * here as well (e.g. print, setTimeout). */
+    jerry_init (JERRY_INIT_EMPTY);
+    jerry_debugger_init (5001);
 
-    if (receive_status == JERRY_DEBUGGER_SOURCE_RECEIVE_FAILED)
+    do
     {
-      // Handle the failure (e.g. create an error).
+      jerry_value_t run_result;
+      jerry_debugger_wait_for_source_status_t receive_status;
+
+      receive_status = jerry_debugger_wait_and_run_client_source (wait_for_source_callback,
+                                                                  NULL,
+                                                                  &run_result);
+
+      jerry_release_value (run_result);
     }
-  }
+    while (receive_status == JERRY_DEBUGGER_SOURCE_RECEIVED);
 
-    jerry_release_value (run_result);
+    jerry_cleanup ();
   }
-  while (receive_status == JERRY_DEBUGGER_SOURCE_RECEIVED);
+  while (receive_status == JERRY_DEBUGGER_CONTEXT_RESET_RECEIVED);
 
-  jerry_cleanup ();
+  if (receive_status == JERRY_DEBUGGER_SOURCE_RECEIVE_FAILED)
+  {
+    // Handle the failure (e.g. display an error).
+  }
+  return 0;
+}
 ```
 
 ### jerry_debugger_send_output