MACSio  0.9
Multi-purpose, Application-Centric, Scalable I/O Proxy App
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
MACSIO_LOG

Message logging utilities. More...

Data Structures

struct  _log_flags_t
 
struct  _MACSIO_LOG_LogHandle_t
 

Macros

#define MACSIO_LOG_DEFAULT_LINE_COUNT   64
 
#define MACSIO_LOG_DEFAULT_EXTRA_LINES   64
 
#define MACSIO_LOG_DEFAULT_LINE_LENGTH   128
 
#define MACSIO_LOG_MSG(SEV, MSG)   MACSIO_LOG_MSG2(MACSIO_LOG_MainLog, MSG, MACSIO_LOG_Msg ## SEV, #SEV, errno, mpi_errno, __FILE__, __LINE__)
 Convenience macro for logging a message to the main log. More...
 
#define MACSIO_LOG_MSGV(VSEV, MSG)
 
#define MACSIO_LOG_MSGL(LOG, SEV, MSG)   MACSIO_LOG_MSG2(LOG, MSG, MACSIO_LOG_Msg ## SEV, #SEV, errno, mpi_errno, __FILE__, __LINE__)
 Convenience macro for logging a message to any specific log. More...
 
#define MACSIO_LOG_MSGLV(LOG, VSEV, MSG)
 Convenience macro for logging a message with variable severity to any specific log. More...
 

Typedefs

typedef struct _log_flags_t log_flags_t
 
typedef struct
_MACSIO_LOG_LogHandle_t 
MACSIO_LOG_LogHandle_t
 
typedef enum
_MACSIO_LOG_MsgSeverity_t 
MACSIO_LOG_MsgSeverity_t
 
typedef struct
_MACSIO_LOG_LogHandle_t 
MACSIO_LOG_LogHandle_t
 

Enumerations

enum  _MACSIO_LOG_MsgSeverity_t {
  MACSIO_LOG_MsgDbg1, MACSIO_LOG_MsgDbg2, MACSIO_LOG_MsgDbg3, MACSIO_LOG_MsgInfo,
  MACSIO_LOG_MsgWarn, MACSIO_LOG_MsgErr, MACSIO_LOG_MsgDie
}
 

Functions

char const * MACSIO_LOG_MakeMsg (char const *format,...)
 Internal convenience method to build a message from a printf-style format string and args. More...
 
MACSIO_LOG_LogHandle_tMACSIO_LOG_LogInit (MPI_Comm comm, char const *path, int line_len, int lines_per_proc, int extra_lines_proc0)
 Initialize a log. More...
 
void MACSIO_LOG_LogMsg (MACSIO_LOG_LogHandle_t const *log, char const *fmt,...)
 Issue a printf-style message to a log. More...
 
void MACSIO_LOG_LogMsgWithDetails (MACSIO_LOG_LogHandle_t const *log, char const *linemsg, MACSIO_LOG_MsgSeverity_t sevVal, char const *sevStr, int sysErrno, int mpiErrno, char const *theFile, int theLine)
 Convenience method for building a detailed message for a log. More...
 
void MACSIO_LOG_LogFinalize (MACSIO_LOG_LogHandle_t *log)
 Finalize and close an open log Should be called collectively by all processors that created the log. More...
 

Variables

int mpi_errno = MPI_SUCCESS
 Error code returned by most recent MPI call. More...
 
int MACSIO_LOG_DebugLevel = 0
 
MACSIO_LOG_LogHandle_tMACSIO_LOG_MainLog = 0
 Log handle for MACSIO's main log. More...
 
MACSIO_LOG_LogHandle_tMACSIO_LOG_StdErr = 0
 Log handle for MACSIO's stderr output. More...
 
int mpi_errno
 Error code returned by most recent MPI call. More...
 
int MACSIO_LOG_DebugLevel
 
MACSIO_LOG_LogHandle_tMACSIO_LOG_MainLog
 Log handle for MACSIO's main log. More...
 
