Main Page Class Hierarchy Alphabetical List Compound List File List Compound Members

FXBinaryLogger.h

Go to the documentation of this file.
00001 /********************************************************************************
00002 *                                                                               *
00003 *                  Binary log file object                                       *
00004 *                                                                               *
00005 *********************************************************************************
00006 * Copyright (C) 2003 by Mathew Robertson.   All Rights Reserved.                *
00007 *********************************************************************************
00008 * This library is free software; you can redistribute it and/or                 *
00009 * modify it under the terms of the GNU Lesser General Public                    *
00010 * License as published by the Free Software Foundation; either                  *
00011 * version 2.1 of the License, or (at your option) any later version.            *
00012 *                                                                               *
00013 * This library is distributed in the hope that it will be useful,               *
00014 * but WITHOUT ANY WARRANTY; without even the implied warranty of                *
00015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU             *
00016 * Lesser General Public License for more details.                               *
00017 *                                                                               *
00018 * You should have received a copy of the GNU Lesser General Public              *
00019 * License along with this library; if not, write to the Free Software           *
00020 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA.    *
00021 *********************************************************************************/
00022 #ifndef FXBINARYLOGGER_H
00023 #define FXBINARYLOGGER_H
00024 
00025 namespace FXEX {
00026 
00027 // A simple set of defines used to simplify the binary logging syntax
00028 // Note that the idea of using a binary logger precludes the 'disabling' of the logger as
00029 // a compile time option.  The reasoning is that, this form of logging is often used where
00030 // you have a long 
00031 #define BINDBG(value)        FXBinaryLogger::instance().debug  (value)
00032 #define BINLOG(value)        FXBinaryLogger::instance().log    (value)
00033 #define BINWRN(value)        FXBinaryLogger::instance().warning(value)
00034 #define BINERR(value)        FXBinaryLogger::instance().error  (value)
00035 #define BINSTATUS(arg1,arg2) FXBinaryLogger::instance().status (arg1,arg2)
00036 #define BINUNKNOWN()         FXBinaryLogger::instance().unknown()
00037 
00038 /// Binary logger options
00039 enum {
00040   BINARYLOGGER_SUBSECOND=0x01   /// log entries contain subsecond resolution
00041   };
00042 
00043 /**
00044  * A binary log file allows applications to log entries to a file, faster and more compact
00045  * than a normal log file.
00046  *
00047  * How this differs from a normal log file is that, up to 1000% of the speed of a log file
00048  * is consumed in the printf style parsing of the input string.  By using numbers only,
00049  * no parsing is necessary.  As an added bonus, you dont log many bytes per log entry so
00050  * the disk I/O time is reduced.
00051  *
00052  * The upshot is that a binary logger can run many times quicker than a text file logger,
00053  * and that the storage of that information is more compact.  The downside is that you need
00054  * a custom program to read the file (see FXBinaryLogReader).
00055  *
00056  * File format:
00057  * - file header (2 bytes)
00058  *   - 1 byte version code
00059  *   - 1 byte options value
00060  * - written per log entry (8-12 bytes)
00061  *   - 32bit date stamp
00062  *     - 1 second resolution
00063  *   - 32bit subsecond date stamp
00064  *     - microsecond resolution
00065  *     - optional
00066  *   - 32bit log entry
00067  *     - upper 16bits are used for indicating error severity
00068  *     - lower 16bits are used for indicating enumerated value
00069  *
00070  * Notes:
00071  * 1. The log file stores the endian-ness of the CPU architecture so that the log file
00072  *    can later be read back on any type of CPU.
00073  * 2. Log entries are automatically written on file open/close (as debug entries)
00074  *
00075  * It is envisaged that you could use this logger in an embedded application.  You would
00076  * log the values you need, when you identify a condition that needs to be logged.  You 
00077  * should create a specific enumerated value, for all possible log cases.
00078  */
00079 
00080 class FXAPI FXBinaryLogger {
00081 private:
00082   static FXBinaryLogger* thisLog;   // self reference indicator
00083   FXFileIO              *fileio;    // file IO object
00084   FXlong                 filesize;  // max size of file
00085   FXuchar                options;
00086 
00087 protected:
00088   /// opens the log file for writing
00089   FXbool open();
00090 
00091   /// closes the log file
00092   void close();
00093 
00094   /**
00095    * Ensures that the log file is no bigger than size
00096    * Returns state whether the log file is open
00097    */
00098   FXbool trim();
00099 
00100 public:
00101   enum {
00102     CODE_NORMAL =0x0000,  // normal log code
00103     CODE_WARNING=0x0001,  // warning log code
00104     CODE_ERROR  =0x0002,  // error log code
00105     CODE_DEBUG  =0x0003   // debug log code
00106     };
00107 
00108   enum {
00109     LOG_STARTED =0x7FFF,  // log started
00110     LOG_ENDED   =0x7FFE,  // log ended
00111     LOG_UNKNOWN =0x7FFD   // log entry unknown
00112     };
00113 
00114 public:
00115   /// Give me a log file
00116   FXBinaryLogger(const FXString& file="",FXlong size=100000,FXuint opts=0);
00117 
00118   /// Use the current instance
00119   static FXBinaryLogger& instance();
00120 
00121   /// Set the size of the log file - checked on next log entry
00122   void size(const FXlong size);
00123 
00124   /// Get the size of the log file
00125   FXlong size() { return filesize; }
00126 
00127   /// Change the location of the log file - change is immediate
00128   FXbool name(const FXString& file);
00129 
00130   /// get the current filename
00131   FXString name();
00132 
00133   /// indicates whether the log file can/will be written to
00134   FXbool opened();
00135 
00136   /// log a numeric entry
00137   void log(FXshort code,FXshort val);
00138 
00139   /// log numeric entries based on generic code
00140   void log(FXshort val);
00141   void warning(FXshort val);
00142   void error(FXshort val);
00143   void debug(FXshort val);
00144 
00145   /// log an error, using the 'unknown' value
00146   void unknown();
00147 
00148   /// Save to stream
00149   friend FXAPI FXStream& operator<<(FXStream& store,const FXBinaryLogger& b);
00150 
00151   /// load from stream
00152   friend FXAPI FXStream& operator>>(FXStream& store,FXBinaryLogger& b);
00153 
00154   /// done
00155   virtual ~FXBinaryLogger();
00156   };
00157 
00158 } // namespace FXEX
00159 #endif // FXBINARYLOGGER_H