39 lines
1.6 KiB
YAML
39 lines
1.6 KiB
YAML
define: DUK_OPT_EXTSTR_INTERN_CHECK
|
|
introduced: 1.1.0
|
|
requires:
|
|
- DUK_OPT_EXTERNAL_STRINGS
|
|
tags:
|
|
- memory
|
|
- experimental
|
|
description: >
|
|
Provide a hook for checking if data for a certain string can be used from
|
|
external memory (outside of Duktape heap, e.g. memory mapped flash).
|
|
The hook is called during string interning with the following semantics:
|
|
|
|
The string data with no NUL termination resides at "ptr" and has "len"
|
|
bytes. The "udata" argument is the heap userdata which may be ignored
|
|
if not needed. If the hook returns NULL, Duktape interns the string
|
|
normally, i.e. string data is allocated from Duktape heap. Otherwise the
|
|
hook return value must point to a memory area which contains
|
|
"len" bytes from "ptr" followed by a NUL byte which is NOT PRESENT
|
|
in the input data. Data behind the returned pointer may not change after
|
|
the hook returns.
|
|
|
|
The hook may be called several times for the same input string. This
|
|
happens when a string is interned, garbage collected, and then interned
|
|
again.
|
|
|
|
The DUK_OPT_EXTSTR_FREE() hook allows application code to detect when
|
|
an external string is about to be freed.
|
|
|
|
In most cases the hook should reject strings whose "len" is less than 4
|
|
because there is no RAM advantage in moving so short strings into external
|
|
memory. The ordinary "duk_hstring" header followed by the data (and a
|
|
NUL byte) has the same size as "duk_hstring_external" header which hosts
|
|
a pointer instead of string data.
|
|
|
|
Also enable DUK_OPT_EXTERNAL_STRINGS to use this feature.
|
|
|
|
See doc/low-memory.rst for more discussion how to use this feature option
|
|
in practice.
|