Классы ошибок, коды ошибок и обработчики ошибок

Пользователи могут пожелать написать иерархическую библиотеку на базе существующей реализации MPI, и эта библиотека может иметь ее собственный наборы кодов и классов ошибок. Пример такой библиотеки - библиотека ввода-вывода, базирующаяся на главе о вводе-выводе в MPI-2. Для достижения этой цели, необходимы функции:

1. Добавления нового класса ошибок к тем, что уже известны в реализации MPI.

2. Ассоциирования кодов ошибок с этим классом ошибок, так чтобы MPI_ERROR_CLASS работал.

3. Ассоциирования строк с этими кодами ошибок, так чтобы MPI_ERROR_STRING работал.

4. Вызова обработчика ошибок, связанного с коммуникатором, окном или объектом.

MPI_ADD_ERROR_CLASS(errorclass)

int MPI_Add_error_class(int *errorclass)

MPI_ADD_ERROR_CLASS(ERRORCLASS, IERROR) INTEGER ERRORCLASS, IERROR

int MPI:: Add_error_class()

MPI_ADD_ERROR_CLASS создает новый класс ошибок и возвращает для него значение.

Объяснение: Во избежание конфликтов с существующими кодами и классами ошибок значение устанавливается реализацией, а не пользователем.

Совет разработчикам: Высококачественная реализация будет возвращать значение для нового errorclass одним и тем же детерминированным способом во всех процессах.

Совет пользователям: Так как вызов MPI_ADD_ERROR_CLASS является локальным, то одинаковый errorclass не может быть возвращен во все процессы, которые сделали этот вызов. Таким образом, не безопасно предполагать, что регистрация новой ошибки для группы процессов в одно и то же время выдаст одинаковый errorclass во все процессы. Конечно, если реализация возвращает новый errorclass детерминированным способом и классы всегда генерируются в одинаковом порядке для выбранной группы процессов (например, всех процессов), то и значение будет тем же самым. Однако, даже если используется детерминированный алгоритм, значение может варьироваться в зависимости от процесса. Это может случиться, например, если различные, но пересекающиеся группы процессов делают серию вызовов. В результате подобной деятельности выдача ``той же'' ошибки в размножающиеся процессы не может заставить сгенерировать одно и то же значение кода ошибки. Это происходит потому, что отображение строки ошибки может быть более полезным, чем код ошибки.

На значение MPI_ERR_LASTCODE не воздействуют новые определяемые пользователем коды и классы ошибок. Как и в MPI-1, мы имеем дело с константами. Вместо этого, предопределенный ключевой атрибут MPI_LASTUSEDCODE (MPI::LASTUSEDCODE - в С++) связан с MPI_COMM_WORLD. Значение атрибута, соответствующее этому ключу, является максимальным текущим классом ошибки, включая определяемые пользователем классы. Это - локальное значение и оно может быть различно для различных процессах. Значение, возвращаемое этим ключом всегда больше или равно MPI_ERR_LASTCODE.

Совет пользователям: Значение, возвращаемое ключом MPI_LASTUSEDCODE не будет изменяться до тех пор, пока пользователь не вызовет функцию, чтобы явно добавить класс/код ошибки. В многонитевой среде пользователь должен проявлять дополнительную осторожность, если он полагает, что это значение не изменяется. Заметьте, что коды и классы ошибок не обязательно кореллируют. Пользователь не может полагать, что каждый класс ошибки меньше MPI_LASTUSEDCODE является допустимым.

MPI_ADD_ERROR_CODE(errorclass, errorcode)

int MPI_Add_error_code(int errorclass, int *errorcode)

MPI_ADD_ERROR_CODE (ERRORCLASS, ERRORCODE, IERROR) INTEGER ERRORCLASS, ERRORCODE, IERROR

int MPI::Add_error_code(int errorclass)

MPI_ADD_ERROR_CODE создает новый код ошибки, связываемый с errorclass и возвращает значение в errorcode.

Объяснение: Во избежание конфликтов с существующими классами и кодами ошибок, значение нового кода ошибки устанавливается реализацией, а не пользователем.

Совет разработчикам: Высококачественная реализация будет возвращать значение для нового errorcode тем же самым детерминированным способом во всех процессах.

MPI_ADD_ERROR_STRING(errorcode, string)

int MPI_Add_error_string(int errorcode, char *string)

MPI_ADD_ERROR_STRING(ERRORCODE, STRING, IERROR) INTEGER ERRORCODE, IERROR CHARACTER*(*) STRING

void MPI::Add_error_string(int errorcode, const char* string)

