Prof. Matloff's Notes on Adsmith

Installation:

If you wish to install adsmith, say on your Linux box, first install PVM and make sure your search path and environment variables are set properly for it. (If you are on the ACS machines, PVM is already installed there.)

In your ~/.cshrc file, add a line

setenv ADSMHOME xxxx

where xxxx is the directory containing the adsmith include/ and lib/ directories.

Next, follow the directions for compilation given in the adsmith Readme file, meaning that you just type "make". However, I recommend that you change src/Makefile.aimk so that BDIR is ~/pvm3/bin, and will assume this below.

If you have Red Hat Linux, you may need to change line 41 of src/sysdept.h, removing

extern "C"

to make it consistent with the g++ compiler's own file.

This will at least produce the essentials: the library $ADSMHOME/lib/$PVM_ARCH/libadsm.a and the executables ~/pvm3/bin/$PVM_ARCH/admsd and ~/pvm3/bin/$PVM_ARCH/admsgate. (It may blow up in compiling the "cord" test program.)

To test the system, try the matmul application, by starting up PVM and then typing

matmul -5

You should get output consisting of a 5x5 matrix with 5s for all entries.

How to Write, Compile and Run Adsmith Programs:

Writing:

Adsmith application programs should be written in C++ (or at least C++-compatible C).

Look at the package's example programs to get an idea as to which library functions are available. You may wish to read my own example program first, as it contains a large number of comments of a tutorial nature.

Important note: Adsmith's adsm_malloc() function returns a pointer with which you access shared variables. Make sure that you do not corrupt these pointers. For example, if XP points to a shared variable X and you wish to set that variable to 12, make sure that you do this by

*XP = 12;
adsm_flush(XP);

rather than

XP = 12;
adsm_flush(XP);

An error like the latter will likely result in an error message like

P0/H0:  Warning: wrong pointer 0x8099714 to a shared object                     
P0/H0:  Adsmith: try to shutdown the application...

Here are some of the more common library functions:

get_seqno()           gets the node number for this node (like MPI "rank")
adsm_malloc()         required to initialize shared scalars
adsm_malloc_array()   required to initialize shared scalars
adsm_spawn()          like PVM's spawn
adsm_refresh()        get latest copy of the shared variable
adsm_prefresh()       start prefetch of shared variable (nonblocking,
                      but still must call adsm_refresh() later as a
                      means of ensuring that the data has arrived)
adsm_flush()          release data for update to other nodes
adsm_gid()            gets shared pointer value

The adsm_malloc_array() function is somewhat tricky to use, and there seems to be a "begin" argument which is not even mentioned in the documentation. I recommend that you just make repeated calls to adsm_malloc() instead, as in my own example program mentioned above.

Many other functions are available, including in C++ classes such as

AdsmMutex             mutex lock/unlock
AdsmSemaphore         semaphore
AdsmBarrier           barrier
Timing                program performance timing

Make sure your program has the proper include files:

#include 
#include 
#include "adsm.h"
#include "adsmutil.h"
#include "adsmtime.h"

Note that argc and argv in main() will not be transmitted to the spawned processes, so you must transmit these via shared variables.

Compiling:

To compile an adsmith application source file y.C (in C++) and produce an executable named y, type

g++ -g -o ~/pvm3/bin/$PVM_ARCH/y -I$PVM_ROOT/include -I$ADSMHOME/include y.C -L$PVM_ROOT/lib/$PVM_ARCH -L$ADSMHOME/lib/$PVM_ARCH -ladsm -lpvm3 -lgpvm3

Note:

The -ladsm must precede the -lpvm3.
For some architectures you must include an additional library, such as -lsocket on SPARCs. See one of the Makefile.aimk files within the adsmith examples/ subdirectory.

You may wish to set up an alias in your .cshrc file for the compile command.

Running:

Then to run the program compiled from y.C, start PVM and type "y" and y's command-line arguments in the Unix shell (not at the PVM console prompt).

Leaving:

Don't forget to shut down PVM later after you are done.

Output:

What about your output? NOTE CAREFULLY that all the output from printf() calls will be collected by pvmd at whichever machine you started it. These may be interspersed together from different nodes, making your output difficult or impossible to read. For this reason, make sure the node number is printed in each call to printf(). (Note: This interspersing of printf() outputs is quite common in parallel systems.)

Debugging:

See my parallel debugging page.