windows-nt/Source/XPSP1/NT/inetsrv/iis/svcs/iisrtl/readme.txt

IISRTL - IIS Run Time Library
George V. Reilly,  <GeorgeRe@microsoft.com>
6/9/1998
Last Updated: 6/8/1999 by JasAndre

This document describes the public interfaces to the code bundled in
iisrtl.dll.  The public header files can be found in iis\inc.  The code can
be found in iis\svcs\iisrtl.


acache.hxx - ALLOC_CACHE_HANDLER - Allocation Cache
===================================================

class ALLOC_CACHE_HANDLER is a memory allocator.  An ACH maintains a
free list of blocks of memory, each N bytes in size.  Typically, you use
this by overriding `operator new' and `operator delete' for your heavily
used C++ class.  You need to maintain a static member variable that
points to your class's instance of an ACH.  Examples of how to do this
abound; look at lkrhash.{h,cpp} for one such.  ACache can also be used
for C-style structs or any fixed-size block of memory.

Pros: ACache is considerably faster than the global `operator new'.  (The
difference isn't as marked in NT5, now that the NT heaps have been
improved, but it's still a win.)  In addition, you can use iisprobe to dump
statistics on your class's use of ACache, and inetdbg has built-in support
for ACache (!inetdbg.acache).  ACache also offers additional debugging
support by checking for double deletions and filling free'd blocks with a
unique, identifiable pattern.

Cons: May waste memory by keeping large lists that might be better
returned to the system.  ACache periodically prunes all free lists in
the background, so this isn't too much of a problem.


madel.hxx   - MEMORY_ALLOC_DELETE    - Memory Allocator
manodel.hxx - MEMORY_ALLOC_NO_DELETE - Memory Allocator
=======================================================

Alternative memory allocators that are supposedly faster than ACache.
They work by allocating large blocks of memory and then suballocating
from those blocks.  (ACache grabs an exact sized block from the system
if its free list is empty.)  Again, see lkrhash.{h,cpp} for an example of
how to use these allocators.

Madel will return memory to the system if its free list grows above a
certain threshold.  Manodel never returns memory to the system, which
makes it faster but more wasteful.

Pros: probably faster than ACache.

Cons: ACache has much better debugging support.  Don't really need three
allocators.  Should build one allocator class that combines the best
features of all three allocators.


pudebug.h - Debugging utilities
===============================

Declares a number of useful debugging utilities, many of them encapsulated
by macros which are available in both the free and checked builds.

There are a number of macros which need to be used:
DECLARE_DEBUG_PRINTS_OBJECT - declares the variables needed for tracing
CREATE_INITIALIZE_DEBUG - called once per process this starts tracing
DELETE_INITIALIZE_DEBUG - called once per process this stops tracing
CREATE_DEBUG_PRINT_OBJECT - called once per module (ie DLL) this informs the
                            tracing mechanism about the module
DELETE_DEBUG_PRINT_OBJECT - called once per module this tells the mechanism
                            that the module is no longer tracing
VALID_DEBUG_PRINT_OBJECT - optional call to see if CREATE_DEBUG_PRINT_OBJECT
                           was successful.
See exe\main.cpp for an example of how to use them for a new process
See svcs\iisrtl\dllmain.cpp for an example of how to use them for a new module

The DEFAULT_TRACE_FLAGS macros control the debug settings, a DWORD variable 
per module that contains a collection of bit flags.  These are typically used 
to conditionalize debug output with the IF_DEBUG macro, e.g.,
    IF_DEBUG(SCHED) { /* ... */ }
    IF_DEBUG(ACACHE) { DBGPRINTF((DBG_CONTEXT, "ACache blah blah\n")); }
IF_DEBUG(arg), which is available in both the FRE and CHK builds, is defined as
    if (DEBUG_## arg & GET_DEBUG_FLAGS())
A set of debug flags should be defined in a local header file,
traditionally called "dbgutil.h", e.g.,
    #define DEBUG_SCHED 0x01000000
The debug flags are automatically loaded from the registry at start up time. If
none are found then the settings in the macro DEFAULT_TRACE_FLAGS are used. You 
can modify the settings are debug time using the trace extension, 
!inetdbg.trace

Other useful macros include DBG_ASSERT and DBG_REQUIRE (simply evaluates its 
argument in a free build, but DBG_ASSERTs in a checked build).  
See <pudebug.h> for the full list.

For a full explanation see the specs available at,
http://iis/kevlar/webfarm/specs/Kevlar%20Tracing.htm
http://iis/kevlar/webfarm/specs/Kevlar%20Supportability.htm

The PLATFORM_TYPE code provides useful helpers for code that needs to know
what platform it's executing on at runtime (NT Server, Win95, etc).

The INITIALIZE_CRITICAL_SECTION macro should be used in place of
::InitializeCriticalSection, as it sets the spincount to a non-zero value
(IIS_DEFAULT_CS_SPIN_COUNT) in a platform-independent manner.  (Critical
section spincounts were introduced in NT 4.0 sp3).  For multiprocessor
scalability, it's very important that busy critical sections have a
non-zero spincount.  If you want to set the spincount by hand, use the
SET_CRITICAL_SECTION_SPIN_COUNT macro.

Use the IIS_CREATE_EVENT, IIS_CREATE_SEMAPHORE, and IIS_CREATE_MUTEX macros
to create events, semaphores, and mutexes.  In debug builds, each of these
objects will be given a debugger-friendly unique name.  In free builds,
they are nameless.


irtldbg.h - More debugging utilities
====================================

They don't do a lot that pudebug.h doesn't do.  They mainly exist so that
LKRhash can be redistributed without needing to provide large chunks of IIS
support code.  Many of the macros will look familiar to MFC users.

Useful macros not included in pudebug.h include ASSERT_VALID,
ASSERT[_NULL_OR]_POINTER, and ASSERT[_NULL_OR]_STRING.


buffer.hxx - BUFFER - memory buffer
buffer.hxx - BUFFER_CHAIN - chain of BUFFERs
============================================

A BUFFER object caches a block of memory.  If the block is no more than
INLINED_BUFFER_LEN (16) bytes long, it's held inside the buffer object
itself; otherwise it's dynamically allocated.  You can either
request an initial size upon construction or pass in a pointer to an
already allocated block of memory.  The size of the cached block can be
adjusted by the Resize method, which takes an optional cbSlop
parameter.  QueryPtr returns a pointer to the storage; QuerySize returns
the current size.  BUFFER is used in the implementations of the STR,
MULTISZ, STRAU, and MLSZAU classes, qv.

A BUFFER_CHAIN is a linked list of BUFFERs.

Pros: very useful when you need a dynamically sized memory buffer.
If the size of the data is small enough, it'll be cached inline, which
makes it very time- and space-efficient.  (The 80-20 rule of memory
allocation: if 80% of your requests can be satisfied by a modest,
fixed-size buffer, inline it; else dynamically allocate.)

Cons: INLINED_BUFFER_LEN is hardwired into BUFFER.  If most of your
buffers need to be larger than this, you're just buying yourself
additional overhead (though you still save because you don't need to
manage allocation of the memory block yourself).


string.hxx - STR - lightweight string class
===========================================

The STR class manages ANSI strings.  It derives from the BUFFER class.
It provides several additional methods (see header for complete list):
* SetLen	safely sets length
* IsEmpty	zero-length string?
* Append	(const char*); (const char*, int len); (const STR&)
* Reset		empties string but retains buffer
* Copy		same as Reset followed by Append (same variations)
* LoadString	reads string from a string resource table
* FormatString	reads string from a .mc resource table; inserts params
* Escape	) Insert or remove any odd ranged Latin-1
* EscapeSpaces	) characters with the escaped hexadecimal
* Unescape	) equivalents (%xx)
* QueryCB	number of bytes in string
* QueryCCH	number of characters in string
* CopyToBuffer	copies stored string to buffer.  Ansi and Unicode variations
* QueryStr	returns the string buffer
* Append	(char); (char, char) append 1 or 2 chars (unsafe)
* AppendCRLF	Append "\r\n" (unsafe; assumes buffer large enough)

The STACK_STR(name, size) macro can be used to declare a string on the
stack.


stringau.hxx - STRAU - lightweight Ansi/Unicode string class
============================================================

A class that looks a lot like STR but transparently converts between
Ansi and Unicode.  All members can take or return a string in either
ANSI or Unicode. For members that take a parameter of bUnicode, the
actual string type must match the flag, even though it gets passed in as
the declared type.

Strings are sync'd on an as needed basis. If a string is set in ANSI,
then a UNICODE version will only be created if a get for UNICODE is
done, or if a UNICODE string is appended.

All conversions are done using Latin-1. This is because the intended use
of this class is for converting HTML pages, which are defined to be
Latin-1.


multisz.hxx - MULTISZ - lightweight multi-string class
======================================================

Another class that looks a lot like STR but contains a set of strings.
The strings are stored consecutively in the buffer, separated by '\0'.


mlszau.hxx - MLSZAU - lightweight Ansi/Unicode multi-string class
=================================================================

Stores and converts multisz's between unicode and ANSI. It does not allow
much manipulation of them.


lkrhash.h - CTypedHashTable - LKR Hash Tables
=============================================

LKRhash is a fast, growable, multiprocessor-friendly hashtable.  The
hashtable will automatically grow (shrink) as you add (delete) elements,
keeping search times short.  It is thread-safe and has been designed to
scale extremely well on MP systems.  It achieves this by carefully
partitioning locks and holding them for a very short time to minimize lock
contention and hence bottlenecks.

The templatized wrapper class, CTypedHashTable, provides an easy-to-use
front end for the underlying implementation.  Several detailed examples
exist in lkrhash.h and svcs\iisrtl\hashtest.  If you need an unordered
collection of data that needs to be searched quickly, you should strongly
consider LKRhash.


locks.h - Miscellaneous locks
=============================

In addition to providing an implementation of a user-mode spinlock for
LKRhash, a number of other locks are provided (critical sections, NT
resources, and other read/write locks).  All provide the same interface, so
they can be used interchangeably.


irtlmisc.h - IISRTL Miscellanea
===============================

Some macros used in IISRTL and some random declarations.  The most useful
functions are InitializeIISRTL and TerminateIISRTL, which should be used by
clients who want to make use of the scheduler functionality.  NumProcessors
and stristr may also be of interest.


tracelog.h - TRACE_LOG
===========================

A trace log is a fast, in-memory, thread safe activity log useful for
debugging certain classes of problems. They are especially useful when
debugging reference count bugs.

Note that the creator of the log has the option of adding "extra" bytes to
the log header. This can be useful if the creator wants to create a set of
global logs, each on a linked list.


reftrace.h - RefTraceLog
=========================

Reftrace logs are built on top of trace logs.  Typically, you write a
reftrace entry whenever you modify a reference count.  In addition to the
value of the refcount and some custom context, the log entry includes a
stack bactrace (top nine functions), so you have a chance of figuring out
how the refcount was modified.  Enormously useful for tracking down
refcount leaks.  Use !inetdbg.ref, !inetdbg.rref, and !inetdbg.resetref to
manipulate the reftrace log.


strlog.hxx - CStringTraceLog
============================

String trace logs are useful for writing logs of free-form strings when
trying to track down race conditions.  DBG_PRINTF, which writes to the
debugger and/or a log file, is relatively slow and involves context swaps,
both of which can make reproducing race conditions much harder.  A string
trace log is synchronously written to main memory.  The Puts method is
little more than a strcpy; the Printf method is slower but much more
versatile.  Use !inetdbg.st, !inetdbg.rst, and !inetdbg.resetst to
manipulate the string trace log.


stktrace.h - IISCaptureStackBackTrace
=====================================

Used by reftrace and DBG_ASSERT to capture a stack backtrace.



datetime.hxx - Date and time manipulation classes
=================================================

A number of classes and helper functions for converting between various
time and date formats.  Particularly used in generating HTTP headers and
the IIS logs.


timer.h - Timer routines
========================

Wrap-proof timer routines (no worries about GetTickCount wrapping around to
zero).


issched.hxx - Scheduler
=======================

The scheduler is used to execute tasks (work items) in the background.
These work items can be one-shot or periodic.  Particularly useful for
cleanup or periodic scavenging.  Use !inetdbg.sched to debug.


eventlog.hxx - EVENT_LOG
=======================

A useful wrapper for the system/security/application event logs.


gip.h - Global Interface Pointer API support
============================================

COM interface pointers are apartment-relative.  The Global Interface Table
makes passing interface pointers across apartment boundaries much easier
than the traditional methods (CoMarshallInterfaceInStream...).  gip.h
further encapsulates the GIT.


giplip.h - global and local interface pointers
==============================================

An alternative to gip.h.


perfutil.h - Performance Monitor helpers
========================================

Some helper functions and macros for implementing PerfMon counters.


trie.h - Trie templates
=======================

A trie is a multiway search tree, useful for doing string
matches.  Read the comments in <trie.h>