casacore
LogOrigin.h
Go to the documentation of this file.
1//# LogOrigin.h: The source code location of the originator of a LogMessageLogOrig
2//# Copyright (C) 1996,1999,2000,2001
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_LOGORIGIN_H
30#define CASA_LOGORIGIN_H
31
32#include <casacore/casa/aips.h>
33#include <casacore/casa/BasicSL/String.h>
34#include <casacore/casa/System/ObjectID.h>
35#include <casacore/casa/iosfwd.h>
36
37namespace casacore { //# NAMESPACE CASACORE - BEGIN
38
39struct SourceLocation;
40
41// <summary>
42// LogOrigin: The source code location of the originator of a LogMessage.
43// </summary>
44
45// <use visibility=export>
46
47// <reviewed reviewer="wbrouw" date="1996/08/21" tests="tLogging.cc" demos="dLogging.cc">
48// </reviewed>
49
50// <prerequisite>
51// <li> <linkto class="ObjectID">ObjectID</linkto> if you are interested in
52// logging from Distributed Objects (don't worry if you don't know what
53// that means - in that case ignore it!).
54// </prerequisite>
55//
56// <etymology>
57// Log[message] Origin[ation point].
58// </etymology>
59//
60// <synopsis>
61// The <src>LogOriging</src> class is used to record the location at which a
62// <linkto class="LogMessage">LogMessage</linkto> originates. It consists of:
63// <ul>
64// <li> A class name, which is blank in the case of a global function.
65// <li> A function name - global or member. You should "cut and paste" not only
66// the function name, but also the arguments (but not the return type) to
67// ensure that the function name is unique in the face of overloading.
68// <li> A source file name, usually filled in with the <src>WHERE</src>
69// predefined macro.
70// <li> A line number, usually filled in with the <src>__LINE__</src> or
71// <src>WHERE</src> macros.
72// <li> An <linkto class="ObjectID">ObjectID</linkto> if the log message comes
73// from a distributed object (if you don't know what this means,
74// you don't need to worry about it).
75// <li> Eventually we may want to canonicalize the path in the filename.
76// </ul>
77// </synopsis>
78//
79// <example>
80
81// </example>
82// See the examples for <linkto class="LogMessage">LogMessage</linkto> and in
83// <linkto file="Logging.h">Logging.h</linkto>.
84//
85// <motivation>
86// It can be very useful for debugging if you know where a message is coming
87// from.
88// </motivation>
89//
90// <todo asof="1996/07/23">
91// <li> Nothing known
92// </todo>
93
95{
96public:
97
98 // The default constructor sets a null class name, function name, object id,
99 // source file name, and sets the line number to zero.
101
102 // Use this constructor if the log message origination is from a
103 // global function. Normally <src>where</src> is provided using
104 // the <src>WHERE</src> macro.
105 LogOrigin(const String &globalFunctionName, const SourceLocation *where = 0);
106
107 // Use this constructor if the log message origination is from a
108 // class member function. Normally <src>where</src> is provided using
109 // the <src>WHERE</src> macro.
110 LogOrigin(const String &className, const String &memberFuncName,
111 const SourceLocation *where = 0);
112
113 // Use this constructor if the log message origination is from a
114 // distributed object (don't worry if you don't know what this
115 // means). Normally <src>where</src> is provided using the
116 // <src>WHERE</src> macro.
117 LogOrigin(const String &className, const String &memberFuncName,
118 const ObjectID &id, const SourceLocation *where = 0);
119
120 // Make <src>this</src> LogOrigin a copy of <src>other</src>.
121 // <group>
122 LogOrigin(const LogOrigin &other);
124 // </group>
125
127
128 // Get or set the corresponding element of the source location. Note that
129 // the "set" functions can be strung together:
130 // <srcBlock>
131 // LogOrigin where;
132 // ...
133 // where.function("anotherFunc").line(__LINE__);
134 // </srcBlock>
135 // <group>
136 const String &taskName() const;
137 LogOrigin &taskName(const String &funcName);
138
139 const String &functionName() const;
140 LogOrigin &functionName(const String &funcName);
141
142 const String &className() const;
144
145 const ObjectID &objectID() const;
147
148 uInt line() const;
150
151 const String &fileName() const;
153 // </group>
154
155 // Set the file name and line number at the same time. Normally
156 // <src>where</src> will be defined with the <src>WHERE</src> macro.
157 LogOrigin &sourceLocation(const SourceLocation *where);
158
159 // Returns <src>class\::function</src> for a member function, or
160 // <src>\::function</src> for a global function.
162
163 // Turn the entire origin into a String.
165
166 // Turns the entire origin except for the ObjectID into a String. The
167 // ObjectID can be turned into a string vie ObjectID::toString.
169
170 // Return true if the line number and file name are not set.
171 Bool isUnset() const;
172
173private:
181
182 // Return a String with the MPI rank
184
185 // Provide common implementation for copy constructor and
186 // assignment operator.
187 void copy_other(const LogOrigin &other);
188};
189
190// <summary>
191// Write a LogOrigin to an ostream.
192// </summary>
193// Write a LogOrigin as a string to an ostream. Merely calls
194// <src>LogOrigin::toString()</src>
195// <group name=LogOrigin_ostream>
196ostream &operator<<(ostream &os, const LogOrigin &origin);
197// </group>
198
199// <summary>
200// Helper struct to get the source line.
201// </summary>
202// The user should only use the <src>WHERE</src> macro.
203// <group name=SourceLocation>
206 const char *fileName;
207 Int lineNumber;
208 static const SourceLocation *canonicalize(const char *file, Int line);
210
211#define WHERE casacore::SourceLocation::canonicalize(__FILE__, __LINE__)
212
213// </group>
214
215
216} //# NAMESPACE CASACORE - END
217
218#endif
String location() const
Turns the entire origin except for the ObjectID into a String.
LogOrigin(const String &globalFunctionName, const SourceLocation *where=0)
Use this constructor if the log message origination is from a global function.
LogOrigin & operator=(const LogOrigin &other)
const String & functionName() const
LogOrigin()
The default constructor sets a null class name, function name, object id, source file name,...
Bool isUnset() const
Return true if the line number and file name are not set.
LogOrigin & fileName(const String &fileName)
const String & className() const
LogOrigin & sourceLocation(const SourceLocation *where)
Set the file name and line number at the same time.
const String & fileName() const
const String & taskName() const
Get or set the corresponding element of the source location.
LogOrigin & functionName(const String &funcName)
String toString() const
Turn the entire origin into a String.
void copy_other(const LogOrigin &other)
Provide common implementation for copy constructor and assignment operator.
LogOrigin & className(const String &className)
const ObjectID & objectID() const
LogOrigin & line(uInt which)
LogOrigin & objectID(const ObjectID &id)
LogOrigin(const String &className, const String &memberFuncName, const SourceLocation *where=0)
Use this constructor if the log message origination is from a class member function.
uInt line() const
String fullName() const
Returns class::function for a member function, or ::function for a global function.
LogOrigin(const LogOrigin &other)
Make this LogOrigin a copy of other.
String getNode()
Return a String with the MPI rank.
LogOrigin & taskName(const String &funcName)
LogOrigin(const String &className, const String &memberFuncName, const ObjectID &id, const SourceLocation *where=0)
Use this constructor if the log message origination is from a distributed object (don't worry if you ...
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
ostream & operator<<(ostream &os, const IComplex &)
Show on ostream.
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
ostream & operator<<(ostream &os, const LogOrigin &origin)
static const SourceLocation * canonicalize(const char *file, Int line)
Helper struct to get the source line.
Definition: LogOrigin.h:204