home *** CD-ROM | disk | FTP | other *** search
/ The CDPD Public Domain Collection for CDTV 3 / CDPDIII.bin / bbs / ff846.lha / FF846 / FileCache / FileCache.Doc < prev    next >
Text File  |  1993-03-31  |  9KB  |  276 lines
  1.  
  2.                           FileCache Server V1.00
  3.                      (C) 1992,93 Christophe PASSUELLO
  4.                      --------------------------------
  5.  
  6.  
  7. INTRODUCTION
  8. ------------
  9.  
  10.   FileCache is a task used as a server, its goal is to cache includes files
  11.   in memory for compilers and assemblers, with this you can greatly speed up
  12.   compilations.
  13.  
  14.   When you ask to the server to load a file it will check before if the file
  15.   is in cache, in this case le file doesn't need to be loaded from disk, else
  16.   the file will be load from disk and put in the cache. If there not enough
  17.   place to put the file in cache the Least Recently Used files will be removed
  18.   from cache to make place for the new file (LRU algorythm). So every next
  19.   compilation or assembly includes file will be read from memory instead of
  20.   disk.
  21.  
  22.   Each file loaded in cache is put in a single block of memory, at return of
  23.   a load request the server will return address of the block for the file and
  24.   its size so you can do parsing directly in the block of memory, so no more
  25.   buffer and Read() call overhead.
  26.  
  27.   Any task can use the server through its public port.
  28.  
  29.  
  30. DISCLAIMER
  31. ----------
  32.  
  33.   The author is not responsible of any damages resulting of FileCache use.
  34.  
  35.  
  36. INSTALLING THE SERVER
  37. ---------------------
  38.  
  39.   Before any program can use the server, you must install it: You install it
  40.   by running it.
  41.  
  42.     1> run FileCache -mXX    : XX is the size max of cache in KBytes.
  43.  
  44.         Memory allocation is dynamic, so the memory used by the cache is only
  45.         the memory used by the files in cache. You can define a bigger cache
  46.         than you really need, to be sure that all files will be in cache and
  47.         no memory will be wasted. (for example a cache of 300 KBytes is enough
  48.         for most compilations).
  49.  
  50.   Once installed, you can flush the cache, get infos on cache and remove it.
  51.  
  52.     1> FileCache -mYY  To modify size of cache. (YY en KBytes)
  53.  
  54.     1> FileCache -f    Flush cache, all memory used by the files is freed.
  55.  
  56.     1> FileCache -i    Give number of file in cache, size of cache, memory
  57.                        really used by the cache and number of locks on cache.
  58.  
  59.     1> FileCache -q    Remove the server and free memory. If you want to use
  60.                        it again you install it again.
  61.  
  62.   Once installed you can send request to the server.
  63.  
  64.  
  65. GENERAL OPERATIONS
  66. ------------------
  67.  
  68.   - If you want to use the server you must check if installed by looking at
  69.     its public port with FindPort():
  70.  
  71.         struct MsgPort *FileCachePort;
  72.  
  73.         if (FileCachePort = FindPort(FILECACHEPORTNAME))
  74.         {
  75.           /* serveur is installed  */
  76.           ....
  77.         }
  78.         else
  79.         {
  80.           /* No port so the server is not installed */
  81.           puts("FileCache Server not installed.");
  82.           exit(0);
  83.         }
  84.  
  85.  -  You must create a port for replies and init the request:
  86.  
  87.         ReplyPort = CreatePort(NULL, 0L);
  88.         msg.fcm_Msg.mn_Node.ln_Type = NT_MESSAGE;
  89.         msg.fcm_Msg.mn_Length = sizeof(struct FileCacheMsg);
  90.         msg.fcm_Msg.mn_ReplyPort = ReplyPort;
  91.  
  92.  -  You send request by sending message on the server port:
  93.  
  94.         PutMsg(FileCachePort, &msg);
  95.  
  96.  -  You wait for reply:
  97.  
  98.         WaitPort(ReplyPort);
  99.         GetMsg(ReplyPort);
  100.  
  101.  -  Now you can check the value returned by the server for ex: fcm_Error.
  102.  
  103.         printf("Error code returned = %ld.\n", msg.fcm_Error);
  104.  
  105.  
  106.  
  107. STRUCT FileCacheMsg
  108. -------------------
  109.  
  110.   Requests are sent using a message defined by a struct FileCacheMsg.
  111.  
  112.   struct FileCacheMsg
  113.   {
  114.     struct Message fcm_Msg;
  115.     ULONG  fcm_Command;
  116.     ULONG  fcm_Flags;
  117.     ULONG  fcm_Error;
  118.     union
  119.     {
  120.       struct
  121.       {
  122.         STRPTR FileName;
  123.         STRPTR *Directory;
  124.         ULONG  DirIndex;
  125.         ULONG  FileBuffer;
  126.         ULONG  FileLength;
  127.         ULONG  Reserved0;
  128.       } FileCmd;
  129.       struct
  130.       {
  131.         ULONG CacheSize;
  132.         ULONG MemoryUsed;
  133.         UWORD NbFiles;
  134.         UWORD NbLocks;
  135.       } CacheCmd;
  136.     } ExtCmdInfo;
  137.     ULONG  fcm_Reserved[2];
  138.   };
  139.  
  140.  
  141.   fcm_Msg:      It is a standard Exec Message. You must init it before sending
  142.                 request.
  143.  
  144.   fcm_Command:  the command to send (see below).
  145.  
  146.   fcm_Flags:    Flags for commands.
  147.  
  148.   fcm_Error:    Error code returned by the server, if no error it contains
  149.                 FC_ERR_OK else FC_ERR_xxx.
  150.  
  151.   The remaining of the struct is defined by the kind of command.
  152.  
  153.  
  154. FILECACHE COMMANDS
  155. ------------------
  156.  
  157.   There is three kind of command for the server.
  158.    - generals commands.
  159.    - commands regarding the cache.
  160.    - commands regarding the file.
  161.  
  162.  
  163. GENERALS COMMANDS
  164. -----------------
  165. Server owns a counter that indiquate the number of locks on the server. If the
  166. counter is zero, there is no lock and the server can be removed.
  167.  
  168. FC_CMD_GETTOKEN: It is the first request to send to server, it increment lock
  169.                  counter, so with this command the server can't be removed.
  170.                  (When exiting your program you must unlock it).
  171.  
  172. FC_CMD_DELTOKEN: Decrements the lock counter, you must send this request before
  173.                  exiting your program.
  174.  
  175. FC_CMD_QUIT:     With this command you can remove the server only if lock
  176.                  counter is zero. at return if fcm_Error is FC_ERR_OK the server
  177.                  has been removed else it is FC_ERR_INUSE. (Of course you must
  178.                  send this request after FC_CMD_DELTOKEN).
  179.  
  180. FC_CMD_FLUSH:    This command flush the cache, all files are removed from the
  181.                  cache, but the server isn't removed.
  182.  
  183.  
  184. CACHE COMMANDS
  185. --------------
  186.  
  187. These commands let you change size of cache, get informations on cache.
  188.  
  189. FC_CMD_SETMEM:   Change the size of cache, the size in bytes you want should
  190.                  be put in fcm_CacheSize.
  191.  
  192. FC_CMD_INFO:     Give informations on cache. At return check the following
  193.                  fields:
  194.                  - fcm_CacheSize size of cache in bytes.
  195.                  - fcm_MemoryUsed memory really use by cache in bytes.
  196.                  - fcm_NbFiles number of files in cache.
  197.                  - fcm_NbLocks number of locks on cache.
  198.  
  199. FILE COMMANDS
  200. -------------
  201.  
  202. With these commands you can load file and delete file from cache.
  203.  
  204.   fcm_FileName contains the name of the file to use, with FG_MULTIPLEDIR flag,
  205.   the server will look for each filename resulting of the concatenation of
  206.   each directory and fcm_FileName, the server will stop at the first filename
  207.   for which a file exist. The array of directory MUST end with NULL.
  208.  
  209.     for ex: with FG_MULTIPLEDIR flag
  210.  
  211.             msg.fcm_FileName = "exec/types.h";
  212.             /* you must puts NULL at the end of array */
  213.             msg.fcm_Directory = { "T:", "", "INCLUDE:", NULL };
  214.             msg.fcm_Flags = FG_MULTIPLEDIR;
  215.  
  216.             The server will look for "exec/types.h", "T:exec/types.h" and
  217.             "INCLUDE:exec/types.h".
  218.  
  219.     for ex: without FG_MULTIPLEDIR flag
  220.  
  221.             msg.fcm_FileName = "INCLUDE:Amiga/exec/types.h";
  222.             msg.fcm_Directory = NULL;
  223.             msg.fcm_Flags = 0;
  224.  
  225.             The server will look only for "INCLUDE:Amiga/exec/types.h".
  226.  
  227.  
  228.   The name of directory must be complete, so you MUST  put a '/' or ':' at the
  229.   end of each directory in fcm_Directory.
  230.  
  231.     for ex:
  232.   
  233.         "INCLUDE:Amiga" is not a correct directory, you should use instead the
  234.         string "INCLUDE:Amiga/".
  235.  
  236.  
  237.   At the return of request, if no error the field fcm_DirIndex will contain
  238.   the directory used.
  239.  
  240.     for ex:
  241.  
  242.       If the fcm_Directory is { "T:", "INCLUDE:Amiga/", "INCLUDE:", NULL }
  243.       and at return fcm_DirIndex contains 1 then directory used was
  244.       "INCLUDE:Amiga/".
  245.  
  246.  
  247. FC_CMD_LOAD:
  248.  
  249.     This command will load a file from the cache, if it is not in cache it
  250.     will load it from disk else if it is already in cache the server will
  251.     verify by default if the file has been modifed (using creation date), if
  252.     the file was modified it will be reloaded in cache else nothing to do.
  253.     If yous set the flags FC_NOUPDATE the server don't verify if the file has
  254.     been changed, this can be a problem, so i sugger you to use instead the
  255.     flag FC_USEWRITEFLAG, with this flag the server will only check files not
  256.     protected against writing. You can protect a lot of file against writing
  257.     (all Amiga includes). the flag FC_USEWRITEFLAG will speed up compilation.
  258.  
  259.     At return of request if fcm_Error is FC_ERR_OK, you will find in fields
  260.     fcm_FileBuffer the address of the block use by the file, fcm_FileLength
  261.     contains the size of the file. Each file is load in a single block of
  262.     memory and the byte following the end of file is reserved for the user
  263.     so you can put a end mark just after the end of file to help to stop
  264.     parsing for example.
  265.  
  266.       STRPTR buffer;
  267.  
  268.       buffer = msg.fcm_FileBuffer;
  269.       /* put a zero end mark after the end of file */
  270.       buffer[msg.fcm_FileLength] = '\0';
  271.  
  272.     
  273. FC_CMD_DELETE: 
  274.  
  275.     This command will remove a file in cache, you can use FC_MULTIPLEDIR flag.
  276.