forked from mozilla/gecko-dev
-
Notifications
You must be signed in to change notification settings - Fork 2
/
jsdebug.h
1590 lines (1382 loc) · 50.9 KB
/
jsdebug.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* ***** BEGIN LICENSE BLOCK *****
* Version: MPL 1.1/GPL 2.0/LGPL 2.1
*
* The contents of this file are subject to the Mozilla Public License Version
* 1.1 (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
* http://www.mozilla.org/MPL/
*
* Software distributed under the License is distributed on an "AS IS" basis,
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
* for the specific language governing rights and limitations under the
* License.
*
* The Original Code is mozilla.org code.
*
* The Initial Developer of the Original Code is
* Netscape Communications Corporation.
* Portions created by the Initial Developer are Copyright (C) 1998
* the Initial Developer. All Rights Reserved.
*
* Contributor(s):
*
* Alternatively, the contents of this file may be used under the terms of
* either the GNU General Public License Version 2 or later (the "GPL"), or
* the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
* in which case the provisions of the GPL or the LGPL are applicable instead
* of those above. If you wish to allow use of your version of this file only
* under the terms of either the GPL or the LGPL, and not to allow others to
* use your version of this file under the terms of the MPL, indicate your
* decision by deleting the provisions above and replace them with the notice
* and other provisions required by the GPL or the LGPL. If you do not delete
* the provisions above, a recipient may use your version of this file under
* the terms of any one of the MPL, the GPL or the LGPL.
*
* ***** END LICENSE BLOCK ***** */
/*
* Header for JavaScript Debugging support - All public functions
*/
#ifndef jsdebug_h___
#define jsdebug_h___
/* Get jstypes.h included first. After that we can use PR macros for doing
* this extern "C" stuff!
*/
#ifdef __cplusplus
extern "C"
{
#endif
#include "jstypes.h"
#ifdef __cplusplus
}
#endif
#include "jsapi.h"
#include "jsdbgapi.h"
#ifdef LIVEWIRE
#include "lwdbgapi.h"
#endif
JS_BEGIN_EXTERN_C
/*
* The linkage of JSD API functions differs depending on whether the file is
* used within the JSD library or not. Any source file within the JSD
* libraray should define EXPORT_JSD_API whereas any client of the library
* should not.
*/
#ifdef EXPORT_JSD_API
#define JSD_PUBLIC_API(t) JS_EXPORT_API(t)
#define JSD_PUBLIC_DATA(t) JS_EXPORT_DATA(t)
#else
#define JSD_PUBLIC_API(t) JS_IMPORT_API(t)
#define JSD_PUBLIC_DATA(t) JS_IMPORT_DATA(t)
#endif
#define JSD_FRIEND_API(t) JSD_PUBLIC_API(t)
#define JSD_FRIEND_DATA(t) JSD_PUBLIC_DATA(t)
/***************************************************************************/
/* Opaque typedefs for handles */
typedef struct JSDContext JSDContext;
typedef struct JSDScript JSDScript;
typedef struct JSDSourceText JSDSourceText;
typedef struct JSDThreadState JSDThreadState;
typedef struct JSDStackFrameInfo JSDStackFrameInfo;
typedef struct JSDValue JSDValue;
typedef struct JSDProperty JSDProperty;
typedef struct JSDObject JSDObject;
/***************************************************************************/
/* High Level calls */
/*
* callback stuff for calls in EXE to be accessed by this code
* when it lives in an explicitly loaded DLL
*/
/*
* This callback allows JSD to inform the embedding when JSD has been
* turned on or off. This is especially useful in the Java-based debugging
* system used in mozilla because the debugger applet controls starting
* up the JSD system.
*/
typedef void
(* JSD_SetContextProc)(JSDContext* jsdc, void* user);
/* This struct could have more fields in future versions */
typedef struct
{
uintN size; /* size of this struct (init before use)*/
JSD_SetContextProc setContext;
} JSD_UserCallbacks;
/*
* Used by an embedding to tell JSD what JSRuntime to use and to set
* callbacks without starting up JSD. This assumes only one JSRuntime
* will be used. This exists to support the mozilla Java-based debugger
* system.
*/
extern JSD_PUBLIC_API(void)
JSD_SetUserCallbacks(JSRuntime* jsrt,
JSD_UserCallbacks* callbacks,
void* user);
/*
* Startup JSD.
* This version of the init function requires that JSD_SetUserCallbacks()
* has been previously called (with a non-NULL callback struct pointer)
*/
extern JSD_PUBLIC_API(JSDContext*)
JSD_DebuggerOn(void);
/*
* Startup JSD on a particular JSRuntime with (optional) callbacks
*/
extern JSD_PUBLIC_API(JSDContext*)
JSD_DebuggerOnForUser(JSRuntime* jsrt,
JSD_UserCallbacks* callbacks,
void* user);
/*
* Startup JSD in an application that uses compartments. Debugger
* objects will be allocated in the same compartment as scopeobj.
*/
extern JSD_PUBLIC_API(JSDContext*)
JSD_DebuggerOnForUserWithCompartment(JSRuntime* jsrt,
JSD_UserCallbacks* callbacks,
void* user,
JSObject* scopeobj);
/*
* Shutdown JSD for this JSDContext
*/
extern JSD_PUBLIC_API(void)
JSD_DebuggerOff(JSDContext* jsdc);
/*
* Pause JSD for this JSDContext
*/
extern JSD_PUBLIC_API(void)
JSD_DebuggerPause(JSDContext* jsdc);
/*
* Unpause JSD for this JSDContext
*/
extern JSD_PUBLIC_API(void)
JSD_DebuggerUnpause(JSDContext* jsdc);
/*
* Get the Major Version (initial JSD release used major version = 1)
*/
extern JSD_PUBLIC_API(uintN)
JSD_GetMajorVersion(void);
/*
* Get the Minor Version (initial JSD release used minor version = 0)
*/
extern JSD_PUBLIC_API(uintN)
JSD_GetMinorVersion(void);
/*
* Returns a 'dumb' JSContext that can be used for utility purposes as needed
*/
extern JSD_PUBLIC_API(JSContext*)
JSD_GetDefaultJSContext(JSDContext* jsdc);
/*
* Set the private data for this context, returns previous value
*/
extern JSD_PUBLIC_API(void *)
JSD_SetContextPrivate(JSDContext *jsdc, void *data);
/*
* Get the private data for this context
*/
extern JSD_PUBLIC_API(void *)
JSD_GetContextPrivate(JSDContext *jsdc);
/*
* Clear profile data for all scripts
*/
extern JSD_PUBLIC_API(void)
JSD_ClearAllProfileData(JSDContext* jsdc);
/*
* Context flags.
*/
/* Include native frames in JSDThreadStates. */
#define JSD_INCLUDE_NATIVE_FRAMES 0x01
/*
* Normally, if a script has a 0 in JSD_SCRIPT_PROFILE_BIT it is included in
* profile data, otherwise it is not profiled. Setting the JSD_PROFILE_WHEN_SET
* flag reverses this convention.
*/
#define JSD_PROFILE_WHEN_SET 0x02
/*
* Normally, when the script in the top frame of a thread state has a 1 in
* JSD_SCRIPT_DEBUG_BIT, the execution hook is ignored. Setting the
* JSD_DEBUG_WHEN_SET flag reverses this convention.
*/
#define JSD_DEBUG_WHEN_SET 0x04
/*
* When this flag is set the internal call hook will collect profile data.
*/
#define JSD_COLLECT_PROFILE_DATA 0x08
/*
* When this flag is set, stack frames that are disabled for debugging
* will not appear in the call stack chain.
*/
#define JSD_HIDE_DISABLED_FRAMES 0x10
/*
* When this flag is set, the debugger will only check the
* JSD_SCRIPT_DEBUG_BIT on the top (most recent) stack frame. This
* makes it possible to stop in an enabled frame which was called from
* a stack that contains a disabled frame.
*
* When this flag is *not* set, any stack that contains a disabled frame
* will not be debugged (the execution hook will not be invoked.)
*
* This only applies when the reason for calling the hook would have
* been JSD_HOOK_INTERRUPTED or JSD_HOOK_THROW. JSD_HOOK_BREAKPOINT,
* JSD_HOOK_DEBUG_REQUESTED, and JSD_HOOK_DEBUGGER_KEYWORD always stop,
* regardless of this setting, as long as the top frame is not disabled.
*
* If JSD_HIDE_DISABLED_FRAMES is set, this is effectively set as well.
*/
#define JSD_MASK_TOP_FRAME_ONLY 0x20
/*
* 0x40 was formerly used to hook into object creation.
*/
#define JSD_DISABLE_OBJECT_TRACE_RETIRED 0x40
extern JSD_PUBLIC_API(void)
JSD_SetContextFlags (JSDContext* jsdc, uint32_t flags);
extern JSD_PUBLIC_API(uint32_t)
JSD_GetContextFlags (JSDContext* jsdc);
/*
* Notify JSD that this JSContext is 'in use'. This allows JSD to hook the
* ErrorReporter. For the most part this is done automatically whenever
* events like script loading happen. But, it is a good idea to call this
* from the embedding when new contexts come into use.
*/
extern JSD_PUBLIC_API(void)
JSD_JSContextInUse(JSDContext* jsdc, JSContext* context);
/*
* Find the JSDContext (if any) associated with the JSRuntime of a
* given JSContext.
*/
extern JSD_PUBLIC_API(JSDContext*)
JSD_JSDContextForJSContext(JSContext* context);
/***************************************************************************/
/* Script functions */
/*
* Lock the entire script subsystem. This grabs a highlevel lock that
* protects the JSD internal information about scripts. It is important
* to wrap script related calls in this lock in multithreaded situations
* -- i.e. where the debugger is running on a different thread than the
* interpreter -- or when multiple debugger threads may be accessing this
* subsystem. It is safe (and best) to use this locking even if the
* environment might not be multi-threaded. Safely nestable.
*/
extern JSD_PUBLIC_API(void)
JSD_LockScriptSubsystem(JSDContext* jsdc);
/*
* Unlock the entire script subsystem -- see JSD_LockScriptSubsystem
*/
extern JSD_PUBLIC_API(void)
JSD_UnlockScriptSubsystem(JSDContext* jsdc);
/*
* Iterate through all the active scripts for this JSDContext.
* NOTE: must initialize iterp to NULL to start iteration.
* NOTE: must lock and unlock the subsystem
* example:
*
* JSDScript jsdscript;
* JSDScript iter = NULL;
*
* JSD_LockScriptSubsystem(jsdc);
* while((jsdscript = JSD_IterateScripts(jsdc, &iter)) != NULL) {
* *** use jsdscript here ***
* }
* JSD_UnlockScriptSubsystem(jsdc);
*/
extern JSD_PUBLIC_API(JSDScript*)
JSD_IterateScripts(JSDContext* jsdc, JSDScript **iterp);
/*
* Get the number of times this script has been called.
*/
extern JSD_PUBLIC_API(uintN)
JSD_GetScriptCallCount(JSDContext* jsdc, JSDScript *script);
/*
* Get the max number of times this script called itself, directly or indirectly.
*/
extern JSD_PUBLIC_API(uintN)
JSD_GetScriptMaxRecurseDepth(JSDContext* jsdc, JSDScript *script);
/*
* Get the shortest execution time recorded.
*/
extern JSD_PUBLIC_API(jsdouble)
JSD_GetScriptMinExecutionTime(JSDContext* jsdc, JSDScript *script);
/*
* Get the longest execution time recorded.
*/
extern JSD_PUBLIC_API(jsdouble)
JSD_GetScriptMaxExecutionTime(JSDContext* jsdc, JSDScript *script);
/*
* Get the total amount of time spent in this script.
*/
extern JSD_PUBLIC_API(jsdouble)
JSD_GetScriptTotalExecutionTime(JSDContext* jsdc, JSDScript *script);
/*
* Get the shortest execution time recorded, excluding time spent in called
* functions.
*/
extern JSD_PUBLIC_API(jsdouble)
JSD_GetScriptMinOwnExecutionTime(JSDContext* jsdc, JSDScript *script);
/*
* Get the longest execution time recorded, excluding time spent in called
* functions.
*/
extern JSD_PUBLIC_API(jsdouble)
JSD_GetScriptMaxOwnExecutionTime(JSDContext* jsdc, JSDScript *script);
/*
* Get the total amount of time spent in this script, excluding time spent
* in called functions.
*/
extern JSD_PUBLIC_API(jsdouble)
JSD_GetScriptTotalOwnExecutionTime(JSDContext* jsdc, JSDScript *script);
/*
* Clear profile data for this script.
*/
extern JSD_PUBLIC_API(void)
JSD_ClearScriptProfileData(JSDContext* jsdc, JSDScript *script);
/*
* Get the JSScript for a JSDScript
*/
extern JSD_PUBLIC_API(JSScript*)
JSD_GetJSScript(JSDContext* jsdc, JSDScript *script);
/*
* Get the JSFunction for a JSDScript
*/
extern JSD_PUBLIC_API(JSFunction*)
JSD_GetJSFunction(JSDContext* jsdc, JSDScript *script);
/*
* Determines whether or not to collect profile information for this
* script. The context flag JSD_PROFILE_WHEN_SET decides the logic.
*/
#define JSD_SCRIPT_PROFILE_BIT 0x01
/*
* Determines whether or not to ignore breakpoints, etc. in this script.
* The context flag JSD_DEBUG_WHEN_SET decides the logic.
*/
#define JSD_SCRIPT_DEBUG_BIT 0x02
extern JSD_PUBLIC_API(uint32_t)
JSD_GetScriptFlags(JSDContext *jsdc, JSDScript* jsdscript);
extern JSD_PUBLIC_API(void)
JSD_SetScriptFlags(JSDContext *jsdc, JSDScript* jsdscript, uint32_t flags);
/*
* Set the private data for this script, returns previous value
*/
extern JSD_PUBLIC_API(void *)
JSD_SetScriptPrivate(JSDScript* jsdscript, void *data);
/*
* Get the private data for this script
*/
extern JSD_PUBLIC_API(void *)
JSD_GetScriptPrivate(JSDScript* jsdscript);
/*
* Determine if this script is still loaded in the interpreter
*/
extern JSD_PUBLIC_API(JSBool)
JSD_IsActiveScript(JSDContext* jsdc, JSDScript *jsdscript);
/*
* Get the filename associated with this script
*/
extern JSD_PUBLIC_API(const char*)
JSD_GetScriptFilename(JSDContext* jsdc, JSDScript *jsdscript);
/*
* Get the function name associated with this script (NULL if not a function).
* If the function does not have a name the result is the string "anonymous".
* *** new for gecko 2.0 ****
*/
extern JSD_PUBLIC_API(JSString *)
JSD_GetScriptFunctionId(JSDContext* jsdc, JSDScript *jsdscript);
/*
* Get the base linenumber of the sourcefile from which this script was loaded.
* This is one-based -- i.e. the first line of a file is line '1'. This may
* return 0 if this infomation is unknown.
*/
extern JSD_PUBLIC_API(uintN)
JSD_GetScriptBaseLineNumber(JSDContext* jsdc, JSDScript *jsdscript);
/*
* Get the count of source lines associated with this script (1 or greater)
*/
extern JSD_PUBLIC_API(uintN)
JSD_GetScriptLineExtent(JSDContext* jsdc, JSDScript *jsdscript);
/*
* Declaration of callback for notification of script creation and destruction.
* 'creating' is JS_TRUE if creating new script, JS_FALSE if destroying existing
* script (callback called just before actual destruction).
* 'callerdata' is what was passed to JSD_SetScriptHook to set the hook.
*/
typedef void
(* JSD_ScriptHookProc)(JSDContext* jsdc,
JSDScript* jsdscript,
JSBool creating,
void* callerdata);
/*
* Set a hook to be called when scripts are created or destroyed (loaded or
* unloaded).
* 'callerdata' can be whatever you want it to be.
*/
extern JSD_PUBLIC_API(JSBool)
JSD_SetScriptHook(JSDContext* jsdc, JSD_ScriptHookProc hook, void* callerdata);
/*
* Get the current script hook.
*/
extern JSD_PUBLIC_API(JSBool)
JSD_GetScriptHook(JSDContext* jsdc, JSD_ScriptHookProc* hook, void** callerdata);
/*
* Get a 'Program Counter' value for a given line. This represents the location
* of the first bit of executable code for this line of source. This 'pc' should
* be considered an opaque handle.
* 0 is returned for invalid scripts, or lines that lie outside the script.
* If no code is on the given line, then the returned pc represents the first
* code within the script (if any) after the given line.
* This function can be used to set breakpoints -- see JSD_SetExecutionHook
*/
extern JSD_PUBLIC_API(uintptr_t)
JSD_GetClosestPC(JSDContext* jsdc, JSDScript* jsdscript, uintN line);
/*
* Get the source line number for a given 'Program Counter' location.
* Returns 0 if no source line information is appropriate (or available) for
* the given pc.
*/
extern JSD_PUBLIC_API(uintN)
JSD_GetClosestLine(JSDContext* jsdc, JSDScript* jsdscript, uintptr_t pc);
/*
* Get a list of lines and the corresponding earliest PC for each (see
* JSD_GetClosestPC). Lines with no PCs associated will not be returned. NULL
* may be passed for either lines or pcs to avoid filling anything in for that
* argument.
*/
extern JSD_PUBLIC_API(JSBool)
JSD_GetLinePCs(JSDContext* jsdc, JSDScript* jsdscript,
uintN startLine, uintN maxLines,
uintN* count, uintN** lines, uintptr_t** pcs);
/* these are only used in cases where scripts are created outside of JS*/
/*
* Direct call to notify JSD that a script has been created.
* Embeddings that use the normal jsapi script functions need not call this.
* Any embedding that follows the (discouraged!) practice of contructing script
* structures manually should call this function to inform JSD. (older ssjs
* systems do this).
*/
extern JSD_PUBLIC_API(void)
JSD_ScriptCreated(JSDContext* jsdc,
JSContext *cx,
const char *filename, /* URL this script loads from */
uintN lineno, /* line where this script starts */
JSScript *script,
JSFunction *fun);
/*
* see JSD_ScriptCreated
*/
extern JSD_PUBLIC_API(void)
JSD_ScriptDestroyed(JSDContext* jsdc,
JSContext *cx,
JSScript *script);
/***************************************************************************/
/* Source Text functions */
/*
* In some embeddings (e.g. mozilla) JavaScript source code from a 'file' may be
* execute before the entire 'file' has even been loaded. This system supports
* access to such incrmentally loaded source. It also allows for the possibility
* that source loading may fail or be aborted (though the source that did load
* may still be usable). Remember that this source is the entire 'file'
* contents and that the JavaScript code may only be part of that source.
*
* For any given URL there can only be one source text item (the most recently
* loaded).
*/
/* these coorespond to netscape.jsdebug.SourceTextItem.java values -
* change in both places if anywhere
*/
typedef enum
{
JSD_SOURCE_INITED = 0, /* initialized, but contains no source yet */
JSD_SOURCE_PARTIAL = 1, /* some source loaded, more expected */
JSD_SOURCE_COMPLETED = 2, /* all source finished loading */
JSD_SOURCE_ABORTED = 3, /* user aborted loading, some may be loaded */
JSD_SOURCE_FAILED = 4, /* loading failed, some may be loaded */
JSD_SOURCE_CLEARED = 5 /* text has been cleared by debugger */
} JSDSourceStatus;
/*
* Lock the entire source text subsystem. This grabs a highlevel lock that
* protects the JSD internal information about sources. It is important to
* wrap source text related calls in this lock in multithreaded situations
* -- i.e. where the debugger is running on a different thread than the
* interpreter (or the loader of sources) -- or when multiple debugger
* threads may be accessing this subsystem. It is safe (and best) to use
* this locking even if the environment might not be multi-threaded.
* Safely Nestable.
*/
extern JSD_PUBLIC_API(void)
JSD_LockSourceTextSubsystem(JSDContext* jsdc);
/*
* Unlock the entire source text subsystem. see JSD_LockSourceTextSubsystem.
*/
extern JSD_PUBLIC_API(void)
JSD_UnlockSourceTextSubsystem(JSDContext* jsdc);
/*
* Iterate the source test items. Use the same pattern of calls shown in
* the example for JSD_IterateScripts - NOTE that the SourceTextSubsystem.
* must be locked before and unlocked after iterating.
*/
extern JSD_PUBLIC_API(JSDSourceText*)
JSD_IterateSources(JSDContext* jsdc, JSDSourceText **iterp);
/*
* Find the source text item for the given URL (or filename - or whatever
* string the given embedding uses to describe source locations).
* Returns NULL is not found.
*/
extern JSD_PUBLIC_API(JSDSourceText*)
JSD_FindSourceForURL(JSDContext* jsdc, const char* url);
/*
* Get the URL string associated with the given source text item
*/
extern JSD_PUBLIC_API(const char*)
JSD_GetSourceURL(JSDContext* jsdc, JSDSourceText* jsdsrc);
/*
* Get the actual source text. This gives access to the actual storage of
* the source - it sHould *not* be written to.
* The buffer is NOT zero terminated (nor is it guaranteed to have space to
* hold a zero terminating char).
* XXX this is 8-bit character data. Unicode source is not yet supported.
*/
extern JSD_PUBLIC_API(JSBool)
JSD_GetSourceText(JSDContext* jsdc, JSDSourceText* jsdsrc,
const char** ppBuf, intN* pLen);
/*
* Clear the text -- delete the text and set the status to JSD_SOURCE_CLEARED.
* This is useful if source is done loading and the debugger wishes to store
* the text data itself (e.g. in a Java String). This allows avoidance of
* storing the same text in multiple places.
*/
extern JSD_PUBLIC_API(void)
JSD_ClearSourceText(JSDContext* jsdc, JSDSourceText* jsdsrc);
/*
* Return the status of the source text item. see JSDSourceStatus enum.
*/
extern JSD_PUBLIC_API(JSDSourceStatus)
JSD_GetSourceStatus(JSDContext* jsdc, JSDSourceText* jsdsrc);
/*
* Has the source been altered since the last call to JSD_SetSourceDirty?
* Use of JSD_IsSourceDirty and JSD_SetSourceDirty is still supported, but
* discouraged in favor of the JSD_GetSourceAlterCount system. This dirty
* scheme ASSUMES that there is only one consumer of the data.
*/
extern JSD_PUBLIC_API(JSBool)
JSD_IsSourceDirty(JSDContext* jsdc, JSDSourceText* jsdsrc);
/*
* Clear the dirty flag
*/
extern JSD_PUBLIC_API(void)
JSD_SetSourceDirty(JSDContext* jsdc, JSDSourceText* jsdsrc, JSBool dirty);
/*
* Each time a source text item is altered this value is incremented. Any
* consumer can store this value when they retieve other data about the
* source text item and then check later to see if the current value is
* different from their stored value. Thus they can know if they have stale
* data or not. NOTE: this value is not gauranteed to start at any given number.
*/
extern JSD_PUBLIC_API(uintN)
JSD_GetSourceAlterCount(JSDContext* jsdc, JSDSourceText* jsdsrc);
/*
* Force an increment in the alter count for a source text item. This is
* normally automatic when the item changes, but a give consumer may want to
* force this to amke an item appear to have changed even if it has not.
*/
extern JSD_PUBLIC_API(uintN)
JSD_IncrementSourceAlterCount(JSDContext* jsdc, JSDSourceText* jsdsrc);
/*
* Destroy *all* the source text items
* (new for server-side USE WITH CARE)
*/
extern JSD_PUBLIC_API(void)
JSD_DestroyAllSources( JSDContext* jsdc );
/* functions for adding source items */
/*
* Add a new item for a given URL. If an iten already exists for the given URL
* then the old item is removed.
* 'url' may not be NULL.
*
* ifdef LIVEWIRE url is treated as a char* and ownership is claimed by jsd
*/
extern JSD_PUBLIC_API(JSDSourceText*)
JSD_NewSourceText(JSDContext* jsdc, const char* url);
/*
* Append text (or change status -- e.g. set completed) for a source text
* item. Text need not be zero terminated. Callers should consider the returned
* JSDSourceText to be the 'current' item for future use. This may return NULL
* if called after this item has been replaced by a call to JSD_NewSourceText.
*/
extern JSD_PUBLIC_API(JSDSourceText*)
JSD_AppendSourceText(JSDContext* jsdc,
JSDSourceText* jsdsrc,
const char* text, /* *not* zero terminated */
size_t length,
JSDSourceStatus status);
/*
* Unicode varient of JSD_AppendSourceText.
*
* NOTE: At this point text is stored in 8bit ASCII so this function just
* extracts the bottom 8bits from each jschar. At some future point we may
* switch to storing and exposing 16bit Unicode.
*/
extern JSD_PUBLIC_API(JSDSourceText*)
JSD_AppendUCSourceText(JSDContext* jsdc,
JSDSourceText* jsdsrc,
const jschar* text, /* *not* zero terminated */
size_t length,
JSDSourceStatus status);
/*
* Convienence function for adding complete source of url in one call.
* same as:
* JSDSourceText* jsdsrc;
* JSD_LOCK_SOURCE_TEXT(jsdc);
* jsdsrc = jsd_NewSourceText(jsdc, url);
* if(jsdsrc)
* jsdsrc = jsd_AppendSourceText(jsdc, jsdsrc,
* text, length, JSD_SOURCE_PARTIAL);
* if(jsdsrc)
* jsdsrc = jsd_AppendSourceText(jsdc, jsdsrc,
* NULL, 0, JSD_SOURCE_COMPLETED);
* JSD_UNLOCK_SOURCE_TEXT(jsdc);
* return jsdsrc ? JS_TRUE : JS_FALSE;
*/
extern JSD_PUBLIC_API(JSBool)
JSD_AddFullSourceText(JSDContext* jsdc,
const char* text, /* *not* zero terminated */
size_t length,
const char* url);
/***************************************************************************/
/* Execution/Interrupt Hook functions */
/* possible 'type' params for JSD_ExecutionHookProc */
#define JSD_HOOK_INTERRUPTED 0
#define JSD_HOOK_BREAKPOINT 1
#define JSD_HOOK_DEBUG_REQUESTED 2
#define JSD_HOOK_DEBUGGER_KEYWORD 3
#define JSD_HOOK_THROW 4
/* legal return values for JSD_ExecutionHookProc */
#define JSD_HOOK_RETURN_HOOK_ERROR 0
#define JSD_HOOK_RETURN_CONTINUE 1
#define JSD_HOOK_RETURN_ABORT 2
#define JSD_HOOK_RETURN_RET_WITH_VAL 3
#define JSD_HOOK_RETURN_THROW_WITH_VAL 4
#define JSD_HOOK_RETURN_CONTINUE_THROW 5
/*
* Implement a callback of this form in order to hook execution.
*/
typedef uintN
(* JSD_ExecutionHookProc)(JSDContext* jsdc,
JSDThreadState* jsdthreadstate,
uintN type,
void* callerdata,
jsval* rval);
/* possible 'type' params for JSD_CallHookProc */
#define JSD_HOOK_TOPLEVEL_START 0 /* about to evaluate top level script */
#define JSD_HOOK_TOPLEVEL_END 1 /* done evaluting top level script */
#define JSD_HOOK_FUNCTION_CALL 2 /* about to call a function */
#define JSD_HOOK_FUNCTION_RETURN 3 /* done calling function */
/*
* Implement a callback of this form in order to hook function call/returns.
* Return JS_TRUE from a TOPLEVEL_START or FUNCTION_CALL type call hook if you
* want to hear about the TOPLEVEL_END or FUNCTION_RETURN too. Return value is
* ignored to TOPLEVEL_END and FUNCTION_RETURN type hooks.
*/
typedef JSBool
(* JSD_CallHookProc)(JSDContext* jsdc,
JSDThreadState* jsdthreadstate,
uintN type,
void* callerdata);
/*
* Set Hook to be called whenever the given pc is about to be executed --
* i.e. for 'trap' or 'breakpoint'
*/
extern JSD_PUBLIC_API(JSBool)
JSD_SetExecutionHook(JSDContext* jsdc,
JSDScript* jsdscript,
uintptr_t pc,
JSD_ExecutionHookProc hook,
void* callerdata);
/*
* Clear the hook for this pc
*/
extern JSD_PUBLIC_API(JSBool)
JSD_ClearExecutionHook(JSDContext* jsdc,
JSDScript* jsdscript,
uintptr_t pc);
/*
* Clear all the pc specific hooks for this script
*/
extern JSD_PUBLIC_API(JSBool)
JSD_ClearAllExecutionHooksForScript(JSDContext* jsdc, JSDScript* jsdscript);
/*
* Clear all the pc specific hooks for the entire JSRuntime associated with
* this JSDContext
*/
extern JSD_PUBLIC_API(JSBool)
JSD_ClearAllExecutionHooks(JSDContext* jsdc);
/*
* Set a hook to be called before the next instruction is executed. Depending
* on the threading situation and whether or not an JS code is currently
* executing the hook might be called before this call returns, or at some
* future time. The hook will continue to be called as each instruction
* executes until cleared.
*/
extern JSD_PUBLIC_API(JSBool)
JSD_SetInterruptHook(JSDContext* jsdc,
JSD_ExecutionHookProc hook,
void* callerdata);
/*
* Call the interrupt hook at least once per source line
*/
extern JSD_PUBLIC_API(JSBool)
JSD_EnableSingleStepInterrupts(JSDContext* jsdc, JSDScript *jsdscript, JSBool enable);
/*
* Clear the current interrupt hook.
*/
extern JSD_PUBLIC_API(JSBool)
JSD_ClearInterruptHook(JSDContext* jsdc);
/*
* Set the hook that should be called whenever a JSD_ErrorReporter hook
* returns JSD_ERROR_REPORTER_DEBUG.
*/
extern JSD_PUBLIC_API(JSBool)
JSD_SetDebugBreakHook(JSDContext* jsdc,
JSD_ExecutionHookProc hook,
void* callerdata);
/*
* Clear the debug break hook
*/
extern JSD_PUBLIC_API(JSBool)
JSD_ClearDebugBreakHook(JSDContext* jsdc);
/*
* Set the hook that should be called when the 'debugger' keyword is
* encountered by the JavaScript interpreter during execution.
*/
extern JSD_PUBLIC_API(JSBool)
JSD_SetDebuggerHook(JSDContext* jsdc,
JSD_ExecutionHookProc hook,
void* callerdata);
/*
* Clear the 'debugger' keyword hook
*/
extern JSD_PUBLIC_API(JSBool)
JSD_ClearDebuggerHook(JSDContext* jsdc);
/*
* Set the hook that should be called when a JS exception is thrown.
* NOTE: the 'do default' return value is: JSD_HOOK_RETURN_CONTINUE_THROW
*/
extern JSD_PUBLIC_API(JSBool)
JSD_SetThrowHook(JSDContext* jsdc,
JSD_ExecutionHookProc hook,
void* callerdata);
/*
* Clear the throw hook
*/
extern JSD_PUBLIC_API(JSBool)
JSD_ClearThrowHook(JSDContext* jsdc);
/*
* Set the hook that should be called when a toplevel script begins or completes.
*/
extern JSD_PUBLIC_API(JSBool)
JSD_SetTopLevelHook(JSDContext* jsdc,
JSD_CallHookProc hook,
void* callerdata);
/*
* Clear the toplevel call hook
*/
extern JSD_PUBLIC_API(JSBool)
JSD_ClearTopLevelHook(JSDContext* jsdc);
/*
* Set the hook that should be called when a function call or return happens.
*/
extern JSD_PUBLIC_API(JSBool)
JSD_SetFunctionHook(JSDContext* jsdc,
JSD_CallHookProc hook,
void* callerdata);
/*
* Clear the function call hook
*/
extern JSD_PUBLIC_API(JSBool)
JSD_ClearFunctionHook(JSDContext* jsdc);
/***************************************************************************/
/* Stack Frame functions */
/*
* Get the count of call stack frames for the given JSDThreadState
*/
extern JSD_PUBLIC_API(uintN)
JSD_GetCountOfStackFrames(JSDContext* jsdc, JSDThreadState* jsdthreadstate);
/*
* Get the 'current' call stack frame for the given JSDThreadState
*/
extern JSD_PUBLIC_API(JSDStackFrameInfo*)
JSD_GetStackFrame(JSDContext* jsdc, JSDThreadState* jsdthreadstate);
/*
* Get the JSContext for the given JSDThreadState
*/
extern JSD_PUBLIC_API(JSContext*)
JSD_GetJSContext(JSDContext* jsdc, JSDThreadState* jsdthreadstate);
/*
* Get the calling call stack frame for the given frame
*/
extern JSD_PUBLIC_API(JSDStackFrameInfo*)
JSD_GetCallingStackFrame(JSDContext* jsdc,
JSDThreadState* jsdthreadstate,
JSDStackFrameInfo* jsdframe);
/*
* Get the script for the given call stack frame
*/
extern JSD_PUBLIC_API(JSDScript*)
JSD_GetScriptForStackFrame(JSDContext* jsdc,
JSDThreadState* jsdthreadstate,
JSDStackFrameInfo* jsdframe);
/*
* Get the 'Program Counter' for the given call stack frame
*/
extern JSD_PUBLIC_API(uintptr_t)
JSD_GetPCForStackFrame(JSDContext* jsdc,
JSDThreadState* jsdthreadstate,
JSDStackFrameInfo* jsdframe);
/*
* Get the JavaScript Call Object for the given call stack frame.
* *** new for version 1.1 ****
*/
extern JSD_PUBLIC_API(JSDValue*)
JSD_GetCallObjectForStackFrame(JSDContext* jsdc,
JSDThreadState* jsdthreadstate,
JSDStackFrameInfo* jsdframe);
/*
* Get the head of the scope chain for the given call stack frame.
* the chain can be traversed using JSD_GetValueParent.
* *** new for version 1.1 ****
*/
extern JSD_PUBLIC_API(JSDValue*)
JSD_GetScopeChainForStackFrame(JSDContext* jsdc,
JSDThreadState* jsdthreadstate,
JSDStackFrameInfo* jsdframe);
/*
* Get the 'this' Object for the given call stack frame.
* *** new for version 1.1 ****
*/
extern JSD_PUBLIC_API(JSDValue*)
JSD_GetThisForStackFrame(JSDContext* jsdc,
JSDThreadState* jsdthreadstate,
JSDStackFrameInfo* jsdframe);
/*
* Get the name of the function executing in this stack frame. Especially useful
* for native frames (without script objects.)
* *** new for gecko 2.0 ****
*/
extern JSD_PUBLIC_API(JSString *)
JSD_GetIdForStackFrame(JSDContext* jsdc,
JSDThreadState* jsdthreadstate,
JSDStackFrameInfo* jsdframe);
/*
* True if stack frame represents a frame created as a result of a debugger
* evaluation.
*/
extern JSD_PUBLIC_API(JSBool)
JSD_IsStackFrameDebugger(JSDContext* jsdc,
JSDThreadState* jsdthreadstate,
JSDStackFrameInfo* jsdframe);
/*
* True if stack frame is constructing a new object.
*/
extern JSD_PUBLIC_API(JSBool)
JSD_IsStackFrameConstructing(JSDContext* jsdc,
JSDThreadState* jsdthreadstate,
JSDStackFrameInfo* jsdframe);