[Haskell-cafe] ANNOUNCE: hpapi 0.1 release

[Michael D. Adams]

I am pleased to announce the first release of hpapi, Performance API
(PAPI) bindings for Haskell.

The release is on Hackage:
  http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hpapi

The source repository is at:
  http://code.haskell.org/hpapi/

Please send bug reports to <adamsmd [AT] cs.indiana.edu>

What is it
==========
This is a simple set of bindings for the Performance API (PAPI).  PAPI
provides access to various CPU counters such as cache-miss,
instruction and pipeline stall counts.

The easiest way to use this library is the withCounts function:
  withCounts :: [EventCode] -> IO a -> IO (a, [Integer])
Given a list of events to count and an IO operation it will run the
operation and return the resulting counts.  So you could do something
like:

  main = do
    [l1,tlb,fp] <- withCounters [papi_l1_dcm, papi_tlb_dm, papi_fp_ins]
                     ioOperationToMeasure
    printLn (l1, tlb, fp)

To use it one will of course need the PAPI C library and any necessary
kernel modifications installed.

Status
======
The High Level interface (which will be sufficient for most people's
needs) should be usable, but the low level interface is still alpha
quality.

That is to say, it is ready for people to start banging on it, but it
is largely untested and the modules/interfaces may be reorganized
based on user feedback.

All of PAPI is supported with the exception of the following
"advanced" features:
 - Multiplexing
 - Threads
 - Locks
 - Overflow
 - Statistical Profiling

Future Directions
=================
Future directions will be determined largely by user feedback.

Principal areas that I am looking for feedback on are:
 - documentation
 - module organization
 - the handling of PAPI errors (currently it throws an IO error)
 - the design of the Haskell interface build on top of the C level
PAPI_get_opt and PAPI_set_opt
 - what advanced features of PAPI to build bindings for next

Comparison with GHC's built-in PAPI
===================================
GHC supports a built-in version of PAPI (see
http://hackage.haskell.org/trac/ghc/wiki/PAPI). This system is
different in a few ways.

First, hpapi allows you to measure specific parts of a program while
GHCI's PAPI only does whole program measurement

Second, since hpapi is a library you can have fine grained and
sophisticated control over how things are measured. On the other hand
GHC's PAPI as part of the RTS gives you less control, but on the plus
side doesn't require any modification to the program.

Finally, GHC's PAPI splits apart the counts that come from the garbage
collector from those that come from the mutator, while hpapi combines
them.  This is a limitation of hpapi we hope to correct some time in
the future.

It remains to be seen whether it would be worth while to unify these
two systems.

================

Bug reports as well as suggestions, feedback or contributions to the
API or the documentation most welcome.

Michael D. Adams