source: anuga_core/source/anuga/caching/README.txt @ 5855

Last change on this file since 5855 was 4864, checked in by ole, 17 years ago

Some renaming for consistency reasons
File size: 5.0 KB
Line 
1Documentation for module caching.py
2
3Ole.Nielsen@anu.edu.au
4-----------------------------------
5       
6  USAGE:
7    result = cache(func, args, kwargs, dependencies, cachedir, verbose,
8                   compression, evaluate, test, return_filename)
9
10  ARGUMENTS:
11    func --            Function object (Required)
12    args --            Arguments to func (Default: ())
13    kwargs --          Keyword arguments to func (Default: {})   
14    dependencies --    Filenames that func depends on (Default: None)
15    cachedir --        Directory for cache files (Default: options['cachedir'])
16    verbose --         Flag verbose output to stdout
17                       (Default: options['verbose'])
18    compression --     Flag zlib compression (Default: options['compression'])
19    evaluate --        Flag forced evaluation of func (Default: 0)
20    test --            Flag test for cached results (Default: 0)
21    clear --           Flag delete cached results (Default: 0)   
22    return_filename -- Flag return of cache filename (Default: 0)   
23
24  DESCRIPTION:
25    A Python function call of the form
26
27      result = func(arg1,...,argn)
28
29    can be replaced by
30
31      from caching import cache
32      result = cache(func,(arg1,...,argn))
33
34  The latter form returns the same output as the former but reuses cached
35  results if the function has been computed previously in the same context.
36  'result' and the arguments can be simple types, tuples, list, dictionaries or
37  objects, but not unhashable types such as functions or open file objects.
38  The function 'func' may be a member function of an object or a module.
39
40  This type of caching is particularly useful for computationally intensive
41  functions with few frequently used combinations of input arguments. Note that
42  if the inputs or output are very large caching might not save time because
43  disc access may dominate the execution time.
44
45  If the function definition changes after a result has been cached it will be
46  detected by examining the functions bytecode (co_code, co_consts,
47  func_defualts, co_argcount) and it will be recomputed.
48
49  LIMITATIONS:
50    1 Caching uses the apply function and will work with anything that can be
51      pickled, so any limitation in apply or pickle extends to caching.
52    2 A function to be cached should not depend on global variables
53      as wrong results may occur if globals are changed after a result has
54      been cached.
55
56  -----------------------------------------------------------------------------
57  Additional functionality:
58
59  Keyword args
60    Keyword arguments (kwargs) can be added as a dictionary of keyword: value
61    pairs, following the syntax of the built-in function apply().
62    A Python function call of the form
63   
64      result = func(arg1,...,argn, kwarg1=val1,...,kwargm=valm)   
65
66    is then cached as follows
67
68      from caching import cache
69      result = cache(func,(arg1,...,argn), {kwarg1:val1,...,kwargm:valm})
70   
71    The default value of kwargs is {} 
72
73  Explicit dependencies:
74    The call
75      cache(func,(arg1,...,argn),dependencies = <list of filenames>)
76    Checks the size, creation time and modification time of each listed file.
77    If any file has changed the function is recomputed and the results stored
78    again.
79
80  Specify caching directory:
81    The call
82      cache(func,(arg1,...,argn), cachedir = <cachedir>)
83    designates <cachedir> where cached data are stored. Use ~ to indicate users
84    home directory - not $HOME. The default is ~/.python_cache on a UNIX
85    platform and c:/.python_cache on a Win platform.
86
87  Silent operation:
88    The call
89      cache(func,(arg1,...,argn),verbose=0)
90    suppresses messages to standard output.
91
92  Compression:
93    The call
94      cache(func,(arg1,...,argn),compression=0)
95    disables compression. (Default: compression=1). If the requested compressed
96    or uncompressed file is not there, it'll try the other version.
97   
98    Sometimes compression==1 can cause a MemoryException.
99    In that case try the uncompressed version.
100
101  Forced evaluation:
102    The call
103      cache(func,(arg1,...,argn),evaluate=1)
104    forces the function to evaluate even though cached data may exist.
105
106  Testing for presence of cached result:
107    The call
108      cache(func,(arg1,...,argn),test=1)
109    retrieves cached result if it exists, otherwise None. The function will not
110    be evaluated. If both evaluate and test are switched on, evaluate takes
111    precedence.
112   
113  Obtain cache filenames:
114    The call   
115      cache(func,(arg1,...,argn),return_filename=1)
116    returns the hashed base filename under which this function and its
117    arguments would be cached
118
119  Clearing cached results:
120    The call
121      cache(func,'clear')
122    clears all cached data for 'func' and
123      cache('clear')
124    clears all cached data.
125 
126    NOTE: The string 'clear' can be passed an *argument* to func using
127      cache(func,('clear',)) or cache(func,tuple(['clear'])).
128
129    New form of clear:
130      cache(func,(arg1,...,argn),clear=1)
131    clears cached data for particular combination func and args
Note: See TracBrowser for help on using the repository browser.