|
| 1 | +============== |
| 2 | +V8 Typed Array |
| 3 | +============== |
| 4 | + |
| 5 | +There are 12 typed array supported. They are as follows. |
| 6 | + |
| 7 | +=================== =========================== =============== =========== ======================= |
| 8 | +Type Value Range Size in bytes Java Type Web IDL type |
| 9 | +=================== =========================== =============== =========== ======================= |
| 10 | +Int8Array -128 to 127 1 byte byte |
| 11 | +Uint8Array 0 to 255 1 byte octet |
| 12 | +Uint8ClampedArray 0 to 255 1 byte octet |
| 13 | +Int16Array -32768 to 32767 2 short short |
| 14 | +Uint16Array 0 to 65535 2 short unsigned short |
| 15 | +Int32Array -2147483648 to 2147483647 4 int long |
| 16 | +Uint32Array 0 to 4294967295 4 int unsigned long |
| 17 | +Float16Array -65504 to 65504 2 short N/A |
| 18 | +Float32Array -3.4e38 to 3.4e38 4 int unrestricted float |
| 19 | +Float64Array -1.8e308 to 1.8e308 8 double unrestricted double |
| 20 | +BigInt64Array -2^63 to 2^63 - 1 8 long bigint |
| 21 | +BigUint64Array 0 to 2^64 - 1 8 long bigint |
| 22 | +=================== =========================== =============== =========== ======================= |
| 23 | + |
| 24 | +Play with V8ValueTypedArray |
| 25 | +=========================== |
| 26 | + |
| 27 | +All typed array share the same V8 value type ``V8ValueTypedArray``. They can be differentiated by their ``getType()`` which is an enum indicating their actual types. There is a buffer associated with the ``V8ValueTypedArray``. That buffer is the actual shared memory between JVM and V8. In other words, there is zero memory copy between JVM and V8 if ``V8ValueTypedArray`` is used. Many performance sensitive applications usually exchange data via ``V8ValueTypedArray``. There are a set of ``from****`` and ``to****`` API for the data exchange. |
| 28 | + |
| 29 | +.. code-block:: java |
| 30 | +
|
| 31 | + try (V8ValueTypedArray v8ValueTypedArray = v8Runtime.createV8ValueTypedArray( |
| 32 | + V8ValueReferenceType.Int8Array, 4)) { |
| 33 | + assertEquals(4, v8ValueTypedArray.getLength()); |
| 34 | + assertEquals(1, v8ValueTypedArray.getSizeInBytes()); |
| 35 | + assertEquals(4, v8ValueTypedArray.getByteLength()); |
| 36 | + assertEquals(0, v8ValueTypedArray.getByteOffset()); |
| 37 | + assertEquals(V8ValueReferenceType.Int8Array, v8ValueTypedArray.getType()); |
| 38 | + try (V8ValueArrayBuffer v8ValueArrayBuffer = v8ValueTypedArray.getBuffer()) { |
| 39 | + v8ValueArrayBuffer.fromBytes(new byte[]{ (byte) 1, (byte) 2, (byte) 3, (byte) 4,}); |
| 40 | + } |
| 41 | + } |
| 42 | +
|
| 43 | +Play with Float16Array |
| 44 | +====================== |
| 45 | + |
| 46 | +``Float16Array`` was `introduced to V8 in Mar, 2024 <https://blog.seokho.dev/development/2024/03/03/V8-Float16Array.html>`_ as an implementation of TC39 `proposal-float16array <https://github.com/tc39/proposal-float16array>`_. It's quite special because there is no float 16 in Java, so has to be mapped to ``short``. |
| 47 | + |
| 48 | +Javet borrows ``Float16`` from the `Android FP16 implementation <https://android.googlesource.com/platform/libcore/+/master/luni/src/main/java/libcore/util/FP16.java>`_ (copyright preserved) to allow easy translation between ``short`` and ``float``. Just call ``short toHalf(float f)`` or ``float toFloat(short h)`` to complete the translation. |
| 49 | + |
| 50 | +``Float16Array`` is not enabled by default. Please make sure the following code is executed before the first ``NodeRuntime`` or ``V8Runtime`` is created. |
| 51 | + |
| 52 | +.. code-block:: java |
| 53 | +
|
| 54 | + // Node.js mode |
| 55 | + NodeRuntimeOptions.NODE_FLAGS.setJsFloat16Array(true); |
| 56 | +
|
| 57 | + // V8 mode |
| 58 | + V8RuntimeOptions.V8_FLAGS.setJsFloat16Array(true); |
| 59 | +
|
| 60 | +Please review the :extsource3:`test cases <../../../src/test/java/com/caoccao/javet/values/reference/TestV8ValueTypedArray.java>` for more detail. |
0 commit comments