tcache-terminology.patch:
------------------
This patch clarifies/fixes some terminology disagreement between the
tcache documentation (in doxygen) and what the tcache actually does.
This patch does not change semantics or behavior, but there is a
function rename. This is basically what is being clarified:
- DELETE: this is the act of a tcache user explicitly removing a
particular entry from the cache
- PURGE: this is the implicit removal of an arbitrary old entry from the
cache due to crossing either the soft or hard limit threshold
The actual name chosen for these operations isn't a big deal, but it
does make things less confusing if the documentation/code/perf counters
all agree on it :)
-Phil
diff -Naur pvfs2-old/src/client/sysint/acache.c pvfs2/src/client/sysint/acache.c
--- pvfs2-old/src/client/sysint/acache.c 2006-04-04 06:47:09.000000000 +0200
+++ pvfs2/src/client/sysint/acache.c 2006-06-07 04:53:10.000000000 +0200
@@ -36,6 +36,7 @@
{"ACACHE_UPDATES", PERF_ACACHE_UPDATES, 0},
{"ACACHE_PURGES", PERF_ACACHE_PURGES, 0},
{"ACACHE_REPLACEMENTS", PERF_ACACHE_REPLACEMENTS, 0},
+ {"ACACHE_DELETIONS", PERF_ACACHE_DELETIONS, 0},
{"ACACHE_ENABLED", PERF_ACACHE_ENABLED, PINT_PERF_PRESERVE},
{NULL, 0, 0},
};
@@ -305,9 +306,12 @@
&tmp_status);
if(ret == 0)
{
- PINT_tcache_purge(acache, tmp_entry);
+ PINT_tcache_delete(acache, tmp_entry);
+ PINT_perf_count(acache_pc, PERF_ACACHE_DELETIONS, 1,
+ PINT_PERF_ADD);
}
+ /* set the new current number of entries */
PINT_perf_count(acache_pc, PERF_ACACHE_NUM_ENTRIES,
acache->num_entries, PINT_PERF_SET);
@@ -371,7 +375,7 @@
struct PINT_tcache_entry* tmp_entry;
struct acache_payload* tmp_payload;
int status;
- int removed;
+ int purged;
unsigned int enabled;
/* skip out immediately if the cache is disabled */
@@ -433,23 +437,31 @@
acache_free_payload(tmp_entry->payload);
tmp_entry->payload = tmp_payload;
ret = PINT_tcache_refresh_entry(acache, tmp_entry);
+ /* this counts as an update of an existing entry */
PINT_perf_count(acache_pc, PERF_ACACHE_UPDATES, 1, PINT_PERF_ADD);
}
else
{
/* not found in cache; insert new payload*/
- ret = PINT_tcache_insert_entry(acache, &refn, tmp_payload, &removed);
- if(removed == 1)
+ ret = PINT_tcache_insert_entry(acache, &refn, tmp_payload, &purged);
+ /* the purged variable indicates how many entries had to be purged
+ * from the tcache to make room for this new one
+ */
+ if(purged == 1)
{
- /* assume an entry was replaced */
- PINT_perf_count(acache_pc, PERF_ACACHE_REPLACEMENTS, removed,
+ /* since only one item was purged, we count this as one item being
+ * replaced rather than as a purge and an insert
+ */
+ PINT_perf_count(acache_pc, PERF_ACACHE_REPLACEMENTS, purged,
PINT_PERF_ADD);
}
else
{
/* otherwise we just purged as part of reclaimation */
- /* NOTE: it is ok if the removed value happens to be zero */
- PINT_perf_count(acache_pc, PERF_ACACHE_PURGES, removed,
+ /* if we didn't purge anything, then the "purged" variable will
+ * be zero and this counter call won't do anything.
+ */
+ PINT_perf_count(acache_pc, PERF_ACACHE_PURGES, purged,
PINT_PERF_ADD);
}
}
diff -Naur pvfs2-old/src/client/sysint/acache.h pvfs2/src/client/sysint/acache.h
--- pvfs2-old/src/client/sysint/acache.h 2005-12-20 01:08:25.000000000 +0100
+++ pvfs2/src/client/sysint/acache.h 2006-06-07 04:53:10.000000000 +0200
@@ -30,6 +30,8 @@
*
* Notes:
* - See tcache for policy documentation
+ * - Note that the acache never explicitly deletes an entry. Instead, it
+ * will invalidate an entry but leave it in the cache.
* .
*
* Operations that may retrieve items from acache:
@@ -56,7 +58,7 @@
* - symlink
* .
*
- * Operations that may purge items from the cache:
+ * Operations that may invalidate items in the cache:
* - remove
* - rename
* - io (size only)
@@ -91,7 +93,8 @@
PERF_ACACHE_UPDATES = 5,
PERF_ACACHE_PURGES = 6,
PERF_ACACHE_REPLACEMENTS = 7,
- PERF_ACACHE_ENABLED = 8,
+ PERF_ACACHE_DELETIONS = 8,
+ PERF_ACACHE_ENABLED = 9,
};
/** acache performance counter keys */
diff -Naur pvfs2-old/src/common/misc/tcache.c pvfs2/src/common/misc/tcache.c
--- pvfs2-old/src/common/misc/tcache.c 2006-05-28 01:47:01.000000000 +0200
+++ pvfs2/src/common/misc/tcache.c 2006-06-07 04:55:05.000000000 +0200
@@ -100,7 +100,7 @@
hash_link);
assert(tmp_entry);
- PINT_tcache_purge(tcache, tmp_entry);
+ PINT_tcache_delete(tcache, tmp_entry);
}
}
@@ -267,14 +267,14 @@
struct PINT_tcache* tcache, /**< pointer to tcache instance */
void* key, /**< that uniquely identifies the payload */
void* payload, /**< data to store in the cache */
- int* removed) /**< number of entries removed to make room */
+ int* purged) /**< number of entries purged to make room */
{
struct PINT_tcache_entry* tmp_entry = NULL;
int tmp_status = 0;
int ret = -1;
- *removed = 0;
-
+ *purged = 0;
+
if(tcache->enable == 0)
{
/* cache has been disabled, do nothing except discard payload*/
@@ -286,7 +286,7 @@
if(tcache->num_entries >= tcache->soft_limit)
{
/* try to reclaim some entries */
- ret = PINT_tcache_reclaim(tcache, removed);
+ ret = PINT_tcache_reclaim(tcache, purged);
if(ret < 0)
{
return(ret);
@@ -313,12 +313,12 @@
/* we don't care about the status- we need to remove an entry
* regardless
*/
- ret = PINT_tcache_purge(tcache, tmp_entry);
+ ret = PINT_tcache_delete(tcache, tmp_entry);
if(ret < 0)
{
return(ret);
}
- *removed = 1;
+ *purged = 1;
}
/* create new entry */
@@ -419,7 +419,7 @@
}
/**
- * Tries to remove and destroy expired entries, up to
+ * Tries to purge and destroy expired entries, up to
* TCACHE_RECLAIM_PERCENTAGE of the current soft limit value. The
* payload_free() function is used to destroy the payload associated with
* reclaimed entries.
@@ -431,7 +431,7 @@
{
struct qlist_head *iterator = NULL, *scratch = NULL;
struct PINT_tcache_entry* tmp_entry;
- int entries_to_remove = (tcache->reclaim_percentage *
+ int entries_to_purge = (tcache->reclaim_percentage *
tcache->soft_limit)/100;
int status = 0;
int ret;
@@ -460,17 +460,17 @@
break;
}
- /* remove entry otherwise */
- ret = PINT_tcache_purge(tcache, tmp_entry);
+ /* delete entry otherwise */
+ ret = PINT_tcache_delete(tcache, tmp_entry);
if(ret < 0)
{
return(ret);
}
- entries_to_remove--;
+ entries_to_purge--;
(*reclaimed)++;
/* break if we hit percentage cap */
- if(entries_to_remove <= 0)
+ if(entries_to_purge <= 0)
{
break;
}
@@ -484,7 +484,7 @@
* will be used to destroy payload data.
* \return 0 on success, -PVFS_error on failure
*/
-int PINT_tcache_purge(
+int PINT_tcache_delete(
struct PINT_tcache* tcache, /**< pointer to tcache instance */
struct PINT_tcache_entry* entry) /**< entry to remove and destroy */
{
diff -Naur pvfs2-old/src/common/misc/tcache.h pvfs2/src/common/misc/tcache.h
--- pvfs2-old/src/common/misc/tcache.h 2006-04-04 06:47:11.000000000 +0200
+++ pvfs2/src/common/misc/tcache.h 2006-06-07 04:53:10.000000000 +0200
@@ -31,10 +31,12 @@
* payload.
* .
* Terminology:
- * - PURGE: Process of removing and delete a single entry from the CACHE
+ * - DELETE: Process of removing a specific entry at the request of the caller
+ * - PURGE: Process of removing an entry because there is not enough room in
+ * the cache (see RECLAIM)
* - EXPIRED: CACHE entry that is older than CACHE_TIMEOUT_MSECS and is
* still in the CACHE
- * - RECLAIM: Process of removing up to CACHE_RECLAIM_PERCENTAGE
+ * - RECLAIM: Process of purging up to CACHE_RECLAIM_PERCENTAGE
* entries from the CACHE that are EXPIRED
* - REFRESH: Process of updating an existing entry in cache with a
* new CACHE_TIMEOUT_MSECS
@@ -150,7 +152,7 @@
struct PINT_tcache* tcache,
void* key,
void* payload,
- int* removed);
+ int* purged);
int PINT_tcache_lookup(
struct PINT_tcache* tcache,
@@ -162,7 +164,7 @@
struct PINT_tcache* tcache,
int* reclaimed);
-int PINT_tcache_purge(
+int PINT_tcache_delete(
struct PINT_tcache* tcache,
struct PINT_tcache_entry* entry);
diff -Naur pvfs2-old/src/io/trove/trove-dbpf/dbpf-keyval-pcache.c pvfs2/src/io/trove/trove-dbpf/dbpf-keyval-pcache.c
--- pvfs2-old/src/io/trove/trove-dbpf/dbpf-keyval-pcache.c 2006-06-02 09:32:03.000000000 +0200
+++ pvfs2/src/io/trove/trove-dbpf/dbpf-keyval-pcache.c 2006-06-07 04:58:17.000000000 +0200
@@ -209,7 +209,7 @@
pcache->tcache, (void *)&key, &tentry, &lookup_status) == 0)
{
/* remove entry that already exists */
- PINT_tcache_purge(pcache->tcache, tentry);
+ PINT_tcache_delete(pcache->tcache, tentry);
}
entry->handle = handle;
diff -Naur pvfs2-old/test/common/misc/test-tcache.c pvfs2/test/common/misc/test-tcache.c
--- pvfs2-old/test/common/misc/test-tcache.c 2006-04-04 06:47:15.000000000 +0200
+++ pvfs2/test/common/misc/test-tcache.c 2006-06-07 04:56:19.000000000 +0200
@@ -200,10 +200,10 @@
/* try destroying an entry */
printf("Destroying an entry...\n");
- ret = PINT_tcache_purge(test_tcache, test_entry);
+ ret = PINT_tcache_delete(test_tcache, test_entry);
if(ret < 0)
{
- PVFS_perror("PINT_tcache_purge", ret);
+ PVFS_perror("PINT_tcache_delete", ret);
return(-1);
}
printf("Done.\n");
_______________________________________________
Pvfs2-developers mailing list
Pvfs2-developers@beowulf-underground.org
http://www.beowulf-underground.org/mailman/listinfo/pvfs2-developers
