Skip to content

Add operational mode for jerry_gc API call. #2385

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
yichoi merged 1 commit into from
Jun 15, 2018
Merged

Add operational mode for jerry_gc API call. #2385

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 32 additions & 3 deletions docs/02.API-REFERENCE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Member

@akosthekiss akosthekiss Jun 7, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm no native English speaker but isn't this "operation mode" or "operating mode"?

Copy link
Member Author

@zherczeg zherczeg Jun 8, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

According to google, operation mode is used 262M sites, while operational mode 117M sites. Both are used by high profile (e.g. microsoft or google technical docs) sites. I think both are ok, so I don't want to change unless you insist on it.

Copy link
Member Author

@zherczeg zherczeg Jun 8, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I checked Cambridge dictionary:

operation - noun
operational - adjective
operating - present participle

I would prefer operational here.

Copy link
Member Author

@zherczeg zherczeg Jun 8, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Google: The present participle is a participle that ends in ing. It can be used with the auxilliary verb 'to be' to form the continuous tense. It always takes the 'ing' form of the verb, even irregular verbs have an '...ing' form, in fact virtually all English words that end with 'ing' are present participles.

I think operating mode is also correct, if we emphasize doing the garbage collection in specific a way. The operational mode simply emphasize the behavior.

Copy link
Member Author

@zherczeg zherczeg Jun 8, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

E.g:
operating system - a system which is running (emphasizing continuity)
operational system - a system which is capable of running (not relevant if it is doing it now)
operation system - double noun, usually a phrase or not used at all. I think the latter is true here.

Copy link
Member

@dbatyai dbatyai Jun 8, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As you've said, saying something is 'operational' means it is capable of running. Saying that the mode is operational means that the thing that is running will be able to run in that mode, but also implies that a 'not operational' mode exists, which 'won't be able to run'. This is not the case, as the mode here means a specific a way of operation, and not whether the GC can actually run, or is running.

I'm not sure what behavior you'd like to emphasize by using operational mode, yet it feels instinctively wrong to me, and I'd say the suggestions made by @akosthekiss would be the the correct way to go.

Copy link
Member Author

@zherczeg zherczeg Jun 11, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I didn't exactly say that. Tricky way of turning my words :)

Adjectives extends the meaning of words, while nouns do not. Think about the difference of "wooden house" and "tree house". The former uses an adjective to extend a noun, while the latter is simply a phrase.

I found "operational mode" in a well known English dictionary:
https://en.oxforddictionaries.com/definition/standby
An operational mode of an electrical appliance in which the power is switched on but the appliance is not actually functioning.

I could not find the same thing with "operation mode".

Copy link
Member

@akosthekiss akosthekiss Jun 15, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've consulted an English teacher and operation was preferred over operational. But still no native speaker chiming in on either side. As this is no API function name but a doc text only, I wont be pushing further.


- 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
Expand Down Expand Up @@ -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**
Copy link
Contributor

@LaszloLango LaszloLango Jun 6, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please update the example as well.

Copy link
Member Author

@zherczeg zherczeg Jun 8, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done. It runs with doctest as well now.


[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**
Expand Down Expand Up @@ -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.

Expand Down
4 changes: 3 additions & 1 deletion docs/10.EXT-REFERENCE-HANDLER.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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**

Expand Down
5 changes: 3 additions & 2 deletions jerry-core/api/jerry.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 */

/**
Expand Down
15 changes: 13 additions & 2 deletions jerry-core/include/jerryscript-core.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*/
Expand Down Expand Up @@ -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);
Expand Down
7 changes: 4 additions & 3 deletions jerry-ext/handler/handler-gc.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 */
2 changes: 1 addition & 1 deletion tests/unit-core/test-api.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -990,7 +990,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";
Expand Down
4 changes: 2 additions & 2 deletions tests/unit-core/test-objects-foreach.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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));
Expand All @@ -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;
Expand Down
2 changes: 1 addition & 1 deletion tests/unit-ext/test-ext-autorelease.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 ();
Expand Down