Add ArrayBuffer detach operations

JerryScript-DCO-1.0-Signed-off-by: legendecas legendecas@gmail.com

Author: legendecas

docs/02.API-REFERENCE.md

@@ -7398,6 +7398,72 @@ jerry_get_arraybuffer_pointer (const jerry_value_t value);
 - [jerry_create_arraybuffer_external](#jerry_create_arraybuffer_external)
 
 
+## jerry_is_arraybuffer_detachable
+
+**Summary**
+Get if the ArrayBuffer is detachable.
+
+**Prototype**
+
+```c
+jerry_value_t 
+jerry_is_arraybuffer_detachable (const jerry_value_t value);
+```
+
+**Example**
+
+```c
+{
+  // create the ArrayBuffer
+  jerry_value_t buffer = jerry_create_arraybuffer (16);
+
+  jerry_value_t res = jerry_is_arraybuffer_detachable (buffer);
+  bool is_detachable = jerry_get_boolean_value (res);
+
+  // release buffer as it is not needed after this point
+  jerry_release_value (buffer);
+}
+```
+
+**See also**
+- [jerry_detach_arraybuffer](#jerry_detach_arraybuffer)
+
+## jerry_detach_arraybuffer
+
+**Summary**
+Detach the underlying data block from ArrayBuffer and set its bytelength to 0.
+
+This operation requires the ArrayBuffer to be external that created by
+`jerry_create_arraybuffer_external`.
+
+**Prototype**
+
+```c
+jerry_value_t 
+jerry_detach_arraybuffer (const jerry_value_t value);
+```
+
+**Example**
+
+```c
+{
+  uint8_t buf[1];
+  jerry_size_t length = 1;
+  // create the ArrayBuffer
+  jerry_value_t buffer = jerry_create_arraybuffer (length, buf, NULL);
+
+  jerry_value_t res = jerry_detach_arraybuffer (buffer);
+
+  // release buffer as it is not needed after this point
+  jerry_release_value(res);
+  jerry_release_value (buffer);
+}
+```
+
+**See also**
+- [jerry_is_arraybuffer_detachable](#jerry_is_arraybuffer_detachable)
+
+
 ## jerry_get_dataview_buffer
 
 **Summary**

jerry-core/api/jerry.c

@@ -3271,6 +3271,59 @@ jerry_get_arraybuffer_pointer (const jerry_value_t array_buffer) /**< Array Buff
   return NULL;
 } /* jerry_get_arraybuffer_pointer */
 
+/**
+ * Get if the ArrayBuffer is detachable.
+ *
+ * @return boolean value - if success
+ *         value marked with error flag - otherwise
+ */
+jerry_value_t
+jerry_is_arraybuffer_detachable (const jerry_value_t value) /**< ArrayBuffer */
+{
+  jerry_assert_api_available ();
+
+#if ENABLED (JERRY_ES2015_BUILTIN_TYPEDARRAY)
+  if (ecma_is_arraybuffer (value))
+  {
+    ecma_object_t *buffer_p = ecma_get_object_from_value (value);
+    return ecma_arraybuffer_is_detachable (buffer_p) ? ECMA_VALUE_TRUE : ECMA_VALUE_FALSE;
+  }
+#else /* !ENABLED (JERRY_ES2015_BUILTIN_TYPEDARRAY) */
+  JERRY_UNUSED (value);
+#endif /* ENABLED (JERRY_ES2015_BUILTIN_TYPEDARRAY) */
+  return jerry_throw (ecma_raise_type_error (ECMA_ERR_MSG ("Expects an ArrayBuffer")));
+} /* jerry_is_arraybuffer_detachable */
+
+/**
+ * Detach the underlying data block from ArrayBuffer and set its bytelength to 0.
+ * This operation requires the ArrayBuffer to be external that created by
+ * `jerry_create_arraybuffer_external`.
+ *
+ * @return undefined value - if success
+ *         value marked with error flag - otherwise
+ */
+jerry_value_t
+jerry_detach_arraybuffer (const jerry_value_t value) /**< ArrayBuffer */
+{
+  jerry_assert_api_available ();
+
+#if ENABLED (JERRY_ES2015_BUILTIN_TYPEDARRAY)
+  if (ecma_is_arraybuffer (value))
+  {
+    ecma_object_t *buffer_p = ecma_get_object_from_value (value);
+    bool detached = ecma_arraybuffer_detach (buffer_p);
+    if (!detached)
+    {
+      return jerry_throw (ecma_raise_type_error (ECMA_ERR_MSG ("Expects a detachable ArrayBuffer.")));
+    }
+    return ECMA_VALUE_UNDEFINED;
+  }
+#else /* !ENABLED (JERRY_ES2015_BUILTIN_TYPEDARRAY) */
+  JERRY_UNUSED (value);
+#endif /* ENABLED (JERRY_ES2015_BUILTIN_TYPEDARRAY) */
+  return jerry_throw (ecma_raise_type_error (ECMA_ERR_MSG ("Expects an ArrayBuffer")));
+} /* jerry_detach_arraybuffer */
+
 /**
  * DataView related functions
  */

jerry-core/ecma/operations/ecma-arraybuffer-object.c

@@ -203,6 +203,60 @@ ecma_arraybuffer_get_buffer (ecma_object_t *object_p) /**< pointer to the ArrayB
   }
 } /* ecma_arraybuffer_get_buffer */
 
+/**
+ * Helper function: check if the target ArrayBuffer is detachable
+ *
+ *
+ * @return true - if value is an detachable ArrayBuffer object
+ *         false - otherwise
+ */
+inline bool JERRY_ATTR_PURE JERRY_ATTR_ALWAYS_INLINE
+ecma_arraybuffer_is_detachable (ecma_object_t *object_p) /**< pointer to the ArrayBuffer object */
+{
+  JERRY_ASSERT (ecma_object_class_is (object_p, LIT_MAGIC_STRING_ARRAY_BUFFER_UL));
+
+  ecma_extended_object_t *ext_object_p = (ecma_extended_object_t *) object_p;
+
+  if (ECMA_ARRAYBUFFER_HAS_EXTERNAL_MEMORY (ext_object_p))
+  {
+    ecma_arraybuffer_external_info *array_p = (ecma_arraybuffer_external_info *) ext_object_p;
+    /* in case the arraybuffer has been detached */
+    return array_p->buffer_p != NULL;
+  }
+  else
+  {
+    return false;
+  }
+} /* ecma_arraybuffer_is_detachable */
+
+/**
+ * ArrayBuffer object detaching operation
+ *
+ *
+ * See also: ES2015 24.1.1.3
+ *
+ * @return true - if detach op succeeded
+ *         false - otherwise
+ */
+inline bool JERRY_ATTR_ALWAYS_INLINE
+ecma_arraybuffer_detach (ecma_object_t *object_p) /**< pointer to the ArrayBuffer object */
+{
+  JERRY_ASSERT (ecma_object_class_is (object_p, LIT_MAGIC_STRING_ARRAY_BUFFER_UL));
+
+  if (!ecma_arraybuffer_is_detachable (object_p))
+  {
+    return false;
+  }
+
+  ecma_extended_object_t *ext_object_p = (ecma_extended_object_t *) object_p;
+
+  ecma_arraybuffer_external_info *array_object_p = (ecma_arraybuffer_external_info *) ext_object_p;
+  array_object_p->buffer_p = NULL;
+  array_object_p->extended_object.u.class_prop.u.length = 0;
+
+  return true;
+} /* ecma_arraybuffer_detach */
+
 /**
  * @}
  * @}

jerry-core/ecma/operations/ecma-arraybuffer-object.h

@@ -43,6 +43,10 @@ lit_utf8_byte_t * JERRY_ATTR_PURE
 ecma_arraybuffer_get_buffer (ecma_object_t *obj_p);
 ecma_length_t JERRY_ATTR_PURE
 ecma_arraybuffer_get_length (ecma_object_t *obj_p);
+bool JERRY_ATTR_PURE
+ecma_arraybuffer_is_detachable (ecma_object_t *obj_p);
+bool
+ecma_arraybuffer_detach (ecma_object_t *obj_p);
 bool
 ecma_is_arraybuffer (ecma_value_t val);
 

jerry-core/include/jerryscript-core.h

@@ -595,6 +595,8 @@ jerry_length_t jerry_arraybuffer_read (const jerry_value_t value,
                                        jerry_length_t buf_size);
 jerry_length_t jerry_get_arraybuffer_byte_length (const jerry_value_t value);
 uint8_t *jerry_get_arraybuffer_pointer (const jerry_value_t value);
+jerry_value_t jerry_is_arraybuffer_detachable (const jerry_value_t value);
+jerry_value_t jerry_detach_arraybuffer (const jerry_value_t value);
 
 /**
  * DataView functions.

tests/unit-core/test-arraybuffer.c

@@ -354,6 +354,51 @@ main (void)
     jerry_release_value (input_buffer);
   }
 
+  /* Test ArrayBuffer detach */
+  {
+    const uint32_t length = 1;
+    jerry_value_t arraybuffer = jerry_create_arraybuffer (length);
+    TEST_ASSERT (!jerry_value_is_error (arraybuffer));
+    TEST_ASSERT (jerry_value_is_arraybuffer (arraybuffer));
+    TEST_ASSERT (jerry_get_arraybuffer_byte_length (arraybuffer) == length);
+
+    jerry_value_t is_detachable = jerry_is_arraybuffer_detachable (arraybuffer);
+    TEST_ASSERT (!jerry_value_is_error (is_detachable));
+    TEST_ASSERT (!jerry_value_to_boolean (is_detachable));
+
+    jerry_value_t res = jerry_detach_arraybuffer (arraybuffer);
+    TEST_ASSERT (jerry_value_is_error (res));
+
+    jerry_release_value (res);
+    jerry_release_value (arraybuffer);
+  }
+
+  /* Test external ArrayBuffer detach */
+  {
+    uint8_t buf[1];
+    const uint32_t length = 1;
+    jerry_value_t arraybuffer = jerry_create_arraybuffer_external (length, buf, NULL);
+    TEST_ASSERT (!jerry_value_is_error (arraybuffer));
+    TEST_ASSERT (jerry_value_is_arraybuffer (arraybuffer));
+    TEST_ASSERT (jerry_get_arraybuffer_byte_length (arraybuffer) == length);
+
+    jerry_value_t is_detachable = jerry_is_arraybuffer_detachable (arraybuffer);
+    TEST_ASSERT (!jerry_value_is_error (is_detachable));
+    TEST_ASSERT (jerry_value_to_boolean (is_detachable));
+    jerry_release_value (is_detachable);
+
+    jerry_value_t res = jerry_detach_arraybuffer (arraybuffer);
+    TEST_ASSERT (!jerry_value_is_error (res));
+
+    is_detachable = jerry_is_arraybuffer_detachable (arraybuffer);
+    TEST_ASSERT (!jerry_value_is_error (is_detachable));
+    TEST_ASSERT (!jerry_value_to_boolean (is_detachable));
+    jerry_release_value (is_detachable);
+
+    jerry_release_value (res);
+    jerry_release_value (arraybuffer);
+  }
+
   jerry_cleanup ();
 
   TEST_ASSERT (callback_called == true);