Category : Pascal Source Code
Archive   : CACHE.ZIP
Filename : CACHE.DOC

Documentation for the TurboPower Disk Caching System


A. Overview
-----------
When Turbo Pascal 4.0 came out, the market for our Turbo Extender product
pretty much evaporated because the new compiler offered its own large code
model. The compiler still lacks, of course, some of the facilities offered by
Extender, notably large arrays and module overlays, but these needs are now
addressed by our Turbo Professional and Overlay Manager packages respectively.
And now CACHE.ARC supplies the disk caching facility formerly found in Turbo
Extender.

This disk caching system--referred to generically as CACHE--is supplied in two
versions. The RAMCACHE unit uses normal RAM (up to 640K) for the storage of
the cache data. The EMSCACHE unit uses EMS (Expanded Memory Specification,
also known as LIM, for Lotus/Intel/Microsoft) memory to store cache data in
memory outside of your normal RAM allocation. With a few minor exceptions, the
two are used identically.

CACHE works only on drives that use the IBM system BIOS. RAM disks use their
own device drivers for operation. Some third party add-on disks use their own
device drivers. CACHE does not affect the normal operation of these devices,
and provides no performance enhancement. CACHE does work with all
IBM-compatible hard disks, with single and double sided double density drives,
and with the 1.2MB floppy drive of the IBM AT.

Important note: Both the EMSCACHE unit and the RESCACHE demo depend on one or
more units found in our Turbo Professional 4.0 package. The RAMCACHE unit
depends only on the standard DOS unit.

B. Using the Cache
------------------
The following is a rough outline of a program that uses CACHE:

program ShowCache;
uses
RAMCACHE;
var
FileName : string[64];
begin
{cache initialization}
if not BuildCache(1000, 256) then begin
WriteLn('Unable to install cache.');
Halt;
end
else
SetCacheState(True, False, 100);

{your program code goes here}

{whenever you open a file, and want that drive cached, call...}
LoginDrivePath(FileName);
end.

To use the expanded memory version of the cache, substitute EMSCACHE for
RAMCACHE in the USES statement.

The main block of this example shows the four procedures that you will call
most often. Following is a brief description of each.

1) BuildCache: This function allocates memory for the cache on the Turbo heap
(if RAMCACHE is used), initializes the cache data structures, and sets up an
interrupt handler in support of the cache.

BuildCache(HeapParasToReserve, MaxCacheSectors : Word) : Boolean;

The first parameter (1000 above) is the number of paragraphs on the heap that
you want to reserve for your own program data (a paragraph equals 16 bytes).
BuildCache will reserve this amount of memory for you. If you are using
EMSCACHE, this value is ignored.

The second parameter (256 above) is the maximum number of 512-byte disk
sectors that you would like to store in the cache. BuildCache will reduce this
number to as low as 10 (MinSects) if limited memory is available.

BuildCache returns True if successful, False if insufficient memory was
available.

Generally, BuildCache should be called only once in a program, and must be
called before any of the other cache procedures.

2) SetCacheState: This procedure defines the operating mode of the cache.

SetCacheState(CacheActive, CheckFAT : Boolean; LoadPriority : Byte);

The first parameter (True above) determines whether the cache is currently
active. If false, all disk activities reference the physical drives. This may
be used when you read a file which will be used only once, and you wish to
avoid disturbing the information stored in the cache.

The second parameter (False above) determines whether "disk change" checking
is activated. A new diskette can obviously be inserted into a floppy drive at
any time. The cache will not know this unless disk change checking is True.
The penalty of disk change checking is that the physical drive must be
referenced more often, resulting in a loss of cache performance. For many
applications, it is safe to set this parameter False.

The third parameter (100 above) sets the priority for subsequent disk data to
remain in the cache. The highest acceptable priority is 254, and the lowest
one is 0. When the cache becomes full, the lowest priority disk sectors are
kicked out of the cache to make room for new data. You can fine tune the
priority to help keep the most important data available in RAM. CACHE uses
another mechanism ("least recently used" replacement) in addition to the
priority value, so you may never need to worry about setting specific priority
values.

SetCacheState may be called as many times as desired within your program. If
it is never called, the state of the cache defaults to "active", "disk changes
checked", and "priority=100".

3) LoginDrivePath: This procedure allows CACHE to determine the drive
parameters of whatever drive the parameter references. The drive parameters
are required for CACHE to accurately track where physical disk data is
located.

