database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-06-14 18:42:34 +03:00
Code Activity

Change SearchSysCache coding conventions so that a reference count is

Browse Source 
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.
This commit is contained in:
Tom Lane
2000-11-16 22:30:52 +00:00
parent cff23842a4
commit a933ee38bb
95 changed files with 2672 additions and 2314 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
doc/src/FAQ/FAQ_DEV.html
View File

@ -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>