\documentclass{article}

\usepackage{graphics}

\usepackage{code}

%hyperref - do not remove this comment

\begin{document}

\title{A Name Publishing Interface for MPICH}

\author{William Gropp}

\maketitle

\section{Introduction}

MPI defines a set of routines for exchanging data with other MPI

programs.  The intent of these is to allow MPI applications to 

exchange the data that is needed for the \code{port} argument in the

\code{MPI_Comm_connect} and \code{MPI_Comm_accept} calls.  

\section{The MPI Name Publishing Routines}

MPI provides three routines to allow MPI applications to exchange the

\emph{port names} that are used to connect two running MPI

applications.  These routines are shown below in a modified C binding;

\code{const} is used to indicate input arguments and array notation is

used instead of pointer notation for character strings (this follows

the MPICH coding recommendations).

\begin{verbatim}

MPI_Publish_name( const char service_name[], const MPI_Info info, 

                  const char port_name[] )

MPI_Unpublish_name( const char service_name[], 

                    const MPI_Info info, 

                    const char port_name[] )

MPI_Lookup_name( const char service_name[], const MPI_Info info, 

                 char port_name[MPI_MAX_PORT_NAME] )

\end{verbatim}

In these routines, the \code{port_name} is the name returned by

\code{MPI_Open_port}.  

The \code{service_name} is a name chosen by the

applications as the name that all related applications will use to

look up the \code{port_name}.

The \code{info} argument is used to pass any necessary information to

the name publishing system (the reason for this will become clear in

Section~\ref{sec:sample-impls}). 

\section{Why Another Interface?}

An alternative to developing another interface is to extend the

process management interface (PMI).  An advantage to this is that the

MPI process already has a connection to the outside world, used by the

PMI interface to implement the PMI put/get interface.  Thus, an

extension to the PMI interface could support the name publishing

routines (an extension is needed because the MPI name publishing

routines are independent, not collective).

To see why another interface is needed, consider the situation in

Figure~\ref{fig:multiple-pm}.  In this Figure, two MPI programs, each

started by a different process manager, wish to connect.  For example,

one MPI job may be run on a batch system (the PBS job in this example)

and one on an interactive visualization cluster.

\begin{figure}

\centerline{\includegraphics{twopm.eps}}

\caption{Two MPI applications using name publishing with two different

process managers}\label{fig:multiple-pm}

\end{figure}

To implement this scenario, it is necessary to separate the name

publishing interface from the process management interface.  

Of course, in a scenario in which there are two MPI jobs using the

same process manager, the process manager could provide the name

service.  The proposed interface allows implementations use either a

separate service or the process manager

\section{A Proposed Interface}

\label{sec:name-interface}

The interface described here provides all the services necessary for

implementing the MPI name servie routines.  In order to provide a hook

for the name service implementation to initialize, there are separate

initializating and finalize calls.  These can, for example, open a

connection to a name service.  The initialization call returns a

handle of type \code{MPID_NS_Handle} that is used in all of the other

calls.  As in other MPI calls, the free routine takes a pointer to the

handle so that the handle can be set to null when the free routine

succeeds.  Each of these routines returns either \code{MPI_SUCCESS} or

a valid MPI error code; implementations may either use the MPICH

error code mechanism or, for external packages, use the MPI routines

for adding error codes and classes.

\begin{verbatim}

int MPID_NS_Create( const MPIR_Info *, MPID_NS_Handle * )

int MPID_NS_Publish( MPID_NS_Handle, const MPIR_Info *,

                     const char service_name[], const char port[] )

int MPID_NS_Lookup( MPID_NS_Handle, const MPIR_Info *,

                    const char service_name[], char port[] )

int MPID_NS_Unpublish( MPID_NS_Handle, const MPIR_Info *,

                       const char service_name[] )

int MPID_NS_Free( MPID_NS_Handle * )

\end{verbatim}

