Mercurial > hg > truffle

comparison agent/doc/jsdb.html @ 0:a61af66fc99e jdk7-b24

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Initial load
author duke
date Sat, 01 Dec 2007 00:00:00 +0000
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:a61af66fc99e
1 <html>
2 <head>
3 <title>
4 JavaScript interface to Hotspot Serviceability Agent
5 </title>
6 </head>
7 <body>
8 <h1>JavaScript interface to Hotspot Serviceability Agent</h1>
9
10 <p>
11 Serviceability Agent (SA) provides Java API and tools to diagnose HotSpot Virtual Machine and
12 Java apps running on it. SA is a snapshot debugger -- can be used to observe state of a frozen java process or java core dump.
13 </p>
14
15 <h2>Existing SA APIs</h2>
16 <p>
17 There are two application programmer interfaces (APIs) for SA:
18 <dl>
19 <dt>1. Private java API
20 </dt>
21 <dd>
22 This tries to mimic hotspot VM's internal C++ classes and methods. Because VM data structures
23 are a moving target, this API can never be 'stable'! Besides, to use SA's private API knowledge of
24 HotSpot code base is essential.
25 </dd>
26 <dt>2. SA-JDI -- Java Debugger Interface read-only subset API
27 </dt>
28 <dd>
29 This is read-only subset of JDI (Java Debugger Interface)
30 This is a standardized interface to get java level state of a java process or java core dump. While this
31 interface is useful, this misses parts of java level state from target process or core such as
32 <ul>
33 <li>heap walking interface -- only objects traceable to static variables (of classes) and local
34 variables of stack frames can be accessed.
35 <li>re-constructing .class from debuggee are missing.
36 <li>re-constructing object mirrors for Java objects of the debuggee.
37 </ul>
38 </dd>
39 </dl>
40 </p>
41
42 <h2>SA Scripting interface</h2>
43
44 <p>
45 Traditionally, platform debuggers such as dbx, gdb and Solaris mdb (Module Debugger), provide a scripting
46 language interface. Scripting language interface provides easy-to-use, dynamically typed
47 interface to access data structures from debuggee. dbx and mdb even allow user to write
48 C/C++ modules to extend the scripting language commands.
49 </p>
50
51 <p>
52 SA provides SOQL - Simple Object Query Language -- a SQL-like query language to access
53 Java heap as an object database. SA's main GUI (HSDB) also exposes scripting interface of underlying debugger such as dbx, windbg.
54 But to use this interface, user has to learn scripting interface of multiple debugger back-ends such as dbx, windbg.
55 And these scripting interfaces are 'raw' in the sense that no java state is exposed -- only C/C++ state of VM is exposed.
56 Higher level SA services are not available through scripting interface.
57 </p>
58
59 <p>
60 <b>jsdb -- JavaScript Debugger</b> attempts to provide JavaScript interface to SA.
61 jsdb provides
62
63 <ul>
64 <li>high-level hotspot (and SA) independent scripting interface
65 <li>low-level SA-aware scripting interface.
66 </ul>
67 </p>
68
69 <h2>High level interface (Java State)</h2>
70
71 <b>jsdb</b> is a command line <a href="http://www.ecma-international.org/publications/standards/Ecma-262.htm">JavaScript</a> shell based on
72 <a href="http://www.mozilla.org/rhino/">Mozilla's Rhino JavaScript Engine</a>.
73 This command line utility attaches to Java process or core file or remote debug server and waits for user input.
74 This shell supports the following global functions and objects in addition to the standard JavaScript functions and
75 objects:
76
77 <h3>jdsb globals</h3>
78
79 <table border="1">
80 <tr>
81 <th>Function/Variable</th>
82 <th>Description</th>
83 </tr>
84 <tr>
85 <td>
86 address(jobject)
87 </td>
88 <td>
89 function that returns the address of the Java object as a string
90 </td>
91 </tr>
92 <td>
93 classof(jobject)
94 </td>
95 <td>
96 function that returns the JavaScript object that represents class object of the Java object
97 </td>
98 </tr>
99 <td>
100 dumpClass(jclass,[dir])
101 </td>
102 <td>
103 function that writes .class for the given Java Class. Optionally (second arg) accepts the directory where the
104 .class has to be written.
105 </td>
106 </tr>
107 <td>
108 help()
109 </td>
110 <td>
111 function that prints help message for global functions and objects
112 </td>
113 </tr>
114 <tr>
115 <td>
116 identityHash(jobject)
117 </td>
118 <td>
119 function that returns the identity hashCode of the Java object
120 </td>
121 </tr>
122 <tr>
123 <td>
124 mirror(jobject)
125 </td>
126 <td>
127 function that returns a local mirror of the Java object.
128 </td>
129 </tr>
130 <tr>
131 <td>
132 load([file1, file2,...])
133 </td>
134 <td>
135 function that loads zero or more JavaScript file(s). With no arguments, reads <stdin> for
136 JavaScript code.
137 </td>
138 </tr>
139 <tr>
140 <td>
141 object(string)
142 </td>
143 <td>
144 function that converts a string address into Java object
145 </td>
146 </tr>
147 <tr>
148 <td>
149 owner(jobject)
150 </td>
151 <td>
152 function that returns the owner thread of this monitor or null
153 </td>
154 </tr>
155 <tr>
156 <td>
157 sizeof(jobject)
158 </td>
159 <td>
160 function that returns the size of Java object in bytes
161 </td>
162 </tr>
163 <tr>
164 <td>
165 staticof(jclass, field)
166 </td>
167 <td>
168 function that returns the value of given field of the given Java class
169 </td>
170 </tr>
171 <tr>
172 <td>
173 print(expr1, expr2,...)
174 </td>
175 <td>
176 function that prints zero or more JavaScript expressions after converting those as strings
177 </td>
178 </tr>
179 <tr>
180 <td>
181 println(expr1, expr2..)
182 </td>
183 <td>
184 function that same as print, but prints a newline at the end
185 </td>
186 </tr>
187 <tr>
188 <td>
189 read([prompt])
190 </td>
191 <td>
192 function that reads a single line from standard input
193 </td>
194 </tr>
195 <tr>
196 <td>
197 quit()
198 </td>
199 <td>
200 function that quits the interactive load call as well as the shell
201 </td>
202 </tr>
203 <tr>
204 <td>
205 jvm
206 </td>
207 <td>
208 variable -- a JavaScript object that represents the target jvm that is being debugged
209 </td>
210 </tr>
211 </table>
212
213 <h3>jvm object</h3>
214
215 <p>
216 jvm object supports the following read-only properties.
217 </p>
218
219 <table border="1">
220 <tr>
221 <th>
222 Property name
223 </th>
224 <th>
225 Description
226 </th>
227 </tr>
228 <tr>
229 <td>
230 threads
231 </td>
232 <td>
233 array of Java threads from the debuggee
234 </td>
235 </tr>
236 <tr>
237 <td>
238 heap
239 </td>
240 <td>
241 object representing the heap of the debuggee
242 </td>
243 </tr>
244 <tr>
245 <td>
246 type
247 </td>
248 <td>
249 string value that is either "Server" or "Client" or "Core" -- the flavour of debuggee VM
250 </td>
251 </tr>
252 <tr>
253 <td>
254 bootClassPath
255 </td>
256 <td>
257 string value of bootclasspath of the debuggee
258 </td>
259 </tr>
260 <tr>
261 <td>
262 cpu
263 </td>
264 <td>
265 string value of cpu on which the debuggee runs/ran
266 </td>
267 </tr>
268 <tr>
269 <td>
270 sysProps
271 </td>
272 <td>
273 name-value pairs (JavaScript associative array) of Java System properties of the debuggee
274 </td>
275 </tr>
276 <tr>
277 <td>
278 addressSize
279 </td>
280 <td>
281 int value -- 32 for 32 bit debuggee, 64 for 64 bit debuggee
282 </td>
283 </tr>
284 <tr>
285 <td>
286 os
287 </td>
288 <td>
289 string value of OS on which the debuggee runs/ran
290 </td>
291 </tr>
292 <tr>
293 <td>
294 buildInfo
295 </td>
296 <td>
297 internal build info string from debuggee
298 </td>
299 </tr>
300 <tr>
301 <td>
302 flags
303 </td>
304 <td>
305 name-value pairs (JavaScript associative array) of JVM command line flags of the debuggee
306 </td>
307 </tr>
308 <tr>
309 <td>
310 classPath
311 </td>
312 <td>
313 string value of classpath of the debuggee
314 </td>
315 </tr>
316 <tr>
317 <td>
318 userDir
319 </td>
320 <td>
321 string value of user.dir System property of the debuggee
322 </td>
323 </tr>
324 </table>
325
326 <h3>heap object</h3>
327
328 <p>
329 heap object represents Java heap of the debuggee VM
330 </p>
331 <table border="1">
332 <tr>
333 <th>
334 Function or property name
335 </th>
336 <th>
337 Description
338 </th>
339 </tr>
340 <tr>
341 <td>
342 capacity
343 </td>
344 <td>
345 byte size of capacity of the heap
346 </td>
347 </tr>
348 <tr>
349 <td>
350 used
351 </td>
352 <td>
353 byte size of used portion (of live objects) of the heap
354 </td>
355 </tr>
356 <tr>
357 <td>
358 forEachObject(func, [class], [include subtypes -- true|false])
359 </td>
360 <td>
361 This function accepts a callback function 'func' and optionally class name and boolean arguments.
362 This function calls the callback for each Java object in the debuggee's heap. The optional class
363 argument may be used to receive objects of given class only. The third arguments specifies whether
364 to include objects of subtype of given class [or interface] or not. The default value of class is "java.lang.Object"
365 and and that of the third argument is true. i.e., by default all objects are included.
366 </td>
367 </tr>
368 <tr>
369 <td>
370 forEachClass(func, [initiating loader -- true|false])
371 </td>
372 <td>
373 This function accepts a callback function 'func'. This function iterates through the classes of the debuggee and calls the
374 callback for each class. The second parameter tells whether to pass initiating loader to the iterator callback or not.
375 </td>
376 </tr>
377 </table>
378
379 <h3>Accessing Java objects and arrays in script</h3>
380
381 <p>
382 From a given Java object, we can access all fields of the Java object by usual '.' operator. i.e., if you got a Java object
383 called 'o' of type java.lang.Thread from debuggee, you can access 'stackSize' field by o.stackSize syntax. Similarly, length of Java array
384 objects can be accessed by length property. And array indexing follows usual syntax. i.e., n'th element of array 'a' is
385 accessed by a[n].
386 </p>
387
388 <h3>jvm.threads array</h3>
389
390 <p>
391 This is a JavaScript array of Java threads of the debuggee. As usual, 'length' property tells the number of threads and individual
392 threads may be accessed by index operator -- i.e, jvm.threads[0] returns the first thread.
393 </p>
394
395 <h3>thread object</h3>
396
397
398 <p>
399 In addition to the fields of java.lang.Thread (or subclass) fields, thread objects have two additional properties.
400
401 <ul>
402 <li>frames -- array of stack frame objects
403 <li>monitors -- array of monitor objects owned by the thread
404 </ul>
405
406 </p>
407
408 <h3>stack frame object</h3>
409
410 <table border="1">
411 <tr>
412 <th>
413 Property name
414 </th>
415 <th>
416 Description
417 </th>
418 </tr>
419 <td>
420 thisObject
421 </td>
422 <td>
423 Object representing 'this' of the current frame [will be null for static methods]
424 </td>
425 </tr>
426 <tr>
427 <td>
428 locals
429 </td>
430 <td>
431 name-value pairs of local variables [JavaScript associative array]
432 </td>
433 </tr>
434 <tr>
435 <td>
436 line
437 </td>
438 <td>
439 Java source line number at which the frame is executing
440 </td>
441 </tr>
442 <tr>
443 <td>
444 bci
445 </td>
446 <td>
447 byte code index of the bytecode that the frame is executing
448 </td>
449 </tr>
450 <tr>
451 <td>
452 thread
453 </td>
454 <td>
455 thread to which this frame belongs
456 </td>
457 </tr>
458 <tr>
459 <td>
460 method
461 </td>
462 <td>
463 Java method that the frame is executing
464 </td>
465 </tr>
466 </table>
467
468 <h3>method object</h3>
469
470 <p>
471 method object represents a Java method of debuggee
472 </p>
473
474 <table border="1">
475 <tr>
476 <th>
477 Property name
478 </th>
479 <th>
480 Description
481 </th>
482 </tr>
483 <tr>
484 <td>
485 isStatic
486 </td>
487 <td>
488 boolean - true for static methods and false for non-static methods
489 </td>
490 </tr>
491
492 <tr>
493 <td>
494 isSynchronized
495 </td>
496 <td>
497 boolean - true for synchronized methods and false for non-synchronized methods
498 </td>
499 </tr>
500
501 <tr>
502 <td>
503 isNative
504 </td>
505 <td>
506 boolean - true for native methods and false for non-native methods
507 </td>
508 </tr>
509
510 <tr>
511 <td>
512 isProtected
513 </td>
514 <td>
515 boolean - true for protected methods and false for non-protected methods
516 </td>
517 </tr>
518
519 <tr>
520 <td>
521 isPrivate
522 </td>
523 <td>
524 boolean - true for private methods and false for non-private methods
525 </td>
526 </tr>
527
528 <tr>
529 <td>
530 isSynthetic
531 </td>
532 <td>
533 boolean - true for Javac generated synthetic methods and false for non-synthetic methods
534 </td>
535 </tr>
536
537 <tr>
538 <td>
539 isPackagePrivate
540 </td>
541 <td>
542 boolean - true for package-private methods and false for non-package-private methods
543 </td>
544 </tr>
545
546 <tr>
547 <td>
548 isPublic
549 </td>
550 <td>
551 boolean - true for public methods and false for non-public methods
552 </td>
553 </tr>
554
555 <tr>
556 <td>
557 holder
558 </td>
559 <td>
560 an object that represents Class that contains this method
561 </td>
562 </tr>
563
564 <tr>
565 <td>
566 signature
567 </td>
568 <td>
569 string -- signature of this method
570 </td>
571 </tr>
572
573 <tr>
574 <td>
575 isObsolete
576 </td>
577 <td>
578 boolean - true for obsolete (hotswapped) methods and false for non-obsolete methods
579 </td>
580 </tr>
581
582 <tr>
583 <td>
584 isStrict
585 </td>
586 <td>
587 boolean - true for strictfp methods and false for non-strictfp methods
588 </td>
589 </tr>
590
591 <tr>
592 <td>
593 isFinal
594 </td>
595 <td>
596 boolean - true for final methods and false for non-final methods
597 </td>
598 </tr>
599
600 <tr>
601 <td>
602 name
603 </td>
604 <td>
605 string - name of this method
606 </td>
607 </tr>
608 </table>
609
610 <h3>class object</h3>
611
612 <p>
613 A class object represents loaded Java class in debuggee VM. This represents java.lang.Class instance in the debuggee.
614 This is type of return value of classof global function. Also, method.holder property and field.holder are
615 of this type.
616 </p>
617
618 <table border="1">
619 <tr>
620 <th>
621 Property name
622 </th>
623 <th>
624 Description
625 </th>
626 </tr>
627
628 <tr>
629 <td>
630 name
631 </td>
632 <td>
633 name of this class
634 </td>
635 </tr>
636
637 <tr>
638 <td>
639 superClass
640 </td>
641 <td>
642 class object representing super class of this class
643 </td>
644 </tr>
645
646 <tr>
647 <td>
648 isArrayClass
649 </td>
650 <td>
651 boolean -- is the current class an array class?
652 </td>
653 </tr>
654
655 <tr>
656 <td>
657 isStatic
658 </td>
659 <td>
660 boolean -- is the current class static or not
661 </td>
662 </tr>
663
664 <tr>
665 <td>
666 isInterface
667 </td>
668 <td>
669 boolean -- is the current class an interface
670 </td>
671 </tr>
672
673 <tr>
674 <td>
675 isAbstract
676 </td>
677 <td>
678 boolean -- is the current class abstract or not
679 </td>
680 </tr>
681
682 <tr>
683 <td>
684 isProtected
685 </td>
686 <td>
687 boolean -- is the current class protected or not
688 </td>
689 </tr>
690
691 <tr>
692 <td>
693 isPrivate
694 </td>
695 <td>
696 boolean -- is the current class private or not
697 </td>
698 </tr>
699
700 <tr>
701 <td>
702 isPackagePrivate
703 </td>
704 <td>
705 boolean -- is the current class package private or not
706 </td>
707 </tr>
708
709 <tr>
710 <td>
711 isSynthetic
712 </td>
713 <td>
714 boolean -- is the current class synthetic or not
715 </td>
716 </tr>
717
718 <tr>
719 <td>
720 classLoader
721 </td>
722 <td>
723 object that represents ClassLoader object that loaded the current class
724 </td>
725 </tr>
726
727
728 <tr>
729 <td>
730 fields
731 </td>
732 <td>
733 array of static and instance fields of the current class
734 </td>
735 </tr>
736
737 <tr>
738 <td>
739 protectionDomain
740 </td>
741 <td>
742 protection domain to which current class belongs
743 </td>
744 </tr>
745
746 <tr>
747 <td>
748 isPublic
749 </td>
750 <td>
751 boolean -- is the current class public or not
752 </td>
753 </tr>
754
755 <tr>
756 <td>
757 signers
758 </td>
759 <td>
760 array of signers for current class
761 </td>
762 </tr>
763
764 <tr>
765 <td>
766 sourceFile
767 </td>
768 <td>
769 string -- name of the source file for current class
770 </td>
771 </tr>
772
773 <tr>
774 <td>
775 interfaces
776 </td>
777 <td>
778 array -- interfaces implemented by current class
779 </td>
780 </tr>
781
782 <tr>
783 <td>
784 isStrict
785 </td>
786 <td>
787 boolean -- is the current class strictfp or not
788 </td>
789 </tr>
790
791 <tr>
792 <td>
793 methods
794 </td>
795 <td>
796 array of methods (static and instance) of the current class
797 </td>
798 </tr>
799
800
801 <tr>
802 <td>
803 isFinal
804 </td>
805 <td>
806 boolean -- is the current class final or not
807 </td>
808 </tr>
809
810 <tr>
811 <td>
812 statics
813 </td>
814 <td>
815 name-value pairs (JavaScript associate array) of static fields of the current class
816 </td>
817 </tr>
818 </table>
819
820 <h3>field object</h3>
821 <p>
822 field represents a static or instance field of some class in debuggee
823 </p>
824
825 <table border="1">
826 <tr>
827 <th>
828 Property name
829 </th>
830 <th>
831 Description
832 </th>
833 </tr>
834
835 <tr>
836 <td>
837 isStatic
838 </td>
839 <td>
840 boolean -- is this field a static field?
841 </td>
842 </tr>
843
844 <tr>
845 <td>
846 holder
847 </td>
848 <td>
849 class that owns this field
850 </td>
851 </tr>
852
853 <tr>
854 <td>
855 signature
856 </td>
857 <td>
858 string signature of this field
859 </td>
860 </tr>
861
862 <tr>
863 <td>
864 isProtected
865 </td>
866 <td>
867 boolean - is this field a protected field or not?
868 </td>
869 </tr>
870
871 <tr>
872 <td>
873 isPrivate
874 </td>
875 <td>
876 boolean - is this field a private field or not?
877 </td>
878 </tr>
879
880 <tr>
881 <td>
882 isSynthetic
883 </td>
884 <td>
885 boolean - is this javac generated synthetic field or not?
886 </td>
887 </tr>
888
889 <tr>
890 <td>
891 isPackagePrivate
892 </td>
893 <td>
894 boolean - is this field a package private field or not?
895 </td>
896 </tr>
897
898 <tr>
899 <td>
900 isTransient
901 </td>
902 <td>
903 boolean - is this field a transient field or not?
904 </td>
905 </tr>
906
907 <tr>
908 <td>
909 isFinal
910 </td>
911 <td>
912 boolean - is this field final or not?
913 </td>
914 </tr>
915
916 <tr>
917 <td>
918 name
919 </td>
920 <td>
921 string - name of this field
922 </td>
923 </tr>
924
925 <tr>
926 <td>
927 isPublic
928 </td>
929 <td>
930 boolean - is this field public or not?
931 </td>
932 </tr>
933 </table>
934
935 <h3>Initialization Script</h3>
936 <p>
937 jsdb engine looks for initialization script file named <b>jsdb.js</b> in user's home directory. If found, it loads just after attaching to debuggee but before printing prompt for user's input. User can assume that s/he can access debuggee VM
938 state during initialization script.
939 </p>
940
941 <h3>Sample scripts</h3>
942
943 Semantics and knowledge of application classes (for eg. AppServer's classes) would be needed to create app specific
944 scripts. The following script samples are app-independent and provide a flavour of kind of scripts that can be written.
945
946 <h4>Script to print system properties of JVM</h4>
947
948 <pre>
949 <code>
950 jvm.sysProps.toString()
951 </code>
952 </pre>
953
954 <h4>Script to print JVM command line flags</h4>
955 <pre>
956 <code>
957 jvm.flags.toString()
958 </code>
959 </pre>
960
961
962 <h4>Script to print class-wise histogram of objects</h4>
963
964 <pre>
965 <code>
966
967 // associate array to hold histogram
968 var histo;
969 function func(obj) {
970 var classname = classof(obj).name;
971 if (histo[classname] == undefined) {
972 // first time we are visiting this class type
973 histo[classname] = 1;
974 } else {
975 histo[classname]++;
976 }
977 }
978
979 // iterate through java heap calling 'func' for each object
980 jvm.heap.forEachObject(func);
981
982 // print the histogram
983 for (i in histo) {
984 println('number of instances of ', i, ' = ', histo[i]);
985 }
986
987 </code>
988 </pre>
989
990 <h4>Script to print stack trace of all Java threads</h4>
991
992 <pre>
993 <code>
994
995 function printStackTrace(t) {
996 println(t.name);
997 println('');
998 for (i in t.frames) {
999 println(t.frames[i]);
1000 }
1001 println('');
1002 }
1003
1004 // walk through the list of threads and call printStackTrace
1005 // for each thread
1006 for (o in jvm.threads) {
1007 printStackTrace(jvm.threads[o]);
1008 }
1009
1010
1011 </code>
1012 </pre>
1013
1014
1015 <h4>Script to re-construct .class files for all non-bootstrap classes</h4>
1016
1017 <pre>
1018 <code>
1019
1020 function dump(cl) {
1021 if (!cl.isArrayClass && cl.classLoader != null) {
1022 // not an array class and a non-bootstrap class
1023 // create .class files in e:\tmp dir
1024 dumpClass(cl, "e:\\tmp);
1025 } else {
1026 println("skipping bootstrap class ", cl.name);
1027 }
1028 }
1029
1030 // walk thru heap and call callback for each java.lang.Class instance
1031 jvm.heap.forEachObject(dump, "java.lang.Class");
1032 </code>
1033 </pre>
1034
1035 <h4>Script to print paths of all java.io.File's currently accessed</h4>
1036
1037 <pre>
1038 <code>
1039
1040 function printFile(f) {
1041 // construct a mirror java.io.File here and
1042 // print absolute path here
1043 println(mirror(f).getAbsolutePath());
1044 }
1045
1046 jvm.heap.forEachObject(printFile, "java.io.File");
1047
1048 </code>
1049 </pre>
1050
1051 <h4>Script to print static fields of java.lang.Thread class</h4>
1052 <pre>
1053 <code>
1054
1055 var threadClass = classof("java.lang.Thread");
1056 for (i in threadClass.statics) {
1057 println(i, '=', threadClass.statics[i]);
1058 }
1059
1060 </code>
1061 </pre>
1062
1063 <h3>Low level interface (VM State)</h3>
1064
1065 <p>
1066 Low level jsdb interface works by <a href="http://www.mozilla.org/rhino/ScriptingJava.html">JavaScript-to-Java (previously known as "LiveConnect")
1067 interface</a> provided by Rhino JavaScript engine.
1068 </p>
1069
1070 <h2>sapkg object</h2>
1071 <p>
1072 This object provides short names for SA package names. For eg. instead of writing
1073 Packages.sun.jvm.hotspot.memory, we can write sapkg.memory.
1074 </p>
1075
1076 <h2>sa object</h2>
1077 <p>
1078 This object contains all SA singleton objects such as VM, Universe, SymbolTable,
1079 SystemDictionary, ObjectHeap, CollectedHeap, Debugger, CDebugger (if available),
1080 Interpreter, TypeDataBase and Threads. For eg. to access SymbolTable of Java debuggee,
1081 we can use sa.symbolTable. User can execute the following code to get fields of this object.
1082 </p>
1083 <pre>
1084 <code>
1085 for (i in sa) {
1086 println(i);
1087 }
1088 </code>
1089 </pre>
1090
1091 <h4>Heap Iterators</h4>
1092 <dl>
1093 <dt>forEachOop(callback)</dt>
1094 <dd>calls a callback function for each Oop in Java heap</dd>
1095 <dt>forEachOopOfKlass(callback, klass, [includeSubtypes])</dt>
1096 <dd>calls a callback function for each Oop of a give Klass type
1097 Optinally, third argument can specify whether to include subtype Oops
1098 or not.
1099 </dd>
1100 </dl>
1101
1102 <h4>System Dictionary Access</h4>
1103 <dl>
1104 <dt>forEachKlass(callback)</dt>
1105 <dd>calls a callback function for each Klass in Java heap</dd>
1106 <dt>forEachKlassAndLoader(callback)</dt>
1107 <dd>
1108 calls callback with Klass and initiating loader (Oop) for System dictionary
1109 entry.
1110 </dd>
1111 <dt>forEachPrimArrayKlass(callback)</dt>
1112 <dd>
1113 calls callback with Klass and initiating loader (Oop) for each
1114 primitive array Klass in the system.
1115 </dd>
1116 <dt>findInstanceKlass(name)</dt>
1117 <dd>
1118 finds the first instance klass with given name from System dictionary
1119 </dd>
1120 </dl>
1121
1122 <h4>Thread, Frame Iterators</h4>
1123 <dl>
1124 <dt>forEachJavaThread(callback)</dt>
1125 <dd>calls callback for each Java Thread</dd>
1126 <dt>forEachFrame(javaThread, callback)</dt>
1127 <dd>calls callback for each Frame of a given JavaThread</dd>
1128 <dt>forEachVFrame(javaThread, callback)</dt>
1129 <dd>calls callback for each JavaVFrame of a given JavaThread</dd>
1130 <dt>forEachThread(callback)</dt>
1131 <dd>calls callback for each (native) ThreadProxy (obtained by CDebugger.getThreadList)
1132 </dd>
1133 <dt>forEachCFrame(threadProxy, callback)</dt>
1134 <dd>
1135 calls callback for each CFrame of a given ThreadProxy object
1136 </dd>
1137 </dl>
1138
1139 <h4>Code blobs, Interpreter codelets</h4>
1140 <dl>
1141 <dt>forEachCodeBlob(callback)</dt>
1142 <dd>
1143 calls callback with each code blob in code cache
1144 </dd>
1145 <dt>findCodeBlob(address)</dt>
1146 <dd>
1147 finds the code blob, if any, that contains the given address.
1148 Returns null, on failure.
1149 </dd>
1150 <dt>findNMethod(address)</dt>
1151 <dd>
1152 finds the NMethod that contains given address.
1153 </dd>
1154 <dt>pcDescAt(addr)</dt>
1155 <dd>
1156 returns PCDesc at given address or null.
1157 </dd>
1158 <dt>forEachInterpCodelet(callbacl)</dt>
1159 <dd>
1160 calls callback with each Interpreter codelet
1161 </dd>
1162 </dl>
1163
1164 <h4>VM structs, constants</h4>
1165 <dl>
1166 <dt>forEachType(callback)</dt>
1167 <dd>
1168 calls callback for each Type in VM's type database
1169 </dd>
1170 <dt>forEachVMIntConst(callback)</dt>
1171 <dd>
1172 calls callback for each named integer constant. passes name
1173 as argument.
1174 </dd>
1175 <dt>forEachVMLongConst(callback)</dt>
1176 <dd>
1177 calls callback for each named long constant. passes name
1178 as argument.
1179 </dd>
1180 <dt>findVMType(name)</dt>
1181 <dd>
1182 finds a VM type by name. returns null if no known Type of given name
1183 exists in type database.
1184 </dd>
1185 <dt>findVMIntConst(name)</dt>
1186 <dd>
1187 finds an integer constant in type data base by name.
1188 </dd>
1189 <dt>findVMLongConst(name)</dt>
1190 <dd>
1191 finds an long constant in type data base by name.
1192 </dd>
1193 <dt>vmTypeof(addr)</dt>
1194 <dd>
1195 returns VM type of object at 'addr' if any. Else, returns null.
1196 </dd>
1197 <dt>isOfVMType(addr, type)</dt>
1198 <dd>
1199 returns whether object at 'addr' is of VM type 'type' or not.
1200 </dd>
1201 <dt>printVMType(type, addr)</dt>
1202 <dd>
1203 prints 'addr' as VM object of type 'type'
1204 </dd>
1205 <dt>print<i>XXX</i>(addr)</dt>
1206 <dd>
1207 For each VM type, these functions are defined. For eg. there is printUniverse,
1208 printSystemDictionary etc. are available. Without 'addr' being passed static fields are printed. With 'addr' param being passed, instance fields are printed.
1209 </dd>
1210 </dl>
1211
1212 <h4>Low level debugger facilities</h4>
1213 <dl>
1214 <dt>num2addr(number)</dt>
1215 <dd>
1216 converts a (long) number to SA Address instance
1217 </dd>
1218 <dt>str2addr(string)</dt>
1219 <dd>
1220 converts a given hex string to SA Address instance
1221 </dd>
1222 <dt>any2addr(any)</dt>
1223 <dd>
1224 Takes a number or a string or an Address and returns
1225 an Address instance. For other types, returns 'undefined'
1226 </dd>
1227 <dt>addr2str(addr)</dt>
1228 <dd>
1229 converts a given Address instance to a hex string
1230 </dd>
1231 <dt>addr2num(addr)</dt>
1232 <dd>
1233 converts a given Address instance to a (long) number
1234 </dd>
1235 <dt>sym2addr(library, symbol)</dt>
1236 <dd>
1237 returns Address of a given symbol in a given library (shared object or DLL)
1238 Example: sym2addr('jvm.dll', 'JNI_CreateJavaVM')
1239 <dt>addr2sym(addr)</dt>
1240 <dd>
1241 Returns nearest symbol to a given address (if any). If no such symbol is found,
1242 returns the given address as a string.
1243 </dd>
1244 <dt>readBytesAt(addr, num)</dt>
1245 <dd>
1246 returns 'num' bytes at 'addr' as a Java byte[]
1247 </dd>
1248 <dt>readWordsAt(addr, num)</dt>
1249 <dd>
1250 returns 'num' words at 'addr' as a Java long[]
1251 </dd>
1252 <dt>readCStrAt(addr)</dt>
1253 <dd>
1254 returns 'C' String at given address
1255 </dd>
1256 <dt>readCStrLen(addr)</dt>
1257 <dd>
1258 returns the length of the 'C' String at given address
1259 </dd>
1260 <dt>readRegs(threadProxy)</dt>
1261 <dd>
1262 returns register set (of Thread Context) of a given thread specified
1263 by threadProxy. return value is an associate array having name-value pairs
1264 of registers.
1265 </dd>
1266 <dt>regs(threadProxy)</dt>
1267 <dd>
1268 prints register set of a given thread.
1269 </dd>
1270 <dt>mem(addr, [num])</dt>
1271 <dd>
1272 prints 'num' words (address size) at 'addr'. Prints nearest symbol for address, if found.
1273 </dd>
1274 <dt>dis(addr, [num])</dt>
1275 <dd>prints native code disassembly of 'num' bytes at given address 'addr'.
1276 Default value of 'num' is 4. This automatically detects whether the given address
1277 inside a nmethod. If so, it prints safepoint info, entry points , method signature etc.
1278 of the nmethod.
1279 </dd>
1280 <dt>jdis(method [or addr])</dt>
1281 <dd>
1282 prints Java bytecode disassembly for given method Oop or address of a method Oop.
1283 </dd>
1284 <dt>nmethoddis(nmethod)</dt>
1285 <dd>
1286 prints disassembly of given nmethod object. Note that you don't have to call this directly
1287 instead use 'dis'.
1288 </dd>
1289 <dt>where</dt>
1290 <dd>
1291 prints Java stack trace for all Java threads
1292 </dd>
1293 </dl>
1294
1295 <h4>Miscellaneous</h4>
1296 <dl>
1297 <dt>addr2oop(addr)</dt>
1298 <dd>
1299 converts a given address to a Oop object
1300 </dd>
1301 <dt>oop2addr(oop)</dt>
1302 <dd>
1303 returns address of a given Oop object
1304 </dd>
1305 <dt>isOfVMType(addr, type)</dt>
1306 <dd>
1307 returns whether the given 'addr' points to a (C++) VM object of specified
1308 type. type may be specified by SA Type object or string name of the type.
1309 </dd>
1310 <dt>newVMObject(addr)</dt>
1311 <dd>
1312 returns instance of SA object for a given address (similar to SA VirtualConstructor
1313 interface).
1314 </dd>
1315 <dt>vmobj2addr(vmobject)</dt>
1316 <dd>
1317 returns Address represented by a given SA VMObject
1318 </dd>
1319 <dt>addr2vmobj(addr)</dt>
1320 <dd>same as newVMObject(addr)</dd>
1321 <dt>whatis(addr)</dt>
1322 <dd>
1323 returns string description of given address (using SA FindPointer and guess type API).
1324 <dt>isOop(addr)</dt>
1325 <dd>
1326 returns whether a given address is a valid Oop address or not
1327 </dd>
1328 </dl>
1329
1330 <h4>Moving b/w jsdb low level and high level interfaces</h4>
1331
1332 <p>
1333 Java objects of debuggee are represented by different script wrappers in high level
1334 interface. In the low-level interface these are instances of SA Oop class or its'
1335 subclass. To move b/w low-level and high-level interfaces the following functions may
1336 be used
1337 </p>
1338 <dl>
1339 <dt>oop2obj(oop)</dt>
1340 <dd>
1341 converts a given Oop object to a high-level wrapper object
1342 </dd>
1343 <dt>obj2oop(obj)</dt>
1344 <dd>
1345 converts a jsdb high level wrapper to underlying Oop instance
1346 </dd>
1347 </dl>
1348
1349 <h3>JavaScript tips</h3>
1350
1351 <ul>
1352 <li>to know properties, functions of any object, use the script
1353 <pre>
1354 <core>
1355 for(i in object) { println(i); }
1356 </code>
1357 </pre>
1358 <li>to view the source code of any function, just type the name of
1359 function in jsdb prompt
1360 <li>to view global functions, properties, run
1361 <pre>
1362 <code>
1363 for(i in this) { println(i); }
1364 </code>
1365 </pre>
1366 </ul>
1367
1368 </body>
1369 </html>