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