casacore
LogSink.h
Go to the documentation of this file.
1//# LogSink.h: Distribute LogMessages to their destination(s)
2//# Copyright (C) 1996,2000,2001,2003,2016
3//# Associated Universities, Inc. Washington DC, USA.
4//#
5//# This library is free software; you can redistribute it and/or modify it
6//# under the terms of the GNU Library General Public License as published by
7//# the Free Software Foundation; either version 2 of the License, or (at your
8//# option) any later version.
9//#
10//# This library is distributed in the hope that it will be useful, but WITHOUT
11//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12//# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13//# License for more details.
14//#
15//# You should have received a copy of the GNU Library General Public License
16//# along with this library; if not, write to the Free Software Foundation,
17//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18//#
19//# Correspondence concerning AIPS++ should be addressed as follows:
20//# Internet email: aips2-request@nrao.edu.
21//# Postal address: AIPS++ Project Office
22//# National Radio Astronomy Observatory
23//# 520 Edgemont Road
24//# Charlottesville, VA 22903-2475 USA
25//#
26//#
27//# $Id$
28
29#ifndef CASA_LOGSINK_H
30#define CASA_LOGSINK_H
31
32#include <casacore/casa/aips.h>
33#include <casacore/casa/Logging/LogSinkInterface.h>
34
35#include <casacore/casa/Utilities/CountedPtr.h>
36#include <casacore/casa/Exceptions/Error.h>
37#include <casacore/casa/iosfwd.h>
38
39#include <mutex>
40
41namespace casacore { //# NAMESPACE CASACORE - BEGIN
42
43// <summary>
44// Distribute LogMessages to their destination(s)
45// </summary>
46
47// <use visibility=export>
48
49// <reviewed reviewer="wbrouw" date="1996/08/21" tests="tLogging.cc" demos="dLogging.cc">
50// </reviewed>
51
52// <prerequisite>
53// <li> <linkto class="LogMessage">LogMessage</linkto>
54// <li> <linkto class="LogSinkInterface">LogSinkInterface</linkto>, if you are
55// interested in extending the set of destinations a <src>LogMessage</src> can
56// be sent.
57// </prerequisite>
58//
59// <etymology>
60// Log as in "Log Book." Sink from its common usage ("source/sink") as a thing
61// which can accept some substance or energy.
62// </etymology>
63//
64// <synopsis>
65// The LogSink class supplies the destination for
66// <linkto class="LogMessage">LogMessage</linkto>s. There are two destinations
67// available through the <src>LogSink</src>
68// <ol>
69// <li> A <i>global</i> destination, which is shared by all LogSinks. The global
70// destination will typically be a GUI window or standard output.
71// <li> A <i>local</i> destination which is intended to log changes to
72// particular dataset(s). The local destination will typically be a
73// Casacore <linkto class="Table">Table</linkto>, but there is also
74// a local sink for temporary storage in memory.
75// </ol>
76// Normally the <src>post()</src> member function will be called which
77// sends the message to both the global and local destinations, however one or
78// the other may be chosen via <src>LogSink::postGlobally()</src> and
79// <src>postLocally()</src> member functions.
80//
81// The global sink will normally be set by system library code (it defaults to
82// using <src>cerr</src>. The type of local sink is defined at
83// construction time. Presently you can choose one of:
84// <ol>
85// <li> a <linkto class="NullLogSink">NullLogSink</linkto> which merely
86// discards the logging messages.
87// <li> a <linkto class="StreamLogSink">StreamLogSink</linkto> which sends
88// the log messages to an <src>ostream</src> (typically <src>cerr</src>)
89// <li> a <linkto class="TableLogSink">TableLogSink</linkto> which sends
90// the messages to a Casacore <linkto class=Table>Table</linkto>.
91// </ol>
92//
93// Every <src>LogSink</src> has an attached
94// <linkto class=LogFilterInterface>LogFilterInterface</linkto>
95// which is used to reject or pass messages.
96// The local and global sinks have their own filters, so they can
97// pass different message priorities (e.g., global <src>DEBUGGING</src> and
98// local <src>NORMAL</src>). Generally applications code shouldn't change the
99// global filter.
100//
101// </synopsis>
102//
103// <example>
104// <srcblock>
105// LogMessage logMessage(...);
106// LogSink logger(LogMessage::NORMAL, "logtable"); // log locally to a 'logtable'
107// logMessage.message("this is a message").line(__LINE__);
108// logger.post(logMessage); // local and global
109// </srcblock>
110// More complete examples are in <linkto file=Logging.h>Logging.h</linkto>.
111// </example>
112//
113// <h3>Advanced topics</h3>
114// All possible sinks are derived from an abstract base class:
115// <linkto class=LogSinkInterface>LogSinkInterface</linkto>. If you want to
116// allow for logging to a different type of sink (i.e. different from
117// a stream or Table) , you first need to derive a new class from
118// <src>LogSinkInterface</src>, and then add a new constructor to
119// <src>LogSink</src>.
120//
121// <src>LogSink</src> itself contains a reference to the actual object that
122// disposes of the messages. Several <src>LogSink</src>'s can share the same
123// actual sink via the copy constructor or assignment operator.
124// <srcblock>
125// LogSink logger1(LogMessage::NORMAL, "logtable");
126// LogSink logger2(logger1); // logger2 references logger1
127// logger2.post(message); // ends up in "logtable"
128// </srcblock>
129// You can even have different <src>LogFilterInterface</src>'s
130// attached to the different <src>LogSink</src>s.
131//
132// <motivation>
133// Logging changes to data and informing users what the software is doing in
134// detail.
135// </motivation>
136//
137// <todo asof="1996/07/24">
138// <li> More sink types - in particular to Glish.
139// <li> A "tee" Sink type might be useful.
140// </todo>
141
143{
144public:
145 //#If you add more sink types, modify the <ol> in the synopsis as well.
146 // Create a null local sink that throws all messages away or create
147 // a memory local sink that holds the messages in memory.
148 // If a filter isn't defined, default to <src>NORMAL</src>.
149 // <group>
151 Bool nullSink = True);
152 explicit LogSink (const LogFilterInterface &filter, Bool nullSink = True);
153 // </group>
154
155 // Log to an ostream. It is the responsiblity of the caller to ensure that
156 // <src>os</src> will last as long as the <src>LogSink</src>s that use it.
157 // Normally you would use <src>&cerr</src> as the argument.
158 // <group>
160 Bool useGlobalSink = True);
161 LogSink (const LogFilterInterface &filter, ostream *os,
162 Bool useGlobalSink = True);
163 // </group>
164
165 // Log to the given sink.
166 // It is primarily intended to log to a
167 // <linkto class=TableLogSink>TableLogSink</linkto>.
170
171 // Make a referencing copy of <src>other</src>. That is, if you post a
172 // message to the new object, it behaves as if you had posted it to the
173 // old one (so long as their filters are the same).
174 // <group>
175 LogSink (const LogSink &other);
176 LogSink &operator= (const LogSink &other);
177 // </group>
178
179 // Temporary to avoid problem that the bool constructor is taken
180 // if a char* is passed.
181 // They are not implemented, so compiler should give warning.
182 // The 3rd argument is added to make it different from current
183 // version which is still in the system library.
184 LogSink (const LogFilterInterface &filter, const String &fileName, Int n=0);
185 LogSink (const LogFilterInterface &filter, const Char* fileName, Int n=0);
186 LogSink (LogMessage::Priority, const String &fileName, Int n=0);
187 LogSink (LogMessage::Priority, const Char* fileName, Int n=0);
188
190
191 // Send <src>message</src> to both the local and global sink. Return
192 // <src>True</src> if it passes either of them.
193 Bool post (const LogMessage &message);
194
195 // Send <src>message</src> to the global sink only. Returns <src>True</src>
196 // if it passes the filter.
197 static Bool postGlobally (const LogMessage &message);
198 // Send <src>message</src> to the local sink only. Returns <src>True</src>
199 // if it passes the filter.
200 virtual Bool postLocally (const LogMessage &message);
201
202 // Post <src>message</src> and then throw an <src>AipsError</src> exception
203 // containing <src>message.toString()</src>. It is always posted as a
204 // <src>SEVERE</src> priority message, no matter what
205 // <src>message.priority()</src> says.
206 // <group>
207 template<typename EXC> void postThenThrow (const LogMessage &message,
208 const EXC& exc)
209 { preparePostThenThrow(message, exc); throw exc; }
210 static void postGloballyThenThrow (const LogMessage &message);
211 // </group>
212
213 // Get number of messages in local sink.
214 virtual uInt nelements() const;
215
216 // Get given part of the i-th message from the local sink.
217 // <group>
218 virtual Double getTime (uInt i) const;
219 virtual String getPriority (uInt i) const;
220 virtual String getMessage (uInt i) const;
221 virtual String getLocation (uInt i) const;
222 virtual String getObjectID (uInt i) const;
223 // </group>
224
225 // Write a message (usually from another logsink) into the local one.
226 // The default implementation does nothing.
227 virtual void writeLocally (Double time, const String& message,
228 const String& priority, const String& location,
229 const String& objectID);
230
231 // Clear the local sink (i.e. remove all messages from it).
232 virtual void clearLocally();
233
234 //# Bring out of LogSinkInterface only for documentation purposes
235 // Get or set the filter of this particular <src>LogSink</src>.
236 // <group>
237 virtual const LogFilterInterface &filter() const;
239 // </group>
240
241 // Change the sink that this <src>LogSink</src> actually uses.
242 // <group>
246 // </group>
247
248 // Get/set the global sink or check if the global sink is null. The global
249 // sink defaults to using <src>cerr</src>. Generally applications code
250 // shouldn't change the global sink. More so, calling globalSink(fromNew)
251 // while using the global sink is not thread-safe. And fromNew is set to 0.
252 // <group>
254 static void globalSink (LogSinkInterface *&fromNew);
256 // </group>
257
258 // Write any pending output (by default also the global sink).
259 virtual void flush (Bool global=True);
260
261 // Returns the id for this class...
262 static String localId( );
263 // Returns the id of the LogSink in use...
264 String id( ) const;
265
266private:
267
268 // LsiIntermediate is a helper class to allow LogSinkInterface to implement
269 // semantics that allow causing all classes accessing the log sink to be
270 // aimed at a different sink object. This used to be done by using an
271 // odd "replace" method in CountedPtr; however, this is functionality is
272 // being removed to CountedPtr as it is modernized so this class was
273 // created to serve this narrow purpose.
274
276
277 public:
278
279
283
286 Bool operator! () const { return ! logSinkInterface_p;}
287
289
290 private:
291
292 // Copy ctor and op= are private and not defined to prevent double-delete.
293
296
298
299 };
300
301 // Prepare for postThenThrow function.
302 void preparePostThenThrow(const LogMessage &message, const AipsError& x) ;
303
304 // Create the global sink (attached to cerr). Always called using theirCallOnce.
305 static void createGlobalSink();
306
307 //# Data members.
310 static std::once_flag theirCallOnceFlag;
311
312 // The following is a reference to the global sink. It is created to
313 // ensure that the global sink is not destroyed before the last local
314 // reference to it is destroyed. This can happen if you have a static
315 // LogSink (or LogIO).
318};
319
320
321
322} //# NAMESPACE CASACORE - END
323
324#endif
Referenced counted pointer for constant data.
Definition: CountedPtr.h:81
Priority
An "importance" which is assigned to each LogMessage.
Definition: LogMessage.h:105
LsiIntermediate is a helper class to allow LogSinkInterface to implement semantics that allow causing...
Definition: LogSink.h:275
LsiIntermediate & operator=(const LsiIntermediate &)
LogSinkInterface & operator*()
Definition: LogSink.h:284
LsiIntermediate(const LsiIntermediate &)
Copy ctor and op= are private and not defined to prevent double-delete.
LsiIntermediate(LogSinkInterface *lsi)
Definition: LogSink.h:281
LogSinkInterface * operator->()
Definition: LogSink.h:285
void replace(LogSinkInterface *newLsi)
Definition: LogSink.h:288
LogSinkInterface * logSinkInterface_p
Definition: LogSink.h:297
String id() const
Returns the id of the LogSink in use...
LogSink(const LogFilterInterface &filter, ostream *os, Bool useGlobalSink=True)
LogSink & localSink(LogSinkInterface *&fromNew)
virtual void writeLocally(Double time, const String &message, const String &priority, const String &location, const String &objectID)
Write a message (usually from another logsink) into the local one.
virtual String getLocation(uInt i) const
LogSink(const LogFilterInterface &filter, const String &fileName, Int n=0)
Temporary to avoid problem that the bool constructor is taken if a char* is passed.
LogSink(LogMessage::Priority, const Char *fileName, Int n=0)
LogSink(const LogFilterInterface &filter, const Char *fileName, Int n=0)
CountedPtr< LsiIntermediate > local_ref_to_global_p
The following is a reference to the global sink.
Definition: LogSink.h:316
virtual String getMessage(uInt i) const
LogSink & operator=(const LogSink &other)
virtual Bool postLocally(const LogMessage &message)
Send message to the local sink only.
LogSink(LogMessage::Priority filter, ostream *os, Bool useGlobalSink=True)
Log to an ostream.
virtual const LogFilterInterface & filter() const
Get or set the filter of this particular LogSink.
virtual void clearLocally()
Clear the local sink (i.e.
virtual LogSinkInterface & filter(const LogFilterInterface &filter)
virtual Double getTime(uInt i) const
Get given part of the i-th message from the local sink.
LogSink(const LogSink &other)
Make a referencing copy of other.
void postThenThrow(const LogMessage &message, const EXC &exc)
Post message and then throw an AipsError exception containing message.toString().
Definition: LogSink.h:207
LogSink(const LogFilterInterface &filter, Bool nullSink=True)
CountedPtr< LogSinkInterface > local_sink_p
Definition: LogSink.h:308
const LogSinkInterface & localSink() const
Change the sink that this LogSink actually uses.
LogSink(LogMessage::Priority, const String &fileName, Int n=0)
static Bool postGlobally(const LogMessage &message)
Send message to the global sink only.
Bool useGlobalSink_p
Definition: LogSink.h:317
static LogSinkInterface & globalSink()
Get/set the global sink or check if the global sink is null.
LogSinkInterface & localSink()
virtual uInt nelements() const
Get number of messages in local sink.
LogSink(LogMessage::Priority filter=LogMessage::NORMAL, Bool nullSink=True)
Create a null local sink that throws all messages away or create a memory local sink that holds the m...
static Bool nullGlobalSink()
static CountedPtr< LsiIntermediate > * global_sink_p
Definition: LogSink.h:309
static void postGloballyThenThrow(const LogMessage &message)
Bool post(const LogMessage &message)
Send message to both the local and global sink.
virtual String getObjectID(uInt i) const
static void createGlobalSink()
Create the global sink (attached to cerr).
LogSink(const LogFilterInterface &filter, const CountedPtr< LogSinkInterface > &)
Log to the given sink.
virtual String getPriority(uInt i) const
static String localId()
Returns the id for this class...
virtual void flush(Bool global=True)
Write any pending output (by default also the global sink).
static std::once_flag theirCallOnceFlag
Definition: LogSink.h:310
static void globalSink(LogSinkInterface *&fromNew)
void preparePostThenThrow(const LogMessage &message, const AipsError &x)
Prepare for postThenThrow function.
String: the storage and methods of handling collections of characters.
Definition: String.h:225
this file contains all the compiler specific defines
Definition: mainpage.dox:28
TableExprNode time(const TableExprNode &node)
Definition: ExprNode.h:1580
unsigned int uInt
Definition: aipstype.h:51
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
const Bool True
Definition: aipstype.h:43
double Double
Definition: aipstype.h:55
char Char
Definition: aipstype.h:46