procps/top/README.top

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