COMPONENT

    appio

SUMMARY

    Application I/O component

DESCRIPTION

    This application I/O component enables PAPI-C to determine
    I/O used by the application. This is to be distinguished
    from system-wide I/O statistics. The goal of this component
    is to help the programmer attribute the I/O (read/write) to
    files and sockets, to the source code.

    Listed below are the events measured by the component:

    Event names
    -----------
      READ_BYTES READ_CALLS READ_ERR READ_INTERRUPTED READ_WOULD_BLOCK READ_SHORT READ_EOF READ_BLOCK_SIZE READ_USEC
      WRITE_BYTES WRITE_CALLS WRITE_ERR WRITE_INTERRUPTED WRITE_WOULD_BLOCK WRITE_SHORT WRITE_BLOCK_SIZE WRITE_USEC
      OPEN_CALLS OPEN_ERR OPEN_FDS
      SELECT_USEC
      RECV_BYTES RECV_CALLS RECV_ERR RECV_INTERRUPTED RECV_WOULD_BLOCK RECV_SHORT RECV_EOF RECV_BLOCK_SIZE RECV_USEC

      SOCK_READ_BYTES SOCK_READ_CALLS SOCK_READ_ERR SOCK_READ_SHORT SOCK_READ_WOULD_BLOCK SOCK_READ_USEC 
      SOCK_WRITE_BYTES SOCK_WRITE_CALLS SOCK_WRITE_ERR SOCK_WRITE_SHORT SOCK_WRITE_WOULD_BLOCK SOCK_WRITE_USEC

      SEEK_CALLS SEEK_ABS_BLOCK_SIZE SEEK_USEC

    The component works by intercepting I/O system calls on Linux. At present,
    the code uses a features available in libc on Linux, and is unlikely to
    work on other platforms without modifications. The code works for static 
    and shared executables.

    The component has been tested on 32 and 64-bit Linux. It's also been tested
    to work for multithreaded programs.

    Limitations and future work:
    ---------------------------
    The most important aspect to note is that the code is likely to only work on
    Linux, given the low-level dependencies on libc features. 

    At present the component intercepts the open(), close(), read(), write(), 
    fread() and fwrite(). In the future it's expected that these will be expanded 
    to cover lseek(), select(), other I/O calls.

    While READ_* and WRITE_* calls will not distinguish between file and network
    I/O, the user can explicitly determine network statistics using SOCK_* calls.

    Threads are handled using thread-specific structures in the backend. However, no 
    aggregation is currently performed across threads. There is also NO global structure
    that has the statistics of all the threads. This means the user can call
    a PAPI read to get statitics for a running thread. However, if the thread has
    joined, then it's statistics can no longer be queried. 

    TESTING:
    -------
    Tests lie in the tests/ sub-directory. All but one test take no argument.

    The iozone test (appio_test_iozone) needs arguments just like iozone does.
    It is not built by default as part of the PAPI tests. To build it:
      cd appio/tests; make appio_test_iozone
    An example run for the iozone test could be:
      ./appio_test_iozone -s 100m -r 64 -i 0 -i 1 -t 1
    
   
AUTHOR

  The code is written by Tushar Mohan <tusharmohan@gmail.com> and
  Philip Mucci <mucci@eecs.utk.edu>. The component leverages code 
  written by Jose Pedro Oliveira <jpo@di.uminho.pt> for the PAPI 
  net component.

SEE ALSO


# vim:set ai ts=4 sw=4 sts=4 et:
