Description
-----------
gkrelltop is a plugin for gkrellm. It monitors and shows
the top three cpu, memory, and IO consuming processes.
The process name is shown on the main krell along with
a bar visually marking the percentage used by that process.

Uses of this plugin can be various from monitoring enthusiasts that want
to know at all times what their system is doing, to simple laptop users
which may not want the cpu to be at 100% at all times for battery or heat
related issues.

Moving the mouse over the krell panel causes a tooltip to appear,
showing more info such as the PID and processor usage percentage.
The refresh of the top three will be suspended for about 2 seconds,
when mouse first moves over.

Upon clicking, the krell will rotate between CPU, Memory, and IO monitoring
of the processes. Upon rightclicking, the config panel will come up.

Upon Ctrl-MiddleClick or Double-MiddleClick on one of the process names
in the krell, you will be asked if you want to kill (signal -9) that process.
This way if a program is going crazy, you can not only see it clearly,
but also kill it right there if necessary. Remember to enable 'Show nice
processes' from the configuration as well, otherwise niced processes
will not appear.

It works for gkrellm 1.* and 2.* by trying to autodetect if there is a
gtk+2.0 installed. But if you have problems, please let me know.
It works for linux and freebsd. For the makefile parameters, read below.

With the release of gkrellm 2.2.0 the gkrellmd server can have plugins.
Thanks to Bill Willson, gkrelltop now has server plugin capability, which
I hope will make a more useful plugin. Note that gkrellm 2.2.0 will need
to be installed in order to compile the gkrelltopd server plugin.
You will need the libgtk package (ex. libgtk2.0-dev in debian) to compile
these sources.


To compile for gkrellm 1 or 2 simply do:
------------------------------------
    make

or make all, or make gkrelltop and it will produce gkrelltop.so in the
directory. To try it out do:

    gkrellm -p gkrelltop.so

To copy this in your plugin directory, for gkrellm do:
    make install

To make the gkrelltopd server plugin using glib 1.2:
    make glib12=yes

To make and install the server plugin only (you may optionally do glib12=yes):
    make server
    make install-server

After the gkrelltopd server plugin is installed, it must be enabled by
adding a line to a gkrellmd.conf file:

    plugin-enable gkrelltopd

To check that it installs properly, do a test run of gkrellmd like so:

    gkrellmd -plog

To make the debian sources package do:

    make deb

To make a debian .deb package do:

    fakeroot debian/rules binary


If make fails then compile the modules manually (look at the Makefile to
find out what is needed).

To only test the top_three.c functionality from a commandline example tool,
you can do:

    make ttest

and then run

    ./ttest

which will constantly dump the 3 most active processes on the terminal.


Notes
-----
Notice to FreeBSD 5.x users: in the more recent versions of FreeBSD (ex. 5.x)
/proc is not mounted by default (at least some people have reported this),
so in order for this plugin to work correctly, you need to make sure
/proc is mounded.

Notes from the Makefile:

   For linux need the -DLINUX as a CFLAGS parameter

   to compile for FREEBSD the CFLAGS parameter
   needs to be -DFREEBSD

   I have attempted to detect the os by the OSFLAG variable
   NOTE that it will work only for LINUX or FREEBSD

   if you think it should work for your os than substituting
   your $(OSFLAG) will not quite do the trick because the wmtop code
   (the three_top.c file) only recognises those two (LINUX and FREEBSD)
   parameters. Let me know if the more recent versions of wmtop
   support more OS.

Testing gkrellm 2.2.0:
----------------------

To test for gkrellm 2.2.0 and gkrellmd 2.2.0 (which should be installed)
follow the steps below.

Run gkrellmd with gkrelltopd.so:

    $ gkrellmd -p gkrelltopd.so -plog

Then on the same machine, run:

    $ gkrellm -s localhost -p gkrelltop.so

And it should be displaying data from the gkrellmd server.

To verify that gkrellmd is sending gkrelltop data, for about
10 seconds run:

    $ gkrellm -s localhost -p gkrelltop.so -d 0x1000 > somelog

then quit gkrellm and search in the somelog file for gkrelltop lines.


Credits:
--------
- written by Adi Zaimi adizaimi-at-users.sourceforge.net
- based on Wmtop -- WindowMaker process view dock app
- Thanks to Bill Wilson for adding gkrellmd support
- Licensed under GNU GPL


Changelog:
----------

Version 2.2.13 20090721
  Added temporary delay to refresh when mouseover so user has a chance to
     double click.
  Refactored code to speed up reading /proc and to find processes in list

Version 2.2.12 20090709
  Fixed bug that showed a process twice, if thresholding was on
     and it was the only process to exceed the threshold.
  Added support to show top processes consuming IO,
     which works with linux > 2.6.20

Version 2.2.11 20071225
  Fixed exclusions problem when a process which was previously set
     to be excluded, would not reappear after removing it from
     the exclusion list.
     Thanks to Kan Sasaki <sasaki-at-fcc.ad.jp> for providing a patch
     to fix the above.

Version 2.2.10 20070721
  Fixed bug which caused crash with floating point exception error
     in calculating master_modulus.
     Thanks to Ethan Romander <eromander-at-prodigy.net> for finding this bug
     and providing a patch.
  Fixed Makefile to have all parts compile with -fPIC because it failed
     to compile on some environments. Thanks to Kurt Roeckx <kurt-at-roeckx.be>
     for pointing the error, and to Julien Cristau <jcristau-at-debian.org>
     for fixing it in the Debian repository.

Version 2.2.9 20070213
  Fixed bug with process displaying twice when there was a threshold.
     Thanks to Jerome UZEL <jerome.uzel-at-wanadoo.fr> for spotting the bug.
  Put back the standard panel since people want skins to apply.

Version 2.2.8 20070207
  Added the sort by memory utilization capability. Clicking on the plugin
     will switch between displaying memory utilization and cpu utilization.
  Send kill signal to process on double-middleclick.
  Made a debian proper configuration.

Version 2.2.7 20070120
  Made the krells into panels so now i can display between 1 and 3
     panels with the top processes.

Version 2.2.6 20040703
  Tooltips show all the necessary process information for which
     there's no room in the main view.

Version 2.2.5 20040617
  Added graphical representations for the percent processor usage
  Added support for a regexp exclusion of process names

Version 2.2.4 20040529
  Fixed the show-nice-processes capability

Version 2.2.3 20040527
  Made functional the configuration tabs:
     Now one can show only processes above a certain threshold.
     One can have the update frequency from once in 5 seconds
     to the gkrell_update value.
     One can disable/enable displaying the nice processes in the list.
  Change Makefile so now *only* produces gkrelltop.so:
     No more differentiating between gkrelltop2.so and the older gkrellm 1.*
     version. If there are people that use the 1.* version, they can still
     use this program (i hope).


Version 2.2.2 20040520
  Added gkrellmd support (Bill Wilson)
  Added debian support. Now running 'dpkg-buildpackage -rfakeroot -uc -us'
     or 'make deb' will create a debian package.


Versions 2.2.1 and earlier
  Ported it to gkrellm 2.0