LoginDrivePath(PName : string) : Boolean;

The parameter to LoginDrivePath is the name of a file or drive that you will
be reading from. LoginDrivePath parses the name of the file to find the drive
specifier. If none is specified, it assumes the default drive of the system.
You may pass a literal file name, a full pathname, a drive letter (followed by
a ":"), or a path variable to LoginDrivePath.

You should call LoginDrivePath every time that you open a new file that you
want cached. It knows when a drive has been previously logged in, and will not
waste time in repeating the effort.

LoginDrivePath will return False if it is unable to obtain the necessary
information about the drive. Usually this means that the drive does not exist,
or that there is no disk in the drive.

4) FlushDrivePath: This procedure flushes all the cache data for a specified
drive. Although it accepts a file name as a parameter, CACHE will flush all
data associated with an entire drive, not just the specified file. This may be
used when you are finished with a file or set of files, and you wish to make
room for a new set of data.

FlushDrivePath(PName : string);

The parameter to FlushDrivePath is specified the same way as for
LoginDrivePath. If PName is empty, the data for all drives is flushed.

FlushDrivePath need never be called. The replacement algorithms
of CACHE will eventually remove data which has not been recently used.

C. Performance and Capacity of CACHE
------------------------------------
CACHE may be configured to use all normal memory of the IBM PC, with up to
512K bytes of RAM dedicated to data storage for the cache. The EMS version of
CACHE supports up to 2 megabytes of data storage in expanded memory (limited
by the pointer array in Turbo's data segment exceeding 64K bytes).

The basic unit of cache storage is the "sector". For all drives supported by
IBM, a sector contains 512 bytes of data.

To set the maximum number of sectors available to CACHE, you will need to
modify two constants at the top of RAMCACHE.PAS or EMSCACHE.PAS: MaxSects and
MaxSects1. The setting needed to provide optimum performance is a function of
the application--how much data is to be read, and how that data will be used.

CACHE uses 14 bytes of memory in the data segment for each sector specified by
MaxSects. This amount of memory is always used regardless of the number of
sectors allocated dynamically at runtime. The actual number of sectors that
CACHE uses is stored in the variable ActSects.

Below are the results of a simple benchmark run on a Compaq Deskpro 286 to
determine the performance of RAMCACHE (not EMSCACHE). The benchmark uses the
Turbo Pascal BLOCKREAD procedure to read 4096 bytes (8 sectors) at a time from
any of several disk types. The results follow:

1) Reading from the cache is about 2x slower than reading from a RAMdisk.
2) Reading from the cache is about 4x faster than reading from the 35ms
access (30MB) hard disk in the Deskpro 286.
3) Reading from the cache is about 20x faster than reading from the 1.2MB
high density drive.
4) Reading from the cache is about 30x faster than reading from a standard
DSDD floppy drive.
5) When the cache must read from the physical disk and load the data into
the cache, it imposes an overhead of about 80% on the fast hard disk,
and an overhead of about 10% on a standard floppy.

CACHE performance is also sensitive to the number of DOS BUFFERS. The reported
results are for 4 DOS buffers. Increasing the number of buffers reduces the
performance advantages of CACHE. DOS buffers provide a system level equivalent
of what CACHE does, but to a more limited degree.

A few guidelines for obtaining optimal performance: The surest method is to
reserve cache space for every unique byte of data that you read (of course!).
If your application repeatedly reads a file sequentially from the beginning,
this is the only way to get any advantage at all. However, if your application
uses random access to files, then the amount of cache can be quite small and
still give performance improvements. We recommend that at least 10 sectors
(about 5K bytes) be made available for the cache, or you will certainly be
wasting your time. In fact, the BuildCache procedure will not install the
cache if fewer than 10 sectors are available in RAM.


D. Other Routines, etc.
-----------------------
FlushCache may be called whenever you want to sweep out the entire cache in
preparation for a new batch of data.

ReleaseCache restores normal diskette operation for DOS and other programs.

ReleaseCache(ReleaseHeap : Boolean);

The ReleaseHeap parameter indicates whether or not any heap space used by
CACHE should be releaseed; if False, ReleaseCache simply resets the interrupt
vector grabbed when BuildCache was called. Since failure to call this
procedure will result in loss of disk access for the system until it is
rebooted, CACHE contains an exit handler so that the cache is automatically
released when your program ends. Therefore you will not normally need to call
ReleaseCache yourself.

