2 Copyright (c) 2004-2007, John Hurst
5 Redistribution and use in source and binary forms, with or without
6 modification, are permitted provided that the following conditions
8 1. Redistributions of source code must retain the above copyright
9 notice, this list of conditions and the following disclaimer.
10 2. Redistributions in binary form must reproduce the above copyright
11 notice, this list of conditions and the following disclaimer in the
12 documentation and/or other materials provided with the distribution.
13 3. The name of the author may not be used to endorse or promote products
14 derived from this software without specific prior written permission.
16 THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
17 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
18 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
19 IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
20 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
21 NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
22 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
23 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
25 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29 \brief message logging API
36 #include <KM_platform.h>
43 #define LOG_MSG_IMPL(t) \
45 va_start(args, fmt); \
46 vLogf((t), fmt, &args); \
49 // Returns RESULT_PTR if the given argument is NULL.
50 # define KM_TEST_NULL_L(p) \
52 DefaultLogSink().Error("NULL pointer in file %s, line %d\n", __FILE__, __LINE__); \
53 return Kumu::RESULT_PTR; \
56 // Returns RESULT_PTR if the given argument is NULL. It then
57 // assumes that the argument is a pointer to a string and returns
58 // RESULT_NULL_STR if the first character is '\0'.
60 # define KM_TEST_NULL_STR_L(p) \
62 if ( (p)[0] == '\0' ) { \
63 DefaultLogSink().Error("Empty string in file %s, line %d\n", __FILE__, __LINE__); \
64 return Kumu::RESULT_NULL_STR; \
70 // no log message will exceed this length
71 const ui32_t MaxLogLength = 512;
73 //---------------------------------------------------------------------------------
76 // Log messages are recorded by objects which implement the interface given
77 // in the class ILogSink below. The library maintains a pointer to a default
78 // log sink which is used by the library to report messages.
81 // types of log messages
83 LOG_DEBUG, // detailed developer info
84 LOG_INFO, // developer info
85 LOG_WARN, // library non-fatal or near-miss error
86 LOG_ERROR, // library fatal error
87 LOG_NOTICE, // application user info
88 LOG_ALERT, // application non-fatal or near-miss error
89 LOG_CRIT, // application fatal error
93 // OR these values together to come up with sink filter flags.
94 // The default mask is LOG_ALLOW_ALL (all messages).
95 const i32_t LOG_ALLOW_DEBUG = 0x00000001;
96 const i32_t LOG_ALLOW_INFO = 0x00000002;
97 const i32_t LOG_ALLOW_WARN = 0x00000004;
98 const i32_t LOG_ALLOW_ERROR = 0x00000008;
99 const i32_t LOG_ALLOW_NOTICE = 0x00000010;
100 const i32_t LOG_ALLOW_ALERT = 0x00000020;
101 const i32_t LOG_ALLOW_CRIT = 0x00000040;
102 const i32_t LOG_ALLOW_NONE = 0x00000000;
103 const i32_t LOG_ALLOW_ALL = 0x000fffff;
105 // options are used to control display format default is 0.
106 const i32_t LOG_OPTION_TYPE = 0x01000000;
107 const i32_t LOG_OPTION_TIMESTAMP = 0x02000000;
108 const i32_t LOG_OPTION_PID = 0x04000000;
109 const i32_t LOG_OPTION_NONE = 0x00000000;
110 const i32_t LOG_OPTION_ALL = 0xfff00000;
112 // A log message with environmental metadata
113 class LogEntry : public IArchive
122 LogEntry(ui32_t pid, LogType_t t, const char* m) : PID(pid), Type(t), Msg(m) { assert(m); }
123 virtual ~LogEntry() {}
125 // returns true if the message Type is present in the mask
126 bool TestFilter(i32_t mask_value) const;
128 // renders the message into outstr using the given dispaly options
130 std::string& CreateStringWithOptions(std::string& outstr, i32_t mask_value) const;
133 bool HasValue() const { return ! Msg.empty(); }
134 ui32_t ArchiveLength() const;
135 bool Archive(MemIOWriter* Writer) const;
136 bool Unarchive(MemIOReader* Reader);
140 std::basic_ostream<char, std::char_traits<char> >&
141 operator<<(std::basic_ostream<char, std::char_traits<char> >& strm, LogEntry const& Entry);
144 typedef ArchivableList<LogEntry> LogEntryList;
154 ILogSink() : m_filter(LOG_ALLOW_ALL), m_options(LOG_OPTION_NONE) {}
155 virtual ~ILogSink() {}
157 void SetFilterFlag(i32_t f) { m_filter |= f; }
158 void UnsetFilterFlag(i32_t f) { m_filter &= ~f; }
159 bool TestFilterFlag(i32_t f) const { return ((m_filter & f) == f); }
161 void SetOptionFlag(i32_t o) { m_options |= o; }
162 void UnsetOptionFlag(i32_t o) { m_options &= ~o; }
163 bool TestOptionFlag(i32_t o) const { return ((m_options & o) == o); }
166 void Error(const char* fmt, ...) { LOG_MSG_IMPL(LOG_ERROR); }
167 void Warn(const char* fmt, ...) { LOG_MSG_IMPL(LOG_WARN); }
168 void Info(const char* fmt, ...) { LOG_MSG_IMPL(LOG_INFO); }
169 void Debug(const char* fmt, ...) { LOG_MSG_IMPL(LOG_DEBUG); }
171 // application messages
172 void Critical(const char* fmt, ...) { LOG_MSG_IMPL(LOG_CRIT); }
173 void Alert(const char* fmt, ...) { LOG_MSG_IMPL(LOG_ALERT); }
174 void Notice(const char* fmt, ...) { LOG_MSG_IMPL(LOG_NOTICE); }
177 void Logf(LogType_t type, const char* fmt, ...) { LOG_MSG_IMPL(type); }
179 // actual log sink input
180 virtual void vLogf(LogType_t, const char*, va_list*);
181 virtual void WriteEntry(const LogEntry&) = 0;
185 // Sets the internal default sink to the given receiver. If the given value
186 // is zero, sets the default sink to the internally allocated stderr sink.
187 void SetDefaultLogSink(ILogSink* = 0);
189 // Returns the internal default sink.
190 ILogSink& DefaultLogSink();
193 // Sets a log sink as the default until the object is destroyed.
194 // The original default sink is saved and then restored on delete.
197 KM_NO_COPY_CONSTRUCT(LogSinkContext);
202 LogSinkContext(ILogSink& sink) {
203 m_orig = &DefaultLogSink();
204 SetDefaultLogSink(&sink);
208 SetDefaultLogSink(m_orig);
212 //------------------------------------------------------------------------------------------
215 // write messages to two subordinate log sinks
216 class TeeLogSink : public ILogSink
218 KM_NO_COPY_CONSTRUCT(TeeLogSink);
225 TeeLogSink(ILogSink& a, ILogSink& b) : m_a(a), m_b(b) {}
226 virtual ~TeeLogSink() {}
228 void WriteEntry(const LogEntry& Entry) {
229 m_a.WriteEntry(Entry);
230 m_b.WriteEntry(Entry);
234 // collect log messages into the given list, does not test filter
235 class EntryListLogSink : public ILogSink
238 LogEntryList& m_Target;
239 KM_NO_COPY_CONSTRUCT(EntryListLogSink);
243 EntryListLogSink(LogEntryList& target) : m_Target(target) {}
244 virtual ~EntryListLogSink() {}
246 void WriteEntry(const LogEntry& Entry);
250 // write messages to a POSIX stdio stream
251 class StdioLogSink : public ILogSink
255 KM_NO_COPY_CONSTRUCT(StdioLogSink);
258 StdioLogSink() : m_stream(stderr) {}
259 StdioLogSink(FILE* stream) : m_stream(stream) {}
260 virtual ~StdioLogSink() {}
262 void WriteEntry(const LogEntry&);
266 // write messages to the Win32 debug stream
267 class WinDbgLogSink : public ILogSink
270 KM_NO_COPY_CONSTRUCT(WinDbgLogSink);
274 virtual ~WinDbgLogSink() {}
276 void WriteEntry(const LogEntry&);
281 // write messages to a POSIX file descriptor
282 class StreamLogSink : public ILogSink
286 KM_NO_COPY_CONSTRUCT(StreamLogSink);
290 StreamLogSink(int fd) : m_fd(fd) {}
291 virtual ~StreamLogSink() {}
293 void WriteEntry(const LogEntry&);