MPI Subroutine Reference

MPI_TYPE_GET_CONTENTS, MPI_Type_get_contents

Purpose

Obtains the arguments used in the creation of the datatype.

C synopsis

#include <mpi.h>
int MPI_Type_get_contents(MPI_Datatype datatype,int *max_integers, 
			  int *max_addresses, int *max_datatypes,
			  int array_of_integers[],
			  int array_of_addresses[],
			  int array_of_datatypes[]);

C++ synopsis

#include mpi.h
void MPI::Datatype::Get_contents(int max_integers, int max_addresses,
                                 int max_datatypes, int array_of_integers[],
                                 MPI::Aint array_of_addresses[],
                                 MPI::Datatype array_of_datatypes[]) 
				 const;

FORTRAN synopsis

include 'mpif.h' or use mpi
MPI_TYPE_GET_CONTENTS(INTEGER DATATYPE, INTEGER MAX_INTEGERS,INTEGER MAX_ADDRESSES, 
		      INTEGER MAX_DATATYPES,INTEGER ARRAY_of_INTEGERS, INTEGER ARRAY_OF_ADDRESSES,
		      INTEGER ARRAY_of_DATATYPES, INTEGER IERROR)

Parameters

datatype

is the datatype to access (handle) (IN)

max_integers

is the number of elements in array_of_integers (non-negative integer) (IN)

max_addresses

is the number of elements in the array_of_addresses (non-negative integer) (IN)

max_datatypes

is the number of elements in array_of_datatypes (non-negative integer) (IN)

array_of_integers

contains integer arguments used in the constructing datatype (array of integers) (OUT)

array_of_addresses

contains address arguments used in the constructing datatype (array of integers) (OUT)

array_of_datatypes

contains datatype arguments used in the constructing datatype (array of handles) (OUT)

If the combiner is MPI_COMBINER_NAMED, it is erroneous to call MPI_TYPE_GET_CONTENTS.

Table 4 lists the combiners and constructor arguments. The lowercase names of the arguments are shown.

Table 4. Combiners and constructor arguments

Description

MPI_TYPE_GET_CONTENTS identifies the combiner and returns the arguments that were used with this combiner to create the datatype of interest. A call to MPI_TYPE_GET_CONTENTS is normally preceded by a call to MPI_TYPE_GET_ENVELOPE to discover whether the type of interest is one that can be decoded and if so, how large the output arrays must be. An MPI_COMBINER_NAMED datatype is a predefined type that may not be decoded. The datatype handles returned in array_of_datatypes can include both named and derived types. The derived types may or may not already be committed. Each entry in array_of_datatypes is a separate datatype handle that must eventually be freed if it represents a derived type.

Notes

An MPI type constructor, such as MPI_TYPE_CONTIGUOUS, creates a datatype object within MPI and gives a handle for that object to the caller. This handle represents one reference to the object. IN PE MPI, the MPI datatypes obtained with calls to MPI_TYPE_GET_CONTENTS are new handles for the existing datatype objects. The number of handles (references) given to the user is tracked by a reference counter in the object. MPI cannot discard a datatype object unless MPI_TYPE_FREE has been called on every handle the user has obtained.

The use of reference-counted objects is encouraged, but not mandated, by the MPI standard. Another MPI implementation may create new objects instead. The user should be aware of a side effect of the reference count approach. Suppose mytype was created by a call to MPI_TYPE_VECTOR and used so that a later call to MPI_TYPE_GET_CONTENTS returns its handle in hertype. Because both handles identify the same datatype object, attribute changes made with either handle are changes in the single object. That object will exist at least until MPI_TYPE_FREE has been called on both mytype and hertype. Freeing either handle alone will leave the object intact and the other handle will remain valid.

Errors

Invalid datatype

Predefined datatype

Maximum array size is not big enough

MPI already finalized

MPI not initialized

Related information

MPI_TYPE_COMMIT

MPI_TYPE_FREE

MPI_TYPE_GET_ENVELOPE