00001 //# LogOrigin.h: The source code location of the originator of a LogMessageLogOrig 00002 //# Copyright (C) 1996,1999,2000,2001 00003 //# Associated Universities, Inc. Washington DC, USA. 00004 //# 00005 //# This library is free software; you can redistribute it and/or modify it 00006 //# under the terms of the GNU Library General Public License as published by 00007 //# the Free Software Foundation; either version 2 of the License, or (at your 00008 //# option) any later version. 00009 //# 00010 //# This library is distributed in the hope that it will be useful, but WITHOUT 00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 00012 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public 00013 //# License for more details. 00014 //# 00015 //# You should have received a copy of the GNU Library General Public License 00016 //# along with this library; if not, write to the Free Software Foundation, 00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA. 00018 //# 00019 //# Correspondence concerning AIPS++ should be addressed as follows: 00020 //# Internet email: aips2-request@nrao.edu. 00021 //# Postal address: AIPS++ Project Office 00022 //# National Radio Astronomy Observatory 00023 //# 520 Edgemont Road 00024 //# Charlottesville, VA 22903-2475 USA 00025 //# 00026 //# 00027 //# $Id$ 00028 00029 #ifndef CASA_LOGORIGIN_H 00030 #define CASA_LOGORIGIN_H 00031 00032 #include <casacore/casa/aips.h> 00033 #include <casacore/casa/BasicSL/String.h> 00034 #include <casacore/casa/System/ObjectID.h> 00035 #include <casacore/casa/iosfwd.h> 00036 00037 namespace casacore { //# NAMESPACE CASACORE - BEGIN 00038 00039 struct SourceLocation; 00040 00041 // <summary> 00042 // LogOrigin: The source code location of the originator of a LogMessage. 00043 // </summary> 00044 00045 // <use visibility=export> 00046 00047 // <reviewed reviewer="wbrouw" date="1996/08/21" tests="tLogging.cc" demos="dLogging.cc"> 00048 // </reviewed> 00049 00050 // <prerequisite> 00051 // <li> <linkto class="ObjectID">ObjectID</linkto> if you are interested in 00052 // logging from Distributed Objects (don't worry if you don't know what 00053 // that means - in that case ignore it!). 00054 // </prerequisite> 00055 // 00056 // <etymology> 00057 // Log[message] Origin[ation point]. 00058 // </etymology> 00059 // 00060 // <synopsis> 00061 // The <src>LogOriging</src> class is used to record the location at which a 00062 // <linkto class="LogMessage">LogMessage</linkto> originates. It consists of: 00063 // <ul> 00064 // <li> A class name, which is blank in the case of a global function. 00065 // <li> A function name - global or member. You should "cut and paste" not only 00066 // the function name, but also the arguments (but not the return type) to 00067 // ensure that the function name is unique in the face of overloading. 00068 // <li> A source file name, usually filled in with the <src>WHERE</src> 00069 // predefined macro. 00070 // <li> A line number, usually filled in with the <src>__LINE__</src> or 00071 // <src>WHERE</src> macros. 00072 // <li> An <linkto class="ObjectID">ObjectID</linkto> if the log message comes 00073 // from a distributed object (if you don't know what this means, 00074 // you don't need to worry about it). 00075 // <li> Eventually we may want to canonicalize the path in the filename. 00076 // </ul> 00077 // </synopsis> 00078 // 00079 // <example> 00080 00081 // </example> 00082 // See the examples for <linkto class="LogMessage">LogMessage</linkto> and in 00083 // <linkto file="Logging.h">Logging.h</linkto>. 00084 // 00085 // <motivation> 00086 // It can be very useful for debugging if you know where a message is coming 00087 // from. 00088 // </motivation> 00089 // 00090 // <todo asof="1996/07/23"> 00091 // <li> Nothing known 00092 // </todo> 00093 00094 class LogOrigin 00095 { 00096 public: 00097 00098 // The default constructor sets a null class name, function name, object id, 00099 // source file name, and sets the line number to zero. 00100 LogOrigin(); 00101 00102 // Use this constructor if the log message origination is from a 00103 // global function. Normally <src>where</src> is provided using 00104 // the <src>WHERE</src> macro. 00105 LogOrigin(const String &globalFunctionName, const SourceLocation *where = 0); 00106 00107 // Use this constructor if the log message origination is from a 00108 // class member function. Normally <src>where</src> is provided using 00109 // the <src>WHERE</src> macro. 00110 LogOrigin(const String &className, const String &memberFuncName, 00111 const SourceLocation *where = 0); 00112 00113 // Use this constructor if the log message origination is from a 00114 // distributed object (don't worry if you don't know what this 00115 // means). Normally <src>where</src> is provided using the 00116 // <src>WHERE</src> macro. 00117 LogOrigin(const String &className, const String &memberFuncName, 00118 const ObjectID &id, const SourceLocation *where = 0); 00119 00120 // Make <src>this</src> LogOrigin a copy of <src>other</src>. 00121 // <group> 00122 LogOrigin(const LogOrigin &other); 00123 LogOrigin &operator=(const LogOrigin &other); 00124 // </group> 00125 00126 ~LogOrigin(); 00127 00128 // Get or set the corresponding element of the source location. Note that 00129 // the "set" functions can be strung together: 00130 // <srcBlock> 00131 // LogOrigin where; 00132 // ... 00133 // where.function("anotherFunc").line(__LINE__); 00134 // </srcBlock> 00135 // <group> 00136 const String &taskName() const; 00137 LogOrigin &taskName(const String &funcName); 00138 00139 const String &functionName() const; 00140 LogOrigin &functionName(const String &funcName); 00141 00142 const String &className() const; 00143 LogOrigin &className(const String &className); 00144 00145 const ObjectID &objectID() const; 00146 LogOrigin &objectID(const ObjectID &id); 00147 00148 uInt line() const; 00149 LogOrigin &line(uInt which); 00150 00151 const String &fileName() const; 00152 LogOrigin &fileName(const String &fileName); 00153 // </group> 00154 00155 // Set the file name and line number at the same time. Normally 00156 // <src>where</src> will be defined with the <src>WHERE</src> macro. 00157 LogOrigin &sourceLocation(const SourceLocation *where); 00158 00159 // Returns <src>class\::function</src> for a member function, or 00160 // <src>\::function</src> for a global function. 00161 String fullName() const; 00162 00163 // Turn the entire origin into a String. 00164 String toString() const; 00165 00166 // Turns the entire origin except for the ObjectID into a String. The 00167 // ObjectID can be turned into a string vie ObjectID::toString. 00168 String location() const; 00169 00170 // Return true if the line number and file name are not set. 00171 Bool isUnset() const; 00172 00173 private: 00174 String task_p; 00175 String function_p; 00176 String class_p; 00177 ObjectID id_p; 00178 uInt line_p; 00179 String file_p; 00180 String node_p; 00181 00182 // Return a String with the MPI rank 00183 String getNode(); 00184 00185 // Provide common implementation for copy constructor and 00186 // assignment operator. 00187 void copy_other(const LogOrigin &other); 00188 }; 00189 00190 // <summary> 00191 // Write a LogOrigin to an ostream. 00192 // </summary> 00193 // Write a LogOrigin as a string to an ostream. Merely calls 00194 // <src>LogOrigin::toString()</src> 00195 // <group name=LogOrigin_ostream> 00196 ostream &operator<<(ostream &os, const LogOrigin &origin); 00197 // </group> 00198 00199 // <summary> 00200 // Helper struct to get the source line. 00201 // </summary> 00202 // The user should only use the <src>WHERE</src> macro. 00203 // <group name=SourceLocation> 00204 struct SourceLocation 00205 { 00206 const char *fileName; 00207 Int lineNumber; 00208 static const SourceLocation *canonicalize(const char *file, Int line); 00209 }; 00210 00211 #define WHERE casacore::SourceLocation::canonicalize(__FILE__, __LINE__) 00212 00213 // </group> 00214 00215 00216 } //# NAMESPACE CASACORE - END 00217 00218 #endif