← Back to branch summary

~ubuntu-branches/ubuntu/warty/openafs/warty

« back to all changes in this revision

Viewing changes to src/WINNT/client_osi/osidebug.rtf

  • Committer: Bazaar Package Importer
  • Author(s): Sam Hartman
  • Date: 2004-01-10 16:37:33 UTC
  • Revision ID: james.westby@ubuntu.com-20040110163733-jvr0n1uahshlb1uu
Tags: upstream-1.2.11
Import upstream version 1.2.11

Show diffs side-by-side

added added

removed removed

Lines of Context:
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
}