MPI_ADD_ERROR_STRING ставит в соответствие строку ошибки с кодом или классом ошибки. Строка должна состоять из не более, чем MPI_MAX_ERROR_STRING символов. Длина строки ограничивается по правилам вызывающего языка. В строке не должен встречаться символ-признак конца в Си или С++. Конечные пробелы будут удалены для ФОРТРАНa. Вызов MPI_ADD_ERROR_STRING для errorcode, который уже именован строкой, заменит старую строку новой строкой. Ошибочно вызывать MPI_ADD_ERROR_STRING для кода или класса ошибки со значением меньшим или равным, чем MPI_ERR_LASTCODE.

Если MPI_ERROR_STRING вызывается без задания какой-либо строки, то вернется пустая строка (все пробелы для ФОРТРАНa, " " - для Си и С++).

В разделе 1-7.5.1 описываются методы для создания и связывания обработчиков ошибок с коммуникаторами, файлами, и окнами. Вызовы для ошибок описаны ниже.

MPI_COMM_CALL_ERRHANDLER(comm, errorcode)

int MPI_Comm_call_errhandler(MPI_Comm comm, int errorcode)

MPI_COMM_CALL_ERRHANDLER(COMM, ERRORCODE, IERROR) INTEGER COMM, ERRORCODE, IERROR

void MPI::Comm::Call_errhandler(int errorcode) const

Эта функция вызывает обработчик ошибки, задаваемый коммуникатором, предназначенным для данного кода ошибки. В Си эта функция возвращает MPI_SUCCESS и такое же значение в IERROR, если обработчик ошибки успешно отработал (предполагается, что процесс не прерывается и обработчик ошибки возвращает результат).

Совет пользователям: Пользователи должны принимать во внимание, что по умолчанию задается обработчик ошибки MPI_ERRORS_ARE_FATAL. Так, вызов MPI_COMM_CALL_ERRHANDLER прервет процессы comm, если заданный по умолчанию обработчик ошибки не был заменен для этого коммуникатора или для родительского процесса прежде, чем коммуникатор был создан.

MPI_WIN_CALL_ERRHANDLER(win, errorcode)

int MPI_Win_call_errhandler(MPI_Win win, int errorcode)

MPI_WIN_CALL_ERRHANDLER(WIN, ERRORCODE, IERROR) INTEGER WIN, ERRORCODE, IERROR

void MPI::Win::Call_errhandler(int errorcode) const

Эта функция вызывает обработчик ошибки, задаваемый окном, предназначенным для данного кода ошибки. В Си эта функция возвращает MPI_SUCCESS и такое же значение в IERROR, если обработчик ошибки успешно отработал (предполагается, что процесс не прерывается и обработчик ошибки возвращает результат).

Совет пользователям: Как и в случае с коммуникаторами, для окон устанавливаемый по умолчанию обработчик ошибки - это MPI_ERRORS_ARE_FATAL.

MPI_FILE_CALL_ERRHANDLER(fh, errorcode)

int MPI_File_call_errhandler(MPI_File fh, int errorcode)

MPI_FILE_CALL_ERRHANDLER(FH, ERRORCODE, IERROR) INTEGER FH, ERRORCODE, IERROR

void MPI::File::Call_errhandler(int errorcode) const

Эта функция вызывает обработчик ошибки, задаваемый файлом, предназначенным для данного кода ошибки. В Си эта функция возвращает MPI_SUCCESS и такое же значение в IERROR, если обработчик ошибки успешно отработал (предполагается, что процесс не прерывается и обработчик ошибки возвращает результат).

Совет пользователям: В отличие от случаев с ошибками коммуникаторов и окон для файлов по умолчанию устанавливается MPI_ERRORS_RETURN.

Совет пользователям: Предупреждаем пользователей, что обработчики не должны вызываться рекурсивно посредством MPI_COMM_CALL_ERRHANDLER, MPI_FILE_CALL_ERRHANDLER или
MPI_WIN_CALL_ERRHANDLER. Такие действия могут создать ситуацию, когда образуется бесконечная рекурсия. Это может происходить, если MPI_COMM_CALL_ERRHANDLER, MPI_FILE_CALL_ERRHANDLER или MPI_WIN_CALL_ERRHANDLER вызываются из обработчика ошибки.

Коды и классы ошибок связаны с процессом. В результате они могут использоваться в любом обработчике ошибки. Обработчик ошибки должен быть готовым иметь дело с любым кодом ошибки, который ему передается. Кроме того, общеупотребительная практика, вызвать только обработчик ошибки с соответствующими необходимым кодами ошибок. Например, файловые ошибки желательно ``нормально'' установить для файла с обработчиком ошибки.