Create a new Duktape heap and return an initial context (thread). +If heap initialization fails, a NULL is returned. There is +currently no way to obtain more detailed error information.
+ +The caller may provide custom memory management functions in +alloc_func, realloc_func, and free_func; +the pointers must either all be NULL or all be +non-NULL. If the pointers are NULL, default +memory management functions (ANSI C malloc(), realloc() +, and free()) are used. The memory management functions +share the same opaque userdata pointer, alloc_udata.
+ +A fatal error handler is provided in fatal_handler. This +handler is called in unrecoverable error situations such as uncaught +errors, out-of-memory errors not resolved by garbage collection, etc. +A caller SHOULD implement a fatal error handler in most applications. +If not given, a default fatal error handler is used. The default +handler ultimately calls ANSI C exit(), which may not always +be the preferred action.
+ +To create a Duktape heap with default settings, use +duk_create_heap_default().
+ +New contexts linked to the same heap can be created with +duk_push_new_thread().
+ +=example +/* + * Simple case: use default allocation functions and fatal error handler + */ + +duk_context *ctx; +ctx = duk_create_heap(NULL, NULL, NULL, NULL, NULL); +if (ctx) { + /* success */ +} else { + /* error */ +} + +/* + * Customized handlers + */ + +duk_context *ctx; + +ctx = duk_create_heap(my_alloc, my_realloc, my_free, + (void *) 0xdeadbeef, my_fatal); +if (ctx) { + /* success */ + + /* ... after heap is no longer needed: */ + duk_destroy_heap(ctx); +} else { + /* error */ +} + diff --git a/website/api/duk_create_heap_default.txt b/website/api/duk_create_heap_default.txt new file mode 100644 index 00000000..66455315 --- /dev/null +++ b/website/api/duk_create_heap_default.txt @@ -0,0 +1,26 @@ +=proto +duk_context *duk_create_heap_default(void); + +=summary +Create a new Duktape heap and return an initial context (thread). +If heap initialization fails, a NULL is returned. There is +currently no way to obtain more detailed error information.
+ +The created heap will use default memory management and fatal error +handler functions. This API call is equivalent to:
++ctx = duk_create_heap(NULL, NULL, NULL, NULL, NULL); ++ +=example +duk_context *ctx; +ctx = duk_create_heap_default(); +if (ctx) { + /* success */ + + /* ... after heap is no longer needed: */ + duk_destroy_heap(ctx); +} else { + /* error */ +} + diff --git a/website/api/duk_destroy_heap.txt b/website/api/duk_destroy_heap.txt new file mode 100644 index 00000000..77094bea --- /dev/null +++ b/website/api/duk_destroy_heap.txt @@ -0,0 +1,13 @@ +=proto +void duk_destroy_heap(duk_context *ctx); + +=summary +
Destroy a Duktape heap. The argument context can be any context linked +to the heap. All resources related to the heap are freed and must not be +referenced after the call completes. These resources include all contexts +linked to the heap, and also all string and buffer pointers within the heap.
+ +If ctx is NULL, the call is a no-op.
+ +=example +duk_destroy_heap(ctx);