MATmarks User's Manual

MMK_Init(2)

3.3 Running MATmarks with the help of tkmarks

To start up tkmarks, you need to have Tcl/Tk installed on your system. Go to the MATmarks installation directory and type

wish tkmarks 2

wish tkmarks host1 host2 ... 

The window may become unwieldy if you use very many processors. We are working on fixing this problem.

In the tkmarks application there is a scrollable window for each of the member processes; if you type into a member process window, the text will be sent to that process only. You can use the per-process text entry widgets (just below the text windows) for the same purpose.

To talk to all processes at once, type into the all-process text entry (as shown on the figure above). The text you type in will be sent when you hit .

The Init button takes care of sending the necessary MMK_Init commands to all processes. When this is done, the Init button will gray out to prevent you from accidentally sending the same set of commands again.

The initial directory text widget specifies the current directory where all the MATLAB processes when Init is done.

The Exit button kills all the MATLABtkmarks processes, but doesn't exit from tkmarks to let you see the Treadmarks^® statistics. Use your window manager to kill tkmarks.

Initializes the MATmarks system.

If the argument is a number, then MATmarks reads nprocs hostnames from the $HOME/.Tmkrc file and runs the processes on those hosts. If the $HOME/.Tmkrc does not exist, the command aborts with an error.

If the argument to MMK_Init specifies a list of hosts, then $HOME/.Tmkrc is ignored; instead, MATmarks expects to start the processes on the hosts as listed in the argument.

The startup process is done either manually, by the user typing MMK_Init, or automatically through the GUI .

The manual startup process is as follows: the user emits the startup command on the first of the MATLAB^® processes. The interpreter writes back to the console the proper command line to start up the second process, then hangs waiting to establish communication. If the startup sequence is done manually, the user is required to copy the proper command into the command line of the second MATLAB^® process. This procedure is repeated until all the member processes have been initialized. Then, and only then, the first process returns to the command prompt.

The automatic startup process is similar, except that the GUI takes care of the proper distribution of the MMK_Init commands.

4.1.2 Leaving MATmarks: MMK_Exit

Quits the MATmarks system. The exitcode parameter is optional.

MMK_Exit kills not only the MATmarks subsystem, but quits the interpreter(s) as well. The standard MATLAB^® exit command works as well and performs the same function.

Note that MMK_Exit involves the passage of a barrier. Thus, if only one of e the member processes calls MMK_Exit, this process will hang. The barrier is necessary because, if one of the processes were to leave the cluster before the others finish their work, the TreadMarks^® system would collapse.

4.2 Shared variables

This command declares varname to be a variable shared by all processors. The initial_value parameter declares both the size and the initial value for the variable.

A shared variable must not be allowed to grow beyond the size declared by initial_value (i.e., a shared variable can not grow in size during the execution of the program). Growing a shared variable during execution results in a runtime error which leaves all running instances of MATLAB^® in an unpredictable state.

All processors should see the same value for a shared variable. However, because of the lazy release consistency protocol that is used in TreadMarks^®, processors may see different values of the variable, until a synchronization point is reached. Such uses of shared variables is considered to be a data race, and it is not considered good deterministic programming.

4.2.2 Removing shared variables: MMK_Clear

MMK_Clear removes all MATLAB^® variables, including those from the shared memory. It performs pretty much the same function as the MATLAB^® clear command, except that it is safe to use on shared variables.

MMK_Clear involves the passage of a barrier. This is necessary to ensure that all member processes forget their shared variables at the same time.

More work needs to be done on this, to make MMK_Clear discriminative (i.e. to make it free only shared variables) and to make the MATLAB^® clear command safe to use.

4.3 Synchronization

A barrier provides a global synchronization point across all processors. Processors arriving at a barrier will wait for all processors to arrive to the barrier before proceeding further. Barriers will also make the shared memory consistent in all running processes, communicating all changes that occured since the last synchronization point.

Note that since a barrier involves communication between all processors, and our processors are workstations, barriers could be very expensive.

Also note that MATmarks barriers, as opposed to TreadMarks^® barriers, have no arguments. We don't consider this a restriction, as good shared-memory programs don't require barrier numbers anyway.

4.3.2 Locks

Syntax: MMK_Unlock(lock_id)

Locks define critical sections in the code. Only one processor can be in a critical section at any moment. Locks are used to protect changes to shared variables.

There is only a finite number of locks available. Use low numbers (i.e. less than 1000) as lock arguments.

4.4 Miscellaneous MATmarks Commands

Returns this processor's number. Each processor running in a cluster of MATmarks processes is guaranteed to have a unique number, anywhere from 0 to MMK_nprocs-1.

4.4.2 MMK_nprocs

Returns the number of processors involved in running the program. This number is guaranteed to be the same on all processes in a cluster.

4.4.3 MMK_addr

This command is not strictly related to shared memory programming; it is mostly a debugging tool. MMK_addr prints out the MATLAB^® address of a variable.

The MATLAB^® representation of variables, described in the documentation, is a complex structure called mxArray (or Matrix in versions of MATLAB^® prior to 5.0).

MMK_addr prints three things: the address of the allocated mxArray; the address of the real part of a "dense" (i.e. not "sparse") array; and the address of the imaginary part of the same. An all-real array will have a NULL imaginary part.

4.4.4 MMK_Debug

This command sets the debug level of MATmarks. Unless you want to dig into the innards of MATmarks, MMK_Debug will probably not do anything useful for you.

MMK_Clear;
MMK_Share('sum', 0);
MMK_Barrier

for i=1+MMK_proc_id:MMK_nprocs:10,
  fprintf (1, 'processor %d adding %d to sum\n', MMK_proc_id, i);
  MMK_Lock (1);
  sum = sum + i;
  MMK_Unlock(1);
end

Note how all shared assignments/operations make heavy use of the ":" operator, in order to comply with the restrictions we imposed on the language (see section 5).

MMK_Clear;
MMK_Share('n', 1000);
MMK_Share('a', zeros(n,n));
MMK_Share('b', zeros(n,n));
MMK_Share('c', zeros(n,n));
MMK_Barrier;

% ------------- assign variables ------------
if (MMK_proc_id == 0),
  a(:,:) = rand(n,n);
  locala = a(:,:);
  b(:,:) = rand(n,n);
  localb = b(:,:);
end

% ------------ calculate bounds -------------
MMK_Barrier;
lbound = ceil (n/MMK_nprocs*MMK_proc_id);
if (mod(n*MMK_proc_id, MMK_nprocs)==0), lbound = lbound + 1; end
ubound = floor (n/MMK_nprocs*(MMK_proc_id+1));

% ------------ perform multiplication -------
t1= cputime;
c(:, lbound:ubound) = a(:,:)*b(:,lbound:ubound);
MMK_Barrier;
t2= cputime;

% ------------- check result ----------------
if (MMK_proc_id == 0),
  fprintf (1, 'Error: %f\n', sum(sum (locala*localb - c)));
end

TIME=t2 - t1