Michał Cierniak

Annotations for Rotor source files (1) - clr/src/inc directory

The other night I spent some time with two colleagues (Jim Miller and Peter Drayton) to look at Rotor source files and write a short annotation for each file.  We looked at a few header files in the clr/src/inc directory.  We thought that the experience was useful and we may sit down again and describe more files - no promises of course, but stay tuned... .

In the text below I will use a different font color and size for the code and comments quoted from the source files but this convention is not essential to understanding the descriptions.

• allocacheck.h
• Here’s a comment that describes well what this short file provides:
  /* check for alloca overruns (which otherwise are hard to track down
     and often only repro on optimized builds). 
     USAGE:
          void foo() {   
              ALLOCA_CHECK();             // Declare at function level scope
              ....
              void* mem = ALLOCA(size);   // does an alloca,
          }   // destructor of ALLOCA_CHECK for buffer overruns. 
  */
• Additional notes:
1. These macros do something in the Debug build only
2. They use C++ destructor semantics to check integrity of all ALLOCA'ed blocks when the function exits.
3. They prefill memory with #DD, puts a sentinel of #CCCDCECF
4. They chains blocks within this function through the sentinels field of the local variable __allocaChecker
• arraylist.h
• Comment:
  // ArrayList is a simple class which is used to contain a growable
  // list of pointers, stored in chunks.  Modification is by appending
  // only currently.  Access is by index (efficient if the number of
  // elements stays small) and iteration (efficient in all cases).
• Notes:
1. Safe for single writer, multiple reader without locking
• blobfetcher.h
• Comment:
  // CBlobFetcher - it fetches binary chunks, similar to new, but more controlled
• Notes:
1. Used only for PE file writing
2. Functions in this class let you obtain a memory block of a given size and alignment, convert and offset into a pointer and vice versa, write out a section to a stream etc.
• cahlpr.h
• Comment:
  // This class assists in the parsing of CustomAttribute blobs.
• Notes:
1. Has methods named GetXX (I1, etc) in checked and unchecked flavors.  Both advance cursor in the blob.