From 36bccc570006216a144e2b15e898f2a65a1e7814 Mon Sep 17 00:00:00 2001 From: w00t Date: Sun, 17 Feb 2008 14:37:34 +0000 Subject: Add some docs git-svn-id: http://svn.inspircd.org/repository/trunk/inspircd@8958 e03df62e-2008-0410-955e-edbf42e46eb7 --- include/logger.h | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 65 insertions(+), 6 deletions(-) (limited to 'include') diff --git a/include/logger.h b/include/logger.h index 121d9ff25..754fa26e8 100644 --- a/include/logger.h +++ b/include/logger.h @@ -32,23 +32,29 @@ class CoreExport FileWriter : public EventHandler /** The creator/owner of this object */ InspIRCd* ServerInstance; + /** The log file (fd is inside this somewhere, * we get it out with fileno()) */ FILE* log; + /** Buffer of pending log lines to be written */ std::string buffer; + /** Number of write operations that have occured */ int writeops; + public: /** The constructor takes an already opened logfile. */ FileWriter(InspIRCd* Instance, FILE* logfile); + /** This returns false, logfiles are writeable. */ virtual bool Readable(); + /** Handle pending write events. * This will flush any waiting data to disk. * If any data remains after the fprintf call, @@ -56,6 +62,7 @@ class CoreExport FileWriter : public EventHandler * the rest of the data when possible. */ virtual void HandleEvent(EventType et, int errornum = 0); + /** Write one or more preformatted log lines. * If the data cannot be written immediately, * this class will insert itself into the @@ -64,15 +71,37 @@ class CoreExport FileWriter : public EventHandler * attempt again to write the data. */ void WriteLogLine(const std::string &line); + /** Close the log file and cancel any events. */ virtual void Close(); + /** Close the log file and cancel any events. * (indirectly call Close() */ virtual ~FileWriter(); }; + + +/* + * New world logging! + * The brief summary: + * Logging used to be a simple affair, a FILE * handled by a nonblocking logging class inheriting from EventHandler, that was inserted + * into the socket engine, and wrote lines. If nofork was on, it was printf()'d. + * + * We decided to horribly overcomplicate matters, and create vastly customisable logging. LogManager and LogStream form the visible basis + * of the new interface. Basically, a LogStream can be inherited to do different things with logging output. We inherit from it once in core + * to create a FileLogStream, that writes to a file, for example. Different LogStreams can hook different types of log messages, and different + * levels of output too, for extreme customisation. Multiple LogStreams can hook the same message/levels of output, meaning that e.g. output + * can go to a channel as well as a file. + * + * HOW THIS WORKS + * LogManager handles all instances of LogStreams, LogStreams (or more likely, derived classes) are instantiated and passed to it. + */ + +/** LogStream base class. Modules (and other stuff) inherit from this to decide what logging they are interested in, and what to do with it. + */ class CoreExport LogStream : public classbase { protected: @@ -86,8 +115,15 @@ class CoreExport LogStream : public classbase virtual ~LogStream() { } - void ChangeLevel(int lvl) { this->loglvl = lvl; } // For on-the-fly change of loglevel. + /** XXX document me properly. + * Used for on the fly changing of loglevel. + */ + void ChangeLevel(int lvl) { this->loglvl = lvl; } + /** Called when there is stuff to log for this particular logstream. The derived class may take no action with it, or do what it + * wants with the output, basically. loglevel and type are primarily for informational purposes (the level and type of the event triggered) + * and msg is, of course, the actual message to log. + */ virtual void OnLog(int loglevel, const std::string &type, const std::string &msg) = 0; }; @@ -96,13 +132,13 @@ typedef std::map FileLogMap; class CoreExport LogManager : public classbase { private: - bool Logging; // true when logging, avoids recursion - LogStream* noforkstream; // LogStream for nofork. + bool Logging; // true when logging, avoids recursion + LogStream* noforkstream; // LogStream for nofork. InspIRCd *ServerInstance; std::map > LogStreams; - std::map AllLogStreams; // holds all logstreams - std::vector GlobalLogStreams; //holds all logstreams with a type of * - FileLogMap FileLogs; /* Holds all file logs, refcounted */ + std::map AllLogStreams; // holds all logstreams + std::vector GlobalLogStreams; //holds all logstreams with a type of * + FileLogMap FileLogs; // Holds all file logs, refcounted public: LogManager(InspIRCd *Instance) { @@ -112,6 +148,7 @@ class CoreExport LogManager : public classbase void SetupNoFork(); + /** XXX document me properly. */ void AddLoggerRef(FileWriter* fw) { FileLogMap::iterator i = FileLogs.find(fw); @@ -125,6 +162,7 @@ class CoreExport LogManager : public classbase } } + /** XXX document me properly. */ void DelLoggerRef(FileWriter* fw) { FileLogMap::iterator i = FileLogs.find(fw); @@ -136,13 +174,34 @@ class CoreExport LogManager : public classbase } } + /** XXX document me properly. */ void OpenSingleFile(FILE* f, const std::string& type, int loglevel); + + /** XXX document me properly. */ void OpenFileLogs(); + + /** Gives all logstreams a chance to clear up (in destructors) while it deletes them. + */ void CloseLogs(); + + /** Registers a new logstream into the logging core, so it can be called for future events + * XXX document me properly. + */ bool AddLogType(const std::string &type, LogStream *l, bool autoclose); + + /** Removes a logstream from the core. After removal, it will not recieve further events. + */ void DelLogStream(LogStream* l); + + /** XXX document me properly. */ bool DelLogType(const std::string &type, LogStream *l); + + /** Pretty self explanatory. + */ void Log(const std::string &type, int loglevel, const std::string &msg); + + /** Duh. + */ void Log(const std::string &type, int loglevel, const char *fmt, ...); }; -- cgit v1.2.3