1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/js/jsd/jsdebug.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,1524 @@
1.4 +/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
1.5 + * vim: set ts=8 sts=4 et sw=4 tw=99:
1.6 + * This Source Code Form is subject to the terms of the Mozilla Public
1.7 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.8 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.9 +
1.10 +/*
1.11 + * Header for JavaScript Debugging support - All public functions
1.12 + */
1.13 +
1.14 +#ifndef jsdebug_h___
1.15 +#define jsdebug_h___
1.16 +
1.17 +#include "jstypes.h"
1.18 +#include "js/TypeDecls.h"
1.19 +
1.20 +extern "C" {
1.21 +
1.22 +/*
1.23 + * The linkage of JSD API functions differs depending on whether the file is
1.24 + * used within the JSD library or not. Any source file within the JSD
1.25 + * libraray should define EXPORT_JSD_API whereas any client of the library
1.26 + * should not.
1.27 + */
1.28 +#ifdef EXPORT_JSD_API
1.29 +#define JSD_PUBLIC_API(t) JS_EXPORT_API(t)
1.30 +#define JSD_PUBLIC_DATA(t) JS_EXPORT_DATA(t)
1.31 +#else
1.32 +#define JSD_PUBLIC_API(t) JS_IMPORT_API(t)
1.33 +#define JSD_PUBLIC_DATA(t) JS_IMPORT_DATA(t)
1.34 +#endif
1.35 +
1.36 +#define JSD_FRIEND_API(t) JSD_PUBLIC_API(t)
1.37 +#define JSD_FRIEND_DATA(t) JSD_PUBLIC_DATA(t)
1.38 +
1.39 +/***************************************************************************/
1.40 +/* Opaque typedefs for handles */
1.41 +
1.42 +typedef struct JSDContext JSDContext;
1.43 +typedef struct JSDScript JSDScript;
1.44 +typedef struct JSDSourceText JSDSourceText;
1.45 +typedef struct JSDThreadState JSDThreadState;
1.46 +typedef struct JSDStackFrameInfo JSDStackFrameInfo;
1.47 +typedef struct JSDValue JSDValue;
1.48 +typedef struct JSDProperty JSDProperty;
1.49 +typedef struct JSDObject JSDObject;
1.50 +
1.51 +/***************************************************************************/
1.52 +/* High Level calls */
1.53 +
1.54 +/*
1.55 +* callback stuff for calls in EXE to be accessed by this code
1.56 +* when it lives in an explicitly loaded DLL
1.57 +*/
1.58 +
1.59 +/*
1.60 +* This callback allows JSD to inform the embedding when JSD has been
1.61 +* turned on or off. This is especially useful in the Java-based debugging
1.62 +* system used in mozilla because the debugger applet controls starting
1.63 +* up the JSD system.
1.64 +*/
1.65 +typedef void
1.66 +(* JSD_SetContextProc)(JSDContext* jsdc, void* user);
1.67 +
1.68 +/* This struct could have more fields in future versions */
1.69 +typedef struct
1.70 +{
1.71 + unsigned size; /* size of this struct (init before use)*/
1.72 + JSD_SetContextProc setContext;
1.73 +} JSD_UserCallbacks;
1.74 +
1.75 +/*
1.76 +* Used by an embedding to tell JSD what JSRuntime to use and to set
1.77 +* callbacks without starting up JSD. This assumes only one JSRuntime
1.78 +* will be used. This exists to support the mozilla Java-based debugger
1.79 +* system.
1.80 +*/
1.81 +extern JSD_PUBLIC_API(void)
1.82 +JSD_SetUserCallbacks(JSRuntime* jsrt,
1.83 + JSD_UserCallbacks* callbacks,
1.84 + void* user);
1.85 +
1.86 +/*
1.87 +* Startup JSD.
1.88 +* This version of the init function requires that JSD_SetUserCallbacks()
1.89 +* has been previously called (with a non-nullptr callback struct pointer)
1.90 +*/
1.91 +extern JSD_PUBLIC_API(JSDContext*)
1.92 +JSD_DebuggerOn(void);
1.93 +
1.94 +/*
1.95 +* Startup JSD on a particular JSRuntime with (optional) callbacks
1.96 +*/
1.97 +extern JSD_PUBLIC_API(JSDContext*)
1.98 +JSD_DebuggerOnForUser(JSRuntime* jsrt,
1.99 + JSD_UserCallbacks* callbacks,
1.100 + void* user);
1.101 +
1.102 +/*
1.103 + * Startup JSD in an application that uses compartments. Debugger
1.104 + * objects will be allocated in the same compartment as scopeobj.
1.105 + */
1.106 +extern JSD_PUBLIC_API(JSDContext*)
1.107 +JSD_DebuggerOnForUserWithCompartment(JSRuntime* jsrt,
1.108 + JSD_UserCallbacks* callbacks,
1.109 + void* user,
1.110 + JSObject* scopeobj);
1.111 +
1.112 +/*
1.113 +* Shutdown JSD for this JSDContext
1.114 +*/
1.115 +extern JSD_PUBLIC_API(void)
1.116 +JSD_DebuggerOff(JSDContext* jsdc);
1.117 +
1.118 +/*
1.119 + * Pause JSD for this JSDContext
1.120 + */
1.121 +extern JSD_PUBLIC_API(void)
1.122 +JSD_DebuggerPause(JSDContext* jsdc);
1.123 +
1.124 +/*
1.125 + * Unpause JSD for this JSDContext
1.126 + */
1.127 +extern JSD_PUBLIC_API(void)
1.128 +JSD_DebuggerUnpause(JSDContext* jsdc);
1.129 +
1.130 +/*
1.131 +* Get the Major Version (initial JSD release used major version = 1)
1.132 +*/
1.133 +extern JSD_PUBLIC_API(unsigned)
1.134 +JSD_GetMajorVersion(void);
1.135 +
1.136 +/*
1.137 +* Get the Minor Version (initial JSD release used minor version = 0)
1.138 +*/
1.139 +extern JSD_PUBLIC_API(unsigned)
1.140 +JSD_GetMinorVersion(void);
1.141 +
1.142 +/*
1.143 +* Returns the default JSD global associated with a given JSDContext.
1.144 +*/
1.145 +extern JSD_PUBLIC_API(JSObject*)
1.146 +JSD_GetDefaultGlobal(JSDContext* jsdc);
1.147 +
1.148 +/*
1.149 +* Returns a JSRuntime this context is associated with
1.150 +*/
1.151 +extern JSD_PUBLIC_API(JSRuntime*)
1.152 +JSD_GetJSRuntime(JSDContext* jsdc);
1.153 +
1.154 +/*
1.155 +* Set the private data for this context, returns previous value
1.156 +*/
1.157 +extern JSD_PUBLIC_API(void *)
1.158 +JSD_SetContextPrivate(JSDContext *jsdc, void *data);
1.159 +
1.160 +/*
1.161 +* Get the private data for this context
1.162 +*/
1.163 +extern JSD_PUBLIC_API(void *)
1.164 +JSD_GetContextPrivate(JSDContext *jsdc);
1.165 +
1.166 +/*
1.167 +* Clear profile data for all scripts
1.168 +*/
1.169 +extern JSD_PUBLIC_API(void)
1.170 +JSD_ClearAllProfileData(JSDContext* jsdc);
1.171 +
1.172 +/*
1.173 +* Context flags.
1.174 +*/
1.175 +
1.176 +/* Include native frames in JSDThreadStates. */
1.177 +#define JSD_INCLUDE_NATIVE_FRAMES 0x01
1.178 +/*
1.179 +* Normally, if a script has a 0 in JSD_SCRIPT_PROFILE_BIT it is included in
1.180 +* profile data, otherwise it is not profiled. Setting the JSD_PROFILE_WHEN_SET
1.181 +* flag reverses this convention.
1.182 +*/
1.183 +#define JSD_PROFILE_WHEN_SET 0x02
1.184 +/*
1.185 +* Normally, when the script in the top frame of a thread state has a 1 in
1.186 +* JSD_SCRIPT_DEBUG_BIT, the execution hook is ignored. Setting the
1.187 +* JSD_DEBUG_WHEN_SET flag reverses this convention.
1.188 +*/
1.189 +#define JSD_DEBUG_WHEN_SET 0x04
1.190 +/*
1.191 +* When this flag is set the internal call hook will collect profile data.
1.192 +*/
1.193 +#define JSD_COLLECT_PROFILE_DATA 0x08
1.194 +/*
1.195 +* When this flag is set, stack frames that are disabled for debugging
1.196 +* will not appear in the call stack chain.
1.197 +*/
1.198 +#define JSD_HIDE_DISABLED_FRAMES 0x10
1.199 +/*
1.200 +* When this flag is set, the debugger will only check the
1.201 +* JSD_SCRIPT_DEBUG_BIT on the top (most recent) stack frame. This
1.202 +* makes it possible to stop in an enabled frame which was called from
1.203 +* a stack that contains a disabled frame.
1.204 +*
1.205 +* When this flag is *not* set, any stack that contains a disabled frame
1.206 +* will not be debugged (the execution hook will not be invoked.)
1.207 +*
1.208 +* This only applies when the reason for calling the hook would have
1.209 +* been JSD_HOOK_INTERRUPTED or JSD_HOOK_THROW. JSD_HOOK_BREAKPOINT,
1.210 +* JSD_HOOK_DEBUG_REQUESTED, and JSD_HOOK_DEBUGGER_KEYWORD always stop,
1.211 +* regardless of this setting, as long as the top frame is not disabled.
1.212 +*
1.213 +* If JSD_HIDE_DISABLED_FRAMES is set, this is effectively set as well.
1.214 +*/
1.215 +#define JSD_MASK_TOP_FRAME_ONLY 0x20
1.216 +
1.217 +/*
1.218 +* 0x40 was formerly used to hook into object creation.
1.219 +*/
1.220 +#define JSD_DISABLE_OBJECT_TRACE_RETIRED 0x40
1.221 +
1.222 +
1.223 +extern JSD_PUBLIC_API(void)
1.224 +JSD_SetContextFlags (JSDContext* jsdc, uint32_t flags);
1.225 +
1.226 +extern JSD_PUBLIC_API(uint32_t)
1.227 +JSD_GetContextFlags (JSDContext* jsdc);
1.228 +
1.229 +/*
1.230 +* Notify JSD that this JSContext is 'in use'. This allows JSD to hook the
1.231 +* ErrorReporter. For the most part this is done automatically whenever
1.232 +* events like script loading happen. But, it is a good idea to call this
1.233 +* from the embedding when new contexts come into use.
1.234 +*/
1.235 +extern JSD_PUBLIC_API(void)
1.236 +JSD_JSContextInUse(JSDContext* jsdc, JSContext* context);
1.237 +
1.238 +/*
1.239 +* Find the JSDContext (if any) associated with the JSRuntime of a
1.240 +* given JSContext.
1.241 +*/
1.242 +extern JSD_PUBLIC_API(JSDContext*)
1.243 +JSD_JSDContextForJSContext(JSContext* context);
1.244 +
1.245 +/***************************************************************************/
1.246 +/* Script functions */
1.247 +
1.248 +/*
1.249 +* Lock the entire script subsystem. This grabs a highlevel lock that
1.250 +* protects the JSD internal information about scripts. It is important
1.251 +* to wrap script related calls in this lock in multithreaded situations
1.252 +* -- i.e. where the debugger is running on a different thread than the
1.253 +* interpreter -- or when multiple debugger threads may be accessing this
1.254 +* subsystem. It is safe (and best) to use this locking even if the
1.255 +* environment might not be multi-threaded. Safely nestable.
1.256 +*/
1.257 +extern JSD_PUBLIC_API(void)
1.258 +JSD_LockScriptSubsystem(JSDContext* jsdc);
1.259 +
1.260 +/*
1.261 +* Unlock the entire script subsystem -- see JSD_LockScriptSubsystem
1.262 +*/
1.263 +extern JSD_PUBLIC_API(void)
1.264 +JSD_UnlockScriptSubsystem(JSDContext* jsdc);
1.265 +
1.266 +/*
1.267 +* Iterate through all the active scripts for this JSDContext.
1.268 +* NOTE: must initialize iterp to nullptr to start iteration.
1.269 +* NOTE: must lock and unlock the subsystem
1.270 +* example:
1.271 +*
1.272 +* JSDScript jsdscript;
1.273 +* JSDScript iter = nullptr;
1.274 +*
1.275 +* JSD_LockScriptSubsystem(jsdc);
1.276 +* while((jsdscript = JSD_IterateScripts(jsdc, &iter)) != nullptr) {
1.277 +* *** use jsdscript here ***
1.278 +* }
1.279 +* JSD_UnlockScriptSubsystem(jsdc);
1.280 +*/
1.281 +extern JSD_PUBLIC_API(JSDScript*)
1.282 +JSD_IterateScripts(JSDContext* jsdc, JSDScript **iterp);
1.283 +
1.284 +/*
1.285 +* Get the number of times this script has been called.
1.286 +*/
1.287 +extern JSD_PUBLIC_API(unsigned)
1.288 +JSD_GetScriptCallCount(JSDContext* jsdc, JSDScript *script);
1.289 +
1.290 +/*
1.291 +* Get the max number of times this script called itself, directly or indirectly.
1.292 +*/
1.293 +extern JSD_PUBLIC_API(unsigned)
1.294 +JSD_GetScriptMaxRecurseDepth(JSDContext* jsdc, JSDScript *script);
1.295 +
1.296 +/*
1.297 +* Get the shortest execution time recorded.
1.298 +*/
1.299 +extern JSD_PUBLIC_API(double)
1.300 +JSD_GetScriptMinExecutionTime(JSDContext* jsdc, JSDScript *script);
1.301 +
1.302 +/*
1.303 +* Get the longest execution time recorded.
1.304 +*/
1.305 +extern JSD_PUBLIC_API(double)
1.306 +JSD_GetScriptMaxExecutionTime(JSDContext* jsdc, JSDScript *script);
1.307 +
1.308 +/*
1.309 +* Get the total amount of time spent in this script.
1.310 +*/
1.311 +extern JSD_PUBLIC_API(double)
1.312 +JSD_GetScriptTotalExecutionTime(JSDContext* jsdc, JSDScript *script);
1.313 +
1.314 +/*
1.315 +* Get the shortest execution time recorded, excluding time spent in called
1.316 +* functions.
1.317 +*/
1.318 +extern JSD_PUBLIC_API(double)
1.319 +JSD_GetScriptMinOwnExecutionTime(JSDContext* jsdc, JSDScript *script);
1.320 +
1.321 +/*
1.322 +* Get the longest execution time recorded, excluding time spent in called
1.323 +* functions.
1.324 +*/
1.325 +extern JSD_PUBLIC_API(double)
1.326 +JSD_GetScriptMaxOwnExecutionTime(JSDContext* jsdc, JSDScript *script);
1.327 +
1.328 +/*
1.329 +* Get the total amount of time spent in this script, excluding time spent
1.330 +* in called functions.
1.331 +*/
1.332 +extern JSD_PUBLIC_API(double)
1.333 +JSD_GetScriptTotalOwnExecutionTime(JSDContext* jsdc, JSDScript *script);
1.334 +
1.335 +/*
1.336 +* Clear profile data for this script.
1.337 +*/
1.338 +extern JSD_PUBLIC_API(void)
1.339 +JSD_ClearScriptProfileData(JSDContext* jsdc, JSDScript *script);
1.340 +
1.341 +/*
1.342 +* Get the JSScript for a JSDScript
1.343 +*/
1.344 +extern JSD_PUBLIC_API(JSScript*)
1.345 +JSD_GetJSScript(JSDContext* jsdc, JSDScript *script);
1.346 +
1.347 +/*
1.348 +* Get the JSFunction for a JSDScript
1.349 +*/
1.350 +extern JSD_PUBLIC_API(JSFunction*)
1.351 +JSD_GetJSFunction(JSDContext* jsdc, JSDScript *script);
1.352 +
1.353 +/*
1.354 +* Determines whether or not to collect profile information for this
1.355 +* script. The context flag JSD_PROFILE_WHEN_SET decides the logic.
1.356 +*/
1.357 +#define JSD_SCRIPT_PROFILE_BIT 0x01
1.358 +/*
1.359 +* Determines whether or not to ignore breakpoints, etc. in this script.
1.360 +* The context flag JSD_DEBUG_WHEN_SET decides the logic.
1.361 +*/
1.362 +#define JSD_SCRIPT_DEBUG_BIT 0x02
1.363 +/*
1.364 + * Determines whether to invoke the onScriptDestroy callback for this
1.365 + * script. The default is for this to be true if the onScriptCreated
1.366 + * callback was invoked for this script.
1.367 + */
1.368 +#define JSD_SCRIPT_CALL_DESTROY_HOOK_BIT 0x04
1.369 +
1.370 +extern JSD_PUBLIC_API(uint32_t)
1.371 +JSD_GetScriptFlags(JSDContext *jsdc, JSDScript* jsdscript);
1.372 +
1.373 +extern JSD_PUBLIC_API(void)
1.374 +JSD_SetScriptFlags(JSDContext *jsdc, JSDScript* jsdscript, uint32_t flags);
1.375 +
1.376 +/*
1.377 +* Set the private data for this script, returns previous value
1.378 +*/
1.379 +extern JSD_PUBLIC_API(void *)
1.380 +JSD_SetScriptPrivate(JSDScript* jsdscript, void *data);
1.381 +
1.382 +/*
1.383 +* Get the private data for this script
1.384 +*/
1.385 +extern JSD_PUBLIC_API(void *)
1.386 +JSD_GetScriptPrivate(JSDScript* jsdscript);
1.387 +
1.388 +/*
1.389 +* Determine if this script is still loaded in the interpreter
1.390 +*/
1.391 +extern JSD_PUBLIC_API(bool)
1.392 +JSD_IsActiveScript(JSDContext* jsdc, JSDScript *jsdscript);
1.393 +
1.394 +/*
1.395 +* Get the filename associated with this script
1.396 +*/
1.397 +extern JSD_PUBLIC_API(const char*)
1.398 +JSD_GetScriptFilename(JSDContext* jsdc, JSDScript *jsdscript);
1.399 +
1.400 +/*
1.401 +* Get the function name associated with this script (nullptr if not a
1.402 +* function). If the function does not have a name the result is the
1.403 +* string "anonymous".
1.404 +* *** new for gecko 2.0 ****
1.405 +*/
1.406 +extern JSD_PUBLIC_API(JSString *)
1.407 +JSD_GetScriptFunctionId(JSDContext* jsdc, JSDScript *jsdscript);
1.408 +
1.409 +/*
1.410 +* Get the base linenumber of the sourcefile from which this script was loaded.
1.411 +* This is one-based -- i.e. the first line of a file is line '1'. This may
1.412 +* return 0 if this infomation is unknown.
1.413 +*/
1.414 +extern JSD_PUBLIC_API(unsigned)
1.415 +JSD_GetScriptBaseLineNumber(JSDContext* jsdc, JSDScript *jsdscript);
1.416 +
1.417 +/*
1.418 +* Get the count of source lines associated with this script (1 or greater)
1.419 +*/
1.420 +extern JSD_PUBLIC_API(unsigned)
1.421 +JSD_GetScriptLineExtent(JSDContext* jsdc, JSDScript *jsdscript);
1.422 +
1.423 +/*
1.424 +* Declaration of callback for notification of script creation and destruction.
1.425 +* 'creating' is true if creating new script, false if destroying existing
1.426 +* script (callback called just before actual destruction).
1.427 +* 'callerdata' is what was passed to JSD_SetScriptHook to set the hook.
1.428 +*/
1.429 +typedef void
1.430 +(* JSD_ScriptHookProc)(JSDContext* jsdc,
1.431 + JSDScript* jsdscript,
1.432 + bool creating,
1.433 + void* callerdata);
1.434 +
1.435 +/*
1.436 +* Set a hook to be called when scripts are created or destroyed (loaded or
1.437 +* unloaded).
1.438 +* 'callerdata' can be whatever you want it to be.
1.439 +*/
1.440 +extern JSD_PUBLIC_API(bool)
1.441 +JSD_SetScriptHook(JSDContext* jsdc, JSD_ScriptHookProc hook, void* callerdata);
1.442 +
1.443 +/*
1.444 +* Get the current script hook.
1.445 +*/
1.446 +extern JSD_PUBLIC_API(bool)
1.447 +JSD_GetScriptHook(JSDContext* jsdc, JSD_ScriptHookProc* hook, void** callerdata);
1.448 +
1.449 +/*
1.450 +* Get a 'Program Counter' value for a given line. This represents the location
1.451 +* of the first bit of executable code for this line of source. This 'pc' should
1.452 +* be considered an opaque handle.
1.453 +* 0 is returned for invalid scripts, or lines that lie outside the script.
1.454 +* If no code is on the given line, then the returned pc represents the first
1.455 +* code within the script (if any) after the given line.
1.456 +* This function can be used to set breakpoints -- see JSD_SetExecutionHook
1.457 +*/
1.458 +extern JSD_PUBLIC_API(uintptr_t)
1.459 +JSD_GetClosestPC(JSDContext* jsdc, JSDScript* jsdscript, unsigned line);
1.460 +
1.461 +/*
1.462 +* Get the source line number for a given 'Program Counter' location.
1.463 +* Returns 0 if no source line information is appropriate (or available) for
1.464 +* the given pc.
1.465 +*/
1.466 +extern JSD_PUBLIC_API(unsigned)
1.467 +JSD_GetClosestLine(JSDContext* jsdc, JSDScript* jsdscript, uintptr_t pc);
1.468 +
1.469 +/*
1.470 + * Get a list of lines and the corresponding earliest PC for each (see
1.471 + * JSD_GetClosestPC). Lines with no PCs associated will not be returned.
1.472 + * nullptr may be passed for either lines or pcs to avoid filling anything in
1.473 + * for that argument.
1.474 + */
1.475 +extern JSD_PUBLIC_API(bool)
1.476 +JSD_GetLinePCs(JSDContext* jsdc, JSDScript* jsdscript,
1.477 + unsigned startLine, unsigned maxLines,
1.478 + unsigned* count, unsigned** lines, uintptr_t** pcs);
1.479 +
1.480 +/* these are only used in cases where scripts are created outside of JS*/
1.481 +
1.482 +/*
1.483 +* Direct call to notify JSD that a script has been created.
1.484 +* Embeddings that use the normal jsapi script functions need not call this.
1.485 +* Any embedding that follows the (discouraged!) practice of contructing script
1.486 +* structures manually should call this function to inform JSD. (older ssjs
1.487 +* systems do this).
1.488 +*/
1.489 +extern JSD_PUBLIC_API(void)
1.490 +JSD_ScriptCreated(JSDContext* jsdc,
1.491 + JSContext *cx,
1.492 + const char *filename, /* URL this script loads from */
1.493 + unsigned lineno, /* line where this script starts */
1.494 + JSScript *script,
1.495 + JSFunction *fun);
1.496 +
1.497 +/*
1.498 +* see JSD_ScriptCreated
1.499 +*/
1.500 +extern JSD_PUBLIC_API(void)
1.501 +JSD_ScriptDestroyed(JSDContext* jsdc,
1.502 + JSFreeOp *fop,
1.503 + JSScript *script);
1.504 +
1.505 +/***************************************************************************/
1.506 +/* Source Text functions */
1.507 +
1.508 +/*
1.509 +* In some embeddings (e.g. mozilla) JavaScript source code from a 'file' may be
1.510 +* execute before the entire 'file' has even been loaded. This system supports
1.511 +* access to such incrmentally loaded source. It also allows for the possibility
1.512 +* that source loading may fail or be aborted (though the source that did load
1.513 +* may still be usable). Remember that this source is the entire 'file'
1.514 +* contents and that the JavaScript code may only be part of that source.
1.515 +*
1.516 +* For any given URL there can only be one source text item (the most recently
1.517 +* loaded).
1.518 +*/
1.519 +
1.520 +/* these coorespond to netscape.jsdebug.SourceTextItem.java values -
1.521 +* change in both places if anywhere
1.522 +*/
1.523 +
1.524 +typedef enum
1.525 +{
1.526 + JSD_SOURCE_INITED = 0, /* initialized, but contains no source yet */
1.527 + JSD_SOURCE_PARTIAL = 1, /* some source loaded, more expected */
1.528 + JSD_SOURCE_COMPLETED = 2, /* all source finished loading */
1.529 + JSD_SOURCE_ABORTED = 3, /* user aborted loading, some may be loaded */
1.530 + JSD_SOURCE_FAILED = 4, /* loading failed, some may be loaded */
1.531 + JSD_SOURCE_CLEARED = 5 /* text has been cleared by debugger */
1.532 +} JSDSourceStatus;
1.533 +
1.534 +/*
1.535 +* Lock the entire source text subsystem. This grabs a highlevel lock that
1.536 +* protects the JSD internal information about sources. It is important to
1.537 +* wrap source text related calls in this lock in multithreaded situations
1.538 +* -- i.e. where the debugger is running on a different thread than the
1.539 +* interpreter (or the loader of sources) -- or when multiple debugger
1.540 +* threads may be accessing this subsystem. It is safe (and best) to use
1.541 +* this locking even if the environment might not be multi-threaded.
1.542 +* Safely Nestable.
1.543 +*/
1.544 +extern JSD_PUBLIC_API(void)
1.545 +JSD_LockSourceTextSubsystem(JSDContext* jsdc);
1.546 +
1.547 +/*
1.548 +* Unlock the entire source text subsystem. see JSD_LockSourceTextSubsystem.
1.549 +*/
1.550 +extern JSD_PUBLIC_API(void)
1.551 +JSD_UnlockSourceTextSubsystem(JSDContext* jsdc);
1.552 +
1.553 +/*
1.554 +* Iterate the source test items. Use the same pattern of calls shown in
1.555 +* the example for JSD_IterateScripts - NOTE that the SourceTextSubsystem.
1.556 +* must be locked before and unlocked after iterating.
1.557 +*/
1.558 +extern JSD_PUBLIC_API(JSDSourceText*)
1.559 +JSD_IterateSources(JSDContext* jsdc, JSDSourceText **iterp);
1.560 +
1.561 +/*
1.562 +* Find the source text item for the given URL (or filename - or whatever
1.563 +* string the given embedding uses to describe source locations).
1.564 +* Returns nullptr if not found.
1.565 +*/
1.566 +extern JSD_PUBLIC_API(JSDSourceText*)
1.567 +JSD_FindSourceForURL(JSDContext* jsdc, const char* url);
1.568 +
1.569 +/*
1.570 +* Get the URL string associated with the given source text item
1.571 +*/
1.572 +extern JSD_PUBLIC_API(const char*)
1.573 +JSD_GetSourceURL(JSDContext* jsdc, JSDSourceText* jsdsrc);
1.574 +
1.575 +/*
1.576 +* Get the actual source text. This gives access to the actual storage of
1.577 +* the source - it sHould *not* be written to.
1.578 +* The buffer is NOT zero terminated (nor is it guaranteed to have space to
1.579 +* hold a zero terminating char).
1.580 +* XXX this is 8-bit character data. Unicode source is not yet supported.
1.581 +*/
1.582 +extern JSD_PUBLIC_API(bool)
1.583 +JSD_GetSourceText(JSDContext* jsdc, JSDSourceText* jsdsrc,
1.584 + const char** ppBuf, int* pLen);
1.585 +
1.586 +/*
1.587 +* Clear the text -- delete the text and set the status to JSD_SOURCE_CLEARED.
1.588 +* This is useful if source is done loading and the debugger wishes to store
1.589 +* the text data itself (e.g. in a Java String). This allows avoidance of
1.590 +* storing the same text in multiple places.
1.591 +*/
1.592 +extern JSD_PUBLIC_API(void)
1.593 +JSD_ClearSourceText(JSDContext* jsdc, JSDSourceText* jsdsrc);
1.594 +
1.595 +/*
1.596 +* Return the status of the source text item. see JSDSourceStatus enum.
1.597 +*/
1.598 +extern JSD_PUBLIC_API(JSDSourceStatus)
1.599 +JSD_GetSourceStatus(JSDContext* jsdc, JSDSourceText* jsdsrc);
1.600 +
1.601 +/*
1.602 +* Has the source been altered since the last call to JSD_SetSourceDirty?
1.603 +* Use of JSD_IsSourceDirty and JSD_SetSourceDirty is still supported, but
1.604 +* discouraged in favor of the JSD_GetSourceAlterCount system. This dirty
1.605 +* scheme ASSUMES that there is only one consumer of the data.
1.606 +*/
1.607 +extern JSD_PUBLIC_API(bool)
1.608 +JSD_IsSourceDirty(JSDContext* jsdc, JSDSourceText* jsdsrc);
1.609 +
1.610 +/*
1.611 +* Clear the dirty flag
1.612 +*/
1.613 +extern JSD_PUBLIC_API(void)
1.614 +JSD_SetSourceDirty(JSDContext* jsdc, JSDSourceText* jsdsrc, bool dirty);
1.615 +
1.616 +/*
1.617 +* Each time a source text item is altered this value is incremented. Any
1.618 +* consumer can store this value when they retieve other data about the
1.619 +* source text item and then check later to see if the current value is
1.620 +* different from their stored value. Thus they can know if they have stale
1.621 +* data or not. NOTE: this value is not gauranteed to start at any given number.
1.622 +*/
1.623 +extern JSD_PUBLIC_API(unsigned)
1.624 +JSD_GetSourceAlterCount(JSDContext* jsdc, JSDSourceText* jsdsrc);
1.625 +
1.626 +/*
1.627 +* Force an increment in the alter count for a source text item. This is
1.628 +* normally automatic when the item changes, but a give consumer may want to
1.629 +* force this to amke an item appear to have changed even if it has not.
1.630 +*/
1.631 +extern JSD_PUBLIC_API(unsigned)
1.632 +JSD_IncrementSourceAlterCount(JSDContext* jsdc, JSDSourceText* jsdsrc);
1.633 +
1.634 +/*
1.635 +* Destroy *all* the source text items
1.636 +* (new for server-side USE WITH CARE)
1.637 +*/
1.638 +extern JSD_PUBLIC_API(void)
1.639 +JSD_DestroyAllSources( JSDContext* jsdc );
1.640 +
1.641 +/* functions for adding source items */
1.642 +
1.643 +/*
1.644 +* Add a new item for a given URL. If an item already exists for the given URL
1.645 +* then the old item is removed.
1.646 +* 'url' may not be nullptr.
1.647 +*/
1.648 +extern JSD_PUBLIC_API(JSDSourceText*)
1.649 +JSD_NewSourceText(JSDContext* jsdc, const char* url);
1.650 +
1.651 +/*
1.652 +* Append text (or change status -- e.g. set completed) for a source text
1.653 +* item. Text need not be zero terminated. Callers should consider the returned
1.654 +* JSDSourceText to be the 'current' item for future use. This may return
1.655 +* nullptr if called after this item has been replaced by a call to
1.656 +* JSD_NewSourceText.
1.657 +*/
1.658 +extern JSD_PUBLIC_API(JSDSourceText*)
1.659 +JSD_AppendSourceText(JSDContext* jsdc,
1.660 + JSDSourceText* jsdsrc,
1.661 + const char* text, /* *not* zero terminated */
1.662 + size_t length,
1.663 + JSDSourceStatus status);
1.664 +
1.665 +/*
1.666 +* Unicode varient of JSD_AppendSourceText.
1.667 +*
1.668 +* NOTE: At this point text is stored in 8bit ASCII so this function just
1.669 +* extracts the bottom 8bits from each jschar. At some future point we may
1.670 +* switch to storing and exposing 16bit Unicode.
1.671 +*/
1.672 +extern JSD_PUBLIC_API(JSDSourceText*)
1.673 +JSD_AppendUCSourceText(JSDContext* jsdc,
1.674 + JSDSourceText* jsdsrc,
1.675 + const jschar* text, /* *not* zero terminated */
1.676 + size_t length,
1.677 + JSDSourceStatus status);
1.678 +/*
1.679 + * Convienence function for adding complete source of url in one call.
1.680 + * same as:
1.681 + * JSDSourceText* jsdsrc;
1.682 + * JSD_LOCK_SOURCE_TEXT(jsdc);
1.683 + * jsdsrc = jsd_NewSourceText(jsdc, url);
1.684 + * if(jsdsrc)
1.685 + * jsdsrc = jsd_AppendSourceText(jsdc, jsdsrc,
1.686 + * text, length, JSD_SOURCE_PARTIAL);
1.687 + * if(jsdsrc)
1.688 + * jsdsrc = jsd_AppendSourceText(jsdc, jsdsrc,
1.689 + * nullptr, 0, JSD_SOURCE_COMPLETED);
1.690 + * JSD_UNLOCK_SOURCE_TEXT(jsdc);
1.691 + * return jsdsrc ? true : false;
1.692 + */
1.693 +extern JSD_PUBLIC_API(bool)
1.694 +JSD_AddFullSourceText(JSDContext* jsdc,
1.695 + const char* text, /* *not* zero terminated */
1.696 + size_t length,
1.697 + const char* url);
1.698 +
1.699 +/***************************************************************************/
1.700 +/* Execution/Interrupt Hook functions */
1.701 +
1.702 +/* possible 'type' params for JSD_ExecutionHookProc */
1.703 +#define JSD_HOOK_INTERRUPTED 0
1.704 +#define JSD_HOOK_BREAKPOINT 1
1.705 +#define JSD_HOOK_DEBUG_REQUESTED 2
1.706 +#define JSD_HOOK_DEBUGGER_KEYWORD 3
1.707 +#define JSD_HOOK_THROW 4
1.708 +
1.709 +/* legal return values for JSD_ExecutionHookProc */
1.710 +#define JSD_HOOK_RETURN_HOOK_ERROR 0
1.711 +#define JSD_HOOK_RETURN_CONTINUE 1
1.712 +#define JSD_HOOK_RETURN_ABORT 2
1.713 +#define JSD_HOOK_RETURN_RET_WITH_VAL 3
1.714 +#define JSD_HOOK_RETURN_THROW_WITH_VAL 4
1.715 +#define JSD_HOOK_RETURN_CONTINUE_THROW 5
1.716 +
1.717 +/*
1.718 +* Implement a callback of this form in order to hook execution.
1.719 +*/
1.720 +typedef unsigned
1.721 +(* JSD_ExecutionHookProc)(JSDContext* jsdc,
1.722 + JSDThreadState* jsdthreadstate,
1.723 + unsigned type,
1.724 + void* callerdata,
1.725 + JS::Value* rval);
1.726 +
1.727 +/* possible 'type' params for JSD_CallHookProc */
1.728 +#define JSD_HOOK_TOPLEVEL_START 0 /* about to evaluate top level script */
1.729 +#define JSD_HOOK_TOPLEVEL_END 1 /* done evaluting top level script */
1.730 +#define JSD_HOOK_FUNCTION_CALL 2 /* about to call a function */
1.731 +#define JSD_HOOK_FUNCTION_RETURN 3 /* done calling function */
1.732 +
1.733 +/*
1.734 +* Implement a callback of this form in order to hook function call/returns.
1.735 +* Return true from a TOPLEVEL_START or FUNCTION_CALL type call hook if you
1.736 +* want to hear about the TOPLEVEL_END or FUNCTION_RETURN too. Return value is
1.737 +* ignored to TOPLEVEL_END and FUNCTION_RETURN type hooks.
1.738 +*/
1.739 +typedef bool
1.740 +(* JSD_CallHookProc)(JSDContext* jsdc,
1.741 + JSDThreadState* jsdthreadstate,
1.742 + unsigned type,
1.743 + void* callerdata);
1.744 +
1.745 +/*
1.746 +* Set Hook to be called whenever the given pc is about to be executed --
1.747 +* i.e. for 'trap' or 'breakpoint'
1.748 +*/
1.749 +extern JSD_PUBLIC_API(bool)
1.750 +JSD_SetExecutionHook(JSDContext* jsdc,
1.751 + JSDScript* jsdscript,
1.752 + uintptr_t pc,
1.753 + JSD_ExecutionHookProc hook,
1.754 + void* callerdata);
1.755 +
1.756 +/*
1.757 +* Clear the hook for this pc
1.758 +*/
1.759 +extern JSD_PUBLIC_API(bool)
1.760 +JSD_ClearExecutionHook(JSDContext* jsdc,
1.761 + JSDScript* jsdscript,
1.762 + uintptr_t pc);
1.763 +
1.764 +/*
1.765 +* Clear all the pc specific hooks for this script
1.766 +*/
1.767 +extern JSD_PUBLIC_API(bool)
1.768 +JSD_ClearAllExecutionHooksForScript(JSDContext* jsdc, JSDScript* jsdscript);
1.769 +
1.770 +/*
1.771 +* Clear all the pc specific hooks for the entire JSRuntime associated with
1.772 +* this JSDContext
1.773 +*/
1.774 +extern JSD_PUBLIC_API(bool)
1.775 +JSD_ClearAllExecutionHooks(JSDContext* jsdc);
1.776 +
1.777 +/*
1.778 +* Set a hook to be called before the next instruction is executed. Depending
1.779 +* on the threading situation and whether or not an JS code is currently
1.780 +* executing the hook might be called before this call returns, or at some
1.781 +* future time. The hook will continue to be called as each instruction
1.782 +* executes until cleared.
1.783 +*/
1.784 +extern JSD_PUBLIC_API(bool)
1.785 +JSD_SetInterruptHook(JSDContext* jsdc,
1.786 + JSD_ExecutionHookProc hook,
1.787 + void* callerdata);
1.788 +
1.789 +/*
1.790 +* Call the interrupt hook at least once per source line
1.791 +*/
1.792 +extern JSD_PUBLIC_API(bool)
1.793 +JSD_EnableSingleStepInterrupts(JSDContext* jsdc, JSDScript *jsdscript, bool enable);
1.794 +
1.795 +/*
1.796 +* Clear the current interrupt hook.
1.797 +*/
1.798 +extern JSD_PUBLIC_API(bool)
1.799 +JSD_ClearInterruptHook(JSDContext* jsdc);
1.800 +
1.801 +/*
1.802 +* Set the hook that should be called whenever a JSD_ErrorReporter hook
1.803 +* returns JSD_ERROR_REPORTER_DEBUG.
1.804 +*/
1.805 +extern JSD_PUBLIC_API(bool)
1.806 +JSD_SetDebugBreakHook(JSDContext* jsdc,
1.807 + JSD_ExecutionHookProc hook,
1.808 + void* callerdata);
1.809 +
1.810 +/*
1.811 +* Clear the debug break hook
1.812 +*/
1.813 +extern JSD_PUBLIC_API(bool)
1.814 +JSD_ClearDebugBreakHook(JSDContext* jsdc);
1.815 +
1.816 +/*
1.817 +* Set the hook that should be called when the 'debugger' keyword is
1.818 +* encountered by the JavaScript interpreter during execution.
1.819 +*/
1.820 +extern JSD_PUBLIC_API(bool)
1.821 +JSD_SetDebuggerHook(JSDContext* jsdc,
1.822 + JSD_ExecutionHookProc hook,
1.823 + void* callerdata);
1.824 +
1.825 +/*
1.826 +* Clear the 'debugger' keyword hook
1.827 +*/
1.828 +extern JSD_PUBLIC_API(bool)
1.829 +JSD_ClearDebuggerHook(JSDContext* jsdc);
1.830 +
1.831 +/*
1.832 +* Set the hook that should be called when a JS exception is thrown.
1.833 +* NOTE: the 'do default' return value is: JSD_HOOK_RETURN_CONTINUE_THROW
1.834 +*/
1.835 +extern JSD_PUBLIC_API(bool)
1.836 +JSD_SetThrowHook(JSDContext* jsdc,
1.837 + JSD_ExecutionHookProc hook,
1.838 + void* callerdata);
1.839 +/*
1.840 +* Clear the throw hook
1.841 +*/
1.842 +extern JSD_PUBLIC_API(bool)
1.843 +JSD_ClearThrowHook(JSDContext* jsdc);
1.844 +
1.845 +/*
1.846 +* Set the hook that should be called when a toplevel script begins or completes.
1.847 +*/
1.848 +extern JSD_PUBLIC_API(bool)
1.849 +JSD_SetTopLevelHook(JSDContext* jsdc,
1.850 + JSD_CallHookProc hook,
1.851 + void* callerdata);
1.852 +/*
1.853 +* Clear the toplevel call hook
1.854 +*/
1.855 +extern JSD_PUBLIC_API(bool)
1.856 +JSD_ClearTopLevelHook(JSDContext* jsdc);
1.857 +
1.858 +/*
1.859 +* Set the hook that should be called when a function call or return happens.
1.860 +*/
1.861 +extern JSD_PUBLIC_API(bool)
1.862 +JSD_SetFunctionHook(JSDContext* jsdc,
1.863 + JSD_CallHookProc hook,
1.864 + void* callerdata);
1.865 +/*
1.866 +* Clear the function call hook
1.867 +*/
1.868 +extern JSD_PUBLIC_API(bool)
1.869 +JSD_ClearFunctionHook(JSDContext* jsdc);
1.870 +
1.871 +/***************************************************************************/
1.872 +/* Stack Frame functions */
1.873 +
1.874 +/*
1.875 +* Get the count of call stack frames for the given JSDThreadState
1.876 +*/
1.877 +extern JSD_PUBLIC_API(unsigned)
1.878 +JSD_GetCountOfStackFrames(JSDContext* jsdc, JSDThreadState* jsdthreadstate);
1.879 +
1.880 +/*
1.881 +* Get the 'current' call stack frame for the given JSDThreadState
1.882 +*/
1.883 +extern JSD_PUBLIC_API(JSDStackFrameInfo*)
1.884 +JSD_GetStackFrame(JSDContext* jsdc, JSDThreadState* jsdthreadstate);
1.885 +
1.886 +/*
1.887 +* Get the JSContext for the given JSDThreadState
1.888 +*/
1.889 +extern JSD_PUBLIC_API(JSContext*)
1.890 +JSD_GetJSContext(JSDContext* jsdc, JSDThreadState* jsdthreadstate);
1.891 +
1.892 +/*
1.893 +* Get the calling call stack frame for the given frame
1.894 +*/
1.895 +extern JSD_PUBLIC_API(JSDStackFrameInfo*)
1.896 +JSD_GetCallingStackFrame(JSDContext* jsdc,
1.897 + JSDThreadState* jsdthreadstate,
1.898 + JSDStackFrameInfo* jsdframe);
1.899 +
1.900 +/*
1.901 +* Get the script for the given call stack frame
1.902 +*/
1.903 +extern JSD_PUBLIC_API(JSDScript*)
1.904 +JSD_GetScriptForStackFrame(JSDContext* jsdc,
1.905 + JSDThreadState* jsdthreadstate,
1.906 + JSDStackFrameInfo* jsdframe);
1.907 +
1.908 +/*
1.909 +* Get the 'Program Counter' for the given call stack frame
1.910 +*/
1.911 +extern JSD_PUBLIC_API(uintptr_t)
1.912 +JSD_GetPCForStackFrame(JSDContext* jsdc,
1.913 + JSDThreadState* jsdthreadstate,
1.914 + JSDStackFrameInfo* jsdframe);
1.915 +
1.916 +/*
1.917 +* Get the JavaScript Call Object for the given call stack frame.
1.918 +* *** new for version 1.1 ****
1.919 +*/
1.920 +extern JSD_PUBLIC_API(JSDValue*)
1.921 +JSD_GetCallObjectForStackFrame(JSDContext* jsdc,
1.922 + JSDThreadState* jsdthreadstate,
1.923 + JSDStackFrameInfo* jsdframe);
1.924 +
1.925 +/*
1.926 +* Get the head of the scope chain for the given call stack frame.
1.927 +* the chain can be traversed using JSD_GetValueParent.
1.928 +* *** new for version 1.1 ****
1.929 +*/
1.930 +extern JSD_PUBLIC_API(JSDValue*)
1.931 +JSD_GetScopeChainForStackFrame(JSDContext* jsdc,
1.932 + JSDThreadState* jsdthreadstate,
1.933 + JSDStackFrameInfo* jsdframe);
1.934 +
1.935 +/*
1.936 +* Get the 'this' Object for the given call stack frame.
1.937 +* *** new for version 1.1 ****
1.938 +*/
1.939 +extern JSD_PUBLIC_API(JSDValue*)
1.940 +JSD_GetThisForStackFrame(JSDContext* jsdc,
1.941 + JSDThreadState* jsdthreadstate,
1.942 + JSDStackFrameInfo* jsdframe);
1.943 +
1.944 +/*
1.945 +* Get the name of the function executing in this stack frame. Especially useful
1.946 +* for native frames (without script objects.)
1.947 +* *** new for gecko 2.0 ****
1.948 +*/
1.949 +extern JSD_PUBLIC_API(JSString *)
1.950 +JSD_GetIdForStackFrame(JSDContext* jsdc,
1.951 + JSDThreadState* jsdthreadstate,
1.952 + JSDStackFrameInfo* jsdframe);
1.953 +
1.954 +/*
1.955 +* True if stack frame represents a frame created as a result of a debugger
1.956 +* evaluation.
1.957 +*/
1.958 +extern JSD_PUBLIC_API(bool)
1.959 +JSD_IsStackFrameDebugger(JSDContext* jsdc,
1.960 + JSDThreadState* jsdthreadstate,
1.961 + JSDStackFrameInfo* jsdframe);
1.962 +
1.963 +/*
1.964 +* True if stack frame is constructing a new object.
1.965 +*/
1.966 +extern JSD_PUBLIC_API(bool)
1.967 +JSD_IsStackFrameConstructing(JSDContext* jsdc,
1.968 + JSDThreadState* jsdthreadstate,
1.969 + JSDStackFrameInfo* jsdframe);
1.970 +
1.971 +/*
1.972 +* Evaluate the given unicode source code in the context of the given stack frame.
1.973 +* returns true and puts result in rval on success, false on failure.
1.974 +* NOTE: The ErrorReporter hook might be called if this fails.
1.975 +*/
1.976 +extern JSD_PUBLIC_API(bool)
1.977 +JSD_EvaluateUCScriptInStackFrame(JSDContext* jsdc,
1.978 + JSDThreadState* jsdthreadstate,
1.979 + JSDStackFrameInfo* jsdframe,
1.980 + const jschar *bytes, unsigned length,
1.981 + const char *filename, unsigned lineno,
1.982 + JS::MutableHandleValue rval);
1.983 +
1.984 +/*
1.985 +* Same as above, but does not eat exceptions.
1.986 +*/
1.987 +extern JSD_PUBLIC_API(bool)
1.988 +JSD_AttemptUCScriptInStackFrame(JSDContext* jsdc,
1.989 + JSDThreadState* jsdthreadstate,
1.990 + JSDStackFrameInfo* jsdframe,
1.991 + const jschar *bytes, unsigned length,
1.992 + const char *filename, unsigned lineno,
1.993 + JS::MutableHandleValue rval);
1.994 +
1.995 +/* single byte character version of JSD_EvaluateUCScriptInStackFrame */
1.996 +extern JSD_PUBLIC_API(bool)
1.997 +JSD_EvaluateScriptInStackFrame(JSDContext* jsdc,
1.998 + JSDThreadState* jsdthreadstate,
1.999 + JSDStackFrameInfo* jsdframe,
1.1000 + const char *bytes, unsigned length,
1.1001 + const char *filename, unsigned lineno, JS::MutableHandleValue rval);
1.1002 +
1.1003 +/*
1.1004 +* Same as above, but does not eat exceptions.
1.1005 +*/
1.1006 +extern JSD_PUBLIC_API(bool)
1.1007 +JSD_AttemptScriptInStackFrame(JSDContext* jsdc,
1.1008 + JSDThreadState* jsdthreadstate,
1.1009 + JSDStackFrameInfo* jsdframe,
1.1010 + const char *bytes, unsigned length,
1.1011 + const char *filename, unsigned lineno, JS::MutableHandleValue rval);
1.1012 +
1.1013 +/*
1.1014 +* Convert the given JS::Value to a string
1.1015 +* NOTE: The ErrorReporter hook might be called if this fails.
1.1016 +*/
1.1017 +extern JSD_PUBLIC_API(JSString*)
1.1018 +JSD_ValToStringInStackFrame(JSDContext* jsdc,
1.1019 + JSDThreadState* jsdthreadstate,
1.1020 + JSDStackFrameInfo* jsdframe,
1.1021 + JS::Value val);
1.1022 +
1.1023 +/*
1.1024 +* Get the JSDValue currently being thrown as an exception (may be nullptr).
1.1025 +* NOTE: must eventually release by calling JSD_DropValue (if not nullptr)
1.1026 +* *** new for version 1.1 ****
1.1027 +*/
1.1028 +extern JSD_PUBLIC_API(JSDValue*)
1.1029 +JSD_GetException(JSDContext* jsdc, JSDThreadState* jsdthreadstate);
1.1030 +
1.1031 +/*
1.1032 +* Set the JSDValue currently being thrown as an exception.
1.1033 +* *** new for version 1.1 ****
1.1034 +*/
1.1035 +extern JSD_PUBLIC_API(bool)
1.1036 +JSD_SetException(JSDContext* jsdc, JSDThreadState* jsdthreadstate,
1.1037 + JSDValue* jsdval);
1.1038 +
1.1039 +/***************************************************************************/
1.1040 +/* Error Reporter functions */
1.1041 +
1.1042 +/*
1.1043 +* XXX The ErrorReporter Hook scheme is going to change soon to more
1.1044 +* Fully support exceptions.
1.1045 +*/
1.1046 +
1.1047 +/* legal return values for JSD_ErrorReporter */
1.1048 +#define JSD_ERROR_REPORTER_PASS_ALONG 0 /* pass along to regular reporter */
1.1049 +#define JSD_ERROR_REPORTER_RETURN 1 /* don't pass to error reporter */
1.1050 +#define JSD_ERROR_REPORTER_DEBUG 2 /* force call to DebugBreakHook */
1.1051 +#define JSD_ERROR_REPORTER_CLEAR_RETURN 3 /* clear exception and don't pass */
1.1052 +
1.1053 +/*
1.1054 +* Implement a callback of this form in order to hook the ErrorReporter
1.1055 +*/
1.1056 +typedef unsigned
1.1057 +(* JSD_ErrorReporter)(JSDContext* jsdc,
1.1058 + JSContext* cx,
1.1059 + const char* message,
1.1060 + JSErrorReport* report,
1.1061 + void* callerdata);
1.1062 +
1.1063 +/* Set ErrorReporter hook */
1.1064 +extern JSD_PUBLIC_API(bool)
1.1065 +JSD_SetErrorReporter(JSDContext* jsdc,
1.1066 + JSD_ErrorReporter reporter,
1.1067 + void* callerdata);
1.1068 +
1.1069 +/* Get Current ErrorReporter hook */
1.1070 +extern JSD_PUBLIC_API(bool)
1.1071 +JSD_GetErrorReporter(JSDContext* jsdc,
1.1072 + JSD_ErrorReporter* reporter,
1.1073 + void** callerdata);
1.1074 +
1.1075 +/***************************************************************************/
1.1076 +/* Generic locks that callers can use for their own purposes */
1.1077 +
1.1078 +struct JSDStaticLock;
1.1079 +
1.1080 +/*
1.1081 +* Is Locking and GetThread supported in this build?
1.1082 +*/
1.1083 +extern JSD_PUBLIC_API(bool)
1.1084 +JSD_IsLockingAndThreadIdSupported();
1.1085 +
1.1086 +/*
1.1087 +* Create a reentrant/nestable lock
1.1088 +*/
1.1089 +extern JSD_PUBLIC_API(JSDStaticLock*)
1.1090 +JSD_CreateLock();
1.1091 +
1.1092 +/*
1.1093 +* Aquire lock for this thread (or block until available). Increments a
1.1094 +* counter if this thread already owns the lock.
1.1095 +*/
1.1096 +extern JSD_PUBLIC_API(void)
1.1097 +JSD_Lock(JSDStaticLock* lock);
1.1098 +
1.1099 +/*
1.1100 +* Release lock for this thread (or decrement the counter if JSD_Lock
1.1101 +* was previous called more than once).
1.1102 +*/
1.1103 +extern JSD_PUBLIC_API(void)
1.1104 +JSD_Unlock(JSDStaticLock* lock);
1.1105 +
1.1106 +/*
1.1107 +* For debugging only if not (JS_THREADSAFE AND DEBUG) then returns true
1.1108 +* So JSD_IsLocked(lock) may not equal !JSD_IsUnlocked(lock)
1.1109 +*/
1.1110 +extern JSD_PUBLIC_API(bool)
1.1111 +JSD_IsLocked(JSDStaticLock* lock);
1.1112 +
1.1113 +/*
1.1114 +* See above...
1.1115 +*/
1.1116 +extern JSD_PUBLIC_API(bool)
1.1117 +JSD_IsUnlocked(JSDStaticLock* lock);
1.1118 +
1.1119 +/*
1.1120 +* return an ID uniquely identifying this thread.
1.1121 +*/
1.1122 +extern JSD_PUBLIC_API(void*)
1.1123 +JSD_CurrentThread();
1.1124 +
1.1125 +/***************************************************************************/
1.1126 +/* Value and Property Functions --- All NEW for 1.1 --- */
1.1127 +
1.1128 +/*
1.1129 +* NOTE: JSDValue and JSDProperty objects are reference counted. This allows
1.1130 +* for rooting these objects AND any underlying garbage collected JS::Values.
1.1131 +* ALL JSDValue and JSDProperty objects returned by the functions below
1.1132 +* MUST eventually be released using the appropriate JSD_Dropxxx function.
1.1133 +*/
1.1134 +
1.1135 +/*
1.1136 +* Create a new JSDValue to wrap the given JS::Value
1.1137 +* NOTE: must eventually release by calling JSD_DropValue (if not nullptr)
1.1138 +* *** new for version 1.1 ****
1.1139 +*/
1.1140 +extern JSD_PUBLIC_API(JSDValue*)
1.1141 +JSD_NewValue(JSDContext* jsdc, JS::Value val);
1.1142 +
1.1143 +/*
1.1144 +* Release the JSDValue. After this call the object MUST not be referenced again!
1.1145 +* *** new for version 1.1 ****
1.1146 +*/
1.1147 +extern JSD_PUBLIC_API(void)
1.1148 +JSD_DropValue(JSDContext* jsdc, JSDValue* jsdval);
1.1149 +
1.1150 +/*
1.1151 +* Get the JS::Value wrapped by this JSDValue
1.1152 +* *** new for version 1.1 ****
1.1153 +*/
1.1154 +extern JSD_PUBLIC_API(JS::Value)
1.1155 +JSD_GetValueWrappedJSVal(JSDContext* jsdc, JSDValue* jsdval);
1.1156 +
1.1157 +/*
1.1158 +* Clear all property and association information about the given JSDValue.
1.1159 +* Such information will be lazily regenerated when later accessed. This
1.1160 +* function must be called to make changes to the properties of an object
1.1161 +* visible to the accessor functions below (if the properties et.al. have
1.1162 +* changed since a previous call to those accessors).
1.1163 +* *** new for version 1.1 ****
1.1164 +*/
1.1165 +extern JSD_PUBLIC_API(void)
1.1166 +JSD_RefreshValue(JSDContext* jsdc, JSDValue* jsdval);
1.1167 +
1.1168 +/**************************************************/
1.1169 +
1.1170 +/*
1.1171 +* Does the JSDValue wrap a JSObject?
1.1172 +* *** new for version 1.1 ****
1.1173 +*/
1.1174 +extern JSD_PUBLIC_API(bool)
1.1175 +JSD_IsValueObject(JSDContext* jsdc, JSDValue* jsdval);
1.1176 +
1.1177 +/*
1.1178 +* Does the JSDValue wrap a number (int or double)?
1.1179 +* *** new for version 1.1 ****
1.1180 +*/
1.1181 +extern JSD_PUBLIC_API(bool)
1.1182 +JSD_IsValueNumber(JSDContext* jsdc, JSDValue* jsdval);
1.1183 +
1.1184 +/*
1.1185 +* Does the JSDValue wrap an int?
1.1186 +* *** new for version 1.1 ****
1.1187 +*/
1.1188 +extern JSD_PUBLIC_API(bool)
1.1189 +JSD_IsValueInt(JSDContext* jsdc, JSDValue* jsdval);
1.1190 +
1.1191 +/*
1.1192 +* Does the JSDValue wrap a double?
1.1193 +* *** new for version 1.1 ****
1.1194 +*/
1.1195 +extern JSD_PUBLIC_API(bool)
1.1196 +JSD_IsValueDouble(JSDContext* jsdc, JSDValue* jsdval);
1.1197 +
1.1198 +/*
1.1199 +* Does the JSDValue wrap a JSString?
1.1200 +* *** new for version 1.1 ****
1.1201 +*/
1.1202 +extern JSD_PUBLIC_API(bool)
1.1203 +JSD_IsValueString(JSDContext* jsdc, JSDValue* jsdval);
1.1204 +
1.1205 +/*
1.1206 +* Does the JSDValue wrap a bool?
1.1207 +* *** new for version 1.1 ****
1.1208 +*/
1.1209 +extern JSD_PUBLIC_API(bool)
1.1210 +JSD_IsValueBoolean(JSDContext* jsdc, JSDValue* jsdval);
1.1211 +
1.1212 +/*
1.1213 +* Does the JSDValue wrap a JSVAL_NULL?
1.1214 +* *** new for version 1.1 ****
1.1215 +*/
1.1216 +extern JSD_PUBLIC_API(bool)
1.1217 +JSD_IsValueNull(JSDContext* jsdc, JSDValue* jsdval);
1.1218 +
1.1219 +/*
1.1220 +* Does the JSDValue wrap a JSVAL_VOID?
1.1221 +* *** new for version 1.1 ****
1.1222 +*/
1.1223 +extern JSD_PUBLIC_API(bool)
1.1224 +JSD_IsValueVoid(JSDContext* jsdc, JSDValue* jsdval);
1.1225 +
1.1226 +/*
1.1227 +* Does the JSDValue wrap a primative (not a JSObject)?
1.1228 +* *** new for version 1.1 ****
1.1229 +*/
1.1230 +extern JSD_PUBLIC_API(bool)
1.1231 +JSD_IsValuePrimitive(JSDContext* jsdc, JSDValue* jsdval);
1.1232 +
1.1233 +/*
1.1234 +* Does the JSDValue wrap a function?
1.1235 +* *** new for version 1.1 ****
1.1236 +*/
1.1237 +extern JSD_PUBLIC_API(bool)
1.1238 +JSD_IsValueFunction(JSDContext* jsdc, JSDValue* jsdval);
1.1239 +
1.1240 +/*
1.1241 +* Does the JSDValue wrap a native function?
1.1242 +* *** new for version 1.1 ****
1.1243 +*/
1.1244 +extern JSD_PUBLIC_API(bool)
1.1245 +JSD_IsValueNative(JSDContext* jsdc, JSDValue* jsdval);
1.1246 +
1.1247 +/**************************************************/
1.1248 +
1.1249 +/*
1.1250 +* Return bool value (does NOT do conversion).
1.1251 +* *** new for version 1.1 ****
1.1252 +*/
1.1253 +extern JSD_PUBLIC_API(bool)
1.1254 +JSD_GetValueBoolean(JSDContext* jsdc, JSDValue* jsdval);
1.1255 +
1.1256 +/*
1.1257 +* Return int32_t value (does NOT do conversion).
1.1258 +* *** new for version 1.1 ****
1.1259 +*/
1.1260 +extern JSD_PUBLIC_API(int32_t)
1.1261 +JSD_GetValueInt(JSDContext* jsdc, JSDValue* jsdval);
1.1262 +
1.1263 +/*
1.1264 +* Return double value (does NOT do conversion).
1.1265 +* *** new for version 1.1 ****
1.1266 +*/
1.1267 +extern JSD_PUBLIC_API(double)
1.1268 +JSD_GetValueDouble(JSDContext* jsdc, JSDValue* jsdval);
1.1269 +
1.1270 +/*
1.1271 +* Return JSString value (DOES do conversion if necessary).
1.1272 +* NOTE that the JSString returned is not protected from garbage
1.1273 +* collection. It should be immediately read or wrapped using
1.1274 +* JSD_NewValue(jsdc,STRING_TO_JSVAL(str)) if necessary.
1.1275 +* *** new for version 1.1 ****
1.1276 +*/
1.1277 +extern JSD_PUBLIC_API(JSString*)
1.1278 +JSD_GetValueString(JSDContext* jsdc, JSDValue* jsdval);
1.1279 +
1.1280 +/*
1.1281 +* Return name of function IFF JSDValue represents a function.
1.1282 +* *** new for gecko 2.0 ****
1.1283 +*/
1.1284 +extern JSD_PUBLIC_API(JSString *)
1.1285 +JSD_GetValueFunctionId(JSDContext* jsdc, JSDValue* jsdval);
1.1286 +
1.1287 +/*
1.1288 +* Return function object IFF JSDValue represents a function or an object
1.1289 +* wrapping a function.
1.1290 +* *** new for version 1.1 ****
1.1291 +*/
1.1292 +extern JSD_PUBLIC_API(JSFunction*)
1.1293 +JSD_GetValueFunction(JSDContext* jsdc, JSDValue* jsdval);
1.1294 +
1.1295 +/**************************************************/
1.1296 +
1.1297 +/*
1.1298 +* Return the number of properties for the JSDValue.
1.1299 +* *** new for version 1.1 ****
1.1300 +*/
1.1301 +extern JSD_PUBLIC_API(unsigned)
1.1302 +JSD_GetCountOfProperties(JSDContext* jsdc, JSDValue* jsdval);
1.1303 +
1.1304 +/*
1.1305 +* Iterate through the properties of the JSDValue.
1.1306 +* Use form similar to that shown for JSD_IterateScripts (no locking required).
1.1307 +* NOTE: each JSDProperty returned must eventually be released by calling
1.1308 +* JSD_DropProperty.
1.1309 +* *** new for version 1.1 ****
1.1310 +*/
1.1311 +extern JSD_PUBLIC_API(JSDProperty*)
1.1312 +JSD_IterateProperties(JSDContext* jsdc, JSDValue* jsdval, JSDProperty **iterp);
1.1313 +
1.1314 +/*
1.1315 +* Get the JSDProperty for the property of this JSDVal with this name.
1.1316 +* NOTE: must eventually release by calling JSD_DropProperty (if not nullptr)
1.1317 +* *** new for version 1.1 ****
1.1318 +*/
1.1319 +extern JSD_PUBLIC_API(JSDProperty*)
1.1320 +JSD_GetValueProperty(JSDContext* jsdc, JSDValue* jsdval, JSString* name);
1.1321 +
1.1322 +/*
1.1323 +* Get the prototype object for this JSDValue.
1.1324 +* NOTE: must eventually release by calling JSD_DropValue (if not nullptr)
1.1325 +* *** new for version 1.1 ****
1.1326 +*/
1.1327 +extern JSD_PUBLIC_API(JSDValue*)
1.1328 +JSD_GetValuePrototype(JSDContext* jsdc, JSDValue* jsdval);
1.1329 +
1.1330 +/*
1.1331 +* Get the parent object for this JSDValue.
1.1332 +* NOTE: must eventually release by calling JSD_DropValue (if not nullptr)
1.1333 +* *** new for version 1.1 ****
1.1334 +*/
1.1335 +extern JSD_PUBLIC_API(JSDValue*)
1.1336 +JSD_GetValueParent(JSDContext* jsdc, JSDValue* jsdval);
1.1337 +
1.1338 +/*
1.1339 +* Get the ctor object for this JSDValue (or likely its prototype's ctor).
1.1340 +* NOTE: must eventually release by calling JSD_DropValue (if not nullptr)
1.1341 +* *** new for version 1.1 ****
1.1342 +*/
1.1343 +extern JSD_PUBLIC_API(JSDValue*)
1.1344 +JSD_GetValueConstructor(JSDContext* jsdc, JSDValue* jsdval);
1.1345 +
1.1346 +/*
1.1347 +* Get the name of the class for this object.
1.1348 +* *** new for version 1.1 ****
1.1349 +*/
1.1350 +extern JSD_PUBLIC_API(const char*)
1.1351 +JSD_GetValueClassName(JSDContext* jsdc, JSDValue* jsdval);
1.1352 +
1.1353 +/*
1.1354 +* Get the script for the given value if the given value represents a
1.1355 +* scripted function. Otherwise, return null.
1.1356 +*/
1.1357 +extern JSD_PUBLIC_API(JSDScript*)
1.1358 +JSD_GetScriptForValue(JSDContext* jsdc, JSDValue* jsdval);
1.1359 +
1.1360 +/**************************************************/
1.1361 +
1.1362 +/* possible or'd together bitflags returned by JSD_GetPropertyFlags
1.1363 + *
1.1364 + * XXX these must stay the same as the JSPD_ flags in js/OldDebugAPI.h
1.1365 + */
1.1366 +#define JSDPD_ENUMERATE JSPD_ENUMERATE /* visible to for/in loop */
1.1367 +#define JSDPD_READONLY JSPD_READONLY /* assignment is error */
1.1368 +#define JSDPD_PERMANENT JSPD_PERMANENT /* property cannot be deleted */
1.1369 +#define JSDPD_ALIAS JSPD_ALIAS /* property has an alias id */
1.1370 +#define JSDPD_EXCEPTION JSPD_EXCEPTION /* exception occurred looking up */
1.1371 + /* proprety, value is exception */
1.1372 +#define JSDPD_ERROR JSPD_ERROR /* native getter returned false */
1.1373 + /* without throwing an exception */
1.1374 +/* this is not one of the JSPD_ flags in js/OldDebugAPI.h - don't overlap! */
1.1375 +#define JSDPD_HINTED 0x800 /* found via explicit lookup */
1.1376 +
1.1377 +/*
1.1378 +* Release this JSDProperty
1.1379 +* *** new for version 1.1 ****
1.1380 +*/
1.1381 +extern JSD_PUBLIC_API(void)
1.1382 +JSD_DropProperty(JSDContext* jsdc, JSDProperty* jsdprop);
1.1383 +
1.1384 +/*
1.1385 +* Get the JSDValue represeting the name of this property (int or string)
1.1386 +* NOTE: must eventually release by calling JSD_DropValue
1.1387 +* *** new for version 1.1 ****
1.1388 +*/
1.1389 +extern JSD_PUBLIC_API(JSDValue*)
1.1390 +JSD_GetPropertyName(JSDContext* jsdc, JSDProperty* jsdprop);
1.1391 +
1.1392 +/*
1.1393 +* Get the JSDValue represeting the current value of this property
1.1394 +* NOTE: must eventually release by calling JSD_DropValue (if not nullptr)
1.1395 +* *** new for version 1.1 ****
1.1396 +*/
1.1397 +extern JSD_PUBLIC_API(JSDValue*)
1.1398 +JSD_GetPropertyValue(JSDContext* jsdc, JSDProperty* jsdprop);
1.1399 +
1.1400 +/*
1.1401 +* Get the JSDValue represeting the alias of this property (if JSDPD_ALIAS set)
1.1402 +* NOTE: must eventually release by calling JSD_DropValue (if not nullptr)
1.1403 +* *** new for version 1.1 ****
1.1404 +*/
1.1405 +extern JSD_PUBLIC_API(JSDValue*)
1.1406 +JSD_GetPropertyAlias(JSDContext* jsdc, JSDProperty* jsdprop);
1.1407 +
1.1408 +/*
1.1409 +* Get the flags for this property
1.1410 +* *** new for version 1.1 ****
1.1411 +*/
1.1412 +extern JSD_PUBLIC_API(unsigned)
1.1413 +JSD_GetPropertyFlags(JSDContext* jsdc, JSDProperty* jsdprop);
1.1414 +
1.1415 +/***************************************************************************/
1.1416 +/* Object Functions --- All NEW for 1.1 --- */
1.1417 +
1.1418 +/*
1.1419 +* JSDObjects exist to allow a means of iterating through all JSObjects in the
1.1420 +* engine. They are created and destroyed as the wrapped JSObjects are created
1.1421 +* and destroyed in the engine. JSDObjects additionally track the location in
1.1422 +* the JavaScript source where their wrapped JSObjects were created and the name
1.1423 +* and location of the (non-native) constructor used.
1.1424 +*
1.1425 +* NOTE: JSDObjects are NOT reference counted. The have only weak links to
1.1426 +* jsObjects - thus they do not inhibit garbage collection of JSObjects. If
1.1427 +* you need a JSDObject to safely persist then wrap it in a JSDValue (using
1.1428 +* jsd_GetValueForObject).
1.1429 +*/
1.1430 +
1.1431 +/*
1.1432 +* Lock the entire Object subsystem -- see JSD_UnlockObjectSubsystem
1.1433 +* *** new for version 1.1 ****
1.1434 +*/
1.1435 +extern JSD_PUBLIC_API(void)
1.1436 +JSD_LockObjectSubsystem(JSDContext* jsdc);
1.1437 +
1.1438 +/*
1.1439 +* Unlock the entire Object subsystem -- see JSD_LockObjectSubsystem
1.1440 +* *** new for version 1.1 ****
1.1441 +*/
1.1442 +extern JSD_PUBLIC_API(void)
1.1443 +JSD_UnlockObjectSubsystem(JSDContext* jsdc);
1.1444 +
1.1445 +/*
1.1446 +* Iterate through the known objects
1.1447 +* Use form similar to that shown for JSD_IterateScripts.
1.1448 +* NOTE: the ObjectSubsystem must be locked before and unlocked after iterating.
1.1449 +* *** new for version 1.1 ****
1.1450 +*/
1.1451 +extern JSD_PUBLIC_API(JSDObject*)
1.1452 +JSD_IterateObjects(JSDContext* jsdc, JSDObject** iterp);
1.1453 +
1.1454 +/*
1.1455 +* Get the JSObject represented by this JSDObject
1.1456 +* *** new for version 1.1 ****
1.1457 +*/
1.1458 +extern JSD_PUBLIC_API(JSObject*)
1.1459 +JSD_GetWrappedObject(JSDContext* jsdc, JSDObject* jsdobj);
1.1460 +
1.1461 +/*
1.1462 +* Get the URL of the line of source that caused this object to be created.
1.1463 +* May be nullptr.
1.1464 +* *** new for version 1.1 ****
1.1465 +*/
1.1466 +extern JSD_PUBLIC_API(const char*)
1.1467 +JSD_GetObjectNewURL(JSDContext* jsdc, JSDObject* jsdobj);
1.1468 +
1.1469 +/*
1.1470 +* Get the line number of the line of source that caused this object to be
1.1471 +* created. May be 0 indicating that the line number is unknown.
1.1472 +* *** new for version 1.1 ****
1.1473 +*/
1.1474 +extern JSD_PUBLIC_API(unsigned)
1.1475 +JSD_GetObjectNewLineNumber(JSDContext* jsdc, JSDObject* jsdobj);
1.1476 +
1.1477 +/*
1.1478 +* Get the URL of the line of source of the constructor for this object.
1.1479 +* May be nullptr.
1.1480 +* *** new for version 1.1 ****
1.1481 +*/
1.1482 +extern JSD_PUBLIC_API(const char*)
1.1483 +JSD_GetObjectConstructorURL(JSDContext* jsdc, JSDObject* jsdobj);
1.1484 +
1.1485 +/*
1.1486 +* Get the line number of the line of source of the constructor for this object.
1.1487 +* created. May be 0 indicating that the line number is unknown.
1.1488 +* *** new for version 1.1 ****
1.1489 +*/
1.1490 +extern JSD_PUBLIC_API(unsigned)
1.1491 +JSD_GetObjectConstructorLineNumber(JSDContext* jsdc, JSDObject* jsdobj);
1.1492 +
1.1493 +/*
1.1494 +* Get the name of the constructor for this object.
1.1495 +* May be nullptr.
1.1496 +* *** new for version 1.1 ****
1.1497 +*/
1.1498 +extern JSD_PUBLIC_API(const char*)
1.1499 +JSD_GetObjectConstructorName(JSDContext* jsdc, JSDObject* jsdobj);
1.1500 +
1.1501 +/*
1.1502 +* Get JSDObject representing this JSObject.
1.1503 +* May return nullptr.
1.1504 +* *** new for version 1.1 ****
1.1505 +*/
1.1506 +extern JSD_PUBLIC_API(JSDObject*)
1.1507 +JSD_GetJSDObjectForJSObject(JSDContext* jsdc, JSObject* jsobj);
1.1508 +
1.1509 +/*
1.1510 +* Get JSDObject representing this JSDValue.
1.1511 +* May return nullptr.
1.1512 +* *** new for version 1.1 ****
1.1513 +*/
1.1514 +extern JSD_PUBLIC_API(JSDObject*)
1.1515 +JSD_GetObjectForValue(JSDContext* jsdc, JSDValue* jsdval);
1.1516 +
1.1517 +/*
1.1518 +* Create a JSDValue to wrap (and root) this JSDObject.
1.1519 +* NOTE: must eventually release by calling JSD_DropValue (if not nullptr)
1.1520 +* *** new for version 1.1 ****
1.1521 +*/
1.1522 +extern JSD_PUBLIC_API(JSDValue*)
1.1523 +JSD_GetValueForObject(JSDContext* jsdc, JSDObject* jsdobj);
1.1524 +
1.1525 +} // extern "C"
1.1526 +
1.1527 +#endif /* jsdebug_h___ */
