# vim: set ft=c:

# Note: MPIX_Delete_error_{code,class,string} are MPI 4.1 APIs, so we are using MPIX_
#       prefixes and supplying the parameter information since they are not in the
#       official standards yet

MPI_Add_error_class:
    .desc: Add an MPI error class to the known classes

MPI_Add_error_code:
    .desc: Add an MPI error code to an MPI error class

MPI_Add_error_string:
    .desc: Associates an error string with an MPI error code or class
/*
    Notes:
    The string must be no more than 'MPI_MAX_ERROR_STRING' characters long.
    The length of the string is as defined in the calling language.
    The length of the string does not include the null terminator in C or C++.
    Note that the string is 'const' even though the MPI standard does not
    specify it that way.

    According to the MPI-2 standard, it is erroneous to call 'MPI_Add_error_string'
    for an error code or class with a value less than or equal
    to 'MPI_ERR_LASTCODE'.  Thus, you cannot replace the predefined error messages
    with this routine.
*/

MPI_Delete_error_class:
    errorclass: ERROR_CLASS, [value of the error class to be remoed]
    .desc: Delete an MPI error class from the known classes

MPI_Delete_error_code:
    errorcode: ERROR_CODE, [value of the error code to be remoed]
    .desc: Delete an MPI error code

MPI_Delete_error_string:
    errorcode: ERROR_CODE, [value of the error code whose string is to be remoed]
    .desc: Delete the error string associated with an MPI error code or class
/*
    Notes:
    According to the MPI 4.1 standard, it is erroneous to call 'MPI_Delete_error_string'
    for an error code or class with a value less than or equal
    to 'MPI_ERR_LASTCODE'.  Thus, you cannot replace the predefined error messages
    with this routine.
*/

MPI_Error_class:
    .desc: Converts an error code into an error class
    .skip: initcheck, global_cs
{
    /* We include the dynamic bit because this is needed to fully
     * describe the dynamic error classes */
    *errorclass = errorcode & (ERROR_CLASS_MASK | ERROR_DYN_MASK);
}

MPI_Error_string:
    .desc: Return a string for a given error code
    .skip: initcheck
/*
    Notes:
    Error codes are the values return by MPI routines (in C) or in the
    'ierr' argument (in Fortran).  These can be converted into error classes
    with the routine 'MPI_Error_class'.
*/
{
    MPIR_Err_get_string(errorcode, string, MPI_MAX_ERROR_STRING, NULL);
    *resultlen = (int) strlen(string);
}

MPI_Errhandler_create:
    comm_errhandler_fn: FUNCTION_SMALL, func_type=MPI_Comm_errhandler_function, [user defined error handling procedure]
    errhandler: ERRHANDLER, direction=out
    .desc: Creates an MPI-style errorhandler
    .replace: removed with MPI_Comm_create_errhandler
    .seealso: MPI_Comm_create_errhandler, MPI_Errhandler_free

MPI_Errhandler_free:
    .desc: Frees an MPI-style errorhandler

MPI_Errhandler_get:
    comm: COMMUNICATOR
    errhandler: ERRHANDLER, direction=out, [error handler currently associated with communicator]
    .desc: Gets the error handler for a communicator
    .replace: removed with MPI_Comm_get_errhandler

MPI_Errhandler_set:
    comm: COMMUNICATOR, direction=lis:inout, param:in
    errhandler: ERRHANDLER, [new error handler for communicator]
    .desc: Sets the error handler for a communicator
    .replace: removed with MPI_Comm_set_errhandler
    .seealso: MPI_Comm_set_errhandler, MPI_Errhandler_create, MPI_Comm_create_errhandler

MPI_Comm_call_errhandler:
    .desc: Call the error handler installed on a communicator
    .docnotes: ThreadSafeNoUpdate
    .extra: ignore_revoked_comm
    .skip: global_cs

MPI_Comm_create_errhandler:
    .desc: Create a communicator error handler
