Monitor - user callbacks for library, process and thread initialization/creation/destruction
Monitor is a library that gives the user callbacks or traps
upon events related to library/process/thread
initialization/creation/destruction. Extra care is taken to
appropriately handle important events such as all forms of fork(),
exec() as well as variants of exit(), abort(), assert() as well as
signals SIGABRT and SIGINT. The most up to date documentation for
monitor is always found in the man
page.
Features
- Callbacks on library initialization and finalization.
- Callbacks on process initialization and finalization.
- Callbacks on thread initialization and finalization.
- Callback on dlopen().
- Automatic thread detection.
- A thread ID function that ALWAYS works.
- Run-time debugging facilities.
- Direct access to functions intercepted by libmonitor (for tools).
- Architecture independent build and monitor-config driver.
- Extensive test cases.
Download and Installation
- CVS is the best way to get the code.
- Those without CVS access (?!) can find the most recent release (1.0): monitor-1.0.tar.gz
- To build/install Monitor, please see the INSTALL file.
- To use Monitor, please see the man page.
- To see the ChangeLog, please see the file.
Example
The best documentation is in the form of an example. This example ASSUMES you
have successfully built Monitor, that you're in the platform specific build directory AND that you are running Bourne shell.
If you're not running bash now, start it now before continuing.
First we need a sample shared library to provide the callbacks that will be called by libmonitor.so.
The code is testtool.c. It includes monitor.h,
the header file containing the prototypes for the callbacks. The testtool library is very simple
and merely prints to stderr the callback name as it occurs. It has already been compiled (assuming the build went smoothly)
in the platform/tests directory with the following command line: (note that it has not been properly versioned)
gcc -Wall -g -O -shared -fPIC testtool.c -o libtesttool.so
Ok, so we have a tool library. Now we have to set up the LD_PRELOAD environment variable to point FIRST to the test tool code and SECOND to the monitor library. Please bother to
replace /path_to_build with the full path of the platform specific directory inside the directory where you unpacked and built monitor.
export LD_PRELOAD=/path_to_build/tests/libtesttool.so:/path_to_build/libmonitor.so
Now let's run a few programs and direct stderr to a file.
[mucci@localhost]$ evolution 2> example.evolution
[mucci@localhost]$ i686-Linux/tests/pthreads 2> example.pthreads
Here's the output: sample.evolution and sample.pthreads. You'll notice that evolution just ignores it's threads when it exits. Naughty, naughty.
If you don't want to both to define or use all the callbacks, they are all weak symbols on Linux. This means you can just define the one's you want and things will still work just fine. You can repeat the previous experiment with libtesttool2.so in the test directory. That library has been built with -DPROCESS_ONLY and thus only defines the monitor_init_process callback.
CVS Access
Currently, the best way to get Monitor is to get it directly from CVS. You can access the CVS repository with your browser or use the anonymous CVS pserver. Just hit enter when asked for the password.
% setenv CVSROOT :pserver:anonymous@cvs.cs.utk.edu:/cvs/homes/ospat
% cvs login
Password:
% cvs co monitor
Testing
The distribution includes a 'make test' phase. The current release has been tested on:
- i686 (Pentium III) / Fedora Core 3/4/5
- x86_64 (AMD 64-bit) / Suse 9
- ia64 (Itanium 2) / Debian 3.0
- x86_64 (Intel EM64T) / Fedora Core 3
- i686 (Pentium IV) / Redhat 9
- PPC32 (7447/G4) / Yellow Dog 4.0
- PPC64 (G5/Power4) / RHEL
- MIPS64 (24K) / Gentoo
Bug Reports
Bugs should be submitted to the author via the OSPAT development mailing List. Be sure to mention the word MONITOR somewhere in the subject line.
Author
Monitor was written by Philip J. Mucci of the Innovative Computing Laboratory while on sabbatical at the Parallel Center for Computers at the Royal Institute of Technology in Stockholm, Sweden. This library contains code from HPCToolkit, written by Nathan Tallent and John Mellor-Crummey of Rice University.
Copyright
This software is COMPLETELY OPEN SOURCE. If you incorporate any portion of this software, I would appreciate an acknowledgement in the appropriate places. Should you find PapiEx useful, please considering making a contribution in the form of hardware, software or plain old cash.