LogOrigin.h

Go to the documentation of this file.
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
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1