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)