LoggerHolder.h

Go to the documentation of this file.

// # LoggerHolder.h: Class holding a hierarchy of loggers
// # Copyright (C) 2001,2003
// # Associated Universities, Inc. Washington DC, USA.
// #
// # This library is free software; you can redistribute it and/or modify it
// # under the terms of the GNU Library General Public License as published by
// # the Free Software Foundation; either version 2 of the License, or (at your
// # option) any later version.
// #
// # This library is distributed in the hope that it will be useful, but WITHOUT
// # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
// # FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
// # License for more details.
// #
// # You should have received a copy of the GNU Library General Public License
// # along with this library; if not, write to the Free Software Foundation,
// # Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
// #
// # Correspondence concerning AIPS++ should be addressed as follows:
// #        Internet email: casa-feedback@nrao.edu.
// #        Postal address: AIPS++ Project Office
// #                        National Radio Astronomy Observatory
// #                        520 Edgemont Road
// #                        Charlottesville, VA 22903-2475 USA
 
#ifndef TABLES_LOGGERHOLDER_H
#define TABLES_LOGGERHOLDER_H
 
// # Includes
#include <casacore/casa/aips.h>
#include <casacore/casa/Logging/LogIO.h>
#include <casacore/casa/Containers/Block.h>
#include <memory>
 
namespace casacore {  // # NAMESPACE CASACORE - BEGIN
 
// # Forward Declarations
class LoggerHolderRep;
class LoggerHolderIterator;
class TableLogSink;
 
// <summary>
// Class holding a hierarchy of loggers.
// </summary>
 
// <use visibility=export>
 
// <reviewed reviewer="" date="" tests="tLoggerHolder.cc" demos="">
// </reviewed>
 
// <prerequisite>
//  <li> <linkto class="LogIO">LogIO</linkto> <li>
// </prerequisite>
 
// <synopsis>
// The LoggerHolder class implements a hierarchy of loggers.
// It has a log sink of its own and can have multiple parent LoggerHolder
// objects representing the log info of parent objects.
// It is used by class
// <linkto class=ImageInterface>ImageInterface</linkto>, but could also
// be used elsewhere.
//
// The sink of a LoggerHolder can be different depending on the type of image.
// E.g. for a transient image it can be a
// <linkto class=MemoryLogSink>MemoryLogSink</linkto>, while for a persistent
// image it will be a <linkto class=TableLogSink>TableLogSink</linkto>.
// <br>An important feature is that an LoggerHolder can have zero or more
// parent LoggerHolder objects. In that way the log of the parent object
// of an image object can be made part of the log of the image object itself,
// without having to copy the log.
//
// To iterate through all messages in a LoggerHolder (including all parents),
// the <linkto class=LoggerHolderIterator>LoggerHolderIterator</linkto> can
// be used. This is an STL-style const_iterator object.
//
// LoggerHolder uses reference counting
// (of class <linkto class=LoggerHolderRep>LoggerHolderRep</linkto>)
// to be able to retain
// the object after the (ImageInterface) object containing it is gone.
// Otherwise classes like SubImage would lose their log info.
// </synopsis>
 
// <example>
// <srcblock>
//  LoggerHolder logger ("tLoggerHolder_tmp.log", True);
//  logger.logio() << "test1" << LogIO::POST;
//  logger.logio() << "test2" << LogIO::POST;
//  for (LoggerHolder::const_iterator iter = logger.begin();
//       iter != logger.end();
//       iter++) {
//    cout << iter->time() << ' ' << iter->message() << endl;
//  }
// </srcblock>
// This example shows the construction of an LoggerHolder with a
// TableLogSink sink. Thereafter some messages are written.
// The latter part shows how to iterate through all messages.
//
// <srcblock>
//  LoggerHolder logger (False);
//  logger.addParent (parent.logger());
//  logger.logio() << "test1" << LogIO::POST;
//  logger.logio() << "test2" << LogIO::POST;
// </srcblock>
// This example shows the construction of an LoggerHolder with a
// MemoryLogSink sink (e.g. for a SubImage). Thereafter the logger of
// the parent image is added to it.
// Finally some messages are written.
// </example>
 
// <motivation>
// This class simplifies and unifies all Image logging activities.
// </motivation>
 
// # <todo asof="2001/06/14">
// # </todo>
 
class LoggerHolder {
 public:
  // Create with a NullSink or MemoryLogSink (default).
  explicit LoggerHolder(Bool nullSink = False);
 
