pantheios - README
==================

Updated:    7th August 2012



See the introduction in the accompanying doc/html/1.0.1-beta214/index.html
file.

Please feel free to request, nay demand, improvements in any areas
that you feel are deficient. We believe that Pantheios is the best
diagnostic logging API ever created, but we are not so deluded as to think
that our presentational skills are as good. Criticism will be gratefully
received.

If you are interested in commercial services and/or training for
Pantheios, contact Synesis Software, via http://synesis.com.au/contact.html

Information about Pantheios training is available at
http://synesis.com.au/training.html


10 important things to know about Pantheios:
--------------------------------------------

1. It's a diagnostic logging **API** library, not a diagnostic logging
   library

2. It's open-source, and 100% free

3. It depends on several other libraries, but they're also open source and
   100% free

4. It's incredibly efficient, and is faster than all other serious C++
   diagnostic logging libraries by a huge margin (up to two orders of
   magnitude)

5. It is 100% type-safe

6. Selection of logging transport (i.e. "back-end(s)") is done at link-time,
   for very good reason

7. It's highly extensible

8. It's being used by serious commercial enterprises, including very high
   throughput financial systems

9. It's highly portable - including most C++ compilers and most/all flavours
   of UNIX, Linux, Mac OS-X and Windows

10. Pantheios is under active development from a highly motivated team, who
   have the ambition that it will become the diagnostic logging API of
   choice for all C++ programmers who wish to have performance without
   sacrificing robustness or flexibility; the team want to hear from you how
   they can better achieve these aims


Details:
- - - -

1. It's a diagnostic logging **API** library, not a diagnostic logging
   library

   The Pantheios architecture is split into four parts:
    - Application Layer - you use this to create diagnostic logging
	   statements in your application code
    - Core - this is what ties it all together. Apart from initialising the
       core (which happens automatically in C++ compilation units), you
       don't need to do anything with the core
    - Front-end - this is what decides which statements are written out, as
       well as providing the application identity (name) to the Core during
       initialisation. There are several stock Front-ends included in the
       Pantheios distribution, but you may well implement your own
    - Back-end - this is what emits the logging statement (if the front-end
       allows it to be written) to the outside world. There are a number of
       stock Back-ends included in the Pantheios distribution, but you may
       well implement your own

   One criticism that we sometimes get from new users goes along the lines
   of

     " the performance is brilliant, but you don't have all the features of
      log4cxx "

   We know. It's designed to be that way.

   Pantheios is a diagnostic logging API library. The interaction between
   Application Layer, Core and Front-end means that nothing else can come
   anywhere near Pantheios in terms of performance, type-safety or
   extensibility. But it's specifically designed for you to use it _above_
   existing logging libraries that have more features. To do so, you can
   write a simple back-end to wrap, say, log4cxx, and plug it in at
   link-time. That way you get all the performance and safety of Pantheios,
   with the rich feature set of log4cxx. It's win-win!


2. It's open-source, and 100% free

   It uses the widely appreciated (modified-)BSD license.


3. It depends on several other libraries, but they're also open source and
   100% free

   Apart from one library - STLSoft - all the libraries on which Pantheios
   depends are bundled with the Pantheios distribution. These libraries are:

    - xTests  (see http://xtests.org/)
      
      A simple, lightweight unit-/component-testing libary for C
      and C++
      
      This library is used only in the unit-/component-testing

    - b64  (see http://synesis.com.au/software/b64.html)
    
      A simple, exceedingly lightweight implementation of the Base-64
      encoding
      
      This library is used by the pantheios::b64 inserter class

    - shwild  (see http://shwild.org/)

      An implementation (UNIX) shell compatible wildcards.
      
      This library is used only in the unit-/component-testing

   The other library on which Pantheios depends is STLSoft (see
   http://stlsoft.org). STLSoft is *not* an STL replacement, it is an STL
   extension library. Additionally, it provides a number of system and
   compiler discrimination features that Pantheios uses to simplify its
   implementation


4. It's incredibly efficient, and is faster than all other serious C++
   diagnostic logging libraries by a huge margin (up to two orders of
   magnitude)

   See http://pantheios.sourceforge.net/performance.html#sweet-spot if you
   don't believe us


5. It is 100% type-safe

   ... unlike any diagnostic logging library built on C's Streams or C++'s
   IOStreams libraries.


6. Selection of logging transport (i.e. "back-end(s)") is done at link-time,
   for very good reason

   The reason is simple: a diagnostic logging library must be available
   whenever _any_ part of the application code needs it. In C++, it's
   possible to execute a significant amount of functionality during dynamic
   initialisation, so we cannot afford to wait for main() to set up the
   logging.

   The consequence of this is Pantheios' only hard-to-use aspect, that of
   setting up the linking. There are several tutorials available for this
   purpose in the documentation


7. It's highly extensible

   Pantheios ships with a number of stock transports (known as
   "back-end(s)"), including console, Syslog, COM Error Object, speech,
   Windows Debugger, Windows Event Log. You can extend the range with a
   custom back-end by implementing a very simple C-API. The details are in
   the documentation.

   By default, the Pantheios Application Layer understands a large range of
   string types (and types that can be meaningfully converted into strings,
   such as struct tm, FILETIME, struct in_addr, and so on). Pantheios allows
   you to infinitely extend the range of types that may be incorporated into
   logging statements in your application code. There is an extensive
   tutorial on this in the documentation.


8. It's being used by serious commercial enterprises, including very high
   throughput financial systems

   Pantheios is in use by companies in Australia, US, and throughout the
   world.
   
   One notable user in New York contacted Synesis Software
   (see http://synesis.com.au/) in Dec 2007 to design and implement custom
   front-/back-ends to enhance the performance to an insane degree - not one
   processor cycle is wasted - because they believe that their systems will
   need to produce more diagnostic logging output than any other softare
   system in history.

   An NDA prevents us from naming the client, their business, or the nature
   of the customisations, but we can say that they're delighted with the
   system's performance and reliability. They said that Pantheios operates
   with "clock-cycle speed"!


9. It's highly portable - including most C++ compilers and most/all flavours
   of UNIX, Linux, Mac OS-X and Windows

   Pantheios has been tested on a wide range of C++ compilers, and a
   reasonable range of operating systems. In UNIX flavours, there are no
   platform-specific constructs used. Any new compiler/platform will
   require a minimum of enhancement to the STLSoft configuration. The
   development team are always happy to help/advise any such user.


10. Pantheios is under active development from a highly motivated team, who
   have the ambition that it will become the diagnostic logging API of
   choice for all C++ programmers who wish to have performance without
   sacrificing robustness or flexibility; the team want to hear from you how
   they can better achieve these aims

   That pretty much says it all. We know it's the best concept based on the
   best theory, and we're keen to help make it work well for all users
   everywhere.

=============================== End of file ================================