Allow changing the 'this' binding of a realm (#4357)

JerryScript-DCO-1.0-Signed-off-by: Zoltan Herczeg zherczeg.u-szeged@partner.samsung.com
2020-12-14 10:05:30 +01:00
parent 7e135b04ed
commit fe29bf7390
15 changed files with 198 additions and 45 deletions
@@ -9171,6 +9171,54 @@ jerry_set_realm (jerry_value_t realm_value);

 - [jerry_create_realm](#jerry_create_realm)

+## jerry_realm_set_this
+
+**Summary**
+
+Sets the 'this' binding of a realm. This function must be called before executing
+any script on the realm. Otherwise the operation is undefined.
+
+*Notes*:
+- This feature depends on build option (`JERRY_BUILTIN_REALMS`) and can be checked
+  in runtime with the `JERRY_FEATURE_REALM` feature enum value,
+  see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+
+**Prototype**
+
+```c
+jerry_value_t
+jerry_realm_set_this (jerry_value_t realm_value, jerry_value_t this_value)
+```
+- `realm_value` - realm value
+- `this_value` - new this value
+- return
+  - exception - if any error is happened
+  - true - otherwise
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+```c
+{
+  jerry_value_t realm_value = jerry_create_realm ();
+
+  jerry_value_t old_realm = jerry_set_realm (realm_value);
+  /* The prototype of the object comes from the new realm. */
+  jerry_value_t this_value = jerry_create_object ();
+  jerry_set_realm (old_realm);
+
+  jerry_value_t result = jerry_realm_set_this (realm_value, this_value);
+
+  ... // usage of the realm
+}
+```
+
+**See also**
+
+- [jerry_create_realm](#jerry_create_realm)
+- [jerry_set_realm](#jerry_set_realm)
+
 # ArrayBuffer and TypedArray functions

 These APIs all depend on the es.next profile.