Utility functions

For a given communicator there is one master process per MPI client the communicator spans. The master process for a client is the process of lowest rank running under the client. Note that process rank 0 within a communicator is always a master process. The master processes in a communicator are numbered from 0 to (number of masters) - 1 in order of rank in the communicator.

For example consider the case of a communicator of size 8 which spans 3 clients (say A, B and C) with ranks 0,1,4 under client A, ranks 2,3,5 under client B and ranks 6,7 under client C. Then the master processes are ranks 0,2 and 6 and they are numbered 0,1 and 2 respectively.

The descriptions of the IMPI collectives make use of the following utility functions. Each implementation is free to implement them in whichever manner they see fit.

int is_master(int r, MPI_Comm comm)

Returns TRUE iff process rank r in comm is a master process.

int are_local(int r1, int r2, MPI_Comm comm)

Returns TRUE iff processes ranked r1 and r2 in comm are local to one-another.

int master_num(int r, MPI_Comm comm)

If process rank r in comm is a master process returns its master number else returns -1.

int master_rank(int n, MPI_Comm comm)

Returns the rank in comm of master number n.

int local_master_num(int r, MPI_Comm comm)

Returns the master number of the master process local to process rank r in comm.

int local_master_rank(int n, MPI_Comm comm)

Returns the rank in comm of the master process local to process rank r in comm.

int num_masters(MPI_Comm comm)

Returns the number of master processes in comm.

int num_local_to_master(int n, MPI_Comm comm)

Returns the number of processes in comm local to master process number n.

int num_local_to_rank(int r, MPI_Comm comm)

Returns the number of processes in comm local to process rank r in comm.

int *locals_to_master(int n, MPI_Comm comm)

Returns an array containing the ranks in comm of the processes local to master number n.

int cubedim(int n)

If n > 0 returns the dimension of the smallest hypercube containing at least n vertices (i.e. smallest i such that n <= 2ⁱ) else returns -1.

int hibit(int r, int dim)

Returns the position of the highest bit set in the lowest dim bits of r else -1 if no bit is set in the lowest dim bits of r. E.g. hibit(5,3) = 2, hibit(5,2) = 0, hibit(8,2) = -1.