Add operational mode for jerry_gc API call. (#2385)

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

docs/02.API-REFERENCE.md

@@ -68,6 +68,18 @@ Option bits for [jerry_parse](#jerry_parse) and
  - JERRY_PARSE_NO_OPTS - no options passed
  - JERRY_PARSE_STRICT_MODE - enable strict mode
 
+## jerry_gc_mode_t
+
+Set garbage collection operational mode
+
+ - JERRY_GC_SEVERITY_LOW - free unused objects
+ - JERRY_GC_SEVERITY_HIGH - free as much memory as possible
+
+The difference between `JERRY_GC_SEVERITY_LOW` and `JERRY_GC_SEVERITY_HIGH`
+is that the former keeps memory allocated for performance improvements such
+as property hash tables for large objects. The latter frees all possible
+memory blocks but the performance may drop after the garbage collection.
+
 ## jerry_generate_snapshot_opts_t
 
 Flags for [jerry_generate_snapshot](#jerry_generate_snapshot) and
@@ -705,13 +717,30 @@ Performs garbage collection.
 
 ```c
 void
-jerry_gc (void);
+jerry_gc (jerry_gc_mode_t mode);
 ```
 
+- `mode` - operational mode, see [jerry_gc_mode_t](#jerry_gc_mode_t)
+
 **Example**
 
+[doctest]: # ()
+
 ```c
-jerry_gc ();
+#include "jerryscript.h"
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  jerry_value_t object_value = jerry_create_object ();
+  jerry_release_value (object_value);
+
+  jerry_gc (JERRY_GC_SEVERITY_LOW);
+
+  jerry_cleanup ();
+}
 ```
 
 **See also**
@@ -1601,7 +1630,7 @@ jerry_value_is_undefined (const jerry_value_t value)
 Returns the JavaScript type
 for a given value as a [jerry_type_t](#jerry_type_t) enum value.
 
-This is a similar operation as the 'typeof' operator
+This is a similar operation to the 'typeof' operator
 in the standard with an exception that the 'null'
 value has its own enum value.
 

docs/10.EXT-REFERENCE-HANDLER.md

@@ -31,7 +31,9 @@ jerryx_handler_assert (const jerry_value_t func_obj_val, const jerry_value_t thi
 
 **Summary**
 
-Expose garbage collector to scripts.
+Expose garbage collector to scripts. If the first argument of the function
+is logical true, it performs a high severity gc. Otherwise a low severity
+gc is performed, which is also the default if no parameters passed.
 
 **Prototype**
 

jerry-core/api/jerry.c

@@ -289,11 +289,12 @@ jerry_register_magic_strings (const jerry_char_ptr_t *ex_str_items_p, /**< chara
  * Run garbage collection
  */
 void
-jerry_gc (void)
+jerry_gc (jerry_gc_mode_t mode) /**< operational mode */
 {
   jerry_assert_api_available ();
 
-  ecma_gc_run (JMEM_FREE_UNUSED_MEMORY_SEVERITY_LOW);
+  ecma_gc_run (mode == JERRY_GC_SEVERITY_LOW ? JMEM_FREE_UNUSED_MEMORY_SEVERITY_LOW
+                                             : JMEM_FREE_UNUSED_MEMORY_SEVERITY_HIGH);
 } /* jerry_gc */
 
 /**

jerry-core/include/jerryscript-core.h

@@ -100,9 +100,20 @@ typedef enum
 typedef enum
 {
   JERRY_PARSE_NO_OPTS = 0, /**< no options passed */
-  JERRY_PARSE_STRICT_MODE = (1 << 0), /**< enable strict mode */
+  JERRY_PARSE_STRICT_MODE = (1 << 0) /**< enable strict mode */
 } jerry_parse_opts_t;
 
+/**
+ * GC operational modes.
+ */
+typedef enum
+{
+  JERRY_GC_SEVERITY_LOW, /**< free unused objects, but keep memory
+                          *   allocated for performance improvements
+                          *   such as property hash tables for large objects */
+  JERRY_GC_SEVERITY_HIGH /**< free as much memory as possible */
+} jerry_gc_mode_t;
+
 /**
  * Character type of JerryScript.
  */
@@ -303,7 +314,7 @@ void jerry_init (jerry_init_flag_t flags);
 void jerry_cleanup (void);
 void jerry_register_magic_strings (const jerry_char_ptr_t *ex_str_items_p, uint32_t count,
                                    const jerry_length_t *str_lengths_p);
-void jerry_gc (void);
+void jerry_gc (jerry_gc_mode_t mode);
 void *jerry_get_context_data (const jerry_context_data_manager_t *manager_p);
 
 bool jerry_get_memory_stats (jerry_heap_stats_t *out_stats_p);

jerry-ext/handler/handler-gc.c

@@ -28,9 +28,10 @@ jerryx_handler_gc (const jerry_value_t func_obj_val, /**< function object */
 {
   (void) func_obj_val; /* unused */
   (void) this_p; /* unused */
-  (void) args_p; /* unused */
-  (void) args_cnt; /* unused */
 
-  jerry_gc ();
+  jerry_gc_mode_t mode = ((args_cnt > 0 && jerry_value_to_boolean (args_p[0])) ? JERRY_GC_SEVERITY_HIGH
+                                                                               : JERRY_GC_SEVERITY_LOW);
+
+  jerry_gc (mode);
   return jerry_create_undefined ();
 } /* jerryx_handler_gc */

tests/unit-core/test-api.c

@@ -1014,7 +1014,7 @@ main (void)
   jerry_release_value (global_obj_val);
 
   /* Test: run gc. */
-  jerry_gc ();
+  jerry_gc (JERRY_GC_SEVERITY_LOW);
 
   /* Test: spaces */
   eval_code_src_p = "\x0a \x0b \x0c \xc2\xa0 \xe2\x80\xa8 \xe2\x80\xa9 \xef\xbb\xbf 4321";

tests/unit-core/test-objects-foreach.c

@@ -99,7 +99,7 @@ main (void)
   jerry_release_value (object);
 
   /* Collect garbage. */
-  jerry_gc ();
+  jerry_gc (JERRY_GC_SEVERITY_LOW);
 
   /* Attempt to retrieve the object by its native pointer again. */
   TEST_ASSERT (!jerry_objects_foreach_by_native_info (&test_info, find_test_object_by_data, &found_object));
@@ -124,7 +124,7 @@ main (void)
   jerry_release_value (args[1]);
 
   /* Collect garbage. */
-  jerry_gc ();
+  jerry_gc (JERRY_GC_SEVERITY_LOW);
 
   /* Attempt to retrieve the object by the presence of its property again. */
   args[0] = property_name;

tests/unit-ext/test-ext-autorelease.c

@@ -57,7 +57,7 @@ main (void)
 
   native_free_cb_call_count = 0;
   test_autorelease_val ();
-  jerry_gc ();
+  jerry_gc (JERRY_GC_SEVERITY_HIGH);
   TEST_ASSERT (native_free_cb_call_count == 1);
 
   jerry_cleanup ();