1# Handle Scope 2 3## jerryx_handle_scope 4 5**Summary** 6It is often necessary to make the lifespan of handles shorter than the lifespan of a native method. Even though the native code could only use the most recent handle, all of the associated objects would also be kept alive since they all share the same scope. 7 8To handle this case, JerryScript HandleScope extension provides the ability to establish a new 'scope' to which newly created handles will be associated. Once those handles are no longer required, the scope can be 'closed' and any handles associated with the scope are invalidated. The methods available to open/close scopes are `jerryx_open_handle_scope` and `jerryx_close_handle_scope`. 9 10JerryScript only supports a single nested hierarchy of scopes. There is only one active scope at any time, and all new handles will be associated with that scope while it is active. Scopes must be closed in the reverse order from which they are opened. In addition, all scopes created within a native method must be closed before returning from that method. 11 12**Example** 13 14[doctest]: # (test="compile") 15 16```c 17#include "jerryscript.h" 18#include "jerryscript-ext/handle-scope.h" 19 20static jerry_value_t 21create_object (void) 22{ 23 jerry_value_t obj = jerry_create_object (); 24 return obj; 25} /* create_object */ 26 27static void 28test_handle_scope_val (void) 29{ 30 jerryx_handle_scope scope; 31 jerryx_open_handle_scope (&scope); 32 jerry_value_t obj = jerryx_create_handle (create_object ()); 33 34 jerryx_close_handle_scope (scope); 35 // now obj has been released 36} /* test_handle_scope_val */ 37 38int 39main (void) 40{ 41 jerry_init (JERRY_INIT_EMPTY); 42 43 test_handle_scope_val (); 44 jerry_gc (JERRY_GC_PRESSURE_LOW); 45 46 jerry_cleanup (); 47} /* main */ 48``` 49 50## jerryx_escapable_handle_scope 51 52**Summary** 53 54It is necessary in common cases that a handle has to be promote to outer scope and prevent from been garbage collected. To handle this case, a escapable handle scope has been proposed from which one object can be promoted to the outer scope. The method available to escape an object from been release at current scope is `jerryx_escape_handle`. 55 56**Example** 57 58[doctest]: # (test="compile") 59 60```c 61#include "jerryscript.h" 62#include "jerryscript-ext/handle-scope.h" 63 64static jerry_value_t 65create_object (void) 66{ 67 jerryx_escapable_handle_scope scope; 68 jerryx_open_escapable_handle_scope (&scope); 69 jerry_value_t obj = jerryx_create_handle (jerry_create_object ()); 70 71 jerry_value_t escaped_obj; 72 jerryx_escape_handle(scope, obj, &escaped_obj); 73 jerryx_close_handle_scope (scope); 74 // escaped_obj has now been escaped to outer scope, thus not released at this point 75 76 return escaped_obj; 77} /* create_object */ 78 79static void 80test_handle_scope_val (void) 81{ 82 jerryx_handle_scope scope; 83 jerryx_open_handle_scope (&scope); 84 jerry_value_t obj = create_object (); 85 86 jerryx_close_handle_scope (scope); 87 // now obj has been released 88} /* test_handle_scope_val */ 89 90int 91main (void) 92{ 93 jerry_init (JERRY_INIT_EMPTY); 94 95 test_handle_scope_val (); 96 jerry_gc (JERRY_GC_PRESSURE_LOW); 97 98 jerry_cleanup (); 99} /* main */ 100``` 101 102**See also** 103 104- [jerry_value_t](../docs/02.API-REFERENCE.md#jerry_value_t) 105- [jerry_acquire_value](../docs/02.API-REFERENCE.md#jerry_acquire_value) 106- [jerry_release_value](../docs/02.API-REFERENCE.md#jerry_release_value) 107 108## Pre-allocated list of handle scopes and handles 109 110To prevent trapping into system calls frequently, a pre-allocated dedicated list mechanism has been introduced to the implementation of JerryX handle scope. 111 112To change the size of pre-allocation list, use build definition `JERRYX_HANDLE_PRELIST_SIZE` and `JERRYX_SCOPE_PRELIST_SIZE` to alter the default value of 20. 113