Doc/lib/libstatcache.tex

   1 \section{\module{statcache} ---
   2          An optimization of \function{os.stat()}}
   3
   4 \declaremodule{standard}{statcache}
   5 \sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
   6 \modulesynopsis{Stat files, and remember results.}
   7
   8
   9 \deprecated{2.2}{Use \function{\refmodule{os}.stat()} directly instead
  10 of using the cache; the cache introduces a very high level of
  11 fragility in applications using it and complicates application code
  12 with the addition of cache management support.}
  13
  14 The \module{statcache} module provides a simple optimization to
  15 \function{os.stat()}: remembering the values of previous invocations.
  16
  17 The \module{statcache} module defines the following functions:
  18
  19 \begin{funcdesc}{stat}{path}
  20 This is the main module entry-point.
  21 Identical for \function{os.stat()}, except for remembering the result
  22 for future invocations of the function.
  23 \end{funcdesc}
  24
  25 The rest of the functions are used to clear the cache, or parts of
  26 it.
  27
  28 \begin{funcdesc}{reset}{}
  29 Clear the cache: forget all results of previous \function{stat()}
  30 calls.
  31 \end{funcdesc}
  32
  33 \begin{funcdesc}{forget}{path}
  34 Forget the result of \code{stat(\var{path})}, if any.
  35 \end{funcdesc}
  36
  37 \begin{funcdesc}{forget_prefix}{prefix}
  38 Forget all results of \code{stat(\var{path})} for \var{path} starting
  39 with \var{prefix}.
  40 \end{funcdesc}
  41
  42 \begin{funcdesc}{forget_dir}{prefix}
  43 Forget all results of \code{stat(\var{path})} for \var{path} a file in
  44 the directory \var{prefix}, including \code{stat(\var{prefix})}.
  45 \end{funcdesc}
  46
  47 \begin{funcdesc}{forget_except_prefix}{prefix}
  48 Similar to \function{forget_prefix()}, but for all \var{path} values
  49 \emph{not} starting with \var{prefix}.
  50 \end{funcdesc}
  51
  52 Example:
  53
  54 \begin{verbatim}
  55 >>> import os, statcache
  56 >>> statcache.stat('.')
  57 (16893, 2049, 772, 18, 1000, 1000, 2048, 929609777, 929609777, 929609777)
  58 >>> os.stat('.')
  59 (16893, 2049, 772, 18, 1000, 1000, 2048, 929609777, 929609777, 929609777)
  60 \end{verbatim}