binutils-gdb/gprofng/examples/mxv-pthreads

README for the matrix-vector multiplication demo code

Synopsis

This program implements the multiplication of a matrix and a vector. It is written in C and has been parallelized using the Pthreads parallel programming model. Each thread gets assigned a contiguous set of rows of the matrix to work on and the results are stored in the output vector.

The code initializes the data, executes the matrix-vector multiplication, and checks the correctness of the results. In case of an error, a message to this extent is printed and the program aborts. Otherwise it prints a one line message on the screen.

About this code

This is a standalone code, not a library. It is meant as a simple example to experiment with gprofng.

Directory structure

There are four directories:

1. bindir - after the build, it contains the executable.

2. experiments - after the installation, it contains the executable and also has an example profiling script called profile.sh.

3. objects - after the build, it contains the object files.

4. src - contains the source code and the make file to build, install, and check correct functioning of the executable.

Code internals

This is the main execution flow:

• Parse the user options.
• Compute the internal settings for the algorithm.
• Initialize the data and compute the reference results needed for the correctness check.
• Create and execute the threads. Each thread performs the matrix-vector multiplication on a pre-determined set of rows.
• Verify the results are correct.
• Print statistics and release the allocated memory.

Installation

The Makefile in the src subdirectory can be used to build, install and check the code.

Use make at the command line to (re)build the executable called mxv-pthreads. It will be stored in the directory bindir:

$ make
gcc -o ../objects/main.o -c -g -O -Wall -Werror=undef -Wstrict-prototypes main.c
gcc -o ../objects/manage_data.o -c -g -O -Wall -Werror=undef -Wstrict-prototypes manage_data.c
gcc -o ../objects/workload.o -c -g -O -Wall -Werror=undef -Wstrict-prototypes workload.c
gcc -o ../objects/mxv.o -c -g -O -Wall -Werror=undef -Wstrict-prototypes mxv.c
gcc -o ../bindir/mxv-pthreads  ../objects/main.o ../objects/manage_data.o ../objects/workload.o ../objects/mxv.o -lm -lpthread
ldd ../bindir/mxv-pthreads
	linux-vdso.so.1 (0x0000ffff9ea8b000)
	libm.so.6 => /lib64/libm.so.6 (0x0000ffff9e9ad000)
	libc.so.6 => /lib64/libc.so.6 (0x0000ffff9e7ff000)
	/lib/ld-linux-aarch64.so.1 (0x0000ffff9ea4e000)
$

The make install command installs the executable in directory experiments.

$ make install
Installed mxv-pthreads in ../experiments
$

The make check command may be used to verify the program works as expected:

$ make check
Running mxv-pthreads in ../experiments
mxv: error check passed - rows = 1000 columns = 1500 threads = 2
$

The make clean comand removes the object files from the objects directory and the executable from the bindir directory.

The make veryclean command implies make clean, but also removes the executable from directory experiments.

Usage

The code takes several options, but all have a default value. If the code is executed without any options, these defaults will be used. To get an overview of all the options supported, and the defaults, use the -h option:

$ ./mxv-pthreads -h
Usage: ./mxv-pthreads [-m <number of rows>] [-n <number of columns] [-r <repeat count>] [-t <number of threads] [-v] [-h]
	-m - number of rows, default = 2000
	-n - number of columns, default = 3000
	-r - the number of times the algorithm is repeatedly executed, default = 200
	-t - the number of threads used, default = 1
	-v - enable verbose mode, off by default
	-h - print this usage overview and exit
$

For more extensive run time diagnostic messages use the -v option.

As an example, these are the options to compute the product of a 2000x1000 matrix with a vector of length 1000 and use 4 threads. Verbose mode has been enabled:

$ ./mxv-pthreads -m 2000 -n 1000 -t 4 -v
Verbose mode enabled
Allocated data structures
Initialized matrix and vectors
Defined workload distribution
Assigned work to threads
Thread 0 has been created
Thread 1 has been created
Thread 2 has been created
Thread 3 has been created
Matrix vector multiplication has completed
Verify correctness of result
Error check passed
mxv: error check passed - rows = 2000 columns = 1000 threads = 4
$

Executing the examples

Directory experiments contains the profile.sh script. This script checks if gprofng can be found and for the executable to be installed.

The script will then run a data collection experiment, followed by a series of invocations of gprofng display text to show various views. The results are printed on stdout.

To include the commands executed in the output of the script, and store the results in a file called LOG, execute the script as follows:

$ bash -x ./profile.sh >& LOG

Additional comments

• The reason that compiler based inlining is disabled is to make the call tree look more interesting. For the same reason, the core multiplication function mxv_core has inlining disabled through the void __attribute__ ((noinline)) attribute. Of course you're free to change this. It certainly does not affect the workings of the code.

• This distribution includes a script called profile.sh. It is in the experiments directory and meant as an example for (new) users of gprofng. It can be used to produce profiles at the command line. It is also suitable as a starting point to develop your own profiling script(s).