mpififo - inter-node named pipes over MPI
=========================================

mpififo is an MPI-based middleware that allows processes in a Unix pipeline to
execute on different nodes in a compute cluster via named pipes.

SUPPORTED PLATFORMS
===================

ipcmd requires the following environment:

  * POSIX
  * C compiler supporting C99
  * OpenMP 2.5
  * MPI implementation supporting MPI_THREAD_MULTIPLE (tested with MPICH 3.0.4)

CONTENTS
========

CHANGES   - Visible changes in the current version and previous versions
Makefile  - POSIX Makefile
README    - This file containing basic information & installation instructions
TODO      - Wish list of future modifications
mpififo.c - source code
tests     - Tests scripts run by "make check"
    
INSTALLATION
============

1. (Optional) Edit the Makefile, customize the CC and/or CFLAGS macro for your
   environment (CC and CFLAGS can also be overridden on the command-line as
   demonstrated below).

2. Issue the "make" command to build mpififo

   make [CC=...] [CFLAGS=...]

3. Submit a batch script or interactive job (e.g., "qsub -I" for PBS/TORQUE)
   that runs the test scripts (MPICH w/ Hydra process manager only):
   
   make check [NODES=1] [NPROC=4]

   By default, a single node & 4 processes are used.

USAGE
=====

[mpiexec] mpififo [-crv] writefifo1 readfifo1 [writefifo2 readfifo2...]
  -c : create fifos upon startup
  -r : remove fifos after mpififo exits
  -v : verbose output to stderr (for debugging)

See the web site and publication for more information.

WEB SITE
========

https://bitbucket.org/nathanweeks/mpififo

PUBLICATION
===========

Weeks N, Kraeva M, Luecke G. Parallelization of software pipelines using the
mpififo tool. Cluster Computing (CLUSTER), 2013 IEEE International Conference
on. [In Press]

Poster presented at IEEE CLUSTER 2013:
http://weeks.public.iastate.edu/files/mpififo_poster.pdf


KNOWN ISSUES
============

To terminate the execution of all mpififo processes, one of the mpififo
processes must be manually killed. As this is typically done by a job
scheduler upon completion of a job, this can be automated by running mpififo
asynchronously ("in the background") in the job script, without wait()'ing on
it. This issue will be addressed in a future release.

Deadlocks have been observed with OpenMPI 1.7.2. This seems to be an issue
with OpenMPI's support for MPI_THREAD_MULTIPLE, rather than a bug in the
mpififo code.

BUGS
====

Please report any bugs in the issue tracker at the web site.

AUTHOR
======

Nathan Weeks
http://weeks.public.iastate.edu/