Add SharedArrayBuffer support (#4689)

JerryScript-DCO-1.0-Signed-off-by: Gergo Csizi csgergo92@gmail.com
2021-07-23 17:29:06 +02:00
parent bbf1c0105b
commit d9360f51d0
28 changed files with 1050 additions and 337 deletions
@@ -52,6 +52,7 @@ Enum that contains JerryScript **object** value types:
 - JERRY_OBJECT_TYPE_CONTAINER - Container object (see [jerry_get_container_type](#jerry_get_container_type))
 - JERRY_OBJECT_TYPE_ERROR - Error object
 - JERRY_OBJECT_TYPE_ARRAYBUFFER - Array buffer object
+ - JERRY_OBJECT_TYPE_SHARED_ARRAYBUFFER - Shared Array buffer object

 - JERRY_OBJECT_TYPE_ARGUMENTS - Arguments object
 - JERRY_OBJECT_TYPE_BOOLEAN - Boolean object
@@ -2130,6 +2131,53 @@ jerry_value_is_arraybuffer (const jerry_value_t value)
 - [jerry_create_arraybuffer](#jerry_create_arraybuffer)
 - [jerry_create_arraybuffer_external](#jerry_create_arraybuffer_external)

+## jerry_value_is_shared_arraybuffer
+
+**Summary**
+
+Returns whether the given `jerry_value_t` is a SharedArrayBuffer object.
+
+*Notes*:
+- This API depends on a build option (`JERRY_BUILTIN_TYPEDARRAY`) and can be checked
+  in runtime with the `JERRY_FEATURE_TYPEDARRAY` feature enum value,
+  see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+- The es.next profile enables this by default.
+
+**Prototype**
+
+```c
+bool
+jerry_value_is_shared_arraybuffer (const jerry_value_t value);
+```
+
+- `value` - api value to check.
+- return value
+    - true, if the given `jerry_value_t` is a SharedArrayBuffer object.
+    - false, otherwise
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+```c
+{
+  jerry_value_t value;
+  ... // create or acquire value
+
+  if (jerry_value_is_shared_arraybuffer (value))
+  {
+    ...
+  }
+
+  jerry_release_value (value);
+}
+```
+
+**See also**
+
+- [jerry_create_shared_arraybuffer](#jerry_create_shared_arraybuffer)
+- [jerry_create_shared_arraybuffer_external](#jerry_create_shared_arraybuffer_external)
+

 ## jerry_value_is_boolean

@@ -6193,6 +6241,108 @@ jerry_create_arraybuffer_external (const jerry_length_t size
 - [jerry_object_native_free_callback_t](#jerry_object_native_free_callback_t)


+## jerry_create_shared_arraybuffer
+
+**Summary**
+
+Create a jerry_value_t representing a SharedArrayBuffer object.
+
+*Note*:
+- This API depends on the es.next profile.
+- Returned value must be freed with [jerry_release_value](#jerry_release_value)
+  when it is no longer needed.
+
+**Prototype**
+
+```c
+jerry_value_t
+jerry_create_shared_arraybuffer (jerry_length_t size);
+```
+
+- `size` - size of the SharedArrayBuffer to create **in bytes**
+- return value - the new SharedArrayBuffer as a `jerry_value_t`
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+```c
+{
+  jerry_value_t buffer_value = jerry_create_shared_arraybuffer (15);
+
+  ... // use the SharedArrayBuffer
+
+  jerry_release_value (buffer_value);
+}
+```
+
+**See also**
+
+- [jerry_arraybuffer_read](#jerry_arraybuffer_read)
+- [jerry_arraybuffer_write](#jerry_arraybuffer_write)
+- [jerry_value_is_shared_arraybuffer](#jerry_value_is_shared_arraybuffer)
+- [jerry_release_value](#jerry_release_value)
+
+
+## jerry_create_shared_arraybuffer_external
+
+**Summary**
+
+Creates a jerry_value_t representing an SharedArrayBuffer object with
+user specified back-buffer.
+
+User must pass a buffer pointer which is at least `size` big.
+After the object is not needed the GC will call the `free_cb`
+so the user can release the buffer which was provided.
+
+*Note*:
+- This API depends on the es.next profile.
+- Returned value must be freed with [jerry_release_value](#jerry_release_value)
+  when it is no longer needed.
+
+**Prototype**
+
+```c
+jerry_value_t
+jerry_create_shared_arraybuffer_external (const jerry_length_t size
+                                          uint8_t *buffer_p,
+                                          jerry_value_free_callback_t free_cb);
+```
+
+- `size` - size of the buffer to use **in bytes** (should not be 0)
+- `buffer_p` - the buffer used for the Shared Array Buffer object (should not be a null pointer)
+- `free_cb` - the callback function called when the object is released
+- return value
+    - the new SharedArrayBuffer as a `jerry_value_t`
+    - if the `size` is zero or `buffer_p` is a null pointer this will return an empty SharedArrayBuffer.
+
+*New in version [[NEXT_RELEASE]]*.
+
+*Changed in version [[NEXT_RELEASE]]*: type of `free_cb` has been changed.
+
+**Example**
+
+```c
+{
+  uint8_t buffer_p[15];
+  jerry_value_t buffer_value = jerry_create_shared_arraybuffer_external (15, buffer_p, NULL);
+
+  ... // use the shared array buffer
+
+  jerry_release_value (buffer_value);
+}
+```
+
+**See also**
+
+- [jerry_get_arraybuffer_pointer](#jerry_get_arraybuffer_pointer)
+- [jerry_arraybuffer_read](#jerry_arraybuffer_read)
+- [jerry_arraybuffer_write](#jerry_arraybuffer_write)
+- [jerry_value_is_shared_arraybuffer](#jerry_value_is_shared_arraybuffer)
+- [jerry_release_value](#jerry_release_value)
+- [jerry_object_native_free_callback_t](#jerry_object_native_free_callback_t)
+
+
 ## jerry_create_boolean

 **Summary**
@@ -11414,7 +11564,7 @@ These APIs all depend on the es.next profile.

 **Summary**

-Get the byte length property of the ArrayBuffer. This is the
+Get the byte length property of the ArrayBuffer or SharedArrayBuffer. This is the
 same value which was passed to the ArrayBuffer constructor call.

 **Prototype**
@@ -11451,7 +11601,7 @@ jerry_get_arraybuffer_byte_length (const jerry_value_t value);

 **Summary**

-Copy the portion of the ArrayBuffer into a user provided buffer.
+Copy the portion of the ArrayBuffer or SharedArrayBuffer into a user provided buffer.
 The start offset of the read operation can be specified.

 The number bytes to be read can be specified via the `buf_size`
@@ -11515,7 +11665,7 @@ jerry_arraybuffer_read (const jerry_value_t value,

 **Summary**

-Copy the contents of a buffer into the ArrayBuffer.
+Copy the contents of a buffer into the ArrayBuffer or SharedArrayBuffer.
 The start offset of the write operation can be specified.

 The number bytes to be written can be specified via the `buf_size`