github
/
duktape
mirror of https://github.com/svaarala/duktape.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Internal doc updates for plain buffer changes

pull/1197/head
Sami Vaarala 8 years ago
parent
2e417662f5
commit
d53cf5c297
3 changed files with 26 additions and 33 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 55
      doc/buffers.rst
  2. 2
      doc/debugger.rst
  3. 2
      doc/types.rst

55
doc/buffers.rst
View File

@ -55,8 +55,8 @@ type so various approaches are used:
a dynamic (resizable) buffer, or an external (user allocated) a dynamic (resizable) buffer, or an external (user allocated)
buffer. buffer.
- The plain buffer behaves like ArrayBuffer for Ecmascript code but maintains - The plain buffer behaves like Uint8Array for Ecmascript code but maintains
separate typing in the C API. It object coerces to an actual ``ArrayBuffer`` separate typing in the C API. It object coerces to an actual ``Uint8Array``
sharing the same underlying storage. sharing the same underlying storage.
* Blob; not very relevant for Duktape: * Blob; not very relevant for Duktape:
@ -96,11 +96,11 @@ object. Plain buffers can be fixed, dynamic, or external:
and length can be changed but Duktape won't resize or automatically free and length can be changed but Duktape won't resize or automatically free
the buffer. the buffer.
Plain buffers have virtual properties for buffer byte indices, .length, Plain buffers have Uint8Array-like virtual properties for buffer byte indices,
.byteOffset, .byteLength, and .BYTES_PER_ELEMENT. Assignment has the same .length, .byteOffset, .byteLength, and .BYTES_PER_ELEMENT. Assignment has the
semantics as Uint8Array: bytes are written with modulo 256 semantics, bytes same semantics as Uint8Array: bytes are written with modulo 256 semantics,
read back as unsigned 8-bit values. The plain buffer type is designed to bytes read back as unsigned 8-bit values. The plain buffer type is designed
be as friendly as possible for low level embedded programming, and has a to be as friendly as possible for low level embedded programming, and has a
minimal footprint because there's no Ecmascript object associated with it. minimal footprint because there's no Ecmascript object associated with it.
It is mostly intended to be accessed from C code. Duktape also uses buffer It is mostly intended to be accessed from C code. Duktape also uses buffer
values internally. values internally.
@ -202,12 +202,12 @@ Summary of buffer-related values
+-------------------+---------------+----------------+-------------+-------------+--------------------+---------+---------+--------------+---------------+---------------------+-------------+------------------+-----------------------------------+ +-------------------+---------------+----------------+-------------+-------------+--------------------+---------+---------+--------------+---------------+---------------------+-------------+------------------+-----------------------------------+
| Type | Specification | .length | .byteLength | .byteOffset | .BYTES_PER_ELEMENT | .buffer | [index] | Element type | Read coercion | Write coercion | Endianness | Accessor methods | Notes | | Type | Specification | .length | .byteLength | .byteOffset | .BYTES_PER_ELEMENT | .buffer | [index] | Element type | Read coercion | Write coercion | Endianness | Accessor methods | Notes |
+===================+===============+================+=============+=============+====================+=========+=========+==============+===============+=====================+=============+==================+===================================+ +===================+===============+================+=============+=============+====================+=========+=========+==============+===============+=====================+=============+==================+===================================+
| plain buffer | Duktape | yes (bytes) | yes | yes | yes | no | yes | uint8 | uint8 | ToUint32() & 0xff | n/a | no | Mimic ArrayBuffer, inherit | | plain buffer | Duktape | yes (bytes) | yes | yes | 1 | no | yes | uint8 | uint8 | ToUint32() & 0xff | n/a | no | Mimic Uint8Array, inherit |
| | | | | | | | | | | | | | from ArrayBuffer.prototype. | | | | | | | | | | | | | | | from Uint8Array.prototype. |
+-------------------+---------------+----------------+-------------+-------------+--------------------+---------+---------+--------------+---------------+---------------------+-------------+------------------+-----------------------------------+ +-------------------+---------------+----------------+-------------+-------------+--------------------+---------+---------+--------------+---------------+---------------------+-------------+------------------+-----------------------------------+
| Buffer | Node.js | yes (bytes) | yes | yes | 1 | no | yes | uint8 | uint8 | ToUint32() & 0xff | n/a | yes | Based on Node.js v0.12.1. | | Buffer | Node.js | yes (bytes) | yes | yes | 1 | no | yes | uint8 | uint8 | ToUint32() & 0xff | n/a | yes | Based on Node.js v0.12.1. |
+-------------------+---------------+----------------+-------------+-------------+--------------------+---------+---------+--------------+---------------+---------------------+-------------+------------------+-----------------------------------+ +-------------------+---------------+----------------+-------------+-------------+--------------------+---------+---------+--------------+---------------+---------------------+-------------+------------------+-----------------------------------+
| ArrayBuffer | TypedArray | yes (bytes) | yes | yes | 1 | no | yes | uint8 | uint8 | ToUint32() & 0xff | n/a | no | | | ArrayBuffer | TypedArray | no | yes | no | no | no | no | n/a | n/a | n/a | n/a | no | |
+-------------------+---------------+----------------+-------------+-------------+--------------------+---------+---------+--------------+---------------+---------------------+-------------+------------------+-----------------------------------+ +-------------------+---------------+----------------+-------------+-------------+--------------------+---------+---------+--------------+---------------+---------------------+-------------+------------------+-----------------------------------+
| DataView | TypedArray | yes (bytes) | yes | yes | 1 | yes | yes | uint8 | uint8 | ToUint32() & 0xff | n/a | yes | | | DataView | TypedArray | yes (bytes) | yes | yes | 1 | yes | yes | uint8 | uint8 | ToUint32() & 0xff | n/a | yes | |
+-------------------+---------------+----------------+-------------+-------------+--------------------+---------+---------+--------------+---------------+---------------------+-------------+------------------+-----------------------------------+ +-------------------+---------------+----------------+-------------+-------------+--------------------+---------+---------+--------------+---------------+---------------------+-------------+------------------+-----------------------------------+
@ -232,8 +232,8 @@ Summary of buffer-related values
Notes: Notes:
* A plain buffer mimics an ArrayBuffer wherever possible, and inherits * A plain buffer mimics an Uint8Array wherever possible, and inherits
methods and other properties through ``ArrayBuffer.prototype``. methods and other properties through ``Uint8Array.prototype``.
* DataView and Node.js Buffer inherit a set of accessor methods from their * DataView and Node.js Buffer inherit a set of accessor methods from their
prototype. These accessors allow fields of different width and type to prototype. These accessors allow fields of different width and type to
@ -256,14 +256,6 @@ Notes:
For the bytes written to memory the signedness of this coercion doesn't For the bytes written to memory the signedness of this coercion doesn't
really matter. really matter.
* Every buffer object type in Duktape provides virtual index access (either
as bytes or as elements), and the virtual "length", "byteLength",
"byteOffset", and "BYTES_PER_ELEMENT" properties. These are a union of
various virtual properties used (e.g. byteLength, byteOffset, and
BYTES_PER_ELEMENT come from TypedArray specification). They're uniformly
provided for all objects implemented internally as a ``duk_hbufobj``.
They're also provided for the plain buffer type.
Built-in objects related to buffers Built-in objects related to buffers
----------------------------------- -----------------------------------
@ -343,9 +335,9 @@ As a general rule:
Khronos DataView() constructor accepts a Node.js Buffer, and Node.js Khronos DataView() constructor accepts a Node.js Buffer, and Node.js
Buffer() accepts a Uint8Array as an input. Buffer() accepts a Uint8Array as an input.
* A plain Duktape buffer is accepted as if it was coerced to an ArrayBuffer. * A plain Duktape buffer is accepted as if it was coerced to an Uint8Array.
To simplify implementation many internals actually do an explicit ArrayBuffer To simplify implementation many internals actually do an explicit
coercion when given plain buffers. Uint8Array coercion when given plain buffers.
This general rules is complicated by a few practical issues: This general rules is complicated by a few practical issues:
@ -549,15 +541,13 @@ Specification notes
* ArrayBuffer does not have virtual indices or 'length' behavior, but TypedArray * ArrayBuffer does not have virtual indices or 'length' behavior, but TypedArray
views do. DataView does not have virtual indices but e.g. V8 provides them in views do. DataView does not have virtual indices but e.g. V8 provides them in
practice. For simplicity, Duktape ArrayBuffers and plain buffers do provide practice.
'length', virtual indices, and other virtual properties. This allows plain
buffers and ArrayBuffers to be manipulated without a view, which saves memory.
* ArrayBuffer has 'byteLength' and 'byteOffset' but no 'length'. Views have * ArrayBuffer has 'byteLength'. Views have a 'byteLength' and a 'length', where
a 'byteLength' and a 'length', where 'length' refers to number of elements, 'length' refers to number of elements, not bytes. For example a Uint32Array
not bytes. For example a Uint32Array view with length 4 would have view with length 4 would have byteLength 16. (For internal reasons, all
byteLength 16. (For internal reasons, all Duktape ArrayBuffer and view Duktape ArrayBuffer and view objects provide 'length', 'byteLength', and
objects provide 'length', 'byteLength', and 'byteOffset'.) 'byteOffset'.)
* ArrayBufferView classes are host endian. DataView is endian independent * ArrayBufferView classes are host endian. DataView is endian independent
because caller specifies endianness for each call. because caller specifies endianness for each call.
@ -875,6 +865,9 @@ The ``set()`` and ``subarray()`` methods are inherited from the intermediate
prototype object. This reduces property count by about 16 at the cost of one prototype object. This reduces property count by about 16 at the cost of one
additional object. additional object.
ES6 makes this the standard model; the TypedArreay prototype is referred to
as %TypedArrayPrototype% intrinsic object in the ES6 specification.
View/slice notes View/slice notes
---------------- ----------------

