home *** CD-ROM | disk | FTP | other *** search
/ PC World 2001 March / PCWorld_2001-03_cd.bin / Software / Komercni / VAgeJava / ivj35 / setup / IDE.Cab / F10032_TRACE.TXT < prev    next >
Text File  |  2000-07-28  |  17KB  |  519 lines
  1. readme.txt for VA/Java Tracing VM
  2. ---------------------------------
  3.  
  4. This file contains the following sections:
  5.  
  6. 1. Description of Directory Contents
  7. 2. Installation
  8. 3. Tracing VM Overview
  9. 4. Description of Image Level API
  10. 5. Description of the User Support DLL API
  11.    5a. General Event Description
  12.    5b. Event Structure Description
  13. 6. The Support Library
  14.  
  15.  
  16. 1. Description of Directory Contents
  17. ------------------------------------
  18.  
  19. This directory contains the tracing version of the VA/Java environment.
  20.  
  21. For Windows and OS/2, this directory contains the following files:
  22.  
  23.    trace.txt           This file
  24.    api.jar             The VM API to be imported into VA/Java
  25.    ivjvm20.dll         The tracing Virtual Machine (VM) DLL
  26.    ivjijs20.dll        The tracing VM support DLL
  27.    trace.dll           Sample user tracing DLL
  28.  
  29. For Unix, this directory contains the following files:
  30.  
  31.    trace.txt           This file
  32.    api.jar             The VM API to be imported into VA/Java
  33.    ide                 The tracing Virtual Machine (VM)
  34.    libivjijs20.so      The tracing VM support shared library
  35.    libtrace.so         Sample user tracing shared library
  36.  
  37. This directory contains the following subdirectories:
  38.  
  39.    include             Support include files for building user tracing DLLs
  40.    lib                 Support library files for building user tracing DLLs
  41.    trace               Sample user tracing DLL source code
  42.  
  43. All references to "dynamic link library" and "DLL" should be assumed to mean
  44. "shared library" for Unix systems, unless otherwise noted.  As well, when
  45. references are made to a DLL of the name "foo.dll", the name should be changed
  46. to meet Unix standards, e.g., "libfoo.so".
  47.  
  48.  
  49. 2. Installation
  50. ---------------
  51.  
  52. Before installing for Windows or OS/2, it is recommended that the file,
  53.  
  54.    ivjvm20.dll
  55.  
  56. be backed up, as the installation overwrites this file.  Since the tracing
  57. VM runs slightly slower in non-tracing mode than the standard VM, development
  58. is typically done with the latter.
  59.  
  60. For Unix, the file to back up is,
  61.  
  62.    ide.
  63.  
  64. To install, recursively copy the current directory up into the program
  65. directory of the VA/Java environment.
  66.  
  67.  
  68. 3. Tracing VM Overview
  69. ----------------------
  70.  
  71. The tracing VM system consists of three parts; i) The tracing VM, ii) The
  72. VM level API, iii) The user support DLL.
  73.  
  74. The tracing VM is an extended VM with hooks that call out to a user DLL when
  75. particular events occur.  This is driven by the VM level API, which specifies
  76. what DLL to call (the user DLL), and what events to report.
  77.  
  78. The image level API is a low level interface to the tracing VM, and provides
  79. the necessary support for more elaborate statistics gathering applications.
  80. The API allows the user to customize what events are reported to the user DLL
  81. automatically by the VM, as well as the ability to manually trigger certain
  82. events.
  83.  
  84. The user DLL acts as the event handler for the tracing VM.  It contains 
  85. specific functions that are called by the VM when events occur.  The user
  86. DLL allows the application programer to customize how events are monitored,
  87. recorded, etc., by modifying the standard user DLL functions.
  88.  
  89.  
  90. 4. Description of Image Level API
  91. ---------------------------------
  92.  
  93. The image level API must be used in conjunction with a user tracing DLL 
  94. (described in section 5).
  95.  
  96. There are two classes used to control the tracing VM,
  97.  
  98.    com.ibm.uvm.instrumenting.InstrumentVMSupport
  99.    com.ibm.uvm.instrumenting.InstrumentVMException
  100.  
  101. All methods described are found in,
  102.  
  103.    com.ibm.uvm.instrumenting.InstrumentVMSupport, 
  104.  
  105. with any constants declared as "public static final".  The exception class is
  106. used to report errors during any of the tracing calls.
  107.  
  108. Each of the first four calls have a corresponding function in the user support
  109. DLL, and is derived by capitalizing the leading letter and prepending 
  110. "Instrument". E.g.,
  111.  
  112.    (Java method) tracingStartup() -> (C function) InstrumentTracingStartup()
  113.  
  114.    1. tracingStartup(String libraryName);
  115.  
  116.    Opens the user tracing DLL to allow any necessary pre-tracing initialization
  117.    to occur.  The DLL opened is specified in a platform independent way.  E.g.,
  118.    if the DLL name "trace" is specified, this signifies the DLL "trace.dll" on
  119.    Windows or OS/2, and "libtrace.so" on Unix platforms.  This call must be
  120.    made before the VM can enter tracing mode.
  121.  
  122.    2. tracingShutdown();
  123.  
  124.    Closes the user tracing DLL opened by tracingStartup(String libraryName) to
  125.    allow any necessary post-tracing management.
  126.  
  127.    3. tracingBegin(int flags);
  128.  
  129.    Turn tracing mode on with event reporting mode set to "flags".  The VM will
  130.    begin reporting tracing events to the user DLL with the types and format of
  131.    the events described by the following flags:
  132.  
  133.    (Note: In each case, exactly one flag from each group should be chosen.
  134.    Flags should be |'d (binary OR'ed) together before being passed).
  135.  
  136.       InsTrcTypeExeOn
  137.       InsTrcTypeExeOnLight
  138.       InsTrcTypeExeOff
  139.  
  140.       The execution tracing type describes what is reported for method entry
  141.       and exit events.  "On" reports method entry and exits.  "OnLight" reports
  142.       method entry.  "Off" reports no method events.
  143.  
  144.       InsTrcTypeGCOn
  145.       InsTrcTypeGCOnLight
  146.       InsTrcTypeGCOff
  147.  
  148.       The GC tracing type describes what is reported for memory management
  149.       events.  "On" reports when scavenges and global garbage collects start
  150.       and end, as well as all object movements and deletions that occur.
  151.       "OnLight" reports when scavenges and global garbage collects start and
  152.       end.  "Off" reports no memory management events.
  153.  
  154.       InsTrcTypeAllocOn
  155.       InsTrcTypeAllocOff
  156.  
  157.       The allocation tracing type describes what is reported for object
  158.       allocation events.  "On" reports all object allocates.  "Off" reports no
  159.       allocation events.
  160.  
  161.    4. tracingEnd();
  162.  
  163.    Turn tracing mode off, but keeps the user DLL active.
  164.  
  165.    5. reportObjectReferences();
  166.  
  167.    Report each object ID currently in the image, and any non-null object
  168.    pointer contained in each object.  This is a heavy weight operation, and is
  169.    made from user code at critical places to determine object connection
  170.    graphs.
  171.  
  172.    6. userEvent(String message);
  173.  
  174.    Report that a user specified event has occurred with the string "message".
  175.    This call is made from user code to signal points of interest.
  176.  
  177.  
  178. 5. Description of the User Support DLL API
  179. ------------------------------------------
  180.  
  181. All constants mentioned in this section can be found in:
  182.    .\include\itrccnst.h
  183.  
  184. All structures mentioned in this section can be found in:
  185.    .\include\itrcstrt.h
  186.  
  187. A sample version of the user tracing DLL can be found in:
  188.    .\trace\*.*
  189.  
  190. Each of the following should be exported from the user DLL when it is compiled
  191. and linked.
  192.  
  193.    1. unsigned long InstrumentTraceStartup(unsigned long vmID)
  194.  
  195.    Called when tracingStartup(String) is called at the image level.
  196.    Tracing mode is not yet active.
  197.  
  198.    2. unsigned long InstrumentTraceShutdown()
  199.  
  200.    Called when tracingShutdown() is called at the image level.
  201.    Tracing mode is not active.
  202.  
  203.    3. unsigned long InstrumentTraceBegin(
  204.          unsigned long vmID,
  205.          unsigned long flags)
  206.  
  207.    Called when tracingBegin(int) is called at the image level.
  208.  
  209.    4. unsigned long InstrumentTraceEnd()
  210.  
  211.    Called when tracingEnd() is called at the image level.
  212.  
  213.    5. unsigned long InstrumentTraceEvent(struct InsEventInfo *event)
  214.  
  215.    For any event generated either implicitly (e.g., method entry) or through
  216.    image API, InstrumentTraceEvent() is called.
  217.  
  218.    Both types of event structures begin with the InsEventHeader structure,
  219.    which contains the event which occurred (listed under InsTrcEvent*), and
  220.    the VM ID code, which is used in the support library (described in section
  221.    6).
  222.  
  223.    Note that both types of events consist of a union of structures; the event
  224.    code determines what structure describes the data allocated.
  225.  
  226. 5a. General Event Description
  227. -----------------------------
  228.  
  229.    Each event is described by an event code and its data.  Below are a
  230.    description of the events provided by the tracing VM.
  231.  
  232.    InsTrcEventMethodEnter
  233.    InsTrcEventMethodLeave
  234.  
  235.       The enter/exit events describe invoking and returning from a particular
  236.       method.
  237.  
  238.    InsTrcEventScavengeStart
  239.    InsTrcEventScavengeEnd
  240.    InsTrcEventGGCStart
  241.    InsTrcEventGGCEnd
  242.  
  243.       The memory management start/stop events describe when the VM has entered
  244.       a garbage collection phase, and when it is a local garbage collect
  245.       (Scavenge) or global garbage collect (GGC).
  246.  
  247.    InsTrcEventOIDRename
  248.    InsTrcEventOIDRangeRename
  249.  
  250.       Report the renaming (movement) of an object from one ID to another, or
  251.       a range of objects from one to other.
  252.  
  253.    InsTrcEventOIDDelete
  254.    InsTrcEventOIDRangeDelete
  255.  
  256.       Report the deletion (collection) of an object ID, or the range of object
  257.       IDs.  These events occur only during a garbage collection phase.
  258.  
  259.    InsTrcEventAllocate
  260.  
  261.       Report an object ID when the object is allocated.
  262.  
  263.    InsTrcEventStartFieldReport
  264.    InsTrcEventFieldReport
  265.    InsTrcEventEndFieldReport
  266.  
  267.       These events are triggered by reportObjectFields(), and describe the
  268.       contents of every object in the image.  The start field describes the
  269.       object being reported, field report describes a non-nil object pointer
  270.       inside the object being described, and end field signifies the end of
  271.       field reporting for a particular object.
  272.  
  273.    InsTrcEventUserEvent
  274.  
  275.       This event is triggered by userEvent(String), and contains the message
  276.       supplied by the user.
  277.  
  278. 5b. Event Structure Description
  279. -------------------------------
  280.  
  281.    Each structure has its corresponding event codes and members described.
  282.  
  283.    1. InsEventTypeMethod
  284.  
  285.    struct InsEventTypeMethod {
  286.       unsigned long methodEventFlags;
  287.       unsigned long stackDepth;
  288.       unsigned long receiver;
  289.       char *methodName;
  290.       unsigned long methodNameSize;
  291.       char *className;
  292.       unsigned long classNameSize;
  293.    };
  294.  
  295.    Used by events:
  296.       InsTrcEventMethodEnter
  297.       InsTrcEventMethodLeave
  298.  
  299.    Members:
  300.       methodEventFlags - Describe method type and string format as follows:
  301.          InstrumentMethodEventMethodDB
  302.             Method name string is wide character format
  303.          InstrumentMethodEventClassDB
  304.             Class name string is wide character format
  305.          InstrumentMethodEventStatic
  306.             Method is static
  307.          InstrumentMethodEventNative
  308.             Method is native
  309.          InstrumentMethodEventSync
  310.             Method is synchronized
  311.       stackDepth - Stack depth of the current method
  312.       receiver - The object ID of the receiver
  313.       methodName - Non-NULL terminated method name
  314.       methodNameSize - Length of the methodName
  315.       className - Non-NULL terminated class name
  316.       classNameSize - Length of className
  317.  
  318.       Notes:
  319.        1) For statics, the receiver is the internal VM class object ID, and is
  320.        affected by object renaming events.
  321.  
  322.    2. InsEventTypeOIDRename
  323.  
  324.    struct InsEventTypeOIDRename {
  325.       unsigned long source;
  326.       unsigned long destination;
  327.    };
  328.  
  329.    Used by event:
  330.       InsTrcEventOIDRename
  331.  
  332.    Members:
  333.       source - object ID to be renamed
  334.       destination - object ID that source is renamed to.
  335.  
  336.    3. InsEventTypeOIDRangeRename
  337.  
  338.    struct InsEventTypeOIDRangeRename {
  339.       unsigned long sourceStart;
  340.       unsigned long sourceEnd;
  341.       unsigned long destination;
  342.    };
  343.  
  344.    Used by event:
  345.       InsTrcEventOIDRangeRename
  346.  
  347.    Members:
  348.       sourceStart - closed lower bound of object ID range to rename
  349.       sourceEnd - open upper bound of object ID range to rename
  350.       destination - starting object ID that the range is renamed to
  351.  
  352.    4. InsEventTypeOIDDelete
  353.  
  354.    struct InsEventTypeOIDDelete {
  355.       unsigned long oid;
  356.    };
  357.  
  358.    Used by event:
  359.       InsTrcEventOIDDelete
  360.  
  361.    Members:
  362.       oid - object ID to delete
  363.  
  364.    5. InsEventTypeOIDRangeDelete
  365.  
  366.    struct InsEventTypeOIDRangeDelete {
  367.       unsigned long start;
  368.       unsigned long end;
  369.    };
  370.  
  371.    Used by event:
  372.       InsTrcEventOIDRangeDelete
  373.  
  374.    Members:
  375.       start - closed lower bound of object ID range to delete
  376.       end - open upper bound of object ID range to delete
  377.  
  378.    6. InsEventTypeAllocate
  379.  
  380.    struct InsEventTypeAllocObj { /* Private */
  381.       unsigned long allocEventFlags;
  382.       char *className;
  383.       unsigned long classNameSize;
  384.    };
  385.    struct InsEventTypeAllocArrObj { /* Private */
  386.       char *className;
  387.       unsigned long classNameSize;
  388.       unsigned long arity;
  389.    };
  390.    struct InsEventTypeAllocate {
  391.       unsigned long oid;
  392.       unsigned long sizeInLongs;
  393.       unsigned long arrayFlag;
  394.       union {
  395.          struct InsEventTypeAllocObj object;
  396.          struct InsEventTypeAllocArrObj array;
  397.          } allocBody;
  398.       };
  399.  
  400.    Used by event:
  401.       InsTrcEventAllocate
  402.  
  403.    Members (struct InsEventTypeAllocate):
  404.       oid - object ID being allocated
  405.       sizeInLongs - the number of 32 bit words the object requires for storage
  406.       arrayFlag - Determine what union member is used for allocation
  407.          description as follows:
  408.             0 - struct InsEventTypeAllocObj object;
  409.             1 - struct InsEventTypeAllocArrObj array;
  410.  
  411.    Members (struct InsEventTypeAllocObj):
  412.       allocEventFlags - Describe allocate class name format as follows:
  413.          InstrumentAllocEventClassDB
  414.             Class name string is wide character format
  415.       className - Non-NULL terminated class name
  416.       classNameSize - Length of className
  417.  
  418.    Members (struct InsEventTypeAllocArrObj):
  419.       className - Name of array type non-null terminated
  420.       classNameSize - Length of className
  421.       arity - array is N dimensional, where N > 1.
  422.  
  423.       Notes: If the className is NULL, the arity field determines whether the
  424.       object is an array of objects (arity == 0) or an array of arrays
  425.       (arity == 1).  At allocation, the exact type of object used for the 
  426.       array is not detectable.
  427.  
  428.    7. InsEventTypeStartFieldReport
  429.  
  430.    struct InsEventTypeStartFieldReport {
  431.       unsigned long oid;
  432.       unsigned long type;
  433.       unsigned long reportEventFlags;
  434.       char *className;
  435.       unsigned long classNameSize;
  436.    };
  437.  
  438.    Used by event:
  439.       InsTrcEventStartFieldReport
  440.  
  441.    Members:
  442.       oid - object ID being reported
  443.       type - The type of object being described as follows:
  444.          InstrumentFREventTypeJava
  445.             oid is a Java object
  446.          InstrumentFREventTypeJavaArray
  447.             oid is a Java Array (className[Size] is not valid)
  448.          InstrumentFREventTypeJavaClass
  449.             oid is a Java Class
  450.       reportEventFlags - Describe report object class name format as follows:
  451.          InstrumentReportEventClassDB
  452.             Class name string is wide character format
  453.       className - Non-NULL terminated class name of oid
  454.       classNameSize - Length of className
  455.  
  456.    8. InsEventTypeFieldReport
  457.  
  458.    struct InsEventTypeFieldReport {
  459.       unsigned long oid;
  460.    };
  461.  
  462.    Used by event:
  463.       InsTrcEventFieldReport
  464.  
  465.    Members:
  466.       oid - object ID contained in the object being reported
  467.  
  468.    9. InsEventTypeUserEvent
  469.  
  470.    struct InsEventTypeUserEvent {
  471.       unsigned long msgEventFlags;
  472.       char *msg;
  473.       unsigned long msgSize;
  474.    };
  475.  
  476.    Used by event:
  477.       InsTrcEventUserEvent
  478.  
  479.    Members:
  480.       msgEventFlags - Describe the msg member format as follows:
  481.          InstrumentUserEventDB
  482.             message string is wide character format
  483.       msg - Non-NULL terminated message supplied by the user
  484.       msgLength - Length of msg
  485.  
  486.  
  487. 6. The Support Library
  488. ----------------------
  489.  
  490. The library .\lib\ivjitrcs.lib is a support library containing routines that
  491. enhance the information provided by tracing events.  For each function,
  492. "vmID" is found in the event header.  The return value is zero on success, 
  493. non-zero on failure.
  494.  
  495. unsigned long InstrumentSupportCurrentThreadDetails(
  496.     unsigned long vmID,
  497.     unsigned long *flags,
  498.     char **name,
  499.     unsigned long *nameLength,
  500.     long *priority,
  501.     char **groupName,
  502.     unsigned long *groupNameLength)
  503.  
  504.    Return the pointer to the thread name as well as its length, the thread
  505.    priority, and the thread group name as well as its length.
  506.    "flags" can be tagged as:
  507.       InstrumentThreadNameDB
  508.          "name" is in wide character mode.
  509.       InstrumentThreadGroupNameDB
  510.          "groupName" is in wide character mode.
  511.  
  512.    Notes:
  513.    1) This routine is not to be called during memory management related
  514.    events, i.e., between the start and end of scavenge or global garbage
  515.    collect events.
  516.    2) The thread with the name, priority and group name of "<ide>", -1 and
  517.    "<ide>" should be treated as a special case internal VM thread.
  518.  
  519.