  // Create with a TableLogSink.
  LoggerHolder(const String& logTableName, Bool isWritable);
 
  // Copy constructor (reference semantics).
  LoggerHolder(const LoggerHolder&);
 
  ~LoggerHolder();
 
  // Assignment (reference semantics).
  LoggerHolder& operator=(const LoggerHolder&);
 
  // Add a logger from a parent.
  void addParent(const LoggerHolder&);
 
  // Append the entries of the other logger to this one.
  void append(const LoggerHolder& other);
 
  // Reopen a readonly logtable for read/write (if needed).
  void reopenRW();
 
  // Reopen the log table if needed (after a tempClose).
  void reopen();
 
  // Temporarily close all log tables.
  // By default the possible parent log tables are also closed.
  void tempClose(Bool closeParents = True) const;
 
  // Unlock the log table.
  void unlock();
 
  // Flush the log table.
  void flush();
 
  // Resync the log table (if needed).
  void resync();
 
  // Is the log table temporarily closed?
  Bool isTempClosed() const;
 
  // Get access to the logger.
  // It assumes that it will be used to post a message, so it reopens
  // the log table for read/write if needed).
  LogIO& logio();
 
  // Get access to the log sink (reopen the log table if needed).
  // It is not assumed you want to write. If you want to do that,
  // you should first call reopenRW() to ensure you can write.
  // <group>
  LogSink& sink();
  const LogSink& sink() const;
  // </group>
 
  // Clear the log.
  // It removes the parents and removes all messages from the sink.
  void clear();
 
  // Remove all parents.
  void removeParents();
 
  // Return the block of parents.
  const Block<LoggerHolder>& parents() const;
 
  // Define the STL-style iterators.
  // Only a const forward iterator is available.
  // It makes it possible to iterate through all messages in the logger.
  // <srcblock>
  //  LoggerHolder logger("log.name", False)
  //  for (LoggerHolder::const_iterator iter=arr.begin();
  //       iter!=arr.end(); iter++) {
  //    cout << iter.message() << endl;
  //  }
  // </srcblock>
  // <group name=STL-iterator>
  // STL-style typedefs.
  typedef LoggerHolderIterator const_iterator;
  // Get the begin and end iterator object.
  const_iterator begin() const;
  const_iterator end() const;
  // </group>
 
 private:
  std::shared_ptr<LoggerHolderRep> itsRep;
};
 
// <summary>
// Representation of the class holding a hierarchy of loggers.
// </summary>
 
// <use visibility=local>
 
// <reviewed reviewer="" date="" tests="tLoggerHolder.cc" demos="">
// </reviewed>
 
// <prerequisite>
//  <li> <linkto class="LogIO">LogIO</linkto> <li>
// </prerequisite>
 
// <synopsis>
// The LoggerHolderRep class is the reference counted implementation
// of <linkto class=LoggerHolder>LoggerHolder</linkto>.
// See that class for more information.
// </synopsis>
 
// <motivation>
// Reference counting was needed to be able to keep a LoggerHolder
// object after the (ImageInterface) object containing it is gone.
// </motivation>
 
// # <todo asof="2001/06/14">
// # </todo>
 
class LoggerHolderRep {
 public:
  // Create with a NullSink or MemoryLogSink (default).
  LoggerHolderRep(Bool nullSink);
 
  // Create with a TableLogSink.
  LoggerHolderRep(const String& logTableName, Bool isWritable);
 
  // Copy constructor.
  LoggerHolderRep(const LoggerHolderRep&);
 
  ~LoggerHolderRep();
 
  // Assignment.
  // It removes the current parents.
  LoggerHolderRep& operator=(const LoggerHolderRep&);
 
  // Add a logger from a parent.
  void addParent(const LoggerHolder&);
 
  // Append the entries of the other logger to this one.
  void append(const LoggerHolder& other);
 
  // Reopen a readonly logtable for read/write (if needed).
  void reopenRW();
 
