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

      E-mail: dmitrys@asu.edu


TAsyncFileStream - asynchronous file input/output in
Windows NT.

Almost the same as TFileStream, but uses Windows NT functions
allowing for the asynchronous file I/O.

Properties:

  CapacityDelta:integer; - determines  the increment with
  which internal list of I/O requests grows. Default value
  of 4096 should be suitable for most applications. Increase
  it if you expect to have many small writes/reads.

  constructor Create(const FileName: string; Mode: Word); - creates
  TAsyncFileStream object. See TFileStream help for details.

  destructor Destroy; - destroys TAsyncFileStream object.

  function Read(var Buffer;Count:longint):longint; - performs synchronous
  read from the file - exactly the same functionality as TFileStream.Read.
  For the asynchronous version of the same function see ReadAsync

  function Write(const Buffer;Count:longint):longint; - performs
  asynchronous write to the file. Contents of the Buffer are copied
  to an internal buffer and queried for the output, function returns
  without waiting for the output to complete.

  procedure SetSize(NewSize:longint); - sets new file size. Completely
  analogous to the TFileStream.SetSize

  function Seek(Offset: Longint; Origin: Word): Longint; - see TFileStream.Seek

  function ReadAsync(var Buffer;Count:longint):longint; - asynchronous version
  of the Read function. Queries an input and returns without waiting for the input
  to complete. Do not read/write from/to the Buffer until the the operation is
  completed.

  function WriteSync(var Buffer;Count:longint):longint; - permorms synchronous
  output, exactly the same behavior as TFileStream.Write.

  function NumPendingRequests:integer; - returns the number of I/O queries
  pending.

  function Busy:boolean; - returns TRUE if there are pending I/O queries, FALSE
  if all I/O queries are completed.

  procedure Wait; - waits for all I/O queries to be flushed.

  function Cancel:boolean; - cancels all pending I/O requests, TRUE if successful, FALSE
  otherwise.



Example:

 //write data to file and perform something useful
 //while data is being written.

 var af:TAsyncFileStream;
 .........
 af:=TAsyncFileStream.Create(name,fmCreate);	//Create new object
 af.size:=n*sizeOf(Buffer);			//Set size of the file		
 for i:=0 to n-1 do begin
  Buffer:=GetSomeData;				//Get buffer
  af.write(Buffer,size);			//Query buffer for write
  while af.busy do 				//Make sure HDD is still noisy
    SomeUsefulProcedure;			//Do something else
 end;


Hints:

  After using Read(Buffer,Count) do NOT read/write from/to the Buffer
  until the the operation is completed. Unlike read method, write method
  is completely safe, you can overwrite the buffer immediately after
  calling Write(Buffer,Count).
  If you need to synchronize I/O and your program flow,
  either use Wait method or something like

   while AsyncFileStream.Busy do Application.ProcessMessages.

  Do not use 

   while AsyncFileStream.Busy do;

  Wait method is least CPU time consuming.