1 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 2 /* */ 3 /* This file is part of the program and library */ 4 /* SCIP --- Solving Constraint Integer Programs */ 5 /* */ 6 /* Copyright (C) 2002-2021 Konrad-Zuse-Zentrum */ 7 /* fuer Informationstechnik Berlin */ 8 /* */ 9 /* SCIP is distributed under the terms of the ZIB Academic License. */ 10 /* */ 11 /* You should have received a copy of the ZIB Academic License */ 12 /* along with SCIP; see the file COPYING. If not visit scipopt.org. */ 13 /* */ 14 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 15 16 /**@file pub_message.h 17 * @ingroup PUBLICCOREAPI 18 * @brief public methods for message output 19 * @author Tobias Achterberg 20 * @author Stefan Heinz 21 */ 22 23 /*---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/ 24 25 #ifndef __SCIP_PUB_MESSAGE_H__ 26 #define __SCIP_PUB_MESSAGE_H__ 27 28 #include <stdarg.h> 29 #include <string.h> 30 31 #include "scip/def.h" 32 #include "scip/type_message.h" 33 34 #ifdef NDEBUG 35 #include "scip/struct_message.h" 36 #endif 37 38 #ifdef __cplusplus 39 extern "C" { 40 #endif 41 42 /** define to identify SCIP version with thread-safe version of message handlers */ 43 #define SCIP_THREADSAFE_MESSAGEHDLRS 44 45 /** define to get the filename of __FILE__ */ 46 #if defined(_WIN32) || defined(_WIN64) 47 /*lint -e613*/ 48 #define __FILENAME__ (strrchr("\\" __FILE__, '\\') + 1) 49 #else 50 /*lint -e613*/ 51 #define __FILENAME__ (strrchr("/" __FILE__, '/') + 1) 52 #endif 53 54 /** prints an error message */ 55 #define SCIPerrorMessage SCIPmessagePrintErrorHeader(__FILENAME__, __LINE__); \ 56 SCIPmessagePrintError 57 58 /** define used in blockmemshell/memory.c */ 59 #define printErrorHeader SCIPmessagePrintErrorHeader 60 #define printError SCIPmessagePrintError 61 62 #ifdef SCIP_DEBUG 63 64 /** executes command only if SCIP_DEBUG flag is set */ 65 #define SCIPdebug(x) x 66 67 /** prints a debugging message if SCIP_DEBUG flag is set - also consider using SCIPdebugMsg/SCIPsetDebugMsg */ 68 #define SCIPdebugMessage printf("[%s:%d] debug: ", __FILENAME__, __LINE__), printf 69 70 /** executes printf command only if SCIP_DEBUG flag is set */ 71 #define SCIPdebugPrintf printf 72 73 /** executes SCIPprintCons() and prints termination symbol ";\n" only if SCIP_DEBUG flag is set */ 74 #define SCIPdebugPrintCons(scip,cons,file) do \ 75 { \ 76 SCIP_CALL_ABORT( SCIPprintCons((scip), (cons), (file)) ); \ 77 SCIPinfoMessage((scip), (file), ";\n"); \ 78 } \ 79 while( FALSE ) 80 81 #else 82 83 /** executes command only if SCIP_DEBUG flag is set */ 84 #define SCIPdebug(x) /**/ 85 86 /** prints a debugging message if SCIP_DEBUG flag is set - also consider using SCIPdebugMsg/SCIPsetDebugMsg */ 87 #define SCIPdebugMessage while( FALSE ) /*lint -e{530}*/ printf 88 89 /** executes printf command only if SCIP_DEBUG flag is set */ 90 #define SCIPdebugPrintf while( FALSE ) /*lint -e{530}*/ printf 91 92 /** executes SCIPprintCons() and prints termination symbol ";\n" only if SCIP_DEBUG flag is set */ 93 #define SCIPdebugPrintCons(x,y,z) /**/ 94 95 #endif 96 97 #ifdef SCIP_STATISTIC 98 99 /** executes command only if SCIP_STATISTIC flag is set */ 100 #define SCIPstatistic(x) x 101 102 /** prints a statistic message if SCIP_STATISTIC flag is set */ 103 #define SCIPstatisticMessage printf("[%s:%d] statistic: ", __FILENAME__, __LINE__), printf 104 105 /** executes printf command only if SCIP_STATISTIC flag is set */ 106 #define SCIPstatisticPrintf printf 107 108 #else 109 110 /** executes command only if SCIP_STATISTIC flag is set */ 111 #define SCIPstatistic(x) /**/ 112 113 /** prints a statistic message if SCIP_STATISTIC flag is set */ 114 #define SCIPstatisticMessage while( FALSE ) /*lint -e{530}*/ printf 115 116 /** executes printf command only if SCIP_STATISTIC flag is set */ 117 #define SCIPstatisticPrintf while( FALSE ) /*lint -e{530}*/ printf 118 119 #endif 120 121 122 /** Creates and captures a message handler which deals with warning, information, and dialog (interactive shell) methods. 123 * 124 * Use SCIPsetMessagehdlr() to make SCIP aware of the created message handler. 125 * @note The message handler does not handle error messages. For that see SCIPmessageSetErrorPrinting() 126 * @note Creating a message handler automatically captures it. 127 */ 128 SCIP_EXPORT 129 SCIP_RETCODE SCIPmessagehdlrCreate( 130 SCIP_MESSAGEHDLR** messagehdlr, /**< pointer to store the message handler */ 131 SCIP_Bool bufferedoutput, /**< should the output be buffered up to the next newline? */ 132 const char* filename, /**< name of log file, or NULL for no log */ 133 SCIP_Bool quiet, /**< should screen messages be suppressed? */ 134 SCIP_DECL_MESSAGEWARNING((*messagewarning)),/**< warning message print method of message handler */ 135 SCIP_DECL_MESSAGEDIALOG((*messagedialog)),/**< dialog message print method of message handler */ 136 SCIP_DECL_MESSAGEINFO ((*messageinfo)), /**< info message print method of message handler */ 137 SCIP_DECL_MESSAGEHDLRFREE((*messagehdlrfree)), /**< destructor of message handler to free message handler data */ 138 SCIP_MESSAGEHDLRDATA* messagehdlrdata /**< message handler data */ 139 ); 140 141 /** captures message handler */ 142 SCIP_EXPORT 143 void SCIPmessagehdlrCapture( 144 SCIP_MESSAGEHDLR* messagehdlr /**< message handler, or NULL */ 145 ); 146 147 /** releases message handler */ 148 SCIP_EXPORT 149 SCIP_RETCODE SCIPmessagehdlrRelease( 150 SCIP_MESSAGEHDLR** messagehdlr /**< pointer to the message handler */ 151 ); 152 153 /** sets the user data of the message handler */ 154 SCIP_EXPORT 155 SCIP_RETCODE SCIPmessagehdlrSetData( 156 SCIP_MESSAGEHDLR* messagehdlr, /**< message handler; must not be NULL */ 157 SCIP_MESSAGEHDLRDATA* messagehdlrdata /**< new message handler data to attach to the handler */ 158 ); 159 160 /** sets the log file name for the message handler */ 161 SCIP_EXPORT 162 void SCIPmessagehdlrSetLogfile( 163 SCIP_MESSAGEHDLR* messagehdlr, /**< message handler */ 164 const char* filename /**< log file name where to copy messages into, or NULL */ 165 ); 166 167 /** sets the messages handler to be quiet */ 168 SCIP_EXPORT 169 void SCIPmessagehdlrSetQuiet( 170 SCIP_MESSAGEHDLR* messagehdlr, /**< message handler */ 171 SCIP_Bool quiet /**< should screen messages be suppressed? */ 172 ); 173 174 /** prints a message, acting like the printf() command */ 175 #ifdef __GNUC__ 176 __attribute__((format(printf, 2, 3))) 177 #endif 178 SCIP_EXPORT 179 void SCIPmessagePrintInfo( 180 SCIP_MESSAGEHDLR* messagehdlr, /**< message handler */ 181 const char* formatstr, /**< format string like in printf() function */ 182 ... /**< format arguments line in printf() function */ 183 ); 184 185 /** prints a message, acting like the vprintf() command */ 186 SCIP_EXPORT 187 void SCIPmessageVPrintInfo( 188 SCIP_MESSAGEHDLR* messagehdlr, /**< message handler */ 189 const char* formatstr, /**< format string like in printf() function */ 190 va_list ap /**< variable argument list */ 191 ); 192 193 /** prints a message into a file, acting like the fprintf() command */ 194 #ifdef __GNUC__ 195 __attribute__((format(printf, 3, 4))) 196 #endif 197 SCIP_EXPORT 198 void SCIPmessageFPrintInfo( 199 SCIP_MESSAGEHDLR* messagehdlr, /**< message handler */ 200 FILE* file, /**< file stream to print into, or NULL for stdout */ 201 const char* formatstr, /**< format string like in printf() function */ 202 ... /**< format arguments line in printf() function */ 203 ); 204 205 /** prints a message into a file, acting like the vfprintf() command */ 206 SCIP_EXPORT 207 void SCIPmessageVFPrintInfo( 208 SCIP_MESSAGEHDLR* messagehdlr, /**< message handler */ 209 FILE* file, /**< file stream to print into, or NULL for stdout */ 210 const char* formatstr, /**< format string like in printf() function */ 211 va_list ap /**< variable argument list */ 212 ); 213 214 /** prints a warning message, acting like the printf() command */ 215 #ifdef __GNUC__ 216 __attribute__((format(printf, 2, 3))) 217 #endif 218 SCIP_EXPORT 219 void SCIPmessagePrintWarning( 220 SCIP_MESSAGEHDLR* messagehdlr, /**< message handler */ 221 const char* formatstr, /**< format string like in printf() function */ 222 ... /**< format arguments line in printf() function */ 223 ); 224 225 /** prints a warning message, acting like the vprintf() command */ 226 SCIP_EXPORT 227 void SCIPmessageVPrintWarning( 228 SCIP_MESSAGEHDLR* messagehdlr, /**< message handler */ 229 const char* formatstr, /**< format string like in printf() function */ 230 va_list ap /**< variable argument list */ 231 ); 232 233 /** prints a warning message into a file, acting like the fprintf() command */ 234 #ifdef __GNUC__ 235 __attribute__((format(printf, 2, 3))) 236 #endif 237 SCIP_EXPORT 238 void SCIPmessageFPrintWarning( 239 SCIP_MESSAGEHDLR* messagehdlr, /**< message handler */ 240 const char* formatstr, /**< format string like in printf() function */ 241 ... /**< format arguments line in printf() function */ 242 ); 243 244 /** prints a warning message into a file, acting like the vfprintf() command */ 245 SCIP_EXPORT 246 void SCIPmessageVFPrintWarning( 247 SCIP_MESSAGEHDLR* messagehdlr, /**< message handler */ 248 const char* formatstr, /**< format string like in printf() function */ 249 va_list ap /**< variable argument list */ 250 ); 251 252 /** prints a dialog message that requests user interaction, acting like the printf() command */ 253 #ifdef __GNUC__ 254 __attribute__((format(printf, 2, 3))) 255 #endif 256 SCIP_EXPORT 257 void SCIPmessagePrintDialog( 258 SCIP_MESSAGEHDLR* messagehdlr, /**< message handler */ 259 const char* formatstr, /**< format string like in printf() function */ 260 ... /**< format arguments line in printf() function */ 261 ); 262 263 /** prints a dialog message that requests user interaction, acting like the vprintf() command */ 264 SCIP_EXPORT 265 void SCIPmessageVPrintDialog( 266 SCIP_MESSAGEHDLR* messagehdlr, /**< message handler */ 267 const char* formatstr, /**< format string like in printf() function */ 268 va_list ap /**< variable argument list */ 269 ); 270 271 /** prints a dialog message that requests user interaction into a file, acting like the fprintf() command */ 272 #ifdef __GNUC__ 273 __attribute__((format(printf, 3, 4))) 274 #endif 275 SCIP_EXPORT 276 void SCIPmessageFPrintDialog( 277 SCIP_MESSAGEHDLR* messagehdlr, /**< message handler */ 278 FILE* file, /**< file stream to print into, or NULL for stdout */ 279 const char* formatstr, /**< format string like in printf() function */ 280 ... /**< format arguments line in printf() function */ 281 ); 282 283 /** prints a dialog message that requests user interaction into a file, acting like the vfprintf() command */ 284 SCIP_EXPORT 285 void SCIPmessageVFPrintDialog( 286 SCIP_MESSAGEHDLR* messagehdlr, /**< message handler */ 287 FILE* file, /**< file stream to print into, or NULL for stdout */ 288 const char* formatstr, /**< format string like in printf() function */ 289 va_list ap /**< variable argument list */ 290 ); 291 292 /** prints a message depending on the verbosity level, acting like the printf() command */ 293 #ifdef __GNUC__ 294 __attribute__((format(printf, 4, 5))) 295 #endif 296 SCIP_EXPORT 297 void SCIPmessagePrintVerbInfo( 298 SCIP_MESSAGEHDLR* messagehdlr, /**< message handler */ 299 SCIP_VERBLEVEL verblevel, /**< current verbosity level */ 300 SCIP_VERBLEVEL msgverblevel, /**< verbosity level of this message */ 301 const char* formatstr, /**< format string like in printf() function */ 302 ... /**< format arguments line in printf() function */ 303 ); 304 305 /** prints a message depending on the verbosity level, acting like the vprintf() command */ 306 SCIP_EXPORT 307 void SCIPmessageVPrintVerbInfo( 308 SCIP_MESSAGEHDLR* messagehdlr, /**< message handler */ 309 SCIP_VERBLEVEL verblevel, /**< current verbosity level */ 310 SCIP_VERBLEVEL msgverblevel, /**< verbosity level of this message */ 311 const char* formatstr, /**< format string like in printf() function */ 312 va_list ap /**< variable argument list */ 313 ); 314 315 /** prints a message into a file depending on the verbosity level, acting like the fprintf() command */ 316 #ifdef __GNUC__ 317 __attribute__((format(printf, 5, 6))) 318 #endif 319 SCIP_EXPORT 320 void SCIPmessageFPrintVerbInfo( 321 SCIP_MESSAGEHDLR* messagehdlr, /**< message handler */ 322 SCIP_VERBLEVEL verblevel, /**< current verbosity level */ 323 SCIP_VERBLEVEL msgverblevel, /**< verbosity level of this message */ 324 FILE* file, /**< file stream to print into, or NULL for stdout */ 325 const char* formatstr, /**< format string like in printf() function */ 326 ... /**< format arguments line in printf() function */ 327 ); 328 329 /** prints a message into a file depending on the verbosity level, acting like the vfprintf() command */ 330 SCIP_EXPORT 331 void SCIPmessageVFPrintVerbInfo( 332 SCIP_MESSAGEHDLR* messagehdlr, /**< message handler */ 333 SCIP_VERBLEVEL verblevel, /**< current verbosity level */ 334 SCIP_VERBLEVEL msgverblevel, /**< verbosity level of this message */ 335 FILE* file, /**< file stream to print into, or NULL for stdout */ 336 const char* formatstr, /**< format string like in printf() function */ 337 va_list ap /**< variable argument list */ 338 ); 339 340 /** prints the header with source file location for an error message using the static message handler */ 341 SCIP_EXPORT 342 void SCIPmessagePrintErrorHeader( 343 const char* sourcefile, /**< name of the source file that called the function */ 344 int sourceline /**< line in the source file where the function was called */ 345 ); 346 347 /** prints an error message, acting like the printf() command using the static message handler */ 348 #ifdef __GNUC__ 349 __attribute__((format(printf, 1, 2))) 350 #endif 351 SCIP_EXPORT 352 void SCIPmessagePrintError( 353 const char* formatstr, /**< format string like in printf() function */ 354 ... /**< format arguments line in printf() function */ 355 ); 356 357 /** prints an error message, acting like the vprintf() command using the static message handler */ 358 SCIP_EXPORT 359 void SCIPmessageVPrintError( 360 const char* formatstr, /**< format string like in printf() function */ 361 va_list ap /**< variable argument list */ 362 ); 363 364 /** Method to set the error printing method. Setting the error printing method to NULL will suspend all error methods. 365 * 366 * @note The error printing method is a static variable. This means that all occurring errors are handled via this method. 367 */ 368 SCIP_EXPORT 369 void SCIPmessageSetErrorPrinting( 370 SCIP_DECL_ERRORPRINTING((*errorPrinting)),/**< error message print method of message handler, or NULL */ 371 void* data /**< data pointer which will be passed to the error printing method, or NULL */ 372 ); 373 374 /** Method to set the error printing method to default version prints everything the stderr. 375 * 376 * @note The error printing method is a static variable. This means that all occurring errors are handled via this method. 377 */ 378 SCIP_EXPORT 379 void SCIPmessageSetErrorPrintingDefault( 380 void 381 ); 382 383 384 /** returns the user data of the message handler */ 385 SCIP_EXPORT 386 SCIP_MESSAGEHDLRDATA* SCIPmessagehdlrGetData( 387 SCIP_MESSAGEHDLR* messagehdlr /**< message handler */ 388 ); 389 390 /** returns the log file or NULL for stdout */ 391 SCIP_EXPORT 392 FILE* SCIPmessagehdlrGetLogfile( 393 SCIP_MESSAGEHDLR* messagehdlr /**< message handler */ 394 ); 395 396 /** returns TRUE if the message handler is set to be quiet */ 397 SCIP_EXPORT 398 SCIP_Bool SCIPmessagehdlrIsQuiet( 399 SCIP_MESSAGEHDLR* messagehdlr /**< message handler */ 400 ); 401 402 #ifdef NDEBUG 403 404 /* In optimized mode, the function calls are overwritten by defines to reduce the number of function calls and 405 * speed up the algorithms. 406 */ 407 408 #define SCIPmessagehdlrGetData(messagehdlr) ((messagehdlr) != NULL) ? messagehdlr->messagehdlrdata : NULL 409 #define SCIPmessagehdlrGetLogfile(messagehdlr) ((messagehdlr) == NULL ? NULL : (messagehdlr)->logfile) 410 #define SCIPmessagehdlrIsQuiet(messagehdlr) ((messagehdlr) == NULL || (messagehdlr)->quiet) 411 412 #endif 413 414 #ifdef __cplusplus 415 } 416 #endif 417 418 #endif 419