The CheckSectorsAvailable function returns the number of free sectors in the
cache.

CheckSectorsAvailable : Word;

Your program may want to use this function to decide when it should flush the
cache.

DumpCache displays information about the performance of the cache. It was
written for use in the example program RESCACHE, but may also be useful when
debugging.

Two global variables, Reads and Misses, keep track of CACHE's performance.
Every sector read (either from disk or from the cache) increments the Reads
counter. Whenever a sector is not found in the cache, the Misses counter is
incremented. Obviously, you want to minimize the ratio Misses/Reads.

E. Cautions
-----------
1) CACHE uses the GETMEM/FREEMEM approach to heap management when ReleaseCache
is called (and only then). It is not compatible with applications using the
MARK/RELEASE technique.

2) CACHE takes over BIOS interrupt $13. It is most likely not compatible with
applications which also take over the same interrupt.

F. RESCACHE.PAS
---------------
The example program, RESCACHE.PAS, installs the cache routines as a memory
resident interrupt handler. All disk accesses thereafter are routed through
the cache. You can use this program to improve DOS performance without
modifying any applications. RESCACHE as supplied is set up to use EMS memory.
You can modify it to use normal RAM simply by deleting the line

{$DEFINE UseEms}

The first time you run RESCACHE, you must go through a one-time configuration
process in which you specify which drives are to be cached. Thereafter,
running RESCACHE will either install it as a resident program or, if it is
already resident, allow you to modify the behavior of (or check the
performance of) the caching system. If you need to reconfigure the program for
different drives, enter "RESCACHE -I".

RESCACHE is intended primarily to demonstrate the CACHE facility. We do not
recommend that you install it permanently in your system.

G. Copyright and Acknowledgement
--------------------------------
The CACHE facility for Turbo Pascal 4.0 is copyright (c) 1986, 1988 by
TurboPower Software. All rights reserved.

TurboPower Software hereby grants a limited license to use this software as
follows:

o The CACHE units and their source code may be distributed freely as long as
there is no charge, with the exception of a handling fee not to exceed $10.
o Programs using the CACHE units may be distributed without restriction,
commercially or otherwise.
o The Turbo Professional units on which RESCACHE and EMSCACHE depend may
not, however, be distributed without the permission of TurboPower
Software.

TurboPower Software accepts no liability for the use of this software.

Contact Brian Foley at Compuserve account 76317,3247 or Kim Kokkonen
[72457,2131] with comments regarding the CACHE facility.


H. Advertisement
----------------
TurboPower Software is in the business of providing powerful tools for the
Turbo Pascal programmer. Our line of products for Turbo Pascal 3.0 includes
the TurboPower Utilities, Turbo Extender, T-DebugPLUS, and Turbo Optimizer.

Our first product for Turbo Pascal 4.0 is Turbo Professional 4.0, a library of
400 routines to solve the most common programming problems. Professional 4.0
includes units to save time and effort in the following ways:

o CRT unit emulation, with many added features: cursor manipulation,
support for Taskview and Desqview multitaskers, screen save and
restore, BufLen control, and more.
o Popup windows, virtual screens, and pulldown menu systems.
o Easy and reliable ways to make your program memory resident.
o Interrupt service routine handlers.
o Keyboard macros.
o Data entry routines.
o Extended and Expanded memory access.
o A complete BCD arithmetic unit, including the transcendental
functions and the Form routine.
o Sorting and searching.
o Extensive string manipulation.
o Strings longer than 255 characters.
o Arrays larger than 64K.
o Runtime error recovery.

Turbo Professional 4.0 also comes with a dozen powerful demo programs,
including a memory resident programmer's calculator, time management system,
and keyboard macro utility, as well as a source code generator for menu
systems. With complete source code (over 30,000 lines of it) and a 450 page
manual, Turbo Professional 4.0 is a bargain at $99.

Also available is Overlay Manager 4.0, which adds overlays and chaining back
to the Turbo Pascal 4.0 compiler. Just $45.

And our latest product is a Turbo 4.0 version of T-DebugPLUS, our acclaimed
symbolic debugger for Turbo Pascal. T-DebugPLUS 4.0 is just $45, or $90 if you
want the complete source code for the debugger.

Following soon thereafter will be Turbo Analyst 4.0, the successor to our
popular TurboPower Utilities.

Call TurboPower Software at 408-438-8608 for more information.