
      Dmitry Streblechenko
      Department of Physics and Astronomy
      Arizona State University
      Box 871504
      Tempe, AZ 85287-1504

      E-mail: dmitrys@asu.edu


 class TMemoryMappedFileStream
 Encapsulation of the Windows Memory Mapped object.

 Use, modify or distribute (do not sell) as you please
 as long as you give me a credit.

 Allows for
        1) simple interprocess communications via the named
           mapped objects transparently accessible either
           as the TStream decendents or as arrays using
           Memory property
        2) Access to any files up to 4GB size as the memory arrays
           using Memory property

 Usage:
        Just like any TStream descendent ( Read(), Write(),
        Size, Position, etc.)

 Additional properties and methods:
   property Memory   :pointer; (read only) - use like any
                               other pointer, DO NOT use in the
                               memory de/re/allocation routines.
   property FileName :string; (read only) - name of the
                              file mapped to memory
   property MapName  :string; (read only) - name of the memory
                              mapped object (has nothing to do with
                              the FileName).
   property MemoryDelta:longint; (read/write) - increment with which
                                 object's allocated memory will grow

 Hints:

  To create new mapped file object, use constructor
    Create(FileName, MapName,Mode)
  FileName - name of the file to map, can be '' if you want to use
             Windows swap file (useful for interprocess communications)
  MapName - name of the mapped object to create, can be '' if
            you do not want to open it using different mapped file object
  Mode - file open/creat mode, see TFileStream.Create help

  To use existing mapped file object, use constructor
     Open(MapName, Mode)
  MapName - name of the existing mapped file object (see above),
            creator can reside in a different process.
  Mode - Mapped object open mode, see TFileStream.Create help.
         DO NOT use fmCreate mode, exception will be thrown!
         All other modes are Ok.

Example - count all letters 'a' in a file
         type hugearray=array[0..$FFFFFFFF-1] of char;
         var mmf: TMemoryMappedFileStream;
             HugeFileName:string;
             i,counter:longint;
         begin
         HugeFileName:=...;
         mmf:=TMemoryMappedFileStream.Create(HugeFileName,'',fmOpenRead);
         counter:=0;
         for i:=0 to mmf.Size-1 do
          if hugearray(mmf.memory^)[i]='a' then inc(counter);


Warning
       As soon as a named memory mapped object is created and open
       you cannot change its size, e.g.,
       ....
       var mmf1,mmf2: TMemoryMappedFileStream;
       ....
       //Create new memory mapped object, defaul size 64kB
       mmf1:=TMemoryMappedFileStream.Create('c:\temp\mmf.tmp','mem_map',fmCreate);
       ....
       //Open it either from the same process or from a different one
       mmf2:=TMemoryMappedFileStream.Open('mem_map',fmOpenReadWrite);
       ....
       //Try setting MM object's size to 1Mb
       mmf1.Size:=$100000;
       //Exception is thrown...

       Remember that Size can be changed both explicitly (above) or
       implicitly by calling Write(Something,SizeOf(Something)), which
       in case of insufficient memory tries to allocate more memory.

       A workaround is to set stream's size BEFORE opening the MM object:
       ....
       var mmf1,mmf2: TMemoryMappedFileStream;
       ....
       mmf1:=TMemoryMappedFileStream.Create('c:\temp\mmf.tmp','mem_map',fmCreate);
       mmf1.Size:=$100000;
       //Now everything is fine
       ....
       mmf2:=TMemoryMappedFileStream.Open('mem_map',fmOpenReadWrite);
       ....


       One more thing: for some reason Windows does not like
       creating MMF object when the file is open with fmOpenWrite
       attribute, I would recommend using fmCreate or fmOpenReadWrite
       for creating MMF's or fmOpenReadWrite for opening MMF's.

       Have fun!

