This file summarizes changes to the top program and supporting documentation
introduced on March 31, 2011.
Contents:
DOCUMENT Changes
INTERNAL Improvements
EXTERNAL Improvements
BUGS Previously Fixed and Preserved
BUGS Newly/Nearly Fixed
BUGS/WISH-LISTS That Should Go Bye-bye
BUGS FIXED You Didn't Know You Had
OTHER Changes, Hopefully They Won't Bite You
BENCHMARKS
DOCUMENT Changes =========================================================
. The entire file was cleaned up, standardized and expanded to include:
- a new section "2. SUMMARY Display" added for symmetry with Fields
- nine new fields were added to section "3a. DESCRIPTIONS of Fields"
- a new section "3b. MANAGING Fields" replaced the obsolete section
"2b. SELECTING and ORDERING Columns"
- section "5c. SCROLLING a Window" was added for that new feature
. I don't know when the explanations for CODE and DATA were changed to
show 'virtual' memory, but I think there's a reason their alternate
names contain the word 'resident'. Thus they were changed back to
say 'physical memory'.
. And as I indicated in a previous email, the former string identifier
'ME' was restored as were the 'h' key/command conventions (vs. <h>).
Oops, the 'h' key/command conventions remain restored, but subsequent
testing revealed problems with the .ME string identifier. Thus, it was
changed to .WE (along with the companion .Me/.We id).
. Also previously mentioned, the 'man2html' program translates top.1 to
HTML with near perfect fidelity. I take that to mean there should be
no problems with the top.1 source on most other platforms.
To further improve translation to HTML, several .Bd and .Ed macros
were added to preserve literal (fixed width) spacing.
INTERNAL Improvements ====================================================
. The old restriction of 26 fields has been lifted. With this new-top
100+ fields are now possible. It currently supports up to 55, of
which 35 are in use. Adding a new field is almost too easy.
. Task row construction has been considerably improved -- both from
a programming perspective and a performance perspective.
. The column highlighting costs for sort field visibility were
virtually eliminated.
An optional define (USE_X_COLHDR) can be enabled to completely
eliminate any costs associated with the 'x' command toggle.
. The management of the HST_t structures, used for %cpu calculations,
was optimized with a hashing scheme. Thus the need for a qsort then
a binary search in each frame was completely eliminated.
An optional define can restore the former qsort/bsearch approach but
with an internal inlined binary search function offering substantially
better performance than the old top.
. This far more capable new-top executable is no larger than old top.
. The above combine to produce substantially improved performance
whose details are documented below under BENCHMARKS.
EXTERNAL Improvements ====================================================
. Field management has been completely redesigned. It's now embodied
on a single screen where display-ability, position and sort selection
can be handled in one place -- for all windows at one time!
This function is dependent on cursor motion keys and should a device
not have the customary arrow keys, alternatives are provided and
documented under "Operation" near the beginning of the man page.
. The following new fields have been added:
Group Id
Minor Page Faults
Number of Threads
Process Group Id
Real User Id
Saved User Id
Saved User Name
Session Id
Tty Process Group Id
. Scrolling keys now allow one to move the view of any window vertically
or horizontally to reveal any desired task or column. Previously, only
some tasks were viewable even with reversible, selectable sort columns.
Each of the four windows is capable of maintaining its own scrolled
coordinates and an optional toggle ('C') displays a message aiding
navigation within the available tasks and displayable fields.
. User interactive line oriented input now provides for true line
editing supported by these new keys:
Left/Right arrow keys, Delete key, Backspace and
Home/End keys (likely limited to xterm, not terminal)
. User filtering via the -u | -U interactive commands is now window
based which means that different windows could be used to filter
different users.
. Signal handling has been normalized and is now consistent regardless
of the particular top screen a user may have been using.
. The 'i' toggle now shows any task that has used *some* cpu since the
last screen update. It's no longer limited to just running tasks.
. The summary area 'task states' line now reflects either 'Threads'
or 'Tasks' depending on the -H toggle.
BUGS Previously Fixed and Preserved ======================================
( but not necessarily literally)
. 228822, suspending top leaves xterm in slightly messed-up state
. 256376, segfaults, if the xterm is to small
. 320289, segv on sigwinch
. 351065, wrong highlight 1st column (escape characters displayed)
. 358724, accepts extra numeric args
. 378695, seg fault if "/proc" is not mounted
. 426782, UID field is too narrow
. 458986, should check xterm for EOF/EIO
. 459890, Irix mode should use %#4.1f when threads shown
BUGS Newly/Nearly Fixed ==================================================
. 225542, 'Unknown command' message blocks further commands
The message is now displayed using usleep for 1.25 seconds, instead
of the former full 2 seconds. And while it still blocks further
commands, the delay is much more tolerable.
Can we consider this bug 'nearly' fixed?
. 410292, interface error when using backspace
Full line editing was added but could be disabled via a #define.
And via that define, even under basic termios support, the backspace
problem was cured.
. 567509, top idle command ('i') not working for threaded programs
Since the 'i' command now reflects tasks that have used *some* cpu,
and is no longer dependent on an 'R' state, I *believe/hope* this
bug has been swatted.
BUGS/WISH-LISTS That Should Go Bye-bye ===================================
. 340751, wish for hostname to benefit multiple top sessions
Craig's suggestion regarding symlinks is the perfect solution.
How dare Craig say that the solution was "not ideal" !
. 586497, wish for graceful degradation on small screen sizes
This objective could be accomplished by setting up 2 symlinks for
top, personalizing them for the 2 tiny phone displays, then writing
the respective configuration files.
I shudder at the programming effort suggested by Paul. And when it
was done you'd find everybody else would have different criteria.
BUGS FIXED You Didn't Know You Had =======================================
. Without amplifying the dirty details, the long standing occasionally
reported display corruption, and an unreported source of performance
degradation, has been eliminated. The cure is in the elimination of
the Pseudo_cols variable and the improved PUFF macro.
. Line oriented input was not sensitive to screen width. Thus a user
could hold down any key and ultimately line wrap, overwriting the
columns header and the entire screen. New top prevents this.
. User filtering (-u|-U) via a user ID (not name) now validates that
number. The old-top just made sure it was numeric, then blindly
displayed no matching users (i.e. an empty window).
. The threads toggle ('H') is no longer window based but more properly
applies to all windows. The previous implementation produced the
following aberration if multiple windows were being shown:
. -H would be acknowledged and applied to all visible windows
. keying 'a' or 'w' would silently turn it off
. then keying -H would turn it back on, but the user expected off
. If you hit ^Z on any help or fields screen to suspend old-top, after
issuing 'fg' you would then be left with a seemingly hung application
inviting ^C. In truth, one could recover with the space bar, but that
was far from intuitive.
. The old-top consistently writes 1 extra byte for each task row or 1
byte too few for columns headers, depending on your perspective.
The new top writes the same number of bytes for each.
. By failing to clear to eol, old top left the display in a terrible
state after exiting a 'fields' screen when only a few columns were
being displayed.
. The old-top used a zero value for the L_NONE library flag which could
cause repeated rebuilding of columns headers with each frame. In truth,
this was not likely to happen in real life since only two fields actually
used that flag. However, if it did happen, performance could be degraded
by 800%.
OTHER Changes, Hopefully They Won't Bite You =============================
. The undocumented TOPRC environment variable is no longer supported.
Any similar need can be met through a symlink alias.
. The use of environment variables to override terminal size is now
off by default but could be enabled through '#define TTYGETENVYES'.
. The global 'bold enable' toggle is active by default and thus agrees
with the documentation. It's been wrong ever since Al's wholesale
'cosmetic' changes in procps-3.2.2.
. Task defaults now show bold (not reverse) and row highlighting.
This agrees with what was always stated in the documentation.
. The 'H' toggle (thread mode) is not persistent. Persistence can be
achieved with a simple shell script employing the -H switch.
. Then 'g' and 'G' commands were reversed to reflect their likely use.
BENCHMARKS ===============================================================
Tested as root with nice -10 and using only common fields
( on a pretty old, slow laptop under Debian Lenny )
but rcfiles specified identical sort fields and identical
settings for the 'B', 'b', 'x' and 'y' toggles (even though
the defaults are not necessarily identical).
In every case new-top outperforms old-top, but I've shown %
improvements for only the most significant. Those cases mostly
involve colors with both row & column highlighting. I suggested
above that the highlighting cost was virtually eliminated in
new-top, and these tests bare that out.
Note the much smaller differences for new-top between the 24x80
window results and full screen (but don't mix apples_terminal
with oranges_xterm). This is a reflection of the simplification
of task row construction, also mentioned above.
It's always been the case that any top in an xterm outperforms
that top under the terminal application, even when the xterm
provides additional rows and columns. It's true below with
Gnome and it was true nine years ago under KDE.
----------------------------------------------------------
The following comparisons were run with:
100 tasks & 160 threads
-d0 -n5000
new-top old-top
xterm 24x80
a 1 win, lflgs_none 11.2 secs 51.8 secs + 462.6%
1 win, default 61.0 secs 66.8 secs
1 win, colors w/ x+y 61.3 secs 83.0 secs + 135.4%
1 win, thread mode 88.3 secs 94.2 secs
b 1 win, every field on 99.7 secs 106.0 secs
1 win, cmdline 71.2 secs 76.6 secs
4 wins, defaults 101.3 secs 107.2 secs
4 wins, colors w/ x+y 101.5 secs 122.8 secs + 121.0%
xterm, full screen (53x170)
a 1 win, lflgs_none 15.9 secs 54.2 secs + 340.9%
1 win, default 70.0 secs 73.2 secs
1 win, colors w/ x+y 69.4 secs 131.3 secs + 189.2%
1 win, thread mode 97.6 secs 102.6 secs
c 1 win, every field on 122.1 secs 128.1 secs
1 win, cmdline 80.8 secs 83.7 secs
4 wins, defaults 111.4 secs 115.8 secs
4 wins, colors w/ x+y 112.0 secs 172.9 secs + 154.4%
terminal 24x80
a 1 win, lflgs_none 8.9 secs 58.6 secs + 658.4%
1 win, default 70.1 secs 80.3 secs
1 win, colors w/ x+y 70.6 secs 157.3 secs + 222.8%
1 win, thread mode 104.7 secs 120.5 secs
b 1 win, every field on 111.2 secs 134.5 secs
1 win, cmdline 83.8 secs 94.5 secs
4 wins, defaults 125.6 secs 146.7 secs
4 wins, colors w/ x+y 125.6 secs 206.9 secs + 176.7%
terminal, full screen (39x125)
a 1 win, lflgs_none 9.1 secs 60.6 secs + 665.9%
1 win, default 74.3 secs 88.0 secs
1 win, colors w/ x+y 73.9 secs 314.5 secs + 425.6%
1 win, thread mode 113.0 secs 140.9 secs
b 1 win, every field on 117.7 secs 154.9 secs
1 win, cmdline 87.4 secs 107.2 secs
4 wins, defaults 139.1 secs 166.7 secs
4 wins, colors w/ x+y 157.3 secs 423.2 secs + 269.0%
----------------------------------------------------------
The following comarisons were run with:
300 tasks & 360 threads
-d0 -n3000
new-top old-top
xterm, full screen (53x170)
a 1 win, lflgs_none 14.3 secs 79.0 secs + 552.4%
1 win, default 101.1 secs 104.5 secs
1 win, colors w/ x+y 101.3 secs 140.0 secs + 138.2%
1 win, thread mode 120.1 secs 123.1 secs
c 1 win, every field on 179.8 secs 185.6 secs
1 win, cmdline 124.9 secs 132.8 secs
4 wins, defaults 174.8 secs 179.2 secs
4 wins, colors w/ x+y 175.0 secs 215.2 secs + 123.0%
terminal, full screen (39x125)
a 1 win, lflgs_none 12.3 secs 98.5 secs + 800.8%
1 win, default 117.4 secs 134.0 secs
1 win, colors w/ x+y 111.6 secs 296.1 secs + 265.3%
1 win, thread mode 141.3 secs 155.3 secs
b 1 win, every field on 197.7 secs 204.8 secs
1 win, cmdline 143.9 secs 157.3 secs
4 wins, defaults 204.0 secs 226.2 secs
4 wins, colors w/ x+y 216.9 secs 434.5 secs + 200.3%
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
notes:
a these results represent the library flags L_NONE zero value and
thus the hidden cost of rebuilding column headers w/ every frame
b while every common field was turned on, not all fields could be
displayed due to limited screen width
c only in a full screen xterm window could all common fields
actually be displayed
BENCHMARKS, Redux (for NLS) ==============================================
December, 2011 benchmarks produced on a much more modern
platform containing:
Intel(R) Core(TM) i3-2310M CPU @ 2.10GHz
SMP with 4 cpus
reflected in the substantially reduced elapsed times.
Tested as root with nice -10 and using only common fields
but rcfiles specified identical sort fields and identical
settings for the 'B', 'b', 'x' and 'y' toggles (even though
the defaults are not necessarily identical).
Each test was run outside of X-windows at a linux console
offering 48 rows and 170 columns. This was done to reduce
contention which sometimes made comparisons problematic.
old-top = procps-3.2.8 (debian patched and memory leaking)
new-top = procps-ng-3.3.2 with NLS support
----------------------------------------------------------
The following comparisons were run with
-d0 -n5000
140 tasks & 275 threads
linux console (48x170) new-top old-top
d 1 win, lflgs_none 2.6 secs 15.0 secs + 577.0%
1 win, default 16.1 secs 19.3 secs
1 win, colors w/ x+y 16.6 secs 35.0 secs + 210.8%
e 1 win, show cpus 16.2 secs 20.1 secs + 124.1%
1 win, thread mode 31.8 secs 34.1 secs
f 1 win, every field on 30.5 secs 34.0 secs
1 win, cmdline 19.9 secs 23.1 secs
4 wins, default 31.9 secs 35.2 secs
4 wins, colors w/ x+y 29.2 secs 47.4 secs + 162.3%
g 1 win, b&w w/ bold x 30.0 secs 33.2 secs
h 1 win, scroll msg on 31.1 secs 33.9 secs
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
notes:
d these represent the same anamoly as the original 'a' footnote
e these represent the '1' toggle, where each of 4 cpus was shown
(not possible on the original uniprocessor)
f every common field was turned on and all fields were visible
g on a black and white display, sort column was shown in bold
(further proof of column highlighting improvements)
h similar to 'g', but new top was showing scroll msg
(old top has no such provision)
80f9815f5f