README

libthekogans_util is at the heart of every other library and
program. It contains a lot of reusable, cross-platform code designed
to hide platform specific details from other, higher level libraries
and programs. The library is developed, and tested on Windows, Linux,
and OS X, in both 32 and 64 bit modes, and on little and big endian
architectures (x86, MIPS, ARM...). A lot of effort has been made to
make sure libthekogans_util is semantically equivalent on all supported
platforms.

libthekogans_util is fully UTF8 compliant (the only Unicode format
that makes any sense IMHO). All methods that accept a std::string
will internally convert them to UTF16 on Windows and call 'W' APIs.
When receiving strings from Windows, again, 'W' APIs are used and
the results are converted to UTF8 before being returned to the caller.
libthekogans_util is completely _UNICODE ambivalent (it will behave
the same whether the macro is defined or not).

VERY IMPORTANT: libthekogans_util DOES NOT return error codes. In
the interest of promoting safe and secure coding habits libthekogans_util
throws exceptions (Exception.h). If you choose to use libthekogans_util
in your projects keep that in mind and use the various guards defined
in Exception.h to protect your code.

Here is a complete feature list:

    - A type system (Types.h, Constants.h) to hide platform specific
      types.

    - A full featured JSON parser/formatter (JSON.h). Supports Variant
      for numbers (f64, i64, ui64). Supports multiline text through a
      clever Array ctor.

    - A collection of useful, simple, and lightweight types (Flags.h,
      Variant.h, GUID.h, Fraction.h, Array.h, FixedArray.h, BitSet.h).

    - A collection of standard container wrappers (AbstractOwnerList.h,
      AbstractOwnerVector.h, OwnerList.h, OwnerVector.h, OwnerMap.h)
      which help with lifetime management of heap allocated objects.

    - An intrusive list (IntrusiveList.h) useful in many situations
      where std::list is not appropriate.

    - A std::exception extension class (Exception.h) which uses a
      trace-back mechanism to track the path of an exception as it is
      being unwound.

    - A high resolution timer (HRTimer.h, HRTimerMgr.h) which can be
      used to help with code profiling.

    - A millisecond resolution periodic timer (Timer.h) designed to be
      used where accuracy is not paramount (idle processing…).

    - A platform independent time interval (TimeSpec.h). This class
      abstracts the time interval used by all timer, thread, and
      synchronization classes, and provides a uniform way to specify a
      timeout value.

    - A full featured logging framework (LoggerMgr.h, Logger.h,
      ConsoleLogger.h, FileLogger.h, MemoryLogger.h, NSLogLogger.h
      OutputDebugStringLogger.h). LoggerMgr can use a background,
      low priority JobQueue to log entries so as not to interfere
      with main thread execution.

    - A per class heap (Heap.h), which makes memory management a
      breeze. It also provides built in diagnostics for leaks, and
      double free (two of the nastiest memory bugs). Use of class
      heap significantly reduces global heap fragmentation leading
      to stable and more performant code.

    - An extensible collection of allocators (Allocator.h,
      DefaultAllocator.h, AlignedAllocator.h, SecureAllocator.h,
      SharedAllocator.h, HGLOBALAllocator.h, NullAllocator.h) that
      plug in to Heap and Buffer.

    - A set of concurrency/synchronization wrappers (Thread.h,
      NullLock.h, SpinLock.h, Mutex.h, Semaphore.h, Barrier.h,
      SpinRWLock.h, RWLock.h, Condition.h, Event.h, TimeSpec.h,
      LockGuard.h, RWLockGuard.h, SharedObject.h) designed to put
      a uniform api on top of pthreads, and Windows specific
      threading api.

    - A run loop framework (RunLoop.h, ThreadRunLoop.h, SystemRunLoop.h
      MainRunLoop.h, JobQueue.h) for executing RunLoop::Jobs on any thread,
      including main.

    - A collection of process classes (ChildProcess.h, DynamicLibrary.h)
      used to instantiate child processes, and load shared libraries
      (*.so, *.dylib, *.dll).

    - A set of higher level threading abstractions (JobQueue.h,
      JobQueuePool.h, Pipeline.h, PipelinePool.h, Vectorizer.h,
      Scheduler.h, RunLoopScheduler.h) useful in many different
      situations.

    - An extensible collection of hashers (Hash.h, MD5.h, SHA1.h,
      SHA2.h, SHA3.h, SHA2_224_256.h, SHA2_384_512.h) to aid in the
      use of third party libraries.

    - A set of classes (File.h, Directory.h, Path.h, MimeTypeMapper.h)
      designed to help when dealing with file system objects. Of
      these, Directory is especially noteworthy. It implements such
      advanced, and useful features as; platform independent file
      system traversal, and an asynchronous directory change
      watcher/notifier.

    - A binary serializer framework (Serializable.h, Serializer.h,
      Buffer.h, FixedBuffer.h, File.h). It’s main purpose is to provide
      serialization/deserialization services for binary protocols.

    - A set of utilities to help with processing xml (XercesUtils.h,
      XMLUtils.h)

    - A collection of string utilities (StringUtils.h) used to hide
      platform inconsistencies and provide useful cross-platform
      functionality.

    - A collection of platform specific utilities (LinuxUtils.h,
      OSXUtils.h, WindowsUtils.h, XlibUtils.h).

    - A reference counted base class (RefCounted.h) which implements
      both SharedPtr and WeakPtr templates.

    - A producer/subscribeer framework (Producer.h, Subscriber.h) which
      allows interested observers to subscribe to async events.

    - A cryptographically secure random byte stream (RandomSource.h).
      Where available, the stream uses dedicated machine instructions
      to harvest entropy.

    - Application plugin manager (Plugins.h).

    - A set of miscellaneous classes (Config.h, Version.h, Console.h,
      CommandLineOptions.h, Singleton.h, SystemInfo.h, ByteSwap.h,
      Base64.h, Point.h, Rectangle.h, CRC32.h).

libthekogans_util has the following required dependencies:

Windows: Ws2_32.lib, mpr.lib, Iphlpapi.lib, Wtsapi32.lib.

Linux: pthread, rt, dl.

OS X: pthread, frameworks: Foundation, Security, Cocoa,
CoreFoundation, CoreServices, CoreGraphics, SystemConfiguration,
IOKit.

libthekogans_util has the following optional dependencies:

if -DTHEKOGANS_UTIL_HAVE_XERCES is specified, xerces.
if -DTHEKOGANS_UTIL_HAVE_ZLIB is specified, zlib.
if -DTHEKOGANS_UTIL_HAVE_TESTS is specified, CppUnitXLite.
Linux: if -DTHEKOGANS_UTIL_HAVE_XLIB is specified, X11.