/*
    Notes:
    The MPI Standard states that an implementation may make the output value
    (errhandler) simply the address of the function.  However, the action of
    'MPI_Errhandler_free' makes this impossible, since it is required to set the
    value of the argument to 'MPI_ERRHANDLER_NULL'.  In addition, the actual
    error handler must remain until all communicators that use it are
    freed.
*/

MPI_Comm_get_errhandler:
    .desc: Get the error handler attached to a communicator
    .extra: ignore_revoked_comm
    .docnotes: ThreadSafeNoUpdate
/*
    Note on Implementation:

    The MPI Standard was unclear on whether this routine required the user to call
    'MPI_Errhandler_free' once for each call made to this routine in order to
    free the error handler.  After some debate, the MPI Forum added an explicit
    statement that users are required to call 'MPI_Errhandler_free' when the
    return value from this routine is no longer needed.  This behavior is similar
    to the other MPI routines for getting objects; for example, 'MPI_Comm_group'
    requires that the user call 'MPI_Group_free' when the group returned
    by 'MPI_Comm_group' is no longer needed.
*/

MPI_Comm_set_errhandler:
    .desc: Set the error handler for a communicator
    .seealso: MPI_Comm_get_errhandler, MPI_Comm_call_errhandler
    .extra: ignore_revoked_comm
    .docnotes: ThreadSafeNoUpdate

MPI_File_call_errhandler:
    .desc: Call the error handler installed on a file
    .docnotes: ThreadSafeNoUpdate
    .skip: global_cs

MPI_File_create_errhandler:
    .desc: Create a file error handler

MPI_File_get_errhandler:
    .desc: Get the error handler attached to a file
    .docnotes: ThreadSafeNoUpdate

MPI_File_set_errhandler:
    .desc: Set the error handler for an MPI file
    .docnotes: ThreadSafeNoUpdate
{ -- error_check --
    if (!HANDLE_IS_BUILTIN(errhandler) && errhandler_ptr->kind != MPIR_FILE) {
        mpi_errno = MPIR_Err_create_code(MPI_SUCCESS, MPIR_ERR_RECOVERABLE,
                                         __func__, __LINE__, MPI_ERR_ARG,
                                         "**errhandnotfile", NULL);
        goto fn_fail;
    }
}

MPI_Win_call_errhandler:
    .desc: Call the error handler installed on a window
    .docnotes: ThreadSafeNoUpdate
    .skip: global_cs

MPI_Win_create_errhandler:
    .desc: Create an error handler for use with MPI window

MPI_Win_get_errhandler:
    .desc: Get the error handler for the MPI RMA window
    .docnotes: ThreadSafeNoUpdate

MPI_Win_set_errhandler:
    .desc: Set window error handler
    .docnotes: ThreadSafeNoUpdate
{ -- error_check --
    if (!HANDLE_IS_BUILTIN(errhandler) && errhandler_ptr->kind != MPIR_WIN) {
        mpi_errno = MPIR_Err_create_code(MPI_SUCCESS, MPIR_ERR_RECOVERABLE,
                                         __func__, __LINE__, MPI_ERR_ARG,
                                         "**errhandnotwin", NULL);
        goto fn_fail;
    }
}

MPI_Session_call_errhandler:
    .desc: Call the error handler installed on a MPI session
    .docnotes: ThreadSafeNoUpdate
    .skip: global_cs

MPI_Session_create_errhandler:
    .desc: Create an error handler for use with MPI session

MPI_Session_get_errhandler:
    .desc: Get the error handler for the MPI session
    .docnotes: ThreadSafeNoUpdate

MPI_Session_set_errhandler:
    .desc: Set MPI session error handler
    .docnotes: ThreadSafeNoUpdate
{ -- error_check --
    if (!HANDLE_IS_BUILTIN(errhandler) && errhandler_ptr->kind != MPIR_SESSION) {
        mpi_errno = MPIR_Err_create_code(MPI_SUCCESS, MPIR_ERR_RECOVERABLE,
                                         __func__, __LINE__, MPI_ERR_ARG,
                                         "**errhandnotsession", NULL);
        goto fn_fail;
    }
}