These calls make use of the \code{MPIR_Info} pointer (a pointer to the

info object passed into the MPI name publisher routines) to provide other

information that the name service may require.

Predefined \code{MPI_Info} keys and values for name service are:

\begin{description}

\item[\code{NAMEPUB\_CONTACT}]Value is a string providing contact

  information for the name service.  This may be an IP address or

  something else (see below).

\item[\code{NAMEPUB\_CREDENTIAL}]Value is a string providing

  credentials for accessing the name service.  The exact format is

  specified by the name service.  See also \code{NAMEPUB_USER}.

\item[\code{NAMEPUB\_EXPIRE}]Value is an integer, represented as a

  string, that specifies an expiration time in seconds from the time

  that a name is published.

\item[\code{NAMEPUB\_IP}]Value is the IP address as a string, usually

  in ``hostname:port'' format.  This is an alternative to

  \code{NAMEPUB_CONTACT}. 

\item[\code{NAMEPUB\_IP\_FROM\_ENV}]Value is the name of an environment

  variable whose value has the same meaning as the \code{NAMEPUB_IP}

  info key. 

\item[\code{NAMEPUB\_REFCOUNT}]Value is an integer, represented as a

  string, giving the number of times a value can

  be looked up before being deleted from the name service.  Set only

  on \code{MPI_Publish_name}.

\item[\code{NAMEPUB\_USER}]Value is a string giving the user name.

\end{description}

Two of these info parameters make slight changes to the semantics of

the name publishing routines by providing a way to cause names to

expire without an explicit call to \code{MPI_UNPUBLISH_NAME}.

However, the benefit of these in terms of ensuring that the name

service does not become clogged with old names outweighs the MPI

requirement that \code{MPI_Info} parameters make no changes to the

semantics of the routines.  

\section{A Few Possible Implementations}

\label{sec:sample-impls}

This section outlines three possible implementations.

\subsection{LDAP}

\label{sec:namepub-ldap}

The Lightweight Directory Access Protocol (LDAP) \cite{ldap} is a

standard for providing general name lookup services.  Open source

implementations of LDAP are available; at many locations, an LDAP

server may already be running.  The following sketches the routines

from OpenLDAP that can be used to implement the name interface.

\begin{description}

\item[\code{MPID\_NS\_Create}]Use \code{ldap_open} to access the ldap server

\item[\code{MPID\_NS\_Publish}]Use \code{ldap_add_s} to insert the name

\item[\code{MPID\_NS\_Lookup}]Use \code{ldap_search_s}, \code{ldap_first_entry}, and

  \code{ldap_get_values} to access the entry

\item[\code{MPID\_NS\_Unpublish}]Use \code{ldap_modify_s} to remove the name

\item[\code{MPID\_NS\_Free}]Use \code{ldap_unbind_s} and \code{ldap_memfree}

\end{description}

\subsection{File}

\label{sec:namepub-file}

If all MPI processes share a single filesystem, a simple

implementation of the name service can use the file system.  

In this design, each value is placed into a separate file whose name

include the key; this avoids

any problems with concurrent updates to a single file.

\begin{description}

\item[\code{MPID\_NS\_Create}]Create a structure to hold the names of all files created.

\item[\code{MPID\_NS\_Publish}]Create a file using a name containing the user, contact

  string, and the key.  The text of the file is the value of the name.

  Save the file name in the name service structure.  Protection is

  provided by the file system.

\item[\code{MPID\_NS\_Unpublish}]Unlink (remote) the file; remove the file name from

  the name service structure.

\item[\code{MPID\_NS\_Lookup}]For the filename using the same rule in publish and read

  the file.

\item[\code{MPID\_NS\_Free}]Remove all of the created files.

\end{description}

Some of the features, such as \code{NAMEPUB_EXPIRE}, are not supported

by this interface.  The info key \code{NAMEPUB_CONTACT} can be used to

specify the directory into which the files will be placed.

\end{document}