2
doc/debugger.rst
View File

@ -2457,7 +2457,7 @@ The following list describes artificial keys included in Duktape 1.5.0, see
+---------------------------------+---------------------------+---------------------------------------------------------+ +---------------------------------+---------------------------+---------------------------------------------------------+
| ``elem_type`` | ``duk_hbufobj`` | DUK_HBUFOBJ_ELEM_xxx | | ``elem_type`` | ``duk_hbufobj`` | DUK_HBUFOBJ_ELEM_xxx |
+---------------------------------+---------------------------+---------------------------------------------------------+ +---------------------------------+---------------------------+---------------------------------------------------------+
| ``is_view`` | ``duk_hbufobj`` | True if bufferobject is a view (e.g. Uint8Array). | | ``is_typedarray`` | ``duk_hbufobj`` | True if bufferobject is a typed array (e.g. Uint8Array).|
+---------------------------------+---------------------------+---------------------------------------------------------+ +---------------------------------+---------------------------+---------------------------------------------------------+
| ``extdata`` | ``duk_hstring`` | DUK_HSTRING_FLAG_EXTDATA | | ``extdata`` | ``duk_hstring`` | DUK_HSTRING_FLAG_EXTDATA |
+---------------------------------+---------------------------+---------------------------------------------------------+ +---------------------------------+---------------------------+---------------------------------------------------------+

2
doc/types.rst
View File

@ -49,7 +49,7 @@ API and internals. What's missing from the table:
+----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+
| n/a | DUK_TYPE_LIGHTFUNC | duk_is_lightfunc() | DUK_TAG_LIGHTFUNC | n/a | n/a | function | [object Function] | | | n/a | DUK_TYPE_LIGHTFUNC | duk_is_lightfunc() | DUK_TAG_LIGHTFUNC | n/a | n/a | function | [object Function] | |
+----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+
| ArrayBuffer.allocPlain(1) | DUK_TYPE_BUFFER | duk_is_buffer() | DUK_TAG_BUFFER | duk_hbuffer_fixed, | n/a | object | [object ArrayBuffer] | | | ArrayBuffer.allocPlain(1) | DUK_TYPE_BUFFER | duk_is_buffer() | DUK_TAG_BUFFER | duk_hbuffer_fixed, | n/a | object | [object Uint8Array] | |
| | | | | duk_hbuffer_dynamic, | | | | | | | | | | duk_hbuffer_dynamic, | | | | |
| | | | | duk_hbuffer_external | | | | | | | | | | duk_hbuffer_external | | | | |
+----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+

Write Preview
Loading…
Cancel
Save