PlotLogger.h

Go to the documentation of this file.
00001 //# PlotLogger.h: Classes to perform various logging actions for the plotter.
00002 //# Copyright (C) 2009
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 //# $Id: $
00027 #ifndef PLOTLOGGER_H_
00028 #define PLOTLOGGER_H_
00029 
00030 #include <graphics/GenericPlotter/PlotOptions.h>
00031 
00032 #include <casa/Logging/LogSinkInterface.h>
00033 #include <casa/Utilities/CountedPtr.h>
00034 
00035 #include <map>
00036 #include <time.h>
00037 #include <vector>
00038 
00039 namespace casa {
00040 
00041 //# Forward declarations
00042 class PlotCanvas;
00043 class Plotter;
00044 
00045 
00046 // Superclass for all messages going through the PlotLogger.  This class has
00047 // been refactored to just be a thin layer on top of LogMessage.
00048 class PlotLogMessage : public LogMessage {
00049 public:
00050     // Static //
00051     
00052     // Default event type.
00053     static const int DEFAULT_EVENT_TYPE;
00054     
00055     
00056     // Non-Static //
00057     
00058     // Constructor which takes an optional priority.
00059     PlotLogMessage(int eventType = DEFAULT_EVENT_TYPE);
00060     
00061     // Constructor which takes the origin(s) and an optional priority.
00062     PlotLogMessage(const String& origin1, const String& origin2,
00063             int eventType = DEFAULT_EVENT_TYPE);
00064     
00065     // Constructor which takes the origin(s), the message, and an optional
00066     // priority.
00067     PlotLogMessage(const String& origin1, const String& origin2,
00068             const String& message, int eventType = DEFAULT_EVENT_TYPE);
00069     
00070     // Copy constructor.
00071     PlotLogMessage(const PlotLogMessage& copy);
00072     
00073     // Destructor.
00074     virtual ~PlotLogMessage();
00075     
00076     
00077     // Returns the event type of this message.
00078     virtual int eventType() const;
00079     
00080 protected:
00081     // Event type, either a value from PlotLogger::Event, or a custom
00082     // user-defined value.
00083     int m_eventType;
00084 };
00085 
00086 
00087 // Used to report time and memory measurements.  This functionality can be
00088 // accessed either directly with a PlotLogMeasurement object or indirectly
00089 // through the PlotLogger class.  Message is:
00090 // END.\tTime: [time] [timeUnits].  Memory: [memory] [memoryUnits].
00091 // If the measurement has not been ended, calls stopMeasurement() first.
00092 class PlotLogMeasurement : public PlotLogMessage {
00093 public:
00094     // Static //
00095     
00096     // Available time units.  Currently only seconds because that's all that
00097     // C++ natively supports.
00098     enum TimeUnit {
00099         SECOND
00100     };
00101     
00102     // Available memory units.
00103     enum MemoryUnit {
00104         BYTE, KILOBYTE, MEGABYTE
00105     };
00106     
00107     // Default units.
00108     // <group>
00109     static const TimeUnit DEFAULT_TIME_UNIT;
00110     static const MemoryUnit DEFAULT_MEMORY_UNIT;
00111     // </group>
00112     
00113     // Get a string representation of the given time/memory unit.
00114     // <group>
00115     static String timeUnits(TimeUnit t);   
00116     static String memoryUnits(MemoryUnit m);
00117     // </group>
00118     
00119     
00120     // Non-Static //
00121     
00122     // Constructor which takes the origin(s), optional time and memory
00123     // units, and an optional priority.  Also calls startMeasurement().
00124     PlotLogMeasurement(const String& origin1, const String& origin2,
00125                        TimeUnit timeUnit = DEFAULT_TIME_UNIT,
00126                        MemoryUnit memoryUnit = DEFAULT_MEMORY_UNIT,
00127                        int eventType = DEFAULT_EVENT_TYPE);
00128     
00129     // Copy constructor.
00130     PlotLogMeasurement(const PlotLogMeasurement& copy);
00131     
00132     // Destructor.
00133     ~PlotLogMeasurement();
00134     
00135     
00136     // Returns the time/memory when the measurement started.
00137     // <group>
00138     time_t startTime() const;
00139     unsigned int startMemory() const;
00140     // </group>
00141     
00142     // Returns the time/memory difference between when the measurement started
00143     // and when the measurement ended.  Invalid if the measurement was never
00144     // started and ended.
00145     // <group>
00146     double time() const;    
00147     double memory() const;
00148     // </group>
00149     
00150     // Returns the time/memory units for this measurement.
00151     // <group>
00152     TimeUnit timeUnit() const;
00153     MemoryUnit memoryUnit() const;
00154     // </group>
00155    
00156     // Starts the measurement by setting the start time and memory.
00157     // Measurement automatically begins when the object is constructed, but
00158     // can be restarted as desired.
00159     void startMeasurement();
00160     
00161     // Calculates the measurements from the last starting point to this point,
00162     // and generates the log message.
00163     void stopMeasurement();
00164     
00165 private:
00166     // Start time
00167     time_t m_startTime;
00168     
00169     // Start memory
00170     unsigned int m_startMemory;
00171     
00172     // Time and memory differences
00173     double m_time, m_memory;
00174     
00175     // Time unit
00176     TimeUnit m_timeUnit;
00177     
00178     // Memory unit
00179     MemoryUnit m_memoryUnit;
00180 };
00181 
00182 
00183 // Used to report located indices.  Basically just a container for the results
00184 // of a PlotCanvas::locate.
00185 class PlotLogLocate : public PlotLogMessage {
00186 public:
00187     // Static //
00188     
00189     // Convenience access to PlotCanvas::locate() to return a PlotLogLocate
00190     // message.
00191     static PlotLogLocate canvasLocate(PlotCanvas* canvas,
00192             const PlotRegion& region);
00193     
00194     
00195     // Non-Static //
00196     
00197     // Constructor which takes the two origins, the region that was located,
00198     // and the located indices (see PlotCanvas::locate()).  If
00199     // deleteIndicesOnDestruction is true, the given indices vector will be
00200     // deleted when this message is destroyed.  This should be used with care
00201     // if multiple PlotLogLocates using the same located indices are being
00202     // used.
00203     PlotLogLocate(const String& origin1, const String& origin2,
00204             const PlotRegion& locateRegion,
00205             std::vector<std::vector<std::pair<unsigned int,unsigned int> > >* locatedIndices,
00206             int eventType = DEFAULT_EVENT_TYPE,
00207             bool deleteIndicesOnDestruction = true);
00208     
00209     // Copy constructor.  NOTE: will set the deleteIndicesOnDestruction flag on
00210     // the original to false so that the indices won't be deleted from out
00211     // under the copy.
00212     PlotLogLocate(const PlotLogLocate& copy);
00213     
00214     // Destructor.
00215     ~PlotLogLocate();
00216     
00217     
00218     // Returns the region that was located.
00219     const PlotRegion& locateRegion() const;
00220     
00221     // Returns the total number of points that were located.
00222     unsigned int numLocatedIndices() const;
00223     
00224     // Returns the number of plots that were searched.
00225     unsigned int numSearchedPlots() const;
00226     
00227     // Returns the located indices.
00228     std::vector<std::vector<std::pair<unsigned int, unsigned int> > >* indices() const;
00229     
00230     // Returns the located indices for the plot at the given index, or NULL for
00231     // invalid.
00232     std::vector<std::pair<unsigned int, unsigned int> >* plotIndices(
00233             unsigned int index) const;
00234     
00235     // Returns whether or not this message will delete the indices vector on
00236     // destruction or not.
00237     bool willDeleteIndices() const;
00238     
00239 private:
00240     // Region.
00241     PlotRegion m_region;
00242     
00243     // Indices.
00244     std::vector<std::vector<std::pair<unsigned int, unsigned int> > >* m_indices;
00245     
00246     // Should delete indices.
00247     bool m_shouldDelete;
00248 };
00249 
00250 
00251 // Subclass of PlotLogMessage to unify messages for method entering/exiting.
00252 class PlotLogMethod : public PlotLogMessage {
00253 public:
00254     // Constructor which takes the class and method names, a flag for whether
00255     // the method is entering or exiting, and an optional additional message
00256     // and priority.
00257     PlotLogMethod(const String& className, const String& methodName,
00258             bool entering, const String& message = String(),
00259             int eventType = DEFAULT_EVENT_TYPE);
00260     
00261     // Destructor.
00262     ~PlotLogMethod();
00263 };
00264 
00265 
00266 // Subclass of PlotLogMessage to unify messages for object creation/deletion.
00267 class PlotLogObject : public PlotLogMessage {
00268 public:
00269     // Constructor which takes the class name and object address, a flag for
00270     // whether the object is being created or destroyed, and an optional
00271     // additional message and priority.
00272     PlotLogObject(const String& className, void* address, bool creation,
00273             const String& message = String(),
00274             int eventType = DEFAULT_EVENT_TYPE);
00275     
00276     // Destructor.
00277     ~PlotLogObject();
00278 };
00279 
00280 
00281 // Subclass of LogFilterInterface to filter on both event flags and minimum
00282 // priority.
00283 class PlotLoggerFilter : public LogFilterInterface {
00284 public:
00285     // Constructor which takes optional event flags and minimum priority.
00286     PlotLoggerFilter(int eventFlags, LogMessage::Priority minPriority);
00287     
00288     // Destructor.
00289     ~PlotLoggerFilter();
00290     
00291     // Implements LogFilterInterface::clone().
00292     LogFilterInterface* clone() const;
00293     
00294     // Implements LogFilterInterface::pass().
00295     Bool pass(const LogMessage& message) const;
00296     
00297     // Gets/Sets the event flags.
00298     // <group>
00299     int eventFlags() const;
00300     void setEventFlags(int flags);
00301     // </group>
00302     
00303     // Gets/Sets the minimum priority.
00304     // <group>
00305     LogMessage::Priority minimumPriority() const;
00306     void setMinimumPriority(LogMessage::Priority minPriority);
00307     // </group>
00308     
00309 private:
00310     // Event flags.
00311     int m_eventFlags;
00312     
00313     // Minimum priority.
00314     LogMessage::Priority m_minPriority;
00315 };
00316 
00317 
00318 // A PlotLogger is used to log messages to an underlying CASA log object, as
00319 // well as provide access to different logging functionality like measurements.
00320 // PlotLogger is associated with a single Plotter object and should be used by
00321 // all children of that Plotter (canvases, plot items, etc.) to report their
00322 // behavior if the proper flag is turned on.  The logger can also filter out
00323 // messages by priority.  Therefore a message must BOTH have its event type
00324 // flag turned on, AND meet the priority minimum in order to be posted to the
00325 // log.  The exception to this is for the MSG_* event types, which are logged
00326 // as long as they meet the filtered priority requirement.  The actual log can
00327 // either be the global sink, or can be set to a file.
00328 class PlotLogger {
00329 public:
00330     // Static //
00331     
00332     // Event types //
00333     
00334     // Event types that are always allowed.
00335     // <group>
00336     static const int MSG_INFO  = -1;
00337     static const int MSG_WARN  = -2;
00338     static const int MSG_ERROR = -3;
00339     // </group>
00340     
00341     // Miscellaneous debugging messages.
00342     static const int MSG_DEBUG       = 1;
00343     
00344     // Replotting/redrawing the whole GUI.
00345     static const int DRAW_TOTAL      = 2;
00346     
00347     // Replotting/redrawing each plot item.
00348     static const int DRAW_INDIVIDUAL = 4;
00349     
00350     // Entering/exiting major methods.
00351     static const int METHODS_MAJOR   = 8;
00352     
00353     // Creation/deletion of major objects.
00354     static const int OBJECTS_MAJOR   = 16;
00355     
00356     // Exporting canvases to file.
00357     static const int EXPORT_TOTAL    = 32;
00358     
00359     
00360     // No events.
00361     static const int NO_EVENTS = 0;
00362     
00363     // All events as a flag.
00364     static int ALL_EVENTS_FLAG();
00365     
00366     // All events as a vector.
00367     static std::vector<int> ALL_EVENTS();
00368     
00369     
00370     // Registers an extended event type with the given name and optional
00371     // priority and returns its value.
00372     static int REGISTER_EVENT_TYPE(const String& name,
00373             LogMessage::Priority priority = LogMessage::NORMAL);
00374     
00375     // Unregisters the given extended event type.  If a priority has been set,
00376     // it is NOT removed.
00377     // <group>
00378     static void UNREGISTER_EVENT_TYPE(int event);
00379     static void UNREGISTER_EVENT_TYPE(const String& name);
00380     // </group>
00381     
00382     // Returns all the event names.
00383     static std::vector<String> EVENT_NAMES();
00384     
00385     // Converts between an event type and its name.
00386     // <group>
00387     static String EVENT(int type);
00388     static int EVENT(const String& name);
00389     // </group>
00390     
00391     // Returns an event flag from the given vector.
00392     // <group>
00393     static int FLAG_FROM_EVENTS(const std::vector<int>& events);
00394     static int FLAG_FROM_EVENTS(const std::vector<String>& names);
00395     // </group>
00396     
00397     // Returns an event flag for all events that meet the given minimum
00398     // priority.
00399     static int FLAG_FROM_PRIORITY(LogMessage::Priority minPriority);
00400     
00401     
00402     // Gets/Sets the message priority for the given log event.  Uses a default
00403     // if the event has not been set.
00404     // <group>
00405     static LogMessage::Priority EVENT_PRIORITY(int event);
00406     static void SET_EVENT_PRIORITY(int event, LogMessage::Priority priority);
00407     // </group>
00408     
00409     
00410     // Disables the global sink until enableGlobalSink() is called.  Can be
00411     // used when something posts undesirably to both the local and global logs.
00412     static void disableGlobalSink();
00413     
00414     // Re-enables the global sink.  See disableGlobalSink().
00415     static void enableGlobalSink();
00416     
00417     
00418     // Non-Static //
00419     
00420     // Constructor which takes the Plotter this logger is associated with.  The
00421     // global log sink is used, and the minimum priority filter is set.
00422     PlotLogger(Plotter* plotter, int filterEventFlags = NO_EVENTS,
00423             LogMessage::Priority filterMinPriority = LogMessage::DEBUGGING);
00424     
00425     // Destructor.
00426     virtual ~PlotLogger();
00427     
00428     
00429     // Log IO Methods //
00430     
00431     // Gets the log sink interface.
00432     // <group>
00433     CountedPtr<LogSinkInterface> sink();
00434     const CountedPtr<LogSinkInterface> sink() const;
00435     // </group>
00436     
00437     // Gets a copy of the log sink interface, IF it is not the global.
00438     LogSinkInterface* localSinkCopy() const;
00439     
00440     // Gets/Sets the log sink file location.  If the filename is empty, it
00441     // means the global sink.
00442     // <group>
00443     const String& sinkLocation() const;
00444     void setSinkLocation(const String& logFile);
00445     // </group>
00446     
00447     // Returns true if the logger is currently using the global sink, false
00448     // otherwise.
00449     bool usingGlobalSink() const { return sinkLocation().empty(); }
00450     
00451     
00452     // Filtering Methods //
00453     
00454     // Gets/Sets the log filter priority level.
00455     // <group>
00456     LogMessage::Priority filterMinPriority() const;
00457     void setFilterMinPriority(PlotLogMessage::Priority minPriority);
00458     // </group>
00459     
00460     // Gets/Sets the log filter event flag for a single event type.
00461     // <group>
00462     bool filterEventFlag(int flag) const;
00463     void setFilterEventFlag(int flag, bool on);
00464     // </group>
00465     
00466     // Gets/Sets the log filter event flag(s).  The flag should be a bitwise-or
00467     // of one or more values in PlotLogger events and any extended event types.
00468     // <group>
00469     int filterEventFlags() const;
00470     void setFilterEventFlags(int flags);
00471     // <group>
00472     
00473     
00474     // Message Methods //
00475     
00476     // Posts the given message to the underlying log sink.
00477     // <group>
00478     void postMessage(const PlotLogMessage& message);
00479     void postMessage(const String& origin1, const String& origin2,
00480                      const String& message,
00481                      int eventType = PlotLogMessage::DEFAULT_EVENT_TYPE);
00482     // </group>
00483     
00484     
00485     // Measurement Methods //
00486     
00487     // Marks the logger to begin a time/memory measurement.  Measurement marks
00488     // can be recursive.  Returns a generic message saying that measurement has
00489     // begun, which will be also posted to the log if postStartMessage is true.
00490     PlotLogMessage markMeasurement(const String& origin1,const String& origin2,
00491             int eventType = PlotLogMessage::DEFAULT_EVENT_TYPE,
00492             bool postStartMessage = true);
00493     
00494     // Gets the measurement since the last mark.  The message will also be
00495     // posted to the log if postReleaseMessage is true.
00496     PlotLogMeasurement releaseMeasurement(bool postReleaseMessage = true);
00497     
00498     
00499     // Locate Methods //
00500     
00501     // Calls locate on the given canvas and returns the result as a message
00502     // that will also be posted if postLocateMessage is true.
00503     PlotLogLocate locate(PlotCanvas* canvas, const PlotRegion& region,
00504             int eventType = MSG_INFO, bool postLocateMessage = true);
00505     
00506 private:
00507     // Plotter.
00508     Plotter* m_plotter;
00509     
00510     // Log sink.
00511     CountedPtr<LogSinkInterface> m_logger;
00512     
00513     // Log filter.
00514     PlotLoggerFilter m_filter;
00515     
00516     // Log sink location.
00517     String m_loggerLocation;
00518     
00519     // Current measurement marks.
00520     std::vector<PlotLogMeasurement> m_measurements;
00521 
00522     
00523     // Static //
00524     
00525     // Registered extended types.
00526     static std::vector<int> EXTENDED_TYPES;
00527     
00528     // Registered extended type names.
00529     static std::vector<String> EXTENDED_NAMES;
00530     
00531     // Map from log event to priority.
00532     static std::map<int, LogMessage::Priority> EVENT_PRIORITIES;
00533     
00534     // Disabled old global filter, or null.
00535     static LogFilterInterface* DISABLED_GLOBAL_FILTER;
00536 };
00537 typedef CountedPtr<PlotLogger> PlotLoggerPtr;
00538 
00539 }
00540 
00541 #endif /* PLOTLOGGER_H_ */
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1