Annotation of libwww/Library/src/HTCache.html, revision 2.13
2.1 frystyk 1: <HTML>
2: <HEAD>
2.10 frystyk 3: <TITLE>W3C Reference Library libwww Persistent Cache Manager</TITLE>
2.1 frystyk 4: </HEAD>
5: <BODY>
2.10 frystyk 6: <H1>
7: Persistent Cache Manager
8: </H1>
2.1 frystyk 9: <PRE>
10: /*
11: ** (c) COPYRIGHT MIT 1995.
12: ** Please first read the full copyright statement in the file COPYRIGH.
13: */
14: </PRE>
2.10 frystyk 15: <P>
2.11 frystyk 16: The cache contains details of persistent files which contain the contents
2.10 frystyk 17: of remote documents. The existing cache manager is somewhat naive - especially
2.11 frystyk 18: in its garbage collection but it is just an example of how it can be
19: done.However, it is a fully HTTP/1.1 compliant cache manager. More advanced
20: implementations are welcome!
2.10 frystyk 21: <P>
22: This module is implemented by <A HREF="HTCache.c">HTCache.c</A>, and it is
23: a part of the <A HREF="http://www.w3.org/pub/WWW/Library/">W3C Reference
24: Library</A>.
2.1 frystyk 25: <PRE>
26: #ifndef HTCACHE_H
27: #define HTCACHE_H
28:
2.10 frystyk 29: #include "WWWLib.h"
2.1 frystyk 30: </PRE>
2.10 frystyk 31: <H2>
2.11 frystyk 32: Initialize and Terminate the Persistent Cache
2.10 frystyk 33: </H2>
34: <P>
2.11 frystyk 35: If `cache_root' is <CODE>NULL</CODE> then use <CODE>HT_CACHE_ROOT</CODE>
36: which by default is set to "<CODE>/tmp/w3c-lib</CODE>". The
37: <CODE>cache_root</CODE> location does not have to exist, it will be created
38: automatically if not. An empty string will make '/' as cache root. The size
39: is the total size in MBytes - the default size is 20M. The cache can not
40: be less than 5M. We can only enable the cache if we are in
41: <A HREF="HTLib.html#Secure">secure mode </A>where we can not access the local
42: file system. This is for example the case if using an application as
43: a telnet shell.
44: <PRE>
45: extern BOOL HTCacheInit (const char * cache_root, int size);
2.10 frystyk 46: </PRE>
47: <P>
2.11 frystyk 48: After the cache has been terminated it can not be used anymore unless you
49: do another <CODE>HTCacheInit()</CODE> call.
50: <PRE>
51: extern BOOL HTCacheTerminate (void);
2.10 frystyk 52: </PRE>
2.11 frystyk 53: <H2>
54: Cache Mode Parameters
55: </H2>
2.10 frystyk 56: <P>
2.11 frystyk 57: The persistent cache has a set of overall parameters that you can adust
2.10 frystyk 58: <H3>
2.11 frystyk 59: Enable and Disable the Cache
2.10 frystyk 60: </H3>
61: <P>
2.11 frystyk 62: The cache can be temporarily suspended by using the enable/disable flag.
63: This does not prevent the cache from being enabled/disable at a later point
64: in time.
65: <PRE>
66: extern void HTCacheMode_setEnabled (BOOL mode);
67: extern BOOL HTCacheMode_enabled (void);
2.10 frystyk 68: </PRE>
69: <H3>
2.11 frystyk 70: What is the current Cache Root?
2.10 frystyk 71: </H3>
72: <P>
2.11 frystyk 73: Return the value of the cache root. The cache root can only be set through
74: the <CODE>HTCacheInit()</CODE> function
75: <PRE>
76: extern const char * HTCacheMode_getRoot (void);
2.10 frystyk 77: </PRE>
78: <H3>
2.11 frystyk 79: Total Cache Size
2.10 frystyk 80: </H3>
81: <P>
2.11 frystyk 82: We set the default cache size to 20M. We set the minimum size to 5M in order
83: not to get into weird problems while writing the cache. The size is indicated
84: in Mega bytes. The size is given in MBytes and is also returned in MBytes.
85: <PRE>
86: extern BOOL HTCacheMode_setMaxSize (int size);
87: extern int HTCacheMode_maxSize (void);
2.10 frystyk 88: </PRE>
89: <H3>
90: How do we handle Expiration of Cached Objects?
91: </H3>
92: <P>
93: There are various ways of handling <CODE>Expires</CODE> header when met in
2.11 frystyk 94: a <I>history list</I>. Either it can be ignored all together, the user can
95: be notified with a warning, or the document can be reloaded automatically.
96: This flag decides what action to be taken. The default action is
2.10 frystyk 97: <CODE>HT_EXPIRES_IGNORE</CODE>. In <CODE>HT_EXPIRES_NOTIFY</CODE> mode ,
98: we push a message on to the Error stack which is presented to the user.
2.4 frystyk 99: <PRE>
100: typedef enum _HTExpiresMode {
101: HT_EXPIRES_IGNORE = 0,
102: HT_EXPIRES_NOTIFY,
103: HT_EXPIRES_AUTO
104: } HTExpiresMode;
105:
2.11 frystyk 106: extern void HTCacheMode_setExpires (HTExpiresMode mode);
107: extern HTExpiresMode HTCacheMode_expires (void);
108: </PRE>
109: <H3>
110: Disconnected Operation
111: </H3>
112: <P>
113: The cache can be set to handle disconnected operation where it does not use
114: the network to validate entries and do not attempt to load new versions.
115: All requests that can not be fulfilled by the cache will be returned with
116: a <CODE>"504 Gateway Timeout"</CODE> response. There are two modes of how
117: the cache can operate in disconnected mode: it can use diconnected mode on
118: its own persistent cache or it can forward the disconnected request to a
119: proxy cache, for example. The latter mode only really makes sense when you
120: are using a proxy, of course.
121: <PRE>
122: typedef enum _HTDisconnectedMode {
123: HT_DISCONNECT_NONE = 0,
124: HT_DISCONNECT_NORMAL = 1,
125: HT_DISCONNECT_EXTERNAL = 2
126: } HTDisconnectedMode;
127:
128: extern void HTCacheMode_setDisconnected (HTDisconnectedMode mode);
129: extern HTDisconnectedMode HTCacheMode_disconnected (void);
130: extern BOOL HTCacheMode_isDisconnected (HTReload mode);
2.1 frystyk 131: </PRE>
2.10 frystyk 132: <H2>
2.12 frystyk 133: The Cache Index
134: </H2>
135: <P>
136: The persistent cache keeps an index of its current entries so that garbage
137: collection and lookup becomes more efficient. This index is stored automatically
138: at regular intervals so that we don't get out of sync. Also, it is automatically
139: loaded at startup and saved at closedown of the cache.
140: <H3>
141: Reading the Cache Index
142: </H3>
143: <P>
144: Read the saved set of cached entries from disk. we only allow the index ro
145: be read when there is no entries in memory. That way we can ensure consistancy.
146: <PRE>
147: extern BOOL HTCacheIndex_read (const char * cache_root);
148: </PRE>
149: <H3>
150: Write the Cache Index
151: </H3>
152: <P>
153: Walk through the list of cached objects and save them to disk. We override
154: any existing version but that is normally OK as we have already read its
155: contents.
156: <PRE>
157: extern BOOL HTCacheIndex_write (const char * cache_root);
158: </PRE>
159: <H2>
2.11 frystyk 160: The HTCache Object
2.10 frystyk 161: </H2>
162: <P>
2.11 frystyk 163: The cache object is what we store about a cached objet in memory.
164: <PRE>
165: typedef struct _HTCache HTCache;
166: </PRE>
167: <H3>
2.12 frystyk 168: Create and Update a Cache Object
2.11 frystyk 169: </H3>
170: <P>
2.10 frystyk 171: Filling the cache is done as all other transportation of bulk data in libwww
172: using <A HREF="HTStream.html">streams</A>. The cache object creater is a
173: stream which in many cases sits on a <A HREF="HTTee.html">T stream</A> so
174: that we get the original feed and at the same time can parse the contents.
2.11 frystyk 175: <PRE>
176: extern HTConverter HTCacheWriter;
177: </PRE>
2.12 frystyk 178: <P>
179: This function writes the metainformation along with the data object stored
180: by the HTCacheWriter stream above. If no headers are available then the meta
181: file is empty
182: <PRE>
183: extern BOOL HTCache_writeMeta (HTCache * cache, HTRequest * request);
184: </PRE>
185: <P>
186: In case we received a "<CODE>304 Not Modified</CODE>" response then we do
187: not have to tough the body but must merge the metainformation with the previous
188: version. Therefore we need a special metainformation update function.
189: <PRE>
190: extern BOOL HTCache_updateMeta (HTCache * cache, HTRequest * request);
191: </PRE>
2.11 frystyk 192: <H3>
193: Load a Cached Object
194: </H3>
195: <P>
196: Loading a cached object is also done as all other loads in libwww by using
197: a <A HREF="HTProt.html">protocol load module</A>. For the moment, this load
198: function handles the persistent cache as if it was on local file but in fact
199: it could be anywhere.
200: <PRE>
201: extern HTEventCallback HTLoadCache;
202: </PRE>
203: <H3>
204: Delete a Cache Object
205: </H3>
206: <P>
207: Remove a HTCache object from memory and from disk. You must explicitly remove
208: a lock before this operation can succeed
209: <PRE>
210: extern BOOL HTCache_remove (HTCache * cache);
211: </PRE>
212: <H3>
2.13 ! frystyk 213: Delete All Cache Objects in Memory
2.11 frystyk 214: </H3>
215: <P>
216: Destroys all cache entried in memory but does not write anything to disk.
217: Use the index methods above for doing that. We do not delete the disk contents.
218: <PRE>
219: extern BOOL HTCache_deleteAll (void);
2.10 frystyk 220: </PRE>
221: <H3>
2.13 ! frystyk 222: Delete all Cache Object and File Entries
! 223: </H3>
! 224: <P>
! 225: Destroys all cache entried in memory <B>and</B> on disk. This call basically
! 226: resets the cache to the inital state but it does not terminate the cache.
! 227: That is, you don't have to reinitialize the cache before you can use it again.
! 228: <PRE>
! 229: extern BOOL HTCache_flushAll (void);
! 230: </PRE>
! 231: <H3>
2.11 frystyk 232: Find a Cached Object
2.10 frystyk 233: </H3>
234: <P>
235: Verifies if a cache object exists for this URL and if so returns a URL for
236: the cached object. It does not verify whether the object is valid or not,
237: for example it might have expired. Use the cache validation methods for checking
238: this.
2.11 frystyk 239: <PRE>
240: extern HTCache * HTCache_find (HTParentAnchor * anchor);
241: </PRE>
242: <H3>
243: Set the Size of a Cached Object
244: </H3>
245: <P>
246: Set and get the size of a cached object. We don't consider the metainformation
247: as part of the size which is the the reason for why the min cache size should
248: not be less than 5M. When we set the cache size we also check whether we
249: should run the gc or not.
250: <PRE>
251: extern BOOL HTCache_setSize (HTCache * cache, long size);
252: extern long HTCache_size (HTCache * cache);
253: </PRE>
254: <H3>
255: Verify if an Object is Fresh
256: </H3>
257: <P>
258: This function checks whether a document has expired or not. The check is
259: based on the metainformation passed in the anchor object The function returns
260: the level of validation needed for getting a fresh version. We also check
261: the cache control directives in the request to see if they change the freshness
262: discission.
263: <PRE>
264: extern HTReload HTCache_isFresh (HTCache * me, HTRequest * request);
265: </PRE>
266: <H3>
267: Register a Cache Hit
268: </H3>
269: <P>
270: As a cache hit may occur several places, we have a public function where
271: we can declare a download to be a true cache hit. The number of hits a cache
272: object has affects its status when we are doing garbage collection.
273: <PRE>
274: extern BOOL HTCache_addHit (HTCache * cache);
275: </PRE>
276: <H3>
277: Find the Location of a Cached Object
278: </H3>
279: <P>
280: Is we have a valid entry in the cache then we also need a location where
281: we can get it. Hopefully, we may be able to access it thourgh one of our
282: protocol modules, for example the <A HREF="WWWFile.html">local file module</A>.
283: The name returned is in URL syntax and must be freed by the caller
284: <PRE>
285: extern char * HTCache_name (HTCache * cache);
286: </PRE>
287: <H3>
288: Locking a Cache Object
289: </H3>
290: <P>
291: While we are creating a new cache object or while we are validating an existing
292: one, we must have a lock on the entry so that not other requests can get
293: to it in the mean while. A lock can be broken if the same request tries to
294: create the cache entry again. This means that we have tried to validate the
295: cache entry but we got a new shipment of bytes back from the origin server
296: or an intermediary proxy.
297: <PRE>
298: extern BOOL HTCache_getLock (HTCache * cache, HTRequest * request);
299: extern BOOL HTCache_breakLock (HTCache * cache, HTRequest * request);
300: extern BOOL HTCache_hasLock (HTCache * cache);
301: extern BOOL HTCache_releaseLock (HTCache * cache);
2.1 frystyk 302: </PRE>
303: <PRE>
304: #endif
305: </PRE>
2.10 frystyk 306: <P>
307: <HR>
2.9 frystyk 308: <ADDRESS>
2.13 ! frystyk 309: @(#) $Id: HTCache.html,v 2.12 1996/09/09 16:23:03 frystyk Exp $
2.9 frystyk 310: </ADDRESS>
2.10 frystyk 311: </BODY></HTML>
Webmaster
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to HTCache.html CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Public] / libwww / Library / src