MACSIO_LOG_LogHandle_tMACSIO_LOG_StdErr
 Log handle for MACSIO's stderr output. More...
 

Detailed Description

Message logging utilities.

MACSIO_LOG is a small utility for logging various kinds of messages from processors. This includes debugging messages, warnings and errors.

A MACSIO_LOG is a single text file that is divided into groups of message lines. Each processor gets its own group of lines within the file it may write to. Rank 0 gets the first group of lines. Rank 1, the next group of lines and so forth. Each line has a maximum length too.

When a MACSIO_LOG is created with MACSIO_LOG_InitLog(), the caller specifies the MPI communicator the log will be used for, the number of message lines per MPI task to allocate plus a count of extra lines for rank 0 and the maximum length of any message. Rank 0 initializes the text file with all space characters except for header lines to distinguish each processor's group of lines in the file. Note that for a large run on say 10^5 processors, it may take rank 0 several seconds to create this file.

Messages are restricted to a single line of text. Any embedded new-line characters are removed from a message and replaced with a '!' character. If a processor's message is longer than the maximum length of a line for the log, the message is truncated to fit within the line. As processors issue messages, they are written to the processors group of lines in round-robin fashion. As the set of messages issued from a processor reaches the end of its group of lines within the file, it starts issuing new messages at the beginning of the group. So, older messages can wind up getting overwritten by newer messages. However, all the most recent messages prior to any significant error will at least be captured in the log.

Parallelism in writing to a MACSIO_LOG file is achieved by ensuring no two processor attempt to write data in overlapping regions in the file by using pwrite() to do the actual writes.

MACSIO's main creates a default log, MACSIO_LOG_MainLog, on the MACSIO_MAIN_Comm. That log is probably the only log needed by MACSIO proper or any of its plugins. The convenience macro, MACSIO_LOG_MSG(SEV, MSG), is the only method one need to worry about to log messages to the main log. That macro will also capture more detailed information regarding error states around the time the message issue issued including the file and line number, the system errno and the most recent MPI error state.

If you use MACSIO_LOG_MSG, messages are allowed one of several severities; Dbg1, Dbg2, Dbg3, Warn, Err and Die. A severity of Die causes an abort. Depending on the current debug level setting, Dbg1-3 messages may or may not be recorded to a log.

MACSIO's main also creates a log for issuing messages to stderr, MACSIO_LOG_StdErr. However, there is no convenience macro like MACSIO_LOG_MSG() for logging messages to MACSIO_LOG_StdErr. A caller simply has to use the MACSIO_LOG interface methods to issue messages to MACSIO_LOG_StdErr.

However, any plugin or other portion of MACSIO may, optionally, create its own, private, log using MACSIO_LOG_InitLog(). Once a log is created, any processor can independently issue messages to the log. There is no parallel communication involved in issuing messages to logs.

Examples of the use of MACSIO_LOG can be found in tstlog.c


Data Structure Documentation

struct _log_flags_t

Definition at line 48 of file macsio_log.c.

Data Fields
unsigned int was_logged: 1

Indicates if a message was ever logged to the log

struct _MACSIO_LOG_LogHandle_t

Definition at line 53 of file macsio_log.c.

Data Fields
MPI_Comm comm

MPI Communicator of tasks that will issue messages to this log

char * pathname

Name of the log file

int logfile

Log file file descriptor

int rank

Rank of the processor that created this log handle

int size

Size of the communicator that created this log handle

int log_line_length

Maximum length of a message line in the log file

int lines_per_proc

Number of message lines allocated in the file for each processor

int extra_lines_proc0

Additional number of message lines for processor with MPI rank 0

int current_line

Index into this processor's group of lines in the log file at which the next message will be written

log_flags_t flags

Informational flags regarding the log

Macro Definition Documentation

#define MACSIO_LOG_DEFAULT_LINE_COUNT   64

Definition at line 115 of file macsio_log.h.