  // Reopen the log table if needed (after a tempClose).
  void reopen() {
    if (itsIsClosed) doReopen();
  }
 
  // Temporarily close all log tables.
  // By default the possible parent log tables are also closed.
  void tempClose(Bool closeParents = True);
 
  // Unlock the log table.
  void unlock();
 
  // Flush the log table.
  void flush();
 
  // Resync the log table (if needed).
  void resync();
 
  // Is the log table temporarily closed?
  Bool isTempClosed() const { return itsIsClosed; }
 
  // Get access to the logger.
  // It assumes that it will be used to post a message, so it reopens
  // the log table for read/write if needed).
  LogIO& logio();
 
  // Get access to the log sink (reopen the log table if needed).
  // It is not assumed you want to write. If you want to do that,
  // you should first call reopenRW() to ensure you can write.
  LogSink& sink();
 
  // Clear the log.
  // It removes the parents and removes all messages from the sink.
  void clear();
 
  // Remove all parents.
  void removeParents();
 
  // Return the block of parents.
  const Block<LoggerHolder>& parents() const { return itsParents; }
 
  // Define the STL-style iterators.
  // Only a const forward iterator is available.
  // It makes it possible to iterate through all messages in the logger.
  // <srcblock>
  //  LoggerHolder logger("log.name", False)
  //  for (LoggerHolder::const_iterator iter=arr.begin();
  //       iter!=arr.end(); iter++) {
  //    cout << iter.message() << endl;
  //  }
  // </srcblock>
  // <group name=STL-iterator-rep>
  // STL-style typedefs.
  typedef LoggerHolderIterator const_iterator;
  // Get the begin and end iterator object.
  const_iterator begin() const;
  const_iterator end() const;
  // </group>
 
 private:
  // Do the actual reopen.
  void doReopen();
 
  Block<LoggerHolder> itsParents;
  LogSink itsSink;
  LogIO itsLogger;
  String itsTableName;
  TableLogSink* itsTablePtr;
  Bool itsIsWritable;
  Bool itsIsClosed;
};
 
// <summary>
// Class representing an entry in a LoggerHolder.
// </summary>
 
// <use visibility=local>
 
// <reviewed reviewer="" date="" tests="tLoggerHolder.cc" demos="">
// </reviewed>
 
// <prerequisite>
//  <li> <linkto class="LoggerHolder">LoggerHolder</linkto> <li>
// </prerequisite>
 
// <synopsis>
// This class makes it possible to use the iterator in the STL-style.
// It only contains a 'pointer' to the current entry in the current logger.
// Function like <src>time()</src> can be used to retrieve the message parts.
// </synopsis>
 
class LogHolderIterEntry {
 public:
  LogHolderIterEntry() : itsSink(0), itsIndex(0) {}
 
  LogHolderIterEntry(const LogSink* sink, uInt index) : itsSink(sink), itsIndex(index) {}
 
  LogHolderIterEntry(const LogHolderIterEntry& that)
      : itsSink(that.itsSink), itsIndex(that.itsIndex) {}
 
  ~LogHolderIterEntry() {}
 
  LogHolderIterEntry& operator=(const LogHolderIterEntry& that) {
    itsSink = that.itsSink;
    itsIndex = that.itsIndex;
    return *this;
  }
 
  // Get the message parts.
  // <group>
  Double time() const { return itsSink->getTime(itsIndex); }
  String message() const { return itsSink->getMessage(itsIndex); }
  String priority() const { return itsSink->getPriority(itsIndex); }
  String location() const { return itsSink->getLocation(itsIndex); }
  String objectID() const { return itsSink->getObjectID(itsIndex); }
  // </group>
 
 private:
  const LogSink* itsSink;
  uInt itsIndex;
};
 
// <summary>
// Class doing the actual iteration through an LoggerHolder.
// </summary>
 
// <use visibility=local>
 
// <reviewed reviewer="" date="" tests="tLoggerHolder.cc" demos="">
// </reviewed>
 
// <prerequisite>
//  <li> <linkto class="LoggerHolder">LoggerHolder</linkto> <li>
// </prerequisite>
 
// <synopsis>
// This class makes it possible to use the iterator in the STL-style.
// It is used by
//<linkto class=LoggerHolderIterator>LoggerHolderIterator</linkto>
// which is the class as seen by the user.
// LogHolderIter makes it easier to make the first entry available on
// construction of an LoggerHolderIterator.
// </synopsis>
 
class LogHolderIter {
 public:
  // Construct the iterator on the given LoggerHolderRep.
  LogHolderIter(const LoggerHolder*);
 
