heap lifecycle api call docs

website/api/duk_create_heap.txt

@@ -0,0 +1,64 @@
+=proto
+duk_context *duk_create_heap(duk_alloc_function alloc_func,
+                             duk_realloc_function realloc_func,
+                             duk_free_function free_func,
+                             void *alloc_udata,
+                             duk_fatal_function fatal_handler);
+
+=summary
+<p>Create a new Duktape heap and return an initial context (thread).
+If heap initialization fails, a <tt>NULL</tt> is returned.  There is
+currently no way to obtain more detailed error information.</p>
+
+<p>The caller may provide custom memory management functions in
+<tt>alloc_func</tt>, <tt>realloc_func</tt>, and <tt>free_func</tt>;
+the pointers must either all be <tt>NULL</tt> or all be
+non-<tt>NULL</tt>.  If the pointers are <tt>NULL</tt>, default
+memory management functions (ANSI C <tt>malloc()</tt>, <tt>realloc()</tt>
+, and <tt>free()</tt>) are used.  The memory management functions
+share the same opaque userdata pointer, <tt>alloc_udata</tt>.</p>
+
+<p>A fatal error handler is provided in <tt>fatal_handler</tt>.  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 <tt>exit()</tt>, which may not always
+be the preferred action.</p>
+
+<p>To create a Duktape heap with default settings, use
+<tt><a href="#duk_create_heap_default">duk_create_heap_default()</a></tt>.</p>
+
+<p>New contexts linked to the same heap can be created with
+<tt><a href="#duk_push_new_thread">duk_push_new_thread()</a></tt>.</p>
+
+=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 */
+}
+

website/api/duk_create_heap_default.txt

@@ -0,0 +1,26 @@
+=proto
+duk_context *duk_create_heap_default(void);
+
+=summary
+<p>Create a new Duktape heap and return an initial context (thread).
+If heap initialization fails, a <tt>NULL</tt> is returned.  There is
+currently no way to obtain more detailed error information.</p>
+
+<p>The created heap will use default memory management and fatal error
+handler functions.  This API call is equivalent to:</p>
+<pre class="c-code">
+ctx = duk_create_heap(NULL, NULL, NULL, NULL, NULL);
+</pre>
+
+=example
+duk_context *ctx;
+ctx = duk_create_heap_default();
+if (ctx) {
+    /* success */
+
+    /* ... after heap is no longer needed: */
+    duk_destroy_heap(ctx);
+} else {
+    /* error */
+}
+

website/api/duk_destroy_heap.txt

@@ -0,0 +1,13 @@
+=proto
+void duk_destroy_heap(duk_context *ctx);
+
+=summary
+<p>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.</p>
+
+<p>If <tt>ctx</tt> is <tt>NULL</tt>, the call is a no-op.</p>
+
+=example
+duk_destroy_heap(ctx);