diff options
Diffstat (limited to 'content/handlers/javascript/js.h')
| -rw-r--r-- | content/handlers/javascript/js.h | 128 |
1 files changed, 95 insertions, 33 deletions
diff --git a/content/handlers/javascript/js.h b/content/handlers/javascript/js.h index 2929d0b5e..55f8e22ef 100644 --- a/content/handlers/javascript/js.h +++ b/content/handlers/javascript/js.h @@ -20,61 +20,121 @@ * Interface to javascript engine functions. */ -#ifndef _NETSURF_JAVASCRIPT_JS_H_ -#define _NETSURF_JAVASCRIPT_JS_H_ +#ifndef NETSURF_JAVASCRIPT_JS_H_ +#define NETSURF_JAVASCRIPT_JS_H_ #include "utils/errors.h" - -typedef struct jscontext jscontext; -typedef struct jsobject jsobject; - -typedef bool(jscallback)(void *ctx); - struct dom_event; struct dom_document; struct dom_node; struct dom_element; struct dom_string; -/** Initialise javascript interpreter */ +/** + * JavaScript interpreter heap + * + * In order to try and be moderately performant, we create a heap + * per browser window. This heap is shared by all browsing contexts + * we end up creating in that window. + */ +typedef struct jsheap jsheap; + +/** + * JavaScript interpreter thread + * + * When we create a browsing context itself (window+content) we have + * to create a JS thread to attach to the browsing context. + * + * JS threads are associated with heaps and will be destroyed when + * the heap is destroyed. They can be shut down manually though + * and should be for object lifetime safety reasons. + */ +typedef struct jsthread jsthread; + +/** + * Initialise javascript interpreter + */ void js_initialise(void); -/** finalise javascript interpreter */ +/** + * finalise javascript interpreter + */ void js_finalise(void); -/** Create a new javascript context. +/** + * Create a new javascript heap. * - * There is usually one context per browser context + * There is usually one heap per browser window. * - * \param timeout elapsed wallclock time (in seconds) before \a callback is called - * \param cb the callback when the runtime exceeds the timeout - * \param cbctx The context to pass to the callback - * \param jsctx Updated to the created JS context + * \param timeout elapsed wallclock time (in seconds) before \a callback is called + * \param heap Updated to the created JS heap * \return NSERROR_OK on success, appropriate error otherwise. */ -nserror js_newcontext(int timeout, jscallback *cb, void *cbctx, - jscontext **jsctx); +nserror js_newheap(int timeout, jsheap **heap); -/** Destroy a previously created context */ -void js_destroycontext(jscontext *ctx); +/** + * Destroy a previously created heap. + * + * \param heap The heap to destroy + */ +void js_destroyheap(jsheap *heap); -/** Create a new javascript compartment +/** + * Create a new javascript thread * * This is called once for a page with javascript script tags on - * it. It constructs a fresh global window object. + * it. It constructs a fresh global window object and prepares the JS + * browsing context. It's important that threads are shut down cleanly + * when the browsing context is going to be cleaned up. + * + * \param heap The heap to create the thread within + * \param win_priv The value to give to the Window constructor as the window + * \param doc_priv The value to give to the Document constructor as the document + * \param thread Updated to the created thread + * \return NSERROR_OK on success, appropriate error otherwise + */ +nserror js_newthread(jsheap *heap, void *win_priv, void *doc_priv, jsthread **thread); + +/** + * Close a javascript thread + * + * This should be called when the HTML content which owns the thread is + * being closed. This is a separate process from destroying the thread + * and merely disconnects any callbacks and thus hopefully stops + * additional JS things from triggering. If any code runs and attempts to + * register callbacks after closedown, they will fail. + * + * \param thread The thread to close down + * \return NSERROR_OK on success, appropriate error otherwise */ -jsobject *js_newcompartment(jscontext *ctx, void *win_priv, void *doc_priv); +nserror js_closethread(jsthread *thread); -/* execute some javascript in a context */ -bool js_exec(jscontext *ctx, const char *txt, size_t txtlen); +/** + * Destroy a javascript thread + * + * This should be called when the browsing context is done with the thread. + * + * This will be called when the HTML content associated with the browsing + * context is being destroyed. The thread should have already been closed + * down during the HTML content close. + * + * \param thread The thread to be destroyed + */ +void js_destroythread(jsthread *thread); +/** + * execute some javascript in a context + */ +bool js_exec(jsthread *thread, const uint8_t *txt, size_t txtlen, const char *name); -/* fire an event at a dom node */ -bool js_fire_event(jscontext *ctx, const char *type, struct dom_document *doc, struct dom_node *target); +/** + * fire an event at a dom node + */ +bool js_fire_event(jsthread *thread, const char *type, struct dom_document *doc, struct dom_node *target); bool -js_dom_event_add_listener(jscontext *ctx, +js_dom_event_add_listener(jsthread *thread, struct dom_document *document, struct dom_node *node, struct dom_string *event_type_dom, @@ -82,21 +142,23 @@ js_dom_event_add_listener(jscontext *ctx, /*** New Events ***/ -/** Handle a new element being created. +/** + * Handle a new element being created. * * This is called once an element is inserted into the DOM document handled * by the context provided. The JS implementation must then scan the element * for on* attributes and register appropriate listeners for those handlers. */ -void js_handle_new_element(jscontext *ctx, struct dom_element *node); +void js_handle_new_element(jsthread *thread, struct dom_element *node); -/** Handle an event propagation finished callback. +/** + * Handle an event propagation finished callback. * * This is called once an event finishes propagating, no matter how it * finishes. The intent here is that the JS context can perform any cleanups * it may need to perform before the DOM finishes and the event may end up * freed. */ -void js_event_cleanup(jscontext *ctx, struct dom_event *evt); +void js_event_cleanup(jsthread *thread, struct dom_event *evt); -#endif /* _NETSURF_JAVASCRIPT_JS_H_ */ +#endif /* NETSURF_JAVASCRIPT_JS_H_ */ |