|
Packit Service |
c5cf8c |
/* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil ; -*- */
|
|
Packit Service |
c5cf8c |
/*
|
|
Packit Service |
c5cf8c |
* (C) 2001 by Argonne National Laboratory.
|
|
Packit Service |
c5cf8c |
* See COPYRIGHT in top-level directory.
|
|
Packit Service |
c5cf8c |
*/
|
|
Packit Service |
c5cf8c |
|
|
Packit Service |
c5cf8c |
#ifndef MPIR_ATTR_GENERIC_H_INCLUDED
|
|
Packit Service |
c5cf8c |
#define MPIR_ATTR_GENERIC_H_INCLUDED
|
|
Packit Service |
c5cf8c |
|
|
Packit Service |
c5cf8c |
/* ------------------------------------------------------------------------- */
|
|
Packit Service |
c5cf8c |
/* Keyvals and attributes */
|
|
Packit Service |
c5cf8c |
/*TKyOverview.tex
|
|
Packit Service |
c5cf8c |
|
|
Packit Service |
c5cf8c |
Keyvals are MPI objects that, unlike most MPI objects, are defined to be
|
|
Packit Service |
c5cf8c |
integers rather than a handle (e.g., 'MPI_Comm'). However, they really
|
|
Packit Service |
c5cf8c |
`are` MPI opaque objects and are handled by the MPICH implementation in
|
|
Packit Service |
c5cf8c |
the same way as all other MPI opaque objects. The only difference is that
|
|
Packit Service |
c5cf8c |
there is no 'typedef int MPI_Keyval;' in 'mpi.h'. In particular, keyvals
|
|
Packit Service |
c5cf8c |
are encoded (for direct and indirect references) in the same way that
|
|
Packit Service |
c5cf8c |
other MPI opaque objects are
|
|
Packit Service |
c5cf8c |
|
|
Packit Service |
c5cf8c |
Each keyval has a copy and a delete function associated with it.
|
|
Packit Service |
c5cf8c |
Unfortunately, these have a slightly different calling sequence for
|
|
Packit Service |
c5cf8c |
each language, particularly when the size of a pointer is
|
|
Packit Service |
c5cf8c |
different from the size of a Fortran integer. The unions
|
|
Packit Service |
c5cf8c |
'copy_function' and 'delete_function' capture the differences
|
|
Packit Service |
c5cf8c |
in a single union type.
|
|
Packit Service |
c5cf8c |
|
|
Packit Service |
c5cf8c |
The above comment is out of date but has never been updated as it should
|
|
Packit Service |
c5cf8c |
have to match the introduction of a different interface. Beware!
|
|
Packit Service |
c5cf8c |
|
|
Packit Service |
c5cf8c |
Notes:
|
|
Packit Service |
c5cf8c |
|
|
Packit Service |
c5cf8c |
In the original design, retrieving a attribute from a different
|
|
Packit Service |
c5cf8c |
language that set it was thought to be an error. The MPI Forum
|
|
Packit Service |
c5cf8c |
decided that this should be allowed, and after much discussion, the
|
|
Packit Service |
c5cf8c |
behavior was defined. Thus, we need to record what sort of
|
|
Packit Service |
c5cf8c |
attribute was provided, and be able to properly return the correct
|
|
Packit Service |
c5cf8c |
value in each case. See MPI 2.2, Section 16.3.7 (Attributes) for
|
|
Packit Service |
c5cf8c |
specific requirements. One consequence of this is that the value
|
|
Packit Service |
c5cf8c |
that is returned may have a different length that how it was set.
|
|
Packit Service |
c5cf8c |
On little-endian platforms (e.g., x86), this doesn't cause much of a
|
|
Packit Service |
c5cf8c |
problem, because the address is that of the least significant byte,
|
|
Packit Service |
c5cf8c |
and the lower bytes have the data that is needed in the case that
|
|
Packit Service |
c5cf8c |
the desired attribute type is shorter than the stored attribute.
|
|
Packit Service |
c5cf8c |
However, on a big-endian platform (e.g., IBM POWER), since the most
|
|
Packit Service |
c5cf8c |
significant bytes are stored first, depending on the length of the
|
|
Packit Service |
c5cf8c |
result type, the address of the result may not be the beginning of
|
|
Packit Service |
c5cf8c |
the memory area. For example, assume that an MPI_Fint is 4 bytes
|
|
Packit Service |
c5cf8c |
and a void * (and a Fortran INTEGER of kind MPI_ADDRESS_KIND) is 8
|
|
Packit Service |
c5cf8c |
bytes, and let the attribute store the value in an 8 byte integer in
|
|
Packit Service |
c5cf8c |
a field named "value". On a little-endian platform, the address of
|
|
Packit Service |
c5cf8c |
the value is always the beginning of the field "value". On a
|
|
Packit Service |
c5cf8c |
big-endian platform, the address of the value is the beginning of
|
|
Packit Service |
c5cf8c |
the field if the return type is a pointer (e.g., from C) or Fortran
|
|
Packit Service |
c5cf8c |
(KIND=MPI_ADDRESS_KIND), and the address of the beginning of the
|
|
Packit Service |
c5cf8c |
field + 4 if the return type is a Fortran 77 integer (and, as
|
|
Packit Service |
c5cf8c |
specified above, an MPI_Fint is 4 bytes shorter than a void *).
|
|
Packit Service |
c5cf8c |
|
|
Packit Service |
c5cf8c |
For the big-endian case, it is possible to manage these shifts (using
|
|
Packit Service |
c5cf8c |
WORDS_LITTLEENDIAN to detect the big-endian case). Alternatively,
|
|
Packit Service |
c5cf8c |
at a small cost in space, copies in variables of the correct length
|
|
Packit Service |
c5cf8c |
can be maintained. At this writing, the code in src/mpi/attr makes
|
|
Packit Service |
c5cf8c |
use of WORDS_LITTLEENDIAN to provide the appropriate code for the most
|
|
Packit Service |
c5cf8c |
common cases.
|
|
Packit Service |
c5cf8c |
|
|
Packit Service |
c5cf8c |
T*/
|
|
Packit Service |
c5cf8c |
/*TAttrOverview.tex
|
|
Packit Service |
c5cf8c |
*
|
|
Packit Service |
c5cf8c |
* The MPI standard allows `attributes`, essentially an '(integer,pointer)'
|
|
Packit Service |
c5cf8c |
* pair, to be attached to communicators, windows, and datatypes.
|
|
Packit Service |
c5cf8c |
* The integer is a `keyval`, which is allocated by a call (at the MPI level)
|
|
Packit Service |
c5cf8c |
* to 'MPI_Comm/Type/Win_create_keyval'. The pointer is the value of
|
|
Packit Service |
c5cf8c |
* the attribute.
|
|
Packit Service |
c5cf8c |
* Attributes are primarily intended for use by the user, for example, to save
|
|
Packit Service |
c5cf8c |
* information on a communicator, but can also be used to pass data to the
|
|
Packit Service |
c5cf8c |
* MPI implementation. For example, an attribute may be used to pass
|
|
Packit Service |
c5cf8c |
* Quality of Service information to an implementation to be used with
|
|
Packit Service |
c5cf8c |
* communication on a particular communicator.
|
|
Packit Service |
c5cf8c |
* To provide the most general access by the ADI to all attributes, the
|
|
Packit Service |
c5cf8c |
* ADI defines a collection of routines that are used by the implementation
|
|
Packit Service |
c5cf8c |
* of the MPI attribute routines (such as 'MPI_Comm_get_attr').
|
|
Packit Service |
c5cf8c |
* In addition, the MPI routines involving attributes will invoke the
|
|
Packit Service |
c5cf8c |
* corresponding 'hook' functions (e.g., 'MPID_Comm_attr_hook')
|
|
Packit Service |
c5cf8c |
* should the device define them.
|
|
Packit Service |
c5cf8c |
*
|
|
Packit Service |
c5cf8c |
* Attributes on windows and datatypes are defined by MPI but not of
|
|
Packit Service |
c5cf8c |
* interest (as yet) to the device.
|
|
Packit Service |
c5cf8c |
*
|
|
Packit Service |
c5cf8c |
* In addition, there are seven predefined attributes that the device must
|
|
Packit Service |
c5cf8c |
* supply to the implementation. This is accomplished through
|
|
Packit Service |
c5cf8c |
* data values that are part of the 'MPIR_Process' data block.
|
|
Packit Service |
c5cf8c |
* The predefined keyvals on 'MPI_COMM_WORLD' are\:
|
|
Packit Service |
c5cf8c |
*.vb
|
|
Packit Service |
c5cf8c |
* Keyval Related Module
|
|
Packit Service |
c5cf8c |
* MPI_APPNUM Dynamic
|
|
Packit Service |
c5cf8c |
* MPI_HOST Core
|
|
Packit Service |
c5cf8c |
* MPI_IO Core
|
|
Packit Service |
c5cf8c |
* MPI_LASTUSEDCODE Error
|
|
Packit Service |
c5cf8c |
* MPI_TAG_UB Communication
|
|
Packit Service |
c5cf8c |
* MPI_UNIVERSE_SIZE Dynamic
|
|
Packit Service |
c5cf8c |
* MPI_WTIME_IS_GLOBAL Timer
|
|
Packit Service |
c5cf8c |
*.ve
|
|
Packit Service |
c5cf8c |
* The values stored in the 'MPIR_Process' block are the actual values. For
|
|
Packit Service |
c5cf8c |
* example, the value of 'MPI_TAG_UB' is the integer value of the largest tag.
|
|
Packit Service |
c5cf8c |
* The
|
|
Packit Service |
c5cf8c |
* value of 'MPI_WTIME_IS_GLOBAL' is a '1' for true and '0' for false. Likely
|
|
Packit Service |
c5cf8c |
* values for 'MPI_IO' and 'MPI_HOST' are 'MPI_ANY_SOURCE' and 'MPI_PROC_NULL'
|
|
Packit Service |
c5cf8c |
* respectively.
|
|
Packit Service |
c5cf8c |
*
|
|
Packit Service |
c5cf8c |
T*/
|
|
Packit Service |
c5cf8c |
|
|
Packit Service |
c5cf8c |
/* bit 0 distinguishes between pointers (0) and integers (1) */
|
|
Packit Service |
c5cf8c |
typedef enum {
|
|
Packit Service |
c5cf8c |
MPIR_ATTR_PTR = 0,
|
|
Packit Service |
c5cf8c |
MPIR_ATTR_AINT = 1,
|
|
Packit Service |
c5cf8c |
MPIR_ATTR_INT = 3
|
|
Packit Service |
c5cf8c |
} MPIR_Attr_type;
|
|
Packit Service |
c5cf8c |
|
|
Packit Service |
c5cf8c |
#define MPII_ATTR_KIND(_a) (_a & 0x1)
|
|
Packit Service |
c5cf8c |
|
|
Packit Service |
c5cf8c |
MPICH_API_PUBLIC int MPII_Comm_set_attr(MPI_Comm, int, void *, MPIR_Attr_type);
|
|
Packit Service |
c5cf8c |
MPICH_API_PUBLIC int MPII_Type_set_attr(MPI_Datatype, int, void *, MPIR_Attr_type);
|
|
Packit Service |
c5cf8c |
MPICH_API_PUBLIC int MPII_Win_set_attr(MPI_Win, int, void *, MPIR_Attr_type);
|
|
Packit Service |
c5cf8c |
MPICH_API_PUBLIC int MPII_Comm_get_attr(MPI_Comm, int, void *, int *, MPIR_Attr_type);
|
|
Packit Service |
c5cf8c |
MPICH_API_PUBLIC int MPII_Type_get_attr(MPI_Datatype, int, void *, int *, MPIR_Attr_type);
|
|
Packit Service |
c5cf8c |
MPICH_API_PUBLIC int MPII_Win_get_attr(MPI_Win, int, void *, int *, MPIR_Attr_type);
|
|
Packit Service |
c5cf8c |
|
|
Packit Service |
c5cf8c |
MPICH_API_PUBLIC int MPII_Comm_get_attr_fort(MPI_Comm, int, void *, int *, MPIR_Attr_type);
|
|
Packit Service |
c5cf8c |
|
|
Packit Service |
c5cf8c |
|
|
Packit Service |
c5cf8c |
#if defined(__cplusplus)
|
|
Packit Service |
c5cf8c |
extern "C" {
|
|
Packit Service |
c5cf8c |
#endif
|
|
Packit Service |
c5cf8c |
|
|
Packit Service |
c5cf8c |
/*E
|
|
Packit Service |
c5cf8c |
Language bindings for MPI
|
|
Packit Service |
c5cf8c |
|
|
Packit Service |
c5cf8c |
A few operations in MPI need to know how to marshal the callback into the calling
|
|
Packit Service |
c5cf8c |
lanuage calling convention. The marshaling code is provided by a thunk layer which
|
|
Packit Service |
c5cf8c |
implements the correct behavior. Examples of these callback functions are the
|
|
Packit Service |
c5cf8c |
keyval attribute copy and delete functions.
|
|
Packit Service |
c5cf8c |
|
|
Packit Service |
c5cf8c |
Module:
|
|
Packit Service |
c5cf8c |
Attribute-DS
|
|
Packit Service |
c5cf8c |
E*/
|
|
Packit Service |
c5cf8c |
|
|
Packit Service |
c5cf8c |
/*
|
|
Packit Service |
c5cf8c |
* Support bindings for Attribute copy/del callbacks
|
|
Packit Service |
c5cf8c |
* Consolidate Comm/Type/Win attribute functions together as the handle type is the same
|
|
Packit Service |
c5cf8c |
* use MPI_Comm for the prototypes
|
|
Packit Service |
c5cf8c |
*/
|
|
Packit Service |
c5cf8c |
typedef
|
|
Packit Service |
c5cf8c |
int
|
|
Packit Service |
c5cf8c |
(MPII_Attr_copy_proxy) (MPI_Comm_copy_attr_function * user_function,
|
|
Packit Service |
c5cf8c |
int handle,
|
|
Packit Service |
c5cf8c |
int keyval,
|
|
Packit Service |
c5cf8c |
void *extra_state,
|
|
Packit Service |
c5cf8c |
MPIR_Attr_type attrib_type,
|
|
Packit Service |
c5cf8c |
void *attrib, void **attrib_copy, int *flag);
|
|
Packit Service |
c5cf8c |
|
|
Packit Service |
c5cf8c |
typedef
|
|
Packit Service |
c5cf8c |
int
|
|
Packit Service |
c5cf8c |
(MPII_Attr_delete_proxy) (MPI_Comm_delete_attr_function * user_function,
|
|
Packit Service |
c5cf8c |
int handle,
|
|
Packit Service |
c5cf8c |
int keyval,
|
|
Packit Service |
c5cf8c |
MPIR_Attr_type attrib_type, void *attrib, void *extra_state);
|
|
Packit Service |
c5cf8c |
|
|
Packit Service |
c5cf8c |
MPICH_API_PUBLIC void
|
|
Packit Service |
c5cf8c |
MPII_Keyval_set_proxy(int keyval,
|
|
Packit Service |
c5cf8c |
MPII_Attr_copy_proxy copy_proxy, MPII_Attr_delete_proxy delete_proxy);
|
|
Packit Service |
c5cf8c |
|
|
Packit Service |
c5cf8c |
#if defined(__cplusplus)
|
|
Packit Service |
c5cf8c |
}
|
|
Packit Service |
c5cf8c |
#endif
|
|
Packit Service |
c5cf8c |
#endif /* MPIR_ATTR_GENERIC_H_INCLUDED */
|