top/README.top

   1 This file summarizes changes to the top program and supporting documentation
   2 introduced on March 31, 2011.
   3
   4 Contents:
   5       DOCUMENT Changes
   6       INTERNAL Improvements
   7       EXTERNAL Improvements
   8       BUGS Previously Fixed and Preserved
   9       BUGS Newly/Nearly Fixed
  10       BUGS/WISH-LISTS That Should Go Bye-bye
  11       BUGS FIXED You Didn't Know You Had
  12       OTHER Changes, Hopefully They Won't Bite You
  13       BENCHMARKS
  14
  15
  16 DOCUMENT Changes =========================================================
  17   . The entire file was cleaned up, standardized and expanded to include:
  18     - a new section "2. SUMMARY Display" added for symmetry with Fields
  19     - nine new fields were added to section "3a. DESCRIPTIONS of Fields"
  20     - a new section "3b. MANAGING Fields" replaced the obsolete section
  21       "2b. SELECTING and ORDERING Columns"
  22     - section "5c. SCROLLING a Window" was added for that new feature
  23
  24   . I don't know when the explanations for CODE and DATA were changed to
  25     show 'virtual' memory, but I think there's a reason their alternate
  26     names contain the word 'resident'.  Thus they were changed back to
  27     say 'physical memory'.
  28
  29   . And as I indicated in a previous email, the former string identifier
  30     'ME' was restored as were the 'h' key/command conventions (vs. <h>).
  31
  32     Oops, the 'h' key/command conventions remain restored, but subsequent
  33     testing revealed problems with the .ME string identifier.  Thus, it was
  34     changed to .WE (along with the companion .Me/.We id).
  35
  36   . Also previously mentioned, the 'man2html' program translates top.1 to
  37     HTML with near perfect fidelity.  I take that to mean there should be
  38     no problems with the top.1 source on most other platforms.
  39
  40     To further improve translation to HTML, several .Bd and .Ed macros
  41     were added to preserve literal (fixed width) spacing.
  42
  43
  44 INTERNAL Improvements ====================================================
  45   . The old restriction of 26 fields has been lifted.  With this new-top
  46     100+ fields are now possible.  It currently supports up to 55, of
  47     which 35 are in use.  Adding a new field is almost too easy.
  48
  49   . Task row construction has been considerably improved -- both from
  50     a programming perspective and a performance perspective.
  51
  52   . The column highlighting costs for sort field visibility were
  53     virtually eliminated.
  54
  55     An optional define (USE_X_COLHDR) can be enabled to completely
  56     eliminate any costs associated with the 'x' command toggle.
  57
  58   . The management of the HST_t structures, used for %cpu calculations,
  59     was optimized with a hashing scheme.  Thus the need for a qsort then
  60     a binary search in each frame was completely eliminated.
  61
  62     An optional define can restore the former qsort/bsearch approach but
  63     with an internal inlined binary search function offering substantially
  64     better performance than the old top.
  65
  66   . This far more capable new-top executable is no larger than old top.
  67
  68   . The above combine to produce substantially improved performance
  69     whose details are documented below under BENCHMARKS.
  70
  71
  72 EXTERNAL Improvements ====================================================
  73   . Field management has been completely redesigned.  It's now embodied
  74     on a single screen where display-ability, position and sort selection
  75     can be handled in one place -- for all windows at one time!
  76
  77     This function is dependent on cursor motion keys and should a device
  78     not have the customary arrow keys, alternatives are provided and
  79     documented under "Operation" near the beginning of the man page.
  80
  81   . The following new fields have been added:
  82        Group Id
  83        Minor Page Faults
  84        Number of Threads
  85        Process Group Id
  86        Real User Id
  87        Saved User Id
  88        Saved User Name
  89        Session Id
  90        Tty Process Group Id
  91
  92   . Scrolling keys now allow one to move the view of any window vertically
  93     or horizontally to reveal any desired task or column.  Previously, only
  94     some tasks were viewable even with reversible, selectable sort columns.
  95
  96     Each of the four windows is capable of maintaining its own scrolled
  97     coordinates and an optional toggle ('C') displays a message aiding
  98     navigation within the available tasks and displayable fields.
  99
 100   . User interactive line oriented input now provides for true line
 101     editing supported by these new keys:
 102         Left/Right arrow keys, Delete key, Backspace and
 103         Home/End keys (likely limited to xterm, not terminal)
 104
 105   . User filtering via the -u | -U interactive commands is now window
 106     based which means that different windows could be used to filter
 107     different users.
 108
 109   . Signal handling has been normalized and is now consistent regardless
 110     of the particular top screen a user may have been using.
 111
 112   . The 'i' toggle now shows any task that has used *some* cpu since the
 113     last screen update.  It's no longer limited to just running tasks.
 114
 115   . The summary area 'task states' line now reflects either 'Threads'
 116     or 'Tasks' depending on the -H toggle.
 117
 118
 119 BUGS Previously Fixed and Preserved ======================================
 120   ( but not necessarily literally)
 121   . 228822, suspending top leaves xterm in slightly messed-up state
 122   . 256376, segfaults, if the xterm is to small
 123   . 320289, segv on sigwinch
 124   . 351065, wrong highlight 1st column (escape characters displayed)
 125   . 358724, accepts extra numeric args
 126   . 378695, seg fault if "/proc" is not mounted
 127   . 426782, UID field is too narrow
 128   . 458986, should check xterm for EOF/EIO
 129   . 459890, Irix mode should use %#4.1f when threads shown
 130
 131
 132 BUGS Newly/Nearly Fixed ==================================================
 133   . 225542, 'Unknown command' message blocks further commands
 134       The message is now displayed using usleep for 1.25 seconds, instead
 135       of the former full 2 seconds.  And while it still blocks further
 136       commands, the delay is much more tolerable.
 137
 138       Can we consider this bug 'nearly' fixed?
 139
 140   . 410292, interface error when using backspace
 141       Full line editing was added but could be disabled via a #define.
 142       And via that define, even under basic termios support, the backspace
 143       problem was cured.
 144
 145   . 567509, top idle command ('i') not working for threaded programs
 146       Since the 'i' command now reflects tasks that have used *some* cpu,
 147       and is no longer dependent on an 'R' state, I *believe/hope* this
 148       bug has been swatted.
 149
 150
 151 BUGS/WISH-LISTS That Should Go Bye-bye ===================================
 152   . 340751, wish for hostname to benefit multiple top sessions
 153       Craig's suggestion regarding symlinks is the perfect solution.
 154       How dare Craig say that the solution was "not ideal" !
 155
 156   . 586497, wish for graceful degradation on small screen sizes
 157       This objective could be accomplished by setting up 2 symlinks for
 158       top, personalizing them for the 2 tiny phone displays, then writing
 159       the respective configuration files.
 160
 161       I shudder at the programming effort suggested by Paul.  And when it
 162       was done you'd find everybody else would have different criteria.
 163
 164
 165 BUGS FIXED You Didn't Know You Had =======================================
 166   . Without amplifying the dirty details, the long standing occasionally
 167     reported display corruption, and an unreported source of performance
 168     degradation, has been eliminated.  The cure is in the elimination of
 169     the Pseudo_cols variable and the improved PUFF macro.
 170
 171   . Line oriented input was not sensitive to screen width.  Thus a user
 172     could hold down any key and ultimately line wrap, overwriting the
 173     columns header and the entire screen.  New top prevents this.
 174
 175   . User filtering (-u|-U) via a user ID (not name) now validates that
 176     number.  The old-top just made sure it was numeric, then blindly
 177     displayed no matching users (i.e. an empty window).
 178
 179   . The threads toggle ('H') is no longer window based but more properly
 180     applies to all windows.  The previous implementation produced the
 181     following aberration if multiple windows were being shown:
 182       . -H would be acknowledged and applied to all visible windows
 183       . keying 'a' or 'w' would silently turn it off
 184       . then keying -H would turn it back on, but the user expected off
 185
 186   . If you hit ^Z on any help or fields screen to suspend old-top, after
 187     issuing 'fg' you would then be left with a seemingly hung application
 188     inviting ^C.  In truth, one could recover with the space bar, but that
 189     was far from intuitive.
 190
 191   . The old-top consistently writes 1 extra byte for each task row or 1
 192     byte too few for columns headers, depending on your perspective.
 193     The new top writes the same number of bytes for each.
 194
 195   . By failing to clear to eol, old top left the display in a terrible
 196     state after exiting a 'fields' screen when only a few columns were
 197     being displayed.
 198
 199   . The old-top used a zero value for the L_NONE library flag which could
 200     cause repeated rebuilding of columns headers with each frame.  In truth,
 201     this was not likely to happen in real life since only two fields actually
 202     used that flag.  However, if it did happen, performance could be degraded
 203     by 800%.
 204
 205
 206 OTHER Changes, Hopefully They Won't Bite You =============================
 207   . The undocumented TOPRC environment variable is no longer supported.
 208     Any similar need can be met through a symlink alias.
 209
 210   . The use of environment variables to override terminal size is now
 211     off by default but could be enabled through '#define TTYGETENVYES'.
 212
 213   . The global 'bold enable' toggle is active by default and thus agrees
 214     with the documentation.  It's been wrong ever since Al's wholesale
 215     'cosmetic' changes in procps-3.2.2.
 216
 217   . Task defaults now show bold (not reverse) and row highlighting.
 218     This agrees with what was always stated in the documentation.
 219
 220   . The 'H' toggle (thread mode) is not persistent.  Persistence can be
 221     achieved with a simple shell script employing the -H switch.
 222
 223   . Then 'g' and 'G' commands were reversed to reflect their likely use.
 224
 225
 226 BENCHMARKS ===============================================================
 227   Tested as root with nice -10 and using only common fields
 228    ( on a pretty old, slow laptop under Debian Lenny )
 229   but rcfiles specified identical sort fields and identical
 230   settings for the 'B', 'b', 'x' and 'y' toggles (even though
 231   the defaults are not necessarily identical).
 232
 233   In every case new-top outperforms old-top, but I've shown %
 234   improvements for only the most significant.  Those cases mostly
 235   involve colors with both row & column highlighting.  I suggested
 236   above that the highlighting cost was virtually eliminated in
 237   new-top, and these tests bare that out.
 238
 239   Note the much smaller differences for new-top between the 24x80
 240   window results and full screen (but don't mix apples_terminal
 241   with oranges_xterm).  This is a reflection of the simplification
 242   of task row construction, also mentioned above.
 243
 244   It's always been the case that any top in an xterm outperforms
 245   that top under the terminal application, even when the xterm
 246   provides additional rows and columns.  It's true below with
 247   Gnome and it was true nine years ago under KDE.
 248
 249   ----------------------------------------------------------
 250    The following comparisons were run with:
 251       100 tasks & 160 threads
 252       -d0 -n5000
 253                                  new-top        old-top
 254   xterm     24x80
 255  a  1 win,  lflgs_none         11.2 secs      51.8 secs    + 462.6%
 256     1 win,  default            61.0 secs      66.8 secs
 257     1 win,  colors w/ x+y      61.3 secs      83.0 secs    + 135.4%
 258     1 win,  thread mode        88.3 secs      94.2 secs
 259  b  1 win,  every field on     99.7 secs     106.0 secs
 260     1 win,  cmdline            71.2 secs      76.6 secs
 261     4 wins, defaults          101.3 secs     107.2 secs
 262     4 wins, colors w/ x+y     101.5 secs     122.8 secs    + 121.0%
 263
 264   xterm, full screen (53x170)
 265  a  1 win,  lflgs_none         15.9 secs      54.2 secs    + 340.9%
 266     1 win,  default            70.0 secs      73.2 secs
 267     1 win,  colors w/ x+y      69.4 secs     131.3 secs    + 189.2%
 268     1 win,  thread mode        97.6 secs     102.6 secs
 269  c  1 win,  every field on    122.1 secs     128.1 secs
 270     1 win,  cmdline            80.8 secs      83.7 secs
 271     4 wins, defaults          111.4 secs     115.8 secs
 272     4 wins, colors w/ x+y     112.0 secs     172.9 secs    + 154.4%
 273
 274   terminal  24x80
 275  a  1 win,  lflgs_none          8.9 secs      58.6 secs    + 658.4%
 276     1 win,  default            70.1 secs      80.3 secs
 277     1 win,  colors w/ x+y      70.6 secs     157.3 secs    + 222.8%
 278     1 win,  thread mode       104.7 secs     120.5 secs
 279  b  1 win,  every field on    111.2 secs     134.5 secs
 280     1 win,  cmdline            83.8 secs      94.5 secs
 281     4 wins, defaults          125.6 secs     146.7 secs
 282     4 wins, colors w/ x+y     125.6 secs     206.9 secs    + 176.7%
 283
 284   terminal, full screen (39x125)
 285  a  1 win,  lflgs_none          9.1 secs      60.6 secs    + 665.9%
 286     1 win,  default            74.3 secs      88.0 secs
 287     1 win,  colors w/ x+y      73.9 secs     314.5 secs    + 425.6%
 288     1 win,  thread mode       113.0 secs     140.9 secs
 289  b  1 win,  every field on    117.7 secs     154.9 secs
 290     1 win,  cmdline            87.4 secs     107.2 secs
 291     4 wins, defaults          139.1 secs     166.7 secs
 292     4 wins, colors w/ x+y     157.3 secs     423.2 secs    + 269.0%
 293
 294   ----------------------------------------------------------
 295    The following comarisons were run with:
 296       300 tasks & 360 threads
 297       -d0 -n3000
 298                                  new-top        old-top
 299   xterm, full screen (53x170)
 300  a  1 win,  lflgs_none         14.3 secs      79.0 secs    + 552.4%
 301     1 win,  default           101.1 secs     104.5 secs
 302     1 win,  colors w/ x+y     101.3 secs     140.0 secs    + 138.2%
 303     1 win,  thread mode       120.1 secs     123.1 secs
 304  c  1 win,  every field on    179.8 secs     185.6 secs
 305     1 win,  cmdline           124.9 secs     132.8 secs
 306     4 wins, defaults          174.8 secs     179.2 secs
 307     4 wins, colors w/ x+y     175.0 secs     215.2 secs    + 123.0%
 308
 309   terminal, full screen (39x125)
 310  a  1 win,  lflgs_none         12.3 secs      98.5 secs    + 800.8%
 311     1 win,  default           117.4 secs     134.0 secs
 312     1 win,  colors w/ x+y     111.6 secs     296.1 secs    + 265.3%
 313     1 win,  thread mode       141.3 secs     155.3 secs
 314  b  1 win,  every field on    197.7 secs     204.8 secs
 315     1 win,  cmdline           143.9 secs     157.3 secs
 316     4 wins, defaults          204.0 secs     226.2 secs
 317     4 wins, colors w/ x+y     216.9 secs     434.5 secs    + 200.3%
 318
 319   . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
 320
 321 notes:
 322  a  these results represent the library flags L_NONE zero value and
 323     thus the hidden cost of rebuilding column headers w/ every frame
 324  b  while every common field was turned on, not all fields could be
 325     displayed due to limited screen width
 326  c  only in a full screen xterm window could all common fields
 327     actually be displayed
 328
 329
 330 BENCHMARKS, Redux (for NLS) ==============================================
 331   December, 2011 benchmarks produced on a much more modern
 332   platform containing:
 333      Intel(R) Core(TM) i3-2310M CPU @ 2.10GHz
 334      SMP with 4 cpus
 335   reflected in the substantially reduced elapsed times.
 336
 337   Tested as root with nice -10 and using only common fields
 338   but rcfiles specified identical sort fields and identical
 339   settings for the 'B', 'b', 'x' and 'y' toggles (even though
 340   the defaults are not necessarily identical).
 341
 342   Each test was run outside of X-windows at a linux console
 343   offering 48 rows and 170 columns.  This was done to reduce
 344   contention which sometimes made comparisons problematic.
 345
 346   old-top = procps-3.2.8 (debian patched and memory leaking)
 347   new-top = procps-ng-3.3.2 with NLS support
 348
 349   ----------------------------------------------------------
 350    The following comparisons were run with
 351       -d0 -n5000
 352       140 tasks & 275 threads
 353
 354   linux console (48x170)         new-top        old-top
 355  d  1 win,  lflgs_none          2.6 secs      15.0 secs    + 577.0%
 356     1 win,  default            16.1 secs      19.3 secs
 357     1 win,  colors w/ x+y      16.6 secs      35.0 secs    + 210.8%
 358  e  1 win,  show cpus          16.2 secs      20.1 secs    + 124.1%
 359     1 win,  thread mode        31.8 secs      34.1 secs
 360  f  1 win,  every field on     30.5 secs      34.0 secs
 361     1 win,  cmdline            19.9 secs      23.1 secs
 362     4 wins, default            31.9 secs      35.2 secs
 363     4 wins, colors w/ x+y      29.2 secs      47.4 secs    + 162.3%
 364  g  1 win,  b&w w/ bold x      30.0 secs      33.2 secs
 365  h  1 win,  scroll msg on      31.1 secs      33.9 secs
 366
 367   . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
 368
 369 notes:
 370  d  these represent the same anamoly as the original 'a' footnote
 371  e  these represent the '1' toggle, where each of 4 cpus was shown
 372       (not possible on the original uniprocessor)
 373  f  every common field was turned on and all fields were visible
 374  g  on a black and white display, sort column was shown in bold
 375       (further proof of column highlighting improvements)
 376  h  similar to 'g', but new top was showing scroll msg
 377       (old top has no such provision)