database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-07-14 08:21:07 +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/FAQ_DEV
View File

@ -311,7 +311,7 @@ c-mode)
9) How do I efficiently access information in tables from the backend code?
You first need to find the tuples(rows) you are interested in. There
are two ways. First, SearchSysCacheTuple() and related functions allow
are two ways. First, SearchSysCache() 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 accessing the
@ -321,14 +321,13 @@ c-mode)
src/backend/utils/cache/lsyscache.c contains many column-specific
cache lookup functions.
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 SearchSysCacheTupleCopy() in these cases, and pfree() the tuple
when you are done.
The rows returned are cache-owned versions of the heap rows. Therefore,
you must not modify or delete the tuple returned by SearchSysCache().
What you *should* do is release it with ReleaseSysCache() when you are
done using it; this informs the cache that it can discard that tuple
if necessary. If you neglect to call ReleaseSysCache(), then the cache
entry will remain locked in the cache until end of transaction, which is
tolerable but not very desirable.
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
@ -344,7 +343,9 @@ c-mode)
You can also use heap_fetch() to fetch rows by block number/offset.
While scans automatically lock/unlock rows from the buffer cache, with
heap_fetch(), you must pass a Buffer pointer, and ReleaseBuffer() it
when completed. Once you have the row, you can get data that is common
when completed.
Once you have the row, you can get data that is common
to all tuples, like t_self and t_oid, by merely accessing the
HeapTuple structure entries. If you need a table-specific column, you
should take the HeapTuple pointer, and use the GETSTRUCT() macro to
@ -355,15 +356,16 @@ c-mode)
((Form_pg_class) GETSTRUCT(tuple))->relnatts
You should not directly change live tuples in this way. The best way
is to use heap_tuplemodify() and pass it your palloc'ed tuple, and the
values you want changed. It returns another palloc'ed tuple, which you
You must not directly change live tuples in this way. The best way
is to use heap_modifytuple() and pass it your original tuple, and the
values you want changed. It returns a palloc'ed tuple, which you
pass to heap_replace(). You can delete tuples by passing the tuple's
t_self to heap_destroy(). You can use it for heap_update() 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 heap_getnext(), heap_endscan, or ReleaseBuffer(), in the
heap_fetch() case. Or it may be a palloc'ed tuple, that you must
t_self to heap_destroy(). You use t_self for heap_update() too.
Remember, tuples can be either system cache copies, which may go away
after you call ReleaseSysCache(), or read directly from disk buffers,
which go away when you heap_getnext(), heap_endscan, or ReleaseBuffer(),
in the heap_fetch() case. Or it may be a palloc'ed tuple, that you must
pfree() when finished.
10) What is elog()?

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>