src/WINNT/client_osi/osidebug.rtf

   1 {\rtf1\ansi
   2
   3 {\fonttbl
   4 \f0\froman Times New Roman;
   5 \f1\fdecor Courier New;}
   6
   7 {\colortbl
   8 \red0\green0\blue0;
   9 \red255\green0\blue0;
  10 \red0\green0\blue255;
  11 \red255\green255\blue0;}
  12
  13 \sb200
  14
  15 \f0
  16 \fs25
  17
  18 #{\footnote contents}
  19 ${\footnote Contents}
  20
  21 \fs40
  22 {\uldb Introduction}{\v intro}
  23 \par
  24
  25 {\uldb Starting and Connecting OSIDebug}{\v startup}
  26 \par
  27
  28 {\uldb Sleep Info}{\v sleep}
  29 \par
  30
  31 {\uldb Lock Info}{\v lock}
  32 \par
  33
  34 \fs25
  35 \page
  36
  37 #{\footnote intro}
  38 ${\footnote Introduction}
  39 +{\footnote x:010}
  40
  41 \fs40\cf2 Introduction\cf0\fs25
  42 \par
  43
  44 The osidebug program retrieves information from running programs using
  45 the OSI package (libosi.lib).  The information you can retrieve depends
  46 partly upon the information that the programmer is gathering, but can include
  47 information on blocked processes and held locks.
  48 \par
  49
  50 \page
  51
  52 #{\footnote startup}
  53 ${\footnote Starting OSIDebug}
  54 +{\footnote x:020}
  55
  56 \fs40\cf2 Starting OSIDebug\cf0\fs25
  57 \par
  58
  59 The osidebug program is started by running it through the program manager
  60 or the command line:
  61 \par
  62
  63 \f1
  64     osidebug\line
  65 \f0
  66 \par
  67
  68 It starts by bringing up a window.
  69 \par
  70
  71 To debug any program, you must know the RPC NSI name space entry that the
  72 program has exported its debugging interface to; this is the name parameter that
  73 was passed to \f1 osi_InitDebug()\f0  in the application program.
  74 \par
  75
  76 You specify this name to \f1osidebug\f0  by clicking on the RPC NSI name entry window
  77 (it will have a default name beginning with "/.:/<something>" in it already) and typing
  78 the RPC NSI name, including the "/.:", that your server is using.
  79 \par
  80
  81 Your next step is to connect the \f1osidebug\f0  to the program by clicking on the
  82 \f1Debug Server\f0 button.  At this time, \f1osidebug\f0  will bind to the server, or
  83 display an error number in the status line at the bottom of the window if it fails.
  84 \par
  85
  86 If the program succeeds at binding to your application, it will display "Done." at the
  87 bottom of the display, and will display a set of collection names in the "Collections"
  88 window.
  89 \par
  90
  91 You can click on any of the collection names and \f1osidebug\f0  will retrieve that collection
  92 and place it in the "Results" window.  There are three collections exported generically, the
  93 "types" collection, which lists the collection names, the "sleep" collection, which provides
  94 information on sleeping threads, and the "lock" collection, which provides information on
  95 locking statistics, assuming that the application is gathering that information.
  96 \par
  97
  98 There isn't much more to say about the "types" collection.  The remaining collections are
  99 described in more detail in the next sections.
 100 \par
 101
 102 You can quit the program by clicking on the \f1Quit\f0  button.
 103 \par
 104
 105 You can rebind to the server at any time by clicking on the \f1Debug Server\f0   button again.
 106 The \f1osidebug\f0  program will reload the set of collection names at this time, and
 107 re-establish the RPC bindings.  You will also need to use this button if the application being
 108 debugged is restarted, since the old RPC binding will go bad at this time, and attempts to
 109 view collections of information will fail.
 110 \par
 111
 112 It is also possible for users to define their own named collections of data to be viewed by
 113 the \f1osidebug\f0  program.  See the documentation from your application program for the
 114 detailed information on those information collections.
 115 \par
 116
 117 \page
 118
 119 #{\footnote sleep}
 120 ${\footnote Sleep Information}
 121 +{\footnote x:030}
 122
 123 \fs40\cf2 Getting Sleep Information\cf0\fs25
 124 \par
 125
 126 You can click on the "sleep" collection name and \f1osidebug\f0  will retrieve
 127 information on sleeping threads, if any.
 128 \par
 129
 130 For each blocked thread, \f1osidebug\f0  will display several lines.  The first line is
 131 labelled "Sleep address", and gives the hex value of the sleep value passed to the
 132 OSI sleep function; if the thread is sleeping waiting for a lock or mutex to become
 133 available, this will be the address of the lock.
 134 \par
 135
 136 The second line gives the thread ID of the blocked thread.
 137 \par
 138
 139 The third line, labelled "States", gives the state of the sleeping thread's sleep control
 140 block.  This is an OR-ed bit mask of the following bits:
 141 \par
 142
 143 \f1
 144 #define OSI_SLEEPINFO_SIGNALLED 1 /* thread has been signalled */ \line
 145 #define OSI_SLEEPINFO_INHASH    2 /* sleep info is in hash table */ \line
 146 #define OSI_SLEEPINFO_DELETED   4 /* sleep info will be deleted when refcount is 0 */ \line
 147 \f0
 148 \par
 149
 150 Typically, you'll just see the INHASH state set, indicating that the block is in the hash
 151 table (where it is while the thread is blocked); this will be reported as a States value of
 152 2.  Infrequently, you may see the other state bits set, which typically indicates that
 153 the \f1osidebug\f0  program caught the system between the time that the thread was woken by
 154 a call to \f1osiwakeup\f0  and the time that the newly woken thread started executing.  These
 155 other states should be transient; if a block stays in one of these states for an appreciable
 156 amount of time, it probably indicates a bug in the OSI package.
 157 \par
 158
 159 \page
 160
 161 #{\footnote lock}
 162 ${\footnote Lock Information}
 163 +{\footnote x:040}
 164
 165 \fs40\cf2 Getting Lock Information\cf0\fs25
 166 \par
 167
 168 You can click on the "lock" collection name and \f1osidebug\f0  will retrieve
 169 information on locks initialized in statistics gathering mode (created after the
 170 application programmer calls osi_LockTypeSetDefault("stat")).
 171 \par
 172
 173 When you do so, \f1osidebug\f0 will retrieve information about the currently known
 174 locks and display this information in the "Results" window.  The information consists of
 175 several lines:
 176 \par
 177
 178 The "Lock name" gives the name passed in as the second parameter to the lock's initialization
 179 call, when the programmer called \f1lock_InitializeMutex\f0   or \f1lock_InitializeRWLock\f0.
 180 The programmer should choose a usefully mnemonic name.
 181 \par
 182
 183 The "Lock address" field gives the address of the lock structure in hex.  If some thread
 184 is waiting for this lock, it will be sleeping with the same address as its sleep value.
 185 \par
 186
 187 The "Writer count" is the count of the number of threads holding this lock for writing.
 188 Since write locks can be held by at most one thread at a time, this count will be either 0,
 189 if the lock is not held, or 1 if it is held.  If the lock is a mutex object, rather than a
 190 read/write lock, this field will be used to indicate whether someone is holding the mutex.
 191 \par
 192
 193 The "Reader count" is the count of the number of threads holding the lock for reading.
 194 Since multiple readers can lock a read/write lock concurrently, this count may be anything from
 195 0, indicating that the lock isn't read locked at all, to any number.  This field should never
 196 be non-zero at the same time that the "Writer count" field is also non-zero.  For mutex locks,
 197 this counter is always zero.
 198 \par
 199
 200 The "Are waiters" field is zero if there are no threads waiting to obtain this lock in a
 201 mode incompatible with the way that it is currently held, or 1 if there are threads waiting for
 202 the lock.
 203 \par
 204
 205 The "Write-locked time" field gives the number of milliseconds that this lock has been write
 206 locked (or locked at all, if this is a mutex) by any thread.
 207 \par
 208
 209 The "Write-locked count" field gives the number of calls that obtained this lock for writing
 210 (or that obtained the mutex at all, if this is a mutex).
 211 \par
 212
 213 The "Write-blocked time" field gives the number of milliseconds that threads trying to
 214 obtain a write lock (or any mutex) have been waiting for this lock or mutex.
 215 \par
 216
 217 The "Write-blocked count" gives the number of calls to write-lock a read/write lock, or
 218 the number of calls to obtain a mutex, that blocked due to a lock conflict.
 219 \par
 220
 221 The "Read-locked time", "Read-locked count", "Read-blocked time" and "Read-blocked count" fields
 222 give the corresponding information for readers obtaining read/write locks.  These fields are
 223 not displayed for mutexes, since their information is inapplicable to those types of locks.
 224 \par
 225
 226 \page
 227
 228 }