4 * FSCache - a glib-style object for caching files
5 * Copyright (C) 2002, the ROX-Filer team.
7 * A cache object holds stat details about files in a hash table, along
8 * with user-specified data. When you want to read in a file try to
9 * get the data via the cache - if the file is cached AND has not been
10 * modified since it was last loaded the cached copy is returned, else the
13 * The actual data need not be the raw file contents - a user specified
14 * function loads the file and associates data with the file in the cache.
16 * This program is free software; you can redistribute it and/or modify it
17 * under the terms of the GNU General Public License as published by the Free
18 * Software Foundation; either version 2 of the License, or (at your option)
21 * This program is distributed in the hope that it will be useful, but WITHOUT
22 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
23 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
26 * You should have received a copy of the GNU General Public License along with
27 * this program; if not, write to the Free Software Foundation, Inc., 59 Temple
28 * Place, Suite 330, Boston, MA 02111-1307 USA
37 #define UPTODATE(data, info) \
38 (data->m_time == info.st_mtime \
39 && data->length == info.st_size \
40 && data->mode == info.st_mode) \
43 /* Static prototypes */
45 static guint
hash_key(gconstpointer key
);
46 static gint
cmp_stats(gconstpointer a
, gconstpointer b
);
47 static void destroy_hash_entry(gpointer key
, gpointer data
, gpointer user_data
);
48 static gboolean
purge_hash_entry(gpointer key
, gpointer data
,
50 static GFSCacheData
*lookup_internal(GFSCache
*cache
, char *pathname
,
51 FSCacheLookup lookup_type
);
61 /****************************************************************
62 * EXTERNAL INTERFACE *
63 ****************************************************************/
66 /* Create a new GFSCache object and return a pointer to it.
68 * When someone tries to lookup a file which is not in the cache,
70 * It should load the file and return a pointer to an object for the file.
71 * The object should have a ref count of 1.
73 * ref() and unref() should modify the reference counter of the object.
74 * When the counter reaches zero, destroy the object.
76 * getref() returns the current value. This can be used to stop objects
77 * being purged from the cache while they are being used elsewhere, which
78 * is rather wasteful. If NULL then this check isn't done.
80 * update() will be called to update an object which is cached, but
81 * out of date. If NULL, the object will be unref'd and load() used
84 * 'user_data' will be passed to all of the above functions.
86 GFSCache
*g_fscache_new(GFSLoadFunc load
,
95 cache
= g_new(GFSCache
, 1);
96 cache
->inode_to_stats
= g_hash_table_new(hash_key
, cmp_stats
);
100 cache
->getref
= getref
;
101 cache
->update
= update
;
102 cache
->user_data
= user_data
;
107 void g_fscache_destroy(GFSCache
*cache
)
109 g_return_if_fail(cache
!= NULL
);
111 g_hash_table_foreach(cache
->inode_to_stats
, destroy_hash_entry
, cache
);
112 g_hash_table_destroy(cache
->inode_to_stats
);
117 /* Call the ref() user function for this object */
118 void g_fscache_data_ref(GFSCache
*cache
, gpointer data
)
120 g_return_if_fail(cache
!= NULL
);
123 cache
->ref(data
, cache
->user_data
);
126 /* Call the unref() user function for this object */
127 void g_fscache_data_unref(GFSCache
*cache
, gpointer data
)
129 g_return_if_fail(cache
!= NULL
);
132 cache
->unref(data
, cache
->user_data
);
135 /* Find the data for this file in the cache, loading it into
136 * the cache if it isn't there already.
138 * Remember to g_fscache_data_unref() the returned value when
139 * you're done with it.
141 * Returns NULL on failure.
143 gpointer
g_fscache_lookup(GFSCache
*cache
, char *pathname
)
145 return g_fscache_lookup_full(cache
, pathname
,
146 FSCACHE_LOOKUP_CREATE
, NULL
);
149 /* Force this already-loaded item into the cache. The cache will
150 * ref the object if it wants to keep it.
151 * If update_details is FALSE then the timestamp and size aren't recorded.
152 * Generally, you call this function with update_details = TRUE when you
153 * start loading some data and then with update_details = FALSE when you
154 * put in the loaded object.
156 void g_fscache_insert(GFSCache
*cache
, char *pathname
, gpointer obj
,
157 gboolean update_details
)
161 data
= lookup_internal(cache
, pathname
,
162 update_details
? FSCACHE_LOOKUP_INIT
163 : FSCACHE_LOOKUP_INSERT
);
169 cache
->unref(data
->data
, cache
->user_data
);
172 cache
->ref(data
->data
, cache
->user_data
);
175 /* As g_fscache_lookup, but 'lookup_type' controls what happens if the data
177 * If found is not NULL, use it to indicate whether something is being
178 * returned (a NULL return could indicate that the data is cached, but
181 gpointer
g_fscache_lookup_full(GFSCache
*cache
, char *pathname
,
182 FSCacheLookup lookup_type
,
187 g_return_val_if_fail(lookup_type
!= FSCACHE_LOOKUP_INIT
, NULL
);
189 data
= lookup_internal(cache
, pathname
, lookup_type
);
202 cache
->ref(data
->data
, cache
->user_data
);
207 /* Call the update() function on this item if it's in the cache
208 * AND it's out-of-date.
210 void g_fscache_may_update(GFSCache
*cache
, char *pathname
)
216 g_return_if_fail(cache
!= NULL
);
217 g_return_if_fail(pathname
!= NULL
);
218 g_return_if_fail(cache
->update
!= NULL
);
220 if (mc_stat(pathname
, &info
))
223 key
.device
= info
.st_dev
;
224 key
.inode
= info
.st_ino
;
226 data
= g_hash_table_lookup(cache
->inode_to_stats
, &key
);
228 if (data
&& !UPTODATE(data
, info
))
230 cache
->update(data
->data
, pathname
, cache
->user_data
);
231 data
->m_time
= info
.st_mtime
;
232 data
->length
= info
.st_size
;
233 data
->mode
= info
.st_mode
;
237 /* Call the update() function on this item iff it's in the cache. */
238 void g_fscache_update(GFSCache
*cache
, char *pathname
)
244 g_return_if_fail(cache
!= NULL
);
245 g_return_if_fail(pathname
!= NULL
);
246 g_return_if_fail(cache
->update
!= NULL
);
248 if (mc_stat(pathname
, &info
))
251 key
.device
= info
.st_dev
;
252 key
.inode
= info
.st_ino
;
254 data
= g_hash_table_lookup(cache
->inode_to_stats
, &key
);
258 cache
->update(data
->data
, pathname
, cache
->user_data
);
259 data
->m_time
= info
.st_mtime
;
260 data
->length
= info
.st_size
;
261 data
->mode
= info
.st_mode
;
265 /* Remove all cache entries last accessed more than 'age' seconds
268 void g_fscache_purge(GFSCache
*cache
, gint age
)
270 struct PurgeInfo info
;
272 g_return_if_fail(cache
!= NULL
);
276 info
.now
= time(NULL
);
278 g_hash_table_foreach_remove(cache
->inode_to_stats
, purge_hash_entry
,
283 /****************************************************************
284 * INTERNAL FUNCTIONS *
285 ****************************************************************/
288 /* Generate a hash number for some stats */
289 static guint
hash_key(gconstpointer key
)
291 GFSCacheKey
*stats
= (GFSCacheKey
*) key
;
296 /* See if two stats blocks represent the same file */
297 static gint
cmp_stats(gconstpointer a
, gconstpointer b
)
299 GFSCacheKey
*c
= (GFSCacheKey
*) a
;
300 GFSCacheKey
*d
= (GFSCacheKey
*) b
;
302 return c
->device
== d
->device
&& c
->inode
== d
->inode
;
305 static void destroy_hash_entry(gpointer key
, gpointer data
, gpointer user_data
)
307 GFSCache
*cache
= (GFSCache
*) user_data
;
308 GFSCacheData
*cache_data
= (GFSCacheData
*) data
;
311 cache
->unref(cache_data
->data
, cache
->user_data
);
317 static gboolean
purge_hash_entry(gpointer key
, gpointer data
,
320 struct PurgeInfo
*info
= (struct PurgeInfo
*) user_data
;
321 GFSCacheData
*cache_data
= (GFSCacheData
*) data
;
322 GFSCache
*cache
= info
->cache
;
324 /* It's wasteful to remove an entry if someone else is using it */
326 cache
->getref(cache_data
->data
, cache
->user_data
) > 1)
329 if (cache_data
->last_lookup
<= info
->now
330 && cache_data
->last_lookup
>= info
->now
- info
->age
)
334 cache
->unref(cache_data
->data
, cache
->user_data
);
342 /* As for g_fscache_lookup_full, but return the GFSCacheData rather than
343 * the data it contains. Doesn't increment the refcount.
345 static GFSCacheData
*lookup_internal(GFSCache
*cache
, char *pathname
,
346 FSCacheLookup lookup_type
)
352 g_return_val_if_fail(cache
!= NULL
, NULL
);
353 g_return_val_if_fail(pathname
!= NULL
, NULL
);
355 if (mc_stat(pathname
, &info
))
358 key
.device
= info
.st_dev
;
359 key
.inode
= info
.st_ino
;
361 data
= g_hash_table_lookup(cache
->inode_to_stats
, &key
);
365 /* We've cached this file already */
367 if (lookup_type
== FSCACHE_LOOKUP_PEEK
||
368 lookup_type
== FSCACHE_LOOKUP_INSERT
)
369 goto out
; /* Never update on peeks */
371 if (lookup_type
== FSCACHE_LOOKUP_INIT
)
374 /* Is it up-to-date? */
376 if (UPTODATE(data
, info
))
379 if (lookup_type
== FSCACHE_LOOKUP_ONLY_NEW
)
384 cache
->update(data
->data
, pathname
, cache
->user_data
);
388 cache
->unref(data
->data
, cache
->user_data
);
394 GFSCacheKey
*new_key
;
396 if (lookup_type
!= FSCACHE_LOOKUP_CREATE
&&
397 lookup_type
!= FSCACHE_LOOKUP_INIT
)
400 new_key
= g_memdup(&key
, sizeof(key
));
402 data
= g_new(GFSCacheData
, 1);
405 g_hash_table_insert(cache
->inode_to_stats
, new_key
, data
);
409 data
->m_time
= info
.st_mtime
;
410 data
->length
= info
.st_size
;
411 data
->mode
= info
.st_mode
;
413 if (data
->data
== NULL
&&
414 lookup_type
!= FSCACHE_LOOKUP_INIT
&&
415 lookup_type
!= FSCACHE_LOOKUP_INSERT
)
417 /* Create the object for the file (ie, not an update) */
419 data
->data
= cache
->load(pathname
, cache
->user_data
);
422 data
->last_lookup
= time(NULL
);