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

Internal doc fixes for renames

pull/798/head
Sami Vaarala 9 years ago
parent
e5f19202f7
commit
a5db8f1062
8 changed files with 85 additions and 85 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 62
      doc/buffers.rst
  2. 40
      doc/debugger.rst
  3. 4
      doc/execution.rst
  4. 25
      doc/hobject-design.rst
  5. 4
      doc/identifier-handling.rst
  6. 12
      doc/low-memory.rst
  7. 13
      doc/memory-management.rst
  8. 10
      doc/objects-in-code-section.rst

62
doc/buffers.rst
View File

@ -109,16 +109,16 @@ The various buffer and view objects ultimately point to an underlying buffer
and provide access to the full buffer or a slice/view of the buffer using
either accessor methods (like getUint32()) or virtual index properties.
All buffer objects are internally implemented using the ``duk_hbufferobject``
All buffer objects are internally implemented using the ``duk_hbufobj``
type which makes it easy to mix values between different APIs. As a result
Duktape e.g. accepts a Node.js Buffer as an input for a Khronos DataView.
duk_hbufferobject
-----------------
duk_hbufobj
-----------
The internal ``duk_hbufferobject`` type is a heap-allocated structure
extended from ``duk_hobject``. In addition having the usual object
property tables and such, it has C struct fields for quick access:
The internal ``duk_hbufobj`` type is a heap-allocated structure extended
from ``duk_hobject``. In addition having the usual object property tables
and such, it has C struct fields for quick access:
* A reference to an underlying plain buffer value (``duk_hbuffer``),
which may be of any type: fixed, dynamic, or external.
@ -155,23 +155,22 @@ The following figure illustrates these for a fictional Int16-view::
length in elements: 5 (= .length)
virtual indices: 0, 1, 2, 3, 4
Each ``duk_hbufferobject`` has virtual index behavior with indices mapping
logically to elements in the range [0,length[. Elements may be signed or
unsigned integers of multiple sizes, IEEE floats, or IEEE doubles. All
accesses to the underlying buffer are byte-based, and no alignment is required
by Duktape; however, Khronos TypedArray specification restricts creation of
Each ``duk_hbufobj`` has virtual index behavior with indices mapping logically
to elements in the range [0,length[. Elements may be signed or unsigned
integers of multiple sizes, IEEE floats, or IEEE doubles. All accesses to
the underlying buffer are byte-based, and no alignment is required by Duktape;
however, Khronos TypedArray specification restricts creation of
non-element-aligned views. All multi-byte elements are accessed in the host
endianness (this is required by the Khronos/ES6 TypedArray specification).
A ``duk_hbufferobject`` acts as a both a buffer representation (providing
Node.js Buffer and ArrayBuffer) and a view representation (prodiving e.g.
DataView, Uint8Array, and other TypedArray views). It supports both a direct
1:1 mapping to an underlying buffer and a slice/view mapping to a subset of
the buffer.
A ``duk_hbufobj`` acts as a both a buffer representation (providing Node.js
Buffer and ArrayBuffer) and a view representation (prodiving e.g. DataView,
Uint8Array, and other TypedArray views). It supports both a direct 1:1 mapping
to an underlying buffer and a slice/view mapping to a subset of the buffer.
The byteLength/byteOffset pair provides a logical window for the buffer object.
The underlying buffer may be smaller, e.g. as a result of a dynamic buffer
being resized after a ``duk_hbufferobject`` was created. For example::
being resized after a ``duk_hbufobj`` was created. For example::
+------+---------------------+
| xx xx:xx xx xx xx xx xx xx | / / / / underlying buffer resized to 9 bytes
@ -263,7 +262,7 @@ Notes:
"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_hbufferobject``.
provided for all objects implemented internally as a ``duk_hbufobj``.
Built-in objects related to buffers
-----------------------------------
@ -345,7 +344,7 @@ specifications require such behavior, of course).
As a general rule:
* Any Buffer object/view (implemented internally as a ``duk_hbufferobject``)
* Any Buffer object/view (implemented internally as a ``duk_hbufobj``)
is accepted by any API expecting a specific object/view. For example,
Khronos DataView() constructor accepts a Node.js Buffer, and Node.js
Buffer() accepts a Duktape.Buffer as an input.
@ -969,10 +968,10 @@ Add support for neutering (detached buffer)
-------------------------------------------
Currently not supported. Neutering an ArrayBuffer must also affect all views
referencing that ArrayBuffer. Because duk_hbufferobject has a direct
duk_hbuffer pointer (not a pointer to ArrayBuffer which is stored as .buffer)
the neutering cannot be implemented by replacing the duk_hbuffer pointer with
zero, as that wouldn't affect all the shared views.
referencing that ArrayBuffer. Because duk_hbufobj has a direct duk_hbuffer
pointer (not a pointer to ArrayBuffer which is stored as .buffer) the neutering
cannot be implemented by replacing the duk_hbuffer pointer with zero, as that
wouldn't affect all the shared views.
Instead, neutering probably needs to be implemented at the plain buffer level;
for example, by adding a "neutered" flag to duk_hbuffer. A dynamic buffer can
@ -993,9 +992,9 @@ which is close to what current code is doing:
Configurable endianness for TypedArray views
--------------------------------------------
Change duk_hbufferobject so that it records requested endianness explicitly:
host, little, or big endian. Then use the specified endianness in readfield
and writefield internal primitives.
Change duk_hbufobj so that it records requested endianness explicitly: host,
little, or big endian. Then use the specified endianness in readfield and
writefield internal primitives.
This should be relatively straightforward to do, and perhaps useful.
@ -1024,8 +1023,8 @@ Additional arguments to TypedArray constructor
It would be nice to have offset/length when constructing a TypedArray from
another TypedArray.
Accept plain buffer values where duk_hbufferobject is accepted
--------------------------------------------------------------
Accept plain buffer values where duk_hbufobj is accepted
--------------------------------------------------------
This would be convenient and easy to add by automatically coercing the
"this" argument (which needs to be type checked anyway).
@ -1076,9 +1075,8 @@ Improve fastint handling for buffer indices, lengths, values, etc.
Unsorted future work
--------------------
* Clean up ``duk_hbufferobject`` ``buf == NULL`` handling. Perhaps don't
allow ``NULL`` at all; this depends on the neutering / detached buffer
solution.
* Clean up ``duk_hbufobj`` ``buf == NULL`` handling. Perhaps don't allow
``NULL`` at all; this depends on the neutering / detached buffer solution.
* Implement and test for integer arithmetic wrap checks e.g. when coercing
an index into a byte offset by shifting.
@ -1118,7 +1116,7 @@ Unsorted future work
add testcases, etc.
* Implement fast path for Node.js Buffer constructor when argument is another
duk_hbufferobject (now reads indexed properties explicitly).
duk_hbufobj (now reads indexed properties explicitly).
* Duktape C API tests for buffer handling.

40
doc/debugger.rst
View File

@ -2361,11 +2361,11 @@ The following list describes artificial keys included in Duktape 1.5.0, see
+---------------------------------+---------------------------+---------------------------------------------------------+
| ``bound`` | ``duk_hobject`` | DUK_HOBJECT_FLAG_BOUND |
+---------------------------------+---------------------------+---------------------------------------------------------+
| ``compiledfunction`` | ``duk_hobject`` | DUK_HOBJECT_FLAG_COMPILEDFUNCTION |
| ``compfunc`` | ``duk_hobject`` | DUK_HOBJECT_FLAG_COMPFUNC |
+---------------------------------+---------------------------+---------------------------------------------------------+
| ``nativefunction`` | ``duk_hobject`` | DUK_HOBJECT_FLAG_NATIVEFUNCTION |
| ``natfunc`` | ``duk_hobject`` | DUK_HOBJECT_FLAG_NATFUNC |
+---------------------------------+---------------------------+---------------------------------------------------------+
| ``bufferobject`` | ``duk_hobject`` | DUK_HOBJECT_FLAG_BUFFEROBJECT |
| ``bufobj`` | ``duk_hobject`` | DUK_HOBJECT_FLAG_BUFOBJ |
+---------------------------------+---------------------------+---------------------------------------------------------+
| ``thread`` | ``duk_hobject`` | DUK_HOBJECT_FLAG_THREAD |
+---------------------------------+---------------------------+---------------------------------------------------------+
@ -2410,37 +2410,37 @@ The following list describes artificial keys included in Duktape 1.5.0, see
+---------------------------------+---------------------------+---------------------------------------------------------+
| ``h_size`` | ``duk_hobject`` | Hash part size. |
+---------------------------------+---------------------------+---------------------------------------------------------+
| (not present yet) | ``duk_hnativefunction`` | Native function pointer. |
| (not present yet) | ``duk_hnatfunc`` | Native function pointer. |
+---------------------------------+---------------------------+---------------------------------------------------------+
| ``nargs`` | ``duk_hnativefunction`` | Number of stack arguments. |
| ``nargs`` | ``duk_hnatfunc`` | Number of stack arguments. |
+---------------------------------+---------------------------+---------------------------------------------------------+
| ``magic`` | ``duk_hnativefunction`` | Magic value. |
| ``magic`` | ``duk_hnatfunc`` | Magic value. |
+---------------------------------+---------------------------+---------------------------------------------------------+
| ``varargs`` | ``duk_hnativefunction`` | True if function has variable arguments. |
| ``varargs`` | ``duk_hnatfunc`` | True if function has variable arguments. |
+---------------------------------+---------------------------+---------------------------------------------------------+
| (not present yet) | ``duk_hcompiledfunction`` | Ecmascript function data area, including bytecode. |
| (not present yet) | ``duk_hcompfunc`` | Ecmascript function data area, including bytecode. |
+---------------------------------+---------------------------+---------------------------------------------------------+
| ``nregs`` | ``duk_hcompiledfunction`` | Number of bytecode executor registers. |
| ``nregs`` | ``duk_hcompfunc`` | Number of bytecode executor registers. |
+---------------------------------+---------------------------+---------------------------------------------------------+
| ``nargs`` | ``duk_hcompiledfunction`` | Number of stack arguments. |
| ``nargs`` | ``duk_hcompfunc`` | Number of stack arguments. |
+---------------------------------+---------------------------+---------------------------------------------------------+
| ``start_line`` | ``duk_hcompiledfunction`` | First source code line. |
| ``start_line`` | ``duk_hcompfunc`` | First source code line. |
+---------------------------------+---------------------------+---------------------------------------------------------+
| ``end_line`` | ``duk_hcompiledfunction`` | Last source code line. |
| ``end_line`` | ``duk_hcompfunc`` | Last source code line. |
+---------------------------------+---------------------------+---------------------------------------------------------+
| (no properties yet) | ``duk_hthread`` | No thread properties yet. |
+---------------------------------+---------------------------+---------------------------------------------------------+
| ``buffer`` | ``duk_hbufferobject`` | Underlying plain buffer (provided as a heapptr). |
| ``buffer`` | ``duk_hbufobj`` | Underlying plain buffer (provided as a heapptr). |
+---------------------------------+---------------------------+---------------------------------------------------------+
| ``slice_offset`` | ``duk_hbufferobject`` | Byte offset to underlying buffer for start of slice. |
| ``slice_offset`` | ``duk_hbufobj`` | Byte offset to underlying buffer for start of slice. |
+---------------------------------+---------------------------+---------------------------------------------------------+
| ``slice_length`` | ``duk_hbufferobject`` | Byte length of slice. |
| ``slice_length`` | ``duk_hbufobj`` | Byte length of slice. |
+---------------------------------+---------------------------+---------------------------------------------------------+
| ``elem_shift`` | ``duk_hbufferobject`` | Shift value for element, e.g. Uint64 -> 3. |
| ``elem_shift`` | ``duk_hbufobj`` | Shift value for element, e.g. Uint64 -> 3. |
+---------------------------------+---------------------------+---------------------------------------------------------+
| ``elem_type`` | ``duk_hbufferobject`` | DUK_HBUFFEROBJECT_ELEM_xxx |
| ``elem_type`` | ``duk_hbufobj`` | DUK_HBUFOBJ_ELEM_xxx |
+---------------------------------+---------------------------+---------------------------------------------------------+
| ``is_view`` | ``duk_hbufferobject`` | True if bufferobject is a view (e.g. Uint8Array). |
| ``is_view`` | ``duk_hbufobj`` | True if bufferobject is a view (e.g. Uint8Array). |
+---------------------------------+---------------------------+---------------------------------------------------------+
| ``extdata`` | ``duk_hstring`` | DUK_HSTRING_FLAG_EXTDATA |
+---------------------------------+---------------------------+---------------------------------------------------------+
@ -2823,8 +2823,8 @@ pair. The current file/line approach is intuitive but means that:
functions. This also affects minified Ecmascript code.
* There are potentially multiple Ecmascript function instance (i.e.
``duk_hcompiledfunction`` objects) that have been created from the same
spot. The breakpoint will match all of them.
``duk_hcompfunc`` objects) that have been created from the same spot.
The breakpoint will match all of them.
Line transitions
----------------

4
doc/execution.rst
View File

@ -668,8 +668,8 @@ The measurements below are using ``gcc -O2`` on x64::
Accessing constants
===================
The executor stores a copy of the ``duk_hcompiledfunction`` constant table
base address into a local variable ``consts``. This reduces code footprint
The executor stores a copy of the ``duk_hcompfunc`` constant table base
address into a local variable ``consts``. This reduces code footprint
and performs better compared to reading the consts base address on-the-fly
through the function reference. Because the constants table has a stable
base address, this is easy and safe.

25
doc/hobject-design.rst
View File

@ -570,10 +570,10 @@ The memory layout of an ``duk_hobject`` is illustrated below::
| duk_u32 h_size | +->| entry part flags |
| duk_hobject *prototype | : | (e_size x duk_u8) |
+------------------------+ : +---------------------------+
: duk_hcompiledfunction : +->| array part values |
: duk_hnativefunction : : | (a_size x duk_tval) |
: duk_hcompfunc : +->| array part values |
: duk_hnatfunc : : | (a_size x duk_tval) |
: duk_hthread : : +---------------------------+
: : +->| hash part indices |
: ... : +->| hash part indices |
: (extended structures) : : | (h_size x duk_u32) |
+------------------------+ : +---------------------------+
:
@ -602,8 +602,9 @@ The object specific part of ``duk_hobject`` contains:
* internal prototype field for fast prototype chain walking;
other internal properties are stored in the property allocation
* ``duk_hcompiledfunction``, ``duk_hnativefunction``, and ``duk_hthread``
object sub-types have an extended structure with more fields
Some ``duk_hobject`` sub-types share the beginning of the ``duk_hobject``
struct but have additional fields. These sub-types include: ``duk_harray``,
``duk_hcompfunc``, ``duk_hnatfunc``, ``duk_hthread``, and ``duk_hbufobj``.
The property allocation part is a single memory allocation containing all
the object properties, both external and internal. It is subdivided
@ -1649,13 +1650,13 @@ double brackets are omitted from the specification property names
| FormalParameters | Internal property ``_Formals``. |
| | |
+-------------------+------------------------------------------------------+
| Code | An Ecmascript function (``duk_hcompiledfunction``) |
| | has a pointer to compiled bytecode and associated |
| | data (such as constants), see |
| | ``duk_hcompiledfunction.h``. |
| | A C function (``duk_hnativefunction``) has a pointer |
| | to a C function and some related control data, see |
| | ``duk_hnativefunction.h``. |
| Code | An Ecmascript function (``duk_hcompfunc``) has |
| | a pointer to compiled bytecode and associated |
| | data (such as constants), see ``duk_hcompfunc.h``. |
| | A C function (``duk_hnatfunc``) has a pointer to a |
| | a C function and some related control data, see |
| | ``duk_hnatfunc.h``. Lightfunc C function pointer is |
| | embedded in the tagged ``duk_tval`` directly.
+-------------------+------------------------------------------------------+
| TargetFunction | ``duk_hobject`` flag ``DUK_HOBJECT_FLAG_BOUND`` is |
| | set, and the internal property ``_Target`` is set |

4
doc/identifier-handling.rst
View File

@ -574,8 +574,8 @@ declarative environment (record2) to be created.
Functions and environment records
---------------------------------
A function object (``duk_hcompiledfunction``) records the following
conceptual variable access related information:
A function object (``duk_hcompfunc``) records the following conceptual
variable access related information:
* A variable map, which maps an identifier to a register number. Ideally
all function variables / functions are register mapped, but this is not

12
doc/low-memory.rst
View File

@ -956,13 +956,13 @@ Normal function representation
In Duktape 1.0.0 functions are represented as:
* A ``duk_hcompiledfunction`` (a superset of ``duk_hobject``): represents
an Ecmascript function which may have a set of properties, and points to
* A ``duk_hcompfuncn`` (a superset of ``duk_hobject``): represents an
Ecmascript function which may have a set of properties, and points to
the function's data area (bytecode, constants, inner function refs).
* A ``duk_hnativefunction`` (a superset of ``duk_hobject``): represents
a Duktape/C function which may also have a set of properties. A pointer
to the C function is inside the ``duk_hnativefunction`` structure.
* A ``duk_hnatfunc`` (a superset of ``duk_hobject``): represents a
Duktape/C function which may also have a set of properties. A pointer
to the C function is inside the ``duk_hnatfunc`` structure.
In Duktape 1.1.0 a lightfunc type is available:
@ -1001,7 +1001,7 @@ functions, Duktape/C function are already stripped of unnecessary properties
and don't have an automatic prototype object.
Even so, there are close to 200 built-in functions, so the footprint of
the ``duk_hnativefunction`` objects is around 14-16kB, not taking into account
the ``duk_hnatfunc`` objects is around 14-16kB, not taking into account
allocator overhead.
Duktape/C lightfuncs

13
doc/memory-management.rst
View File

@ -511,7 +511,7 @@ allocation.
Normally, heap elements are typed by the tagged value (``duk_tval``)
which holds the heap pointer, or if the heap element reference is in
a struct field, the field is usually already correctly typed through its
C type (e.g. a field might have the type "``duk_hcompiledfunction *``").
C type (e.g. a field might have the type "``duk_hcompfunc *``").
However, heap elements do have a "heap type" field as part of the
``h_flags`` field of the header; this is not normally used, but is
needed by e.g. reference counting. As a separate issue, some heap types
@ -532,23 +532,24 @@ The current specific heap element types are:
+ Fixed size allocation consisting of a header, whose size
depends on the object type (``duk_hobject``, ``duk_hthread``,
``duk_hcompiledfunction``, or ``duk_hnativefunction``).
``duk_hcompfunc``, ``duk_hnatfunc``, etc).
+ The specific "sub type" and its associated struct definition
can be determined using object flags, using the macros:
- ``DUK_HOBJECT_IS_COMPILEDFUNCTION``
- ``DUK_HOBJECT_IS_NATIVEFUNCTION``
- ``DUK_HOBJECT_IS_COMPFUNC``
- ``DUK_HOBJECT_IS_NATFUNC``
- ``DUK_HOBJECT_IS_THREAD``
- (and other sub types added later)
- If none of the above are true, the object is a plain object
(``duk_hobject`` without any extended structure)
+ Properties are stored in a separate, dynamic allocation, and contain
references to other heap elements.
+ For ``duk_hcompiledfunction``, function bytecode, constants, and
+ For ``duk_hcompfunc``, function bytecode, constants, and
references to inner functions are stored in a fixed ``duk_hbuffer``
referenced by the ``duk_hcompiledfunction`` header. These provide
referenced by the ``duk_hcompfunc`` header. These provide
further references to other heap elements.
+ For ``duk_hthread`` the heap header contains references to the

10
doc/objects-in-code-section.rst
View File

@ -104,7 +104,7 @@ duk_hobject
-----------
* Many built-in objects are actually native functions, so the relevant
structure is often ``duk_hnativefunction``.
structure is often ``duk_hnatfunc``.
* Heap header will have more bits in use, but no effect otherwise.
@ -153,8 +153,8 @@ duk_hobject properties allocation
to duplicate into ``duk_propvalue_dataprop`` and ``duk_propvalue_accessorprop``
so that non-union initializers can be used (which is more portable).
duk_hnativefunction
-------------------
duk_hnatfunc
------------
Same issues as ``duk_hobject`` plus the following:
@ -162,8 +162,8 @@ Same issues as ``duk_hobject`` plus the following:
* Nargs and magic should have no issues.
duk_hcompiledfunction
---------------------
duk_hcompfunc
-------------
Same issues as ``duk_hobject`` plus the following:

Write Preview
Loading…
Cancel
Save