Mercurial > jdk8-mips64-public > hotspot / file revision
agent/doc/jsdb.html@7b4fb6089361
agent/doc/jsdb.html
Thu, 21 Apr 2011 19:49:49 -0700
- author
- trims
- date
- Thu, 21 Apr 2011 19:49:49 -0700
- changeset 2771
- 7b4fb6089361
- parent 0
- f90c822e73f8
- permissions
- -rw-r--r--
Added tag hs21-b09 for changeset 611e19a16519
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>
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>
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>
42 <h2>SA Scripting interface</h2>
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>
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>
59 <p>
60 <b>jsdb -- JavaScript Debugger</b> attempts to provide JavaScript interface to SA.
61 jsdb provides
63 <ul>
64 <li>high-level hotspot (and SA) independent scripting interface
65 <li>low-level SA-aware scripting interface.
66 </ul>
67 </p>
69 <h2>High level interface (Java State)</h2>
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:
77 <h3>jdsb globals</h3>
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>
213 <h3>jvm object</h3>
215 <p>
216 jvm object supports the following read-only properties.
217 </p>
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>
326 <h3>heap object</h3>
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>
379 <h3>Accessing Java objects and arrays in script</h3>
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>
388 <h3>jvm.threads array</h3>
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>
395 <h3>thread object</h3>
398 <p>
399 In addition to the fields of java.lang.Thread (or subclass) fields, thread objects have two additional properties.
401 <ul>
402 <li>frames -- array of stack frame objects
403 <li>monitors -- array of monitor objects owned by the thread
404 </ul>
406 </p>
408 <h3>stack frame object</h3>
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>
468 <h3>method object</h3>
470 <p>
471 method object represents a Java method of debuggee
472 </p>
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>
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>
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>
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>
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>
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>
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>
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>
555 <tr>
556 <td>
557 holder
558 </td>
559 <td>
560 an object that represents Class that contains this method
561 </td>
562 </tr>
564 <tr>
565 <td>
566 signature
567 </td>
568 <td>
569 string -- signature of this method
570 </td>
571 </tr>
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>
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>
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>
600 <tr>
601 <td>
602 name
603 </td>
604 <td>
605 string - name of this method
606 </td>
607 </tr>
608 </table>
610 <h3>class object</h3>
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>
618 <table border="1">
619 <tr>
620 <th>
621 Property name
622 </th>
623 <th>
624 Description
625 </th>
626 </tr>
628 <tr>
629 <td>
630 name
631 </td>
632 <td>
633 name of this class
634 </td>
635 </tr>
637 <tr>
638 <td>
639 superClass
640 </td>
641 <td>
642 class object representing super class of this class
643 </td>
644 </tr>
646 <tr>
647 <td>
648 isArrayClass
649 </td>
650 <td>
651 boolean -- is the current class an array class?
652 </td>
653 </tr>
655 <tr>
656 <td>
657 isStatic
658 </td>
659 <td>
660 boolean -- is the current class static or not
661 </td>
662 </tr>
664 <tr>
665 <td>
666 isInterface
667 </td>
668 <td>
669 boolean -- is the current class an interface
670 </td>
671 </tr>
673 <tr>
674 <td>
675 isAbstract
676 </td>
677 <td>
678 boolean -- is the current class abstract or not
679 </td>
680 </tr>
682 <tr>
683 <td>
684 isProtected
685 </td>
686 <td>
687 boolean -- is the current class protected or not
688 </td>
689 </tr>
691 <tr>
692 <td>
693 isPrivate
694 </td>
695 <td>
696 boolean -- is the current class private or not
697 </td>
698 </tr>
700 <tr>
701 <td>
702 isPackagePrivate
703 </td>
704 <td>
705 boolean -- is the current class package private or not
706 </td>
707 </tr>
709 <tr>
710 <td>
711 isSynthetic
712 </td>
713 <td>
714 boolean -- is the current class synthetic or not
715 </td>
716 </tr>
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>
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>
737 <tr>
738 <td>
739 protectionDomain
740 </td>
741 <td>
742 protection domain to which current class belongs
743 </td>
744 </tr>
746 <tr>
747 <td>
748 isPublic
749 </td>
750 <td>
751 boolean -- is the current class public or not
752 </td>
753 </tr>
755 <tr>
756 <td>
757 signers
758 </td>
759 <td>
760 array of signers for current class
761 </td>
762 </tr>
764 <tr>
765 <td>
766 sourceFile
767 </td>
768 <td>
769 string -- name of the source file for current class
770 </td>
771 </tr>
773 <tr>
774 <td>
775 interfaces
776 </td>
777 <td>
778 array -- interfaces implemented by current class
779 </td>
780 </tr>
782 <tr>
783 <td>
784 isStrict
785 </td>
786 <td>
787 boolean -- is the current class strictfp or not
788 </td>
789 </tr>
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>
801 <tr>
802 <td>
803 isFinal
804 </td>
805 <td>
806 boolean -- is the current class final or not
807 </td>
808 </tr>
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>
820 <h3>field object</h3>
821 <p>
822 field represents a static or instance field of some class in debuggee
823 </p>
825 <table border="1">
826 <tr>
827 <th>
828 Property name
829 </th>
830 <th>
831 Description
832 </th>
833 </tr>
835 <tr>
836 <td>
837 isStatic
838 </td>
839 <td>
840 boolean -- is this field a static field?
841 </td>
842 </tr>
844 <tr>
845 <td>
846 holder
847 </td>
848 <td>
849 class that owns this field
850 </td>
851 </tr>
853 <tr>
854 <td>
855 signature
856 </td>
857 <td>
858 string signature of this field
859 </td>
860 </tr>
862 <tr>
863 <td>
864 isProtected
865 </td>
866 <td>
867 boolean - is this field a protected field or not?
868 </td>
869 </tr>
871 <tr>
872 <td>
873 isPrivate
874 </td>
875 <td>
876 boolean - is this field a private field or not?
877 </td>
878 </tr>
880 <tr>
881 <td>
882 isSynthetic
883 </td>
884 <td>
885 boolean - is this javac generated synthetic field or not?
886 </td>
887 </tr>
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>
898 <tr>
899 <td>
900 isTransient
901 </td>
902 <td>
903 boolean - is this field a transient field or not?
904 </td>
905 </tr>
907 <tr>
908 <td>
909 isFinal
910 </td>
911 <td>
912 boolean - is this field final or not?
913 </td>
914 </tr>
916 <tr>
917 <td>
918 name
919 </td>
920 <td>
921 string - name of this field
922 </td>
923 </tr>
925 <tr>
926 <td>
927 isPublic
928 </td>
929 <td>
930 boolean - is this field public or not?
931 </td>
932 </tr>
933 </table>
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>
941 <h3>Sample scripts</h3>
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.
946 <h4>Script to print system properties of JVM</h4>
948 <pre>
949 <code>
950 jvm.sysProps.toString()
951 </code>
952 </pre>
954 <h4>Script to print JVM command line flags</h4>
955 <pre>
956 <code>
957 jvm.flags.toString()
958 </code>
959 </pre>
962 <h4>Script to print class-wise histogram of objects</h4>
964 <pre>
965 <code>
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 }
979 // iterate through java heap calling 'func' for each object
980 jvm.heap.forEachObject(func);
982 // print the histogram
983 for (i in histo) {
984 println('number of instances of ', i, ' = ', histo[i]);
985 }
987 </code>
988 </pre>
990 <h4>Script to print stack trace of all Java threads</h4>
992 <pre>
993 <code>
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 }
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 }
1011 </code>
1012 </pre>
1015 <h4>Script to re-construct .class files for all non-bootstrap classes</h4>
1017 <pre>
1018 <code>
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 }
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>
1035 <h4>Script to print paths of all java.io.File's currently accessed</h4>
1037 <pre>
1038 <code>
1040 function printFile(f) {
1041 // construct a mirror java.io.File here and
1042 // print absolute path here
1043 println(mirror(f).getAbsolutePath());
1044 }
1046 jvm.heap.forEachObject(printFile, "java.io.File");
1048 </code>
1049 </pre>
1051 <h4>Script to print static fields of java.lang.Thread class</h4>
1052 <pre>
1053 <code>
1055 var threadClass = classof("java.lang.Thread");
1056 for (i in threadClass.statics) {
1057 println(i, '=', threadClass.statics[i]);
1058 }
1060 </code>
1061 </pre>
1063 <h3>Low level interface (VM State)</h3>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
1330 <h4>Moving b/w jsdb low level and high level interfaces</h4>
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>
1349 <h3>JavaScript tips</h3>
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>
1368 </body>
1369 </html>
