Change SearchSysCache coding conventions so that a reference count is

maintained for each cache entry.  A cache entry will not be freed until
the matching ReleaseSysCache call has been executed.  This eliminates
worries about cache entries getting dropped while still in use.  See
my posting to pg-hackers of even date for more info.

1 files changed, 18 insertions, 20 deletions

diff --git a/doc/src/FAQ/FAQ_DEV.html b/doc/src/FAQ/FAQ_DEV.html
index e62d0c3533a..3c1433d345b 100644
--- a/doc/src/FAQ/FAQ_DEV.html
+++ b/doc/src/FAQ/FAQ_DEV.html
@@ -358,7 +358,7 @@ cases where Name and char * are used interchangeably.<P>
 tables from the backend code?</H3><P>
 
 You first need to find the tuples(rows) you are interested in.  There
-are two ways.  First, <I>SearchSysCacheTuple()</I> and related functions
+are two ways.  First, <I>SearchSysCache()</I> and related functions
 allow you to query the system catalogs.  This is the preferred way to
 access system tables, because the first call to the cache loads the
 needed rows, and future requests can return the results without
@@ -367,15 +367,14 @@ to look up tuples.  A list of available caches is located in
 <I>src/backend/utils/cache/syscache.c.</I> 
 <I>src/backend/utils/cache/lsyscache.c</I> contains many column-specific
 cache lookup functions.<P>
-
-The rows returned are cached-owned versions of the heap rows.  They are
-invalidated when the base table changes.   Because the cache is local to
-each backend, you may use the pointer returned from the cache for short
-periods without making a copy of the tuple.  If you send the pointer
-into a large function that will be doing its own cache lookups, it is
-possible the cache entry may be flushed, so you should use
-<I>SearchSysCacheTupleCopy()</I> in these cases, and <I>pfree()</I> the
-tuple when you are done.<P>
+   
+The rows returned are cache-owned versions of the heap rows.  Therefore, you
+must not modify or delete the tuple returned by <I>SearchSysCache()</I>.  What
+you <I>should</I> do is release it with <I>ReleaseSysCache()</I> when you are
+done using it; this informs the cache that it can discard that tuple if
+necessary.  If you neglect to call <I>ReleaseSysCache()</I>, then the cache
+entry will remain locked in the cache until end of transaction, which is
+tolerable but not very desirable.<P>
 
 If you can't use the system cache, you will need to retrieve the data
 directly from the heap table, using the buffer cache that is shared by
@@ -392,12 +391,11 @@ and only the valid rows returned.<P>
 You can also use <I>heap_fetch()</I> to fetch rows by block
 number/offset.  While scans automatically lock/unlock rows from the
 buffer cache, with <I>heap_fetch(),</I> you must pass a <I>Buffer</I>
-pointer, and <I>ReleaseBuffer()</I> it when completed.
+pointer, and <I>ReleaseBuffer()</I> it when completed.<P>
 
 Once you have the row, you can get data that is common to all tuples,
 like <I>t_self</I> and <I>t_oid,</I> by merely accessing the
 <I>HeapTuple</I> structure entries.
-
 If you need a table-specific column, you should take the HeapTuple
 pointer, and use the <I>GETSTRUCT()</I> macro to access the
 table-specific start of the tuple.  You then cast the pointer as a
@@ -411,18 +409,18 @@ the columns by using a structure pointer:
 </CODE>
 </PRE>
 
-You should not directly change <I>live</I> tuples in this way.  The best
-way is to use <I>heap_tuplemodify()</I> and pass it your palloc'ed
-tuple, and the values you want changed.  It returns another palloc'ed
+You must not directly change <I>live</I> tuples in this way.  The best
+way is to use <I>heap_modifytuple()</I> and pass it your original
+tuple, and the values you want changed.  It returns a palloc'ed
 tuple, which you pass to <I>heap_replace().</I>
 
 You can delete tuples by passing the tuple's <I>t_self</I> to
-<I>heap_destroy().</I>  You can use it for <I>heap_update()</I> too.
+<I>heap_destroy().</I>  You use <I>t_self</I> for <I>heap_update()</I> too.
 
-Remember, tuples can be either system cache versions, which may go away
-soon after you get them, buffer cache versions, which go away when
-you <I>heap_getnext(),</I> <I>heap_endscan,</I> or
-<I>ReleaseBuffer()</I>, in the <I>heap_fetch()</I> case.  Or it may be a
+Remember, tuples can be either system cache copies, which may go away after
+you call <I>ReleaseSysCache()</I>, or read directly from disk buffers, which
+go away when you <I>heap_getnext()</I>, <I>heap_endscan</I>, or
+<I>ReleaseBuffer()</I>, in the <I>heap_fetch()</I> case. Or it may be a
 palloc'ed tuple, that you must <I>pfree()</I> when finished.
 
 <H3><a name="10">10</a>)	What is elog()?</H3><P>