#define MACSIO_LOG_DEFAULT_EXTRA_LINES   64

Definition at line 120 of file macsio_log.h.

#define MACSIO_LOG_DEFAULT_LINE_LENGTH   128

Definition at line 125 of file macsio_log.h.

#define MACSIO_LOG_MSG (   SEV,
  MSG 
)    MACSIO_LOG_MSG2(MACSIO_LOG_MainLog, MSG, MACSIO_LOG_Msg ## SEV, #SEV, errno, mpi_errno, __FILE__, __LINE__)

Convenience macro for logging a message to the main log.

Parameters
[in]SEVAbbreviated message severity (e.g. 'Dbg1', 'Warn')
[in]MSGCaller's sprintf-style message enclosed in parenthises (e.g. '("Rank %d failed",rank))'

Definition at line 133 of file macsio_log.h.

#define MACSIO_LOG_MSGV (   VSEV,
  MSG 
)
Value:
do \
{ \
switch (VSEV) \
{ \
case MACSIO_LOG_MsgDbg1: {MACSIO_LOG_MSG(Dbg1, MSG); break;} \
case MACSIO_LOG_MsgDbg2: {MACSIO_LOG_MSG(Dbg2, MSG); break;} \
case MACSIO_LOG_MsgDbg3: {MACSIO_LOG_MSG(Dbg3, MSG); break;} \
case MACSIO_LOG_MsgInfo: {MACSIO_LOG_MSG(Info, MSG); break;} \
case MACSIO_LOG_MsgWarn: {MACSIO_LOG_MSG(Warn, MSG); break;} \
case MACSIO_LOG_MsgErr: {MACSIO_LOG_MSG(Err, MSG); break; } \
case MACSIO_LOG_MsgDie: {MACSIO_LOG_MSG(Die, MSG); break; } \
} \
}while(0)
#define MACSIO_LOG_MSG(SEV, MSG)
Convenience macro for logging a message to the main log.
Definition: macsio_log.h:133

Alterantive to MACSIO_LOG_MSG when severity is a runtime variable

Parameters
[in]VSEVRuntime variable in which message severity is stored
[in]MSGCaller's sprintf-style message enclosed in parenthises (e.g. '("Rank %d failed",rank))'

Definition at line 141 of file macsio_log.h.

#define MACSIO_LOG_MSGL (   LOG,
  SEV,
  MSG 
)    MACSIO_LOG_MSG2(LOG, MSG, MACSIO_LOG_Msg ## SEV, #SEV, errno, mpi_errno, __FILE__, __LINE__)

Convenience macro for logging a message to any specific log.

Parameters
[in]LOGThe log handle
[in]SEVAbbreviated message severity (e.g. 'Dbg1', 'Warn')
[in]MSGCaller's sprintf-style message enclosed in parenthises (e.g. '("Rank %d failed",rank))'

Definition at line 163 of file macsio_log.h.

#define MACSIO_LOG_MSGLV (   LOG,
  VSEV,
  MSG 
)
Value:
do \
{ \
switch (VSEV) \
{ \
case MACSIO_LOG_MsgDbg1: {MACSIO_LOG_MSGL(LOG, Dbg1, MSG); break;} \
case MACSIO_LOG_MsgDbg2: {MACSIO_LOG_MSGL(LOG, Dbg2, MSG); break;} \
case MACSIO_LOG_MsgDbg3: {MACSIO_LOG_MSGL(LOG, Dbg3, MSG); break;} \
case MACSIO_LOG_MsgInfo: {MACSIO_LOG_MSGL(LOG, Info, MSG); break;} \
case MACSIO_LOG_MsgWarn: {MACSIO_LOG_MSGL(LOG, Warn, MSG); break;} \
case MACSIO_LOG_MsgErr: {MACSIO_LOG_MSGL(LOG, Err, MSG); break; } \
case MACSIO_LOG_MsgDie: {MACSIO_LOG_MSGL(LOG, Die, MSG); break; } \
} \
}while(0)
#define MACSIO_LOG_MSGL(LOG, SEV, MSG)
Convenience macro for logging a message to any specific log.
Definition: macsio_log.h:163

