276 lines
8.9 KiB
Groff
276 lines
8.9 KiB
Groff
.\" Man page generated from reStructuredText.
|
|
.
|
|
.TH "MPI_KEYVAL_CREATE" "3" "Feb 14, 2025" "" "Open MPI"
|
|
.
|
|
.nr rst2man-indent-level 0
|
|
.
|
|
.de1 rstReportMargin
|
|
\\$1 \\n[an-margin]
|
|
level \\n[rst2man-indent-level]
|
|
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
-
|
|
\\n[rst2man-indent0]
|
|
\\n[rst2man-indent1]
|
|
\\n[rst2man-indent2]
|
|
..
|
|
.de1 INDENT
|
|
.\" .rstReportMargin pre:
|
|
. RS \\$1
|
|
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
|
|
. nr rst2man-indent-level +1
|
|
.\" .rstReportMargin post:
|
|
..
|
|
.de UNINDENT
|
|
. RE
|
|
.\" indent \\n[an-margin]
|
|
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.nr rst2man-indent-level -1
|
|
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
|
..
|
|
.sp
|
|
\fI\%MPI_Keyval_create\fP — Generates a new attribute key — this routine is deprecated in favor of \fI\%MPI_Comm_create_keyval\fP\&.
|
|
.SH SYNTAX
|
|
.SS C Syntax
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
#include <mpi.h>
|
|
|
|
int MPI_Keyval_create(MPI_Copy_function *copy_fn,
|
|
MPI_Delete_function *delete_fn, int *keyval, void *extra_state)
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS Fortran Syntax
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
USE MPI
|
|
! or the older form: INCLUDE \(aqmpif.h\(aq
|
|
|
|
MPI_KEYVAL_CREATE(COPY_FN, DELETE_FN, KEYVAL, EXTRA_STATE, IERROR)
|
|
EXTERNAL COPY_FN, DELETE_FN
|
|
INTEGER KEYVAL, EXTRA_STATE, IERROR
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SH INPUT PARAMETERS
|
|
.INDENT 0.0
|
|
.IP \(bu 2
|
|
\fBcopy_fn\fP: Copy callback function for keyval.
|
|
.IP \(bu 2
|
|
\fBdelete_fn\fP: Delete callback function for keyval.
|
|
.IP \(bu 2
|
|
\fBextra_state\fP: Extra state for callback functions.
|
|
.UNINDENT
|
|
.SH OUTPUT PARAMETERS
|
|
.INDENT 0.0
|
|
.IP \(bu 2
|
|
\fBkeyval\fP: Key value for future access (integer).
|
|
.IP \(bu 2
|
|
\fBierror\fP: Fortran only: Error status (integer).
|
|
.UNINDENT
|
|
.SH DESCRIPTION
|
|
.sp
|
|
Note that use of this routine is \fIdeprecated\fP as of MPI\-2. Please use
|
|
\fI\%MPI_Comm_create_keyval\fP instead.
|
|
.sp
|
|
Generates a new attribute key. Keys are locally unique in a process and
|
|
opaque to the user, though they are explicitly stored in integers. Once
|
|
allocated, the key value can be used to associate attributes and access
|
|
them on any locally defined communicator.
|
|
.sp
|
|
The copy_fn function is invoked when a communicator is duplicated by
|
|
\fI\%MPI_Comm_dup\fP\&. copy_fn should be of type MPI_Copy_function, which is
|
|
defined as follows:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
typedef int MPI_Copy_function(MPI_Comm oldcomm, int keyval,
|
|
void *extra_state, void *attribute_val_in,
|
|
void *attribute_val_out, int *flag)
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
A Fortran declaration for such a function is as follows:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
SUBROUTINE COPY_FUNCTION(OLDCOMM, KEYVAL, EXTRA_STATE, ATTRIBUTE_VAL_IN,
|
|
ATTRIBUTE_VAL_OUT, FLAG, IERR)
|
|
INTEGER OLDCOMM, KEYVAL, EXTRA_STATE,
|
|
ATTRIBUTE_VAL_IN, ATTRIBUTE_VAL_OUT, IERR
|
|
LOGICAL FLAG
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
The copy callback function is invoked for each key value in oldcomm in
|
|
arbitrary order. Each call to the copy callback is made with a key value
|
|
and its corresponding attribute. If it returns flag = 0, then the
|
|
attribute is deleted in the duplicated communicator. Otherwise ( flag =
|
|
1), the new attribute value is set to the value returned in
|
|
attribute_val_out. The function returns MPI_SUCCESS on success and an
|
|
error code on failure (in which case \fI\%MPI_Comm_dup\fP will fail).
|
|
.sp
|
|
copy_fn may be specified as MPI_NULL_COPY_FN or MPI_DUP_FN from either C
|
|
or Fortran; MPI_NULL_COPY_FN is a function that does nothing other than
|
|
return flag = 0, and MPI_SUCCESS. MPI_DUP_FN is a simple\-minded copy
|
|
function that sets flag = 1, returns the value of attribute_val_in in
|
|
attribute_val_out, and returns MPI_SUCCESS.
|
|
.SH NOTES
|
|
.sp
|
|
Key values are global (available for any and all communicators).
|
|
.sp
|
|
There are subtle differences between C and Fortran that require that the
|
|
copy_fn be written in the same language that \fI\%MPI_Keyval_create\fP is called
|
|
from. This should not be a problem for most users; only programmers
|
|
using both Fortran and C in the same program need to be sure that they
|
|
follow this rule.
|
|
.sp
|
|
Even though both formal arguments attribute_val_in and attribute_val_out
|
|
are of type void*, their usage differs. The C copy function is passed by
|
|
MPI in attribute_val_in the value of the attribute, and in
|
|
attribute_val_out the address of the attribute, so as to allow the
|
|
function to return the (new) attribute value. The use of type \fBvoid *\fP for
|
|
both is to avoid messy type casts.
|
|
.sp
|
|
A valid copy function is one that completely duplicates the information
|
|
by making a full duplicate copy of the data structures implied by an
|
|
attribute; another might just make another reference to that data
|
|
structure, while using a reference\-count mechanism. Other types of
|
|
attributes might not copy at all (they might be specific to oldcomm
|
|
only).
|
|
.sp
|
|
Analogous to copy_fn is a callback deletion function, defined as
|
|
follows. The delete_fn function is invoked when a communicator is
|
|
deleted by \fI\%MPI_Comm_free\fP or when a call is made explicitly to
|
|
\fI\%MPI_Attr_delete\fP\&. delete_fn should be of type MPI_Delete_function, which
|
|
is defined as follows:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
typedef int MPI_Delete_function(MPI_Comm comm, int keyval,
|
|
void *attribute_val, void *extra_state);
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
A Fortran declaration for such a function is as follows:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
SUBROUTINE DELETE_FUNCTION(COMM, KEYVAL,ATTRIBUTE_VAL, EXTRA_STATE, IERR)
|
|
INTEGER COMM, KEYVAL, ATTRIBUTE_VAL, EXTRA_STATE, IERR
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
This function is called by \fI\%MPI_Comm_free\fP, \fI\%MPI_Attr_delete\fP, and
|
|
\fI\%MPI_Attr_put\fP to do whatever is needed to remove an attribute. The
|
|
function returns MPI_SUCCESS on success and an error code on failure (in
|
|
which case \fI\%MPI_Comm_free\fP will fail).
|
|
.sp
|
|
delete_fn may be specified as MPI_NULL_DELETE_FN from either C or
|
|
FORTRAN; MPI_NULL_DELETE_FN is a function that does nothing, other than
|
|
returning MPI_SUCCESS.
|
|
.sp
|
|
The special key value MPI_KEYVAL_INVALID is never returned by
|
|
\fI\%MPI_Keyval_create\fP\&. Therefore, it can be used for static initialization
|
|
of key values.
|
|
.SH ERRORS
|
|
.sp
|
|
Almost all MPI routines return an error value; C routines as the return result
|
|
of the function and Fortran routines in the last argument.
|
|
.sp
|
|
Before the error value is returned, the current MPI error handler associated
|
|
with the communication object (e.g., communicator, window, file) is called.
|
|
If no communication object is associated with the MPI call, then the call is
|
|
considered attached to MPI_COMM_SELF and will call the associated MPI error
|
|
handler. When MPI_COMM_SELF is not initialized (i.e., before
|
|
\fI\%MPI_Init\fP/\fI\%MPI_Init_thread\fP, after \fI\%MPI_Finalize\fP, or when using the Sessions
|
|
Model exclusively) the error raises the initial error handler. The initial
|
|
error handler can be changed by calling \fI\%MPI_Comm_set_errhandler\fP on
|
|
MPI_COMM_SELF when using the World model, or the mpi_initial_errhandler CLI
|
|
argument to mpiexec or info key to \fI\%MPI_Comm_spawn\fP/\fI\%MPI_Comm_spawn_multiple\fP\&.
|
|
If no other appropriate error handler has been set, then the MPI_ERRORS_RETURN
|
|
error handler is called for MPI I/O functions and the MPI_ERRORS_ABORT error
|
|
handler is called for all other MPI functions.
|
|
.sp
|
|
Open MPI includes three predefined error handlers that can be used:
|
|
.INDENT 0.0
|
|
.IP \(bu 2
|
|
\fBMPI_ERRORS_ARE_FATAL\fP
|
|
Causes the program to abort all connected MPI processes.
|
|
.IP \(bu 2
|
|
\fBMPI_ERRORS_ABORT\fP
|
|
An error handler that can be invoked on a communicator,
|
|
window, file, or session. When called on a communicator, it
|
|
acts as if \fI\%MPI_Abort\fP was called on that communicator. If
|
|
called on a window or file, acts as if \fI\%MPI_Abort\fP was called
|
|
on a communicator containing the group of processes in the
|
|
corresponding window or file. If called on a session,
|
|
aborts only the local process.
|
|
.IP \(bu 2
|
|
\fBMPI_ERRORS_RETURN\fP
|
|
Returns an error code to the application.
|
|
.UNINDENT
|
|
.sp
|
|
MPI applications can also implement their own error handlers by calling:
|
|
.INDENT 0.0
|
|
.IP \(bu 2
|
|
\fI\%MPI_Comm_create_errhandler\fP then \fI\%MPI_Comm_set_errhandler\fP
|
|
.IP \(bu 2
|
|
\fI\%MPI_File_create_errhandler\fP then \fI\%MPI_File_set_errhandler\fP
|
|
.IP \(bu 2
|
|
\fI\%MPI_Session_create_errhandler\fP then \fI\%MPI_Session_set_errhandler\fP or at \fI\%MPI_Session_init\fP
|
|
.IP \(bu 2
|
|
\fI\%MPI_Win_create_errhandler\fP then \fI\%MPI_Win_set_errhandler\fP
|
|
.UNINDENT
|
|
.sp
|
|
Note that MPI does not guarantee that an MPI program can continue past
|
|
an error.
|
|
.sp
|
|
See the \fI\%MPI man page\fP for a full list of \fI\%MPI error codes\fP\&.
|
|
.sp
|
|
See the Error Handling section of the MPI\-3.1 standard for
|
|
more information.
|
|
.sp
|
|
\fBSEE ALSO:\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.INDENT 0.0
|
|
.IP \(bu 2
|
|
\fI\%MPI_Keyval_free\fP
|
|
.IP \(bu 2
|
|
\fI\%MPI_Comm_create_keyval\fP
|
|
.IP \(bu 2
|
|
\fI\%MPI_Comm_free_keyval\fP
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SH COPYRIGHT
|
|
2003-2025, The Open MPI Community
|
|
.\" Generated by docutils manpage writer.
|
|
.
|