This is documentation of the compose/perform interface to deposit
model message passing.  There are two primary goals for this interface:

    1. Separate message passing into two parts, message composition
       (in terms of addresses) and message performance.  The intent
       is to make it easy to amortize the cost of composition over
       many communications.

    2. Make possible a very free-form composition, while making it
       possible for the mpl to cast the communication is a form that
       is efficient for the available networking hardware.


Compositions

A simple composition is conceptually a set of 2-tuples that maps local
addresses to remote addresses on a singel receiver:

   simple_composition={d,{(l,r) | M_local[l] is delivered into M_d[r]}}

Tuples can be added to a simple composition via a number of
descriptive functions. 

A merged composition is a set of 3-tuples that maps local addresses to
remote addresses on multiple receivers:

   merged_composition={(l,r,d) | M_local[l] is delivered into M_d[r]}

Both simple and merged compositions can be merged, however, tuples can
only be added to a merged_composition via mergers.

A mapped composition is a simple or merged composition that has been
converted into a device-dependent form.  A composition must be mapped
before it can be performed.  Mapped compositions cannot be merged or
modified.  

Compositions are uniquely identified by an integer.  It is possible to
determine the type of a composition:

    int cp_comptype(int compnum);

cp_comptype returns a negative value if compnum is not a valid composition
or some other error occurred.  If it succeeds, it returns one of the following
values:
   
    CP_COMPTYPE_SIMPLE - Simple composition
    CP_COMPTYPE_MERGED - Merged composition
    CP_COMPTYPE_MAPPED - Mapped composition

Creating compositions

Simple and merged compositions can be created, loaded, stored, and destroyed.

    int   cp_create(int targetproc);
    int   cp_load(int filenum);
    int   cp_store(int filenum, int compnum);
    int   cp_destroy(int compnum);


Each of these functions returns a negative value on failure.  On success,
cp_create and cp_load return the number of the composition that was just
created or loaded.  This number uniquely identifies the composition.


Adding Addresses to a simple composition

    int   cp_add_adxpair(int compnum, 
                         void *localadx, 
                         void *remoteadx);
    int   cp_add_adxpairvector(int compnum,
                               void *localadx[],
                               void *remoteadx[],
                               unsigned int numpairs);
    int   cp_add_adxblock(int compnum,
                          void *localadxstart,
                          void *remoteadxstart,
                          unsigned int length);
    int   cp_add_adxblockvector(int compnum,
                                void *localadxstart[],
                                void *remoteadxstart[],
                                unsigned int length[],
                                unsigned int numblocks);
    int   cp_add_adxslice(int compnum,
                          void *localadxstart,
                          void *localadxstride,
                          unsigned int localblocklen,
                          unsigned int localnumblocks,
                          void *remoteadxstart,
                          void *remoteadxstride,
                          unsigned int remoteblocklen,
                          unsigned int remotenumblocks);

Each of these functions returns a negative value on failure and zero
on success.  The cp_add functions do not work on merged or mapped compositions.


Merging Simple or Merged Compositions

    int   cp_merge(int compnum1, int compnum2);

cp_merge operates on merged or unmerged compositions.  On failure, it
returns a negative value.  On sucess it returns a positive number that
uniquely identifies the merged composition.  Note that merging two
compositions does not destroy either of the compositions being merged.

  Merged compositions can also be loaded and stored with the functions
defined above.


Mapping compositions

    int   cp_map(int compnum);

cp_map operates on simple or merged compositions.  On failure, it 
returns a negative value.  On success, it returns a postive integer that
uniguely identifies the composition.  Note that the composition compnum
is unaffected. 

Mapped compositions can be loaded and stored using the functions defined
above.


Performances

Performance entails executing a mapped composition to copy the values
at local addresses to remote addresses.  Because performance implies
no intermediate buffering, it is necessary to synchronize before a 
performance.  The following assumes SPMD style phased execution.  
The communication is an exchange between P1 and P2 where source
and destination addresses do not overlap:


    P1                         P2

    cp_sync();                 cp_sync();

    cp_perform(compnum);       cp_perform(compnum);

    cp_waitfor(1);             cp_waitfor(1);