Convenience macro for logging a message with variable severity to any specific log.

Parameters
[in]LOGThe log handle
[in]VSEVRuntime variable in which message severity is stored
[in]MSGCaller's sprintf-style message enclosed in parenthises (e.g. '("Rank %d failed",rank))'

Definition at line 172 of file macsio_log.h.

Typedef Documentation

typedef struct _log_flags_t log_flags_t

Definition at line 202 of file macsio_log.h.

Enumeration Type Documentation

Enumerator
MACSIO_LOG_MsgDbg1 

Debug level 1: For coarse grained debugging messages (rare enough performance isn't effected)

MACSIO_LOG_MsgDbg2 

Debug level 2: For moderate grained debugging messages (may effect performance)

MACSIO_LOG_MsgDbg3 

Debug level 3: For fine grained debugging messages (most likely effects performance)

MACSIO_LOG_MsgInfo 

Informational messages

MACSIO_LOG_MsgWarn 

Warnings of minor problems that can be recovered from without undue effects

MACSIO_LOG_MsgErr 

Error conditions that result in a change in expected/anticipated behavior

MACSIO_LOG_MsgDie 

Unrecoverable errors

Definition at line 191 of file macsio_log.h.

Function Documentation

char const * MACSIO_LOG_MakeMsg ( char const *  format,
  ... 
)

Internal convenience method to build a message from a printf-style format string and args.

This method is public only because it is used within the MACSIO_LOG_MSG convenience macro.

Parameters
[in]formatA printf-like error message format string.

Definition at line 79 of file macsio_log.c.

MACSIO_LOG_LogHandle_t * MACSIO_LOG_LogInit ( MPI_Comm  comm,
char const *  path,
int  line_len,
int  lines_per_proc,
int  extra_lines_proc0 
)

Initialize a log.

All processors in the comm communicator must call this function collectively with identical values for path, line_len, and lines_per_proc.

Parameters
[in]commMPI Communicator of tasks that will issue messages to this log
[in]pathThe name of the log file
[in]line_lenThe length of each message line in the log file
[in]lines_per_procThe number of message lines for each MPI task
[in]extra_lines_proc0The number of extra message lines for processor rank 0

Definition at line 113 of file macsio_log.c.

void MACSIO_LOG_LogMsg ( MACSIO_LOG_LogHandle_t const *  log,
char const *  fmt,
  ... 
)

Issue a printf-style message to a log.

May be called independently by any processor in the communicator used to initialize the log.

Parameters
[in]logThe handle for the specified log
[in]fmtA printf-style format string for the log message

Definition at line 186 of file macsio_log.c.

void MACSIO_LOG_LogMsgWithDetails ( MACSIO_LOG_LogHandle_t const *  log,
char const *  linemsg,
MACSIO_LOG_MsgSeverity_t  sevVal,
char const *  sevStr,
int  sysErrno,
int  mpiErrno,
char const *  theFile,
int  theLine 
)

Convenience method for building a detailed message for a log.

Parameters
[in]logLog handle to issue message to
[in]linemsgCaller's message string
[in]sevValCaller's message severity value
[in]sevStrCaller's message severity abbreviation string
[in]sysErrnoCurrent (most recnet) system's errno
[in]mpiErrnoCurrent (most recent) MPI error
[in]theFileCaller's file name
[in]theLineCaller's line number within the file

Definition at line 249 of file macsio_log.c.

void MACSIO_LOG_LogFinalize ( MACSIO_LOG_LogHandle_t log)

Finalize and close an open log Should be called collectively by all processors that created the log.

Parameters
[in]logThe log to be closed

Definition at line 295 of file macsio_log.c.

Variable Documentation

int mpi_errno = MPI_SUCCESS

Error code returned by most recent MPI call.

MACSIO uses mpi_errno much like the system's errno. However, there is no way to enforce that any particular MPI function calls set mpi_errno. MACSIO relies upon the honor system of develepors to always make MPI calls by setting mpi_errno to the return value of those calls. Assuming this practice is followed throughout MACSIO and any of its plugins, then the global variable mpi_errno should always hold the MPI error return value of the most recent MPI call.

Definition at line 43 of file macsio_log.c.

int MACSIO_LOG_DebugLevel = 0

Filtering level for debugging messages

MACSIO generates 3 levels of debug messages numbered 1, 2 and 3. Each level is intended to represent more and more detailed debugging messages. Level 1 messages are issued rare enough by MACSIO (e.g. coarse grained) that they will not impact performance. Level 3 messages can be issued often enough by MACSIO that they will almost certainly impact performance. Level 2 messages are somewhere in between. The global variable MACSIO_LOG_DebugLevel is used to filter what messages generated by MACSIO that will actually make it into a detailed log message. If MACSIO_LOG_DebugLevel is set to level N, then messages at and below N debug level will appear in a log when written via MACSIO_LOG_LogMsgWithDetails. However, messages above this level will be discarded. As developers write code blocks in MACSIO, developers must choose what kind of messages are issued and, for debugging kinds of messages, the appropriate debug level.

Definition at line 44 of file macsio_log.c.

MACSIO_LOG_LogHandle_t* MACSIO_LOG_MainLog = 0

Log handle for MACSIO's main log.

Typically, developers will use MACSIO_LOG_MSG macro to log messages. Such messages are automatically logged to the main log. The main log is created by MACSIO's main.

Definition at line 45 of file macsio_log.c.

MACSIO_LOG_LogHandle_t* MACSIO_LOG_StdErr = 0

Log handle for MACSIO's stderr output.

In rare cases, developers may want to issues messages to stderr. In this case, MACSIO's stderr log handle should be used.

Definition at line 46 of file macsio_log.c.

int mpi_errno

Error code returned by most recent MPI call.

MACSIO uses mpi_errno much like the system's errno. However, there is no way to enforce that any particular MPI function calls set mpi_errno. MACSIO relies upon the honor system of develepors to always make MPI calls by setting mpi_errno to the return value of those calls. Assuming this practice is followed throughout MACSIO and any of its plugins, then the global variable mpi_errno should always hold the MPI error return value of the most recent MPI call.

Definition at line 43 of file macsio_log.c.

int MACSIO_LOG_DebugLevel

Filtering level for debugging messages

MACSIO generates 3 levels of debug messages numbered 1, 2 and 3. Each level is intended to represent more and more detailed debugging messages. Level 1 messages are issued rare enough by MACSIO (e.g. coarse grained) that they will not impact performance. Level 3 messages can be issued often enough by MACSIO that they will almost certainly impact performance. Level 2 messages are somewhere in between. The global variable MACSIO_LOG_DebugLevel is used to filter what messages generated by MACSIO that will actually make it into a detailed log message. If MACSIO_LOG_DebugLevel is set to level N, then messages at and below N debug level will appear in a log when written via MACSIO_LOG_LogMsgWithDetails. However, messages above this level will be discarded. As developers write code blocks in MACSIO, developers must choose what kind of messages are issued and, for debugging kinds of messages, the appropriate debug level.

Definition at line 44 of file macsio_log.c.

MACSIO_LOG_LogHandle_t* MACSIO_LOG_MainLog

Log handle for MACSIO's main log.

Typically, developers will use MACSIO_LOG_MSG macro to log messages. Such messages are automatically logged to the main log. The main log is created by MACSIO's main.

Definition at line 45 of file macsio_log.c.

MACSIO_LOG_LogHandle_t* MACSIO_LOG_StdErr

Log handle for MACSIO's stderr output.

In rare cases, developers may want to issues messages to stderr. In this case, MACSIO's stderr log handle should be used.

Definition at line 46 of file macsio_log.c.