  ~LogHolderIter();
 
  // Copy constructor is not needed, thus forbidden.
  LogHolderIter(const LogHolderIter&) = delete;
 
  // Assignment is not needed, thus forbidden.
  LogHolderIter& operator=(const LogHolderIter&) = delete;
 
  // Increment to next message.
  // Returns False if at the end.
  Bool next();
 
  // Get the entry.
  const LogHolderIterEntry& getEntry() const { return itsEntry; }
 
  const LoggerHolder& logger() const { return *itsLogger; }
 
 private:
  const LoggerHolder* itsLogger;
  Bool itsTempClosed;
  LogHolderIter* itsParentIter;
  uInt itsCounter;
  LogHolderIterEntry itsEntry;
};
 
// <summary>
// Class to iterate through an LoggerHolder.
// </summary>
 
// <use visibility=export>
 
// <reviewed reviewer="" date="" tests="tLoggerHolder.cc" demos="">
// </reviewed>
 
// <prerequisite>
//  <li> <linkto class="LoggerHolder">LoggerHolder</linkto> <li>
// </prerequisite>
 
// <synopsis>
// This class makes it possible to iterate in the STL-style through all
// entries of an LoggerHolder object. If the logger has parent LoggerHolder
// objects, it first iterates through all parents (recursively) and
// finally through all entries in the LoggerHolder object itself.
// </synopsis>
 
// <example>
// <srcblock>
//  LoggerHolder logger ("tLoggerHolder_tmp.log", True);
//  logger.logio() << "test1" << LogIO::POST;
//  logger.logio() << "test2" << LogIO::POST;
//  for (LoggerHolder::const_iterator iter = logger.begin();
//       iter != logger.end();
//       iter++) {
//    cout << iter->time() << ' ' << iter->message() << endl;
//  }
// </srcblock>
// </example>
 
class LoggerHolderIterator {
 public:
  LoggerHolderIterator() : itsIter(0), itsNotAtEnd(False) {}
 
  LoggerHolderIterator(const LoggerHolder*);
 
  LoggerHolderIterator(const LoggerHolderIterator&);
 
  ~LoggerHolderIterator() { delete itsIter; }
 
  LoggerHolderIterator& operator=(const LoggerHolderIterator&);
 
  // Increment to next message.
  // <group>
  void operator++() { next(); }
  void operator++(int) { next(); }
  // </group>
 
  // Is the iterator not at the end yet?
  Bool operator!=(const LoggerHolderIterator&) { return itsNotAtEnd; }
 
  // Get the entry.
  // <group>
  const LogHolderIterEntry& operator*() const { return itsIter->getEntry(); }
  const LogHolderIterEntry* operator->() const { return &(itsIter->getEntry()); }
  // </group>
 
  const LoggerHolder& logger() const { return itsIter->logger(); }
 
 private:
  // Get the next entry (if available).
  void next() { itsNotAtEnd = itsIter->next(); }
 
  LogHolderIter* itsIter;
  Bool itsNotAtEnd;
};
 
inline void LoggerHolder::reopen() { itsRep->reopen(); }
inline Bool LoggerHolder::isTempClosed() const { return itsRep->isTempClosed(); }
inline LogIO& LoggerHolder::logio() { return itsRep->logio(); }
inline LogSink& LoggerHolder::sink() { return itsRep->sink(); }
inline const LogSink& LoggerHolder::sink() const { return itsRep->sink(); }
inline const Block<LoggerHolder>& LoggerHolder::parents() const { return itsRep->parents(); }
inline LoggerHolder::const_iterator LoggerHolder::begin() const {
  return LoggerHolderIterator(this);
}
inline LoggerHolder::const_iterator LoggerHolder::end() const { return LoggerHolderIterator(); }
 
}  // namespace casacore
 
#endif