contrib/openmp/runtime/src/kmp_i18n.h

   1 /*
   2  * kmp_i18n.h
   3  */
   4
   5 //===----------------------------------------------------------------------===//
   6 //
   7 //                     The LLVM Compiler Infrastructure
   8 //
   9 // This file is dual licensed under the MIT and the University of Illinois Open
  10 // Source Licenses. See LICENSE.txt for details.
  11 //
  12 //===----------------------------------------------------------------------===//
  13
  14 #ifndef KMP_I18N_H
  15 #define KMP_I18N_H
  16
  17 #include "kmp_str.h"
  18
  19 #ifdef __cplusplus
  20 extern "C" {
  21 #endif // __cplusplus
  22
  23 /* kmp_i18n_id.inc defines kmp_i18n_id_t type. It is an enumeration with
  24    identifiers of all the messages in the catalog. There is one special
  25    identifier: kmp_i18n_null, which denotes absence of message. */
  26 #include "kmp_i18n_id.inc" // Generated file. Do not edit it manually.
  27
  28 /* Low-level functions handling message catalog. __kmp_i18n_open() opens message
  29    catalog, __kmp_i18n_closes() it. Explicit opening is not required: if message
  30    catalog is not yet open, __kmp_i18n_catgets() will open it implicitly.
  31    However, catalog should be explicitly closed, otherwise resources (mamory,
  32    handles) may leak.
  33
  34    __kmp_i18n_catgets() returns read-only string. It should not be freed.
  35
  36    KMP_I18N_STR macro simplifies acces to strings in message catalog a bit.
  37    Following two lines are equivalent:
  38
  39    __kmp_i18n_catgets( kmp_i18n_str_Warning )
  40    KMP_I18N_STR( Warning )
  41 */
  42
  43 void __kmp_i18n_catopen();
  44 void __kmp_i18n_catclose();
  45 char const *__kmp_i18n_catgets(kmp_i18n_id_t id);
  46
  47 #define KMP_I18N_STR(id) __kmp_i18n_catgets(kmp_i18n_str_##id)
  48
  49 /* High-level interface for printing strings targeted to the user.
  50
  51    All the strings are divided into 3 types:
  52    * messages,
  53    * hints,
  54    * system errors.
  55
  56    There are 3 kind of message severities:
  57    * informational messages,
  58    * warnings (non-fatal errors),
  59    * fatal errors.
  60
  61    For example:
  62      OMP: Warning #2: Cannot open message catalog "libguide.cat":   (1)
  63      OMP: System error #2: No such file or directory                (2)
  64      OMP: Hint: Please check NLSPATH environment variable.          (3)
  65      OMP: Info #3: Default messages will be used.                   (4)
  66
  67    where
  68    (1) is a message of warning severity,
  69    (2) is a system error caused the previous warning,
  70    (3) is a hint for the user how to fix the problem,
  71    (4) is a message of informational severity.
  72
  73    Usage in complex cases (message is accompanied with hints and system errors):
  74
  75    int error = errno; // We need save errno immediately, because it may
  76                       // be changed.
  77    __kmp_msg(
  78        kmp_ms_warning,                        // Severity
  79        KMP_MSG( CantOpenMessageCatalog, name ), // Primary message
  80        KMP_ERR( error ),                      // System error
  81        KMP_HNT( CheckNLSPATH ),               // Hint
  82        __kmp_msg_null                         // Variadic argument list finisher
  83    );
  84
  85    Usage in simple cases (just a message, no system errors or hints):
  86    KMP_INFORM( WillUseDefaultMessages );
  87    KMP_WARNING( CantOpenMessageCatalog, name );
  88    KMP_FATAL( StackOverlap );
  89    KMP_SYSFAIL( "pthread_create", status );
  90    KMP_CHECK_SYSFAIL( "pthread_create", status );
  91    KMP_CHECK_SYSFAIL_ERRNO( "gettimeofday", status );
  92 */
  93
  94 enum kmp_msg_type {
  95   kmp_mt_dummy = 0, // Special type for internal purposes.
  96   kmp_mt_mesg =
  97       4, // Primary OpenMP message, could be information, warning, or fatal.
  98   kmp_mt_hint = 5, // Hint to the user.
  99   kmp_mt_syserr = -1 // System error message.
 100 }; // enum kmp_msg_type
 101 typedef enum kmp_msg_type kmp_msg_type_t;
 102
 103 struct kmp_msg {
 104   kmp_msg_type_t type;
 105   int num;
 106   char *str;
 107   int len;
 108 }; // struct kmp_message
 109 typedef struct kmp_msg kmp_msg_t;
 110
 111 // Special message to denote the end of variadic list of arguments.
 112 extern kmp_msg_t __kmp_msg_null;
 113
 114 // Helper functions. Creates messages either from message catalog or from
 115 // system. Note: these functions allocate memory. You should pass created
 116 // messages to __kmp_msg() function, it will print messages and destroy them.
 117 kmp_msg_t __kmp_msg_format(unsigned id_arg, ...);
 118 kmp_msg_t __kmp_msg_error_code(int code);
 119 kmp_msg_t __kmp_msg_error_mesg(char const *mesg);
 120
 121 // Helper macros to make calls shorter.
 122 #define KMP_MSG(...) __kmp_msg_format(kmp_i18n_msg_##__VA_ARGS__)
 123 #define KMP_HNT(...) __kmp_msg_format(kmp_i18n_hnt_##__VA_ARGS__)
 124 #define KMP_SYSERRCODE(code) __kmp_msg_error_code(code)
 125 #define KMP_SYSERRMESG(mesg) __kmp_msg_error_mesg(mesg)
 126 #define KMP_ERR KMP_SYSERRCODE
 127
 128 // Message severity.
 129 enum kmp_msg_severity {
 130   kmp_ms_inform, // Just information for the user.
 131   kmp_ms_warning, // Non-fatal error, execution continues.
 132   kmp_ms_fatal // Fatal error, program aborts.
 133 }; // enum kmp_msg_severity
 134 typedef enum kmp_msg_severity kmp_msg_severity_t;
 135
 136 // Primary function for printing messages for the user. The first message is
 137 // mandatory. Any number of system errors and hints may be specified. Argument
 138 // list must be finished with __kmp_msg_null.
 139 void __kmp_msg(kmp_msg_severity_t severity, kmp_msg_t message, ...);
 140 KMP_NORETURN void __kmp_fatal(kmp_msg_t message, ...);
 141
 142 // Helper macros to make calls shorter in simple cases.
 143 #define KMP_INFORM(...)                                                        \
 144   __kmp_msg(kmp_ms_inform, KMP_MSG(__VA_ARGS__), __kmp_msg_null)
 145 #define KMP_WARNING(...)                                                       \
 146   __kmp_msg(kmp_ms_warning, KMP_MSG(__VA_ARGS__), __kmp_msg_null)
 147 #define KMP_FATAL(...) __kmp_fatal(KMP_MSG(__VA_ARGS__), __kmp_msg_null)
 148 #define KMP_SYSFAIL(func, error)                                               \
 149   __kmp_fatal(KMP_MSG(FunctionError, func), KMP_SYSERRCODE(error),             \
 150               __kmp_msg_null)
 151
 152 // Check error, if not zero, generate fatal error message.
 153 #define KMP_CHECK_SYSFAIL(func, error)                                         \
 154   {                                                                            \
 155     if (error) {                                                               \
 156       KMP_SYSFAIL(func, error);                                                \
 157     }                                                                          \
 158   }
 159
 160 // Check status, if not zero, generate fatal error message using errno.
 161 #define KMP_CHECK_SYSFAIL_ERRNO(func, status)                                  \
 162   {                                                                            \
 163     if (status != 0) {                                                         \
 164       int error = errno;                                                       \
 165       KMP_SYSFAIL(func, error);                                                \
 166     }                                                                          \
 167   }
 168
 169 #ifdef KMP_DEBUG
 170 void __kmp_i18n_dump_catalog(kmp_str_buf_t *buffer);
 171 #endif // KMP_DEBUG
 172
 173 #ifdef __cplusplus
 174 }; // extern "C"
 175 #endif // __cplusplus
 176
 177 #endif // KMP_I18N_H
 178
 179 // end of file //