head	1.8;
access;
symbols
	REL9_0_0:1.8
	REL9_1_ALPHA1:1.8
	REL9_0_RC1:1.8
	REL9_0_BETA4:1.8
	REL9_0_STABLE:1.8.0.14
	REL9_0_BETA3:1.8
	REL9_0_BETA2:1.8
	REL8_0_25:1.3
	REL8_1_21:1.3
	REL8_2_17:1.4
	REL8_3_11:1.5
	REL8_4_4:1.8
	REL9_0_BETA1:1.8
	REL9_0_ALPHA5_BRANCH:1.8.0.12
	REL9_0_ALPHA5:1.8
	REL8_0_24:1.3
	REL8_1_20:1.3
	REL8_2_16:1.4
	REL8_3_10:1.5
	REL8_4_3:1.8
	REL9_0_ALPHA4:1.8
	REL9_0_ALPHA4_BRANCH:1.8.0.10
	REL8_5_ALPHA3:1.8
	REL8_5_ALPHA3_BRANCH:1.8.0.8
	REL8_0_23:1.3
	REL8_1_19:1.3
	REL8_2_15:1.4
	REL8_3_9:1.5
	REL8_4_2:1.8
	REL8_5_ALPHA2:1.8
	REL8_5_ALPHA2_BRANCH:1.8.0.6
	REL8_0_22:1.3
	REL8_1_18:1.3
	REL8_2_14:1.4
	REL8_3_8:1.5
	REL8_4_1:1.8
	REL8_5_ALPHA1:1.8
	REL8_5_ALPHA1_BRANCH:1.8.0.4
	REL8_4_STABLE:1.8.0.2
	REL8_4_0:1.8
	REL8_4_RC2:1.8
	REL8_4_RC1:1.8
	REL8_4_BETA2:1.8
	REL8_4_BETA1:1.8
	REL8_0_21:1.3
	REL8_1_17:1.3
	REL8_2_13:1.4
	REL8_3_7:1.5
	REL8_0_20:1.3
	REL8_1_16:1.3
	REL8_2_12:1.4
	REL8_3_6:1.5
	REL8_0_19:1.3
	REL8_1_15:1.3
	REL8_2_11:1.4
	REL8_3_5:1.5
	REL8_0_18:1.3
	REL8_1_14:1.3
	REL8_2_10:1.4
	REL8_3_4:1.5
	REL8_0_17:1.3
	REL8_1_13:1.3
	REL8_2_9:1.4
	REL8_3_3:1.5
	REL8_0_16:1.3
	REL8_1_12:1.3
	REL8_2_8:1.4
	REL8_3_2:1.5
	REL8_2_7:1.4
	REL8_3_1:1.5
	REL8_3_STABLE:1.5.0.2
	REL8_3_0:1.5
	REL8_3_RC2:1.5
	REL8_0_15:1.3
	REL8_1_11:1.3
	REL8_2_6:1.4
	REL8_3_RC1:1.5
	REL8_3_BETA4:1.5
	REL8_3_BETA3:1.5
	REL8_3_BETA2:1.5
	REL8_3_BETA1:1.5
	REL8_0_14:1.3
	REL8_1_10:1.3
	REL8_2_5:1.4
	REL8_0_13:1.3
	REL8_1_9:1.3
	REL8_2_4:1.4
	REL8_0_12:1.3
	REL8_1_8:1.3
	REL8_2_3:1.4
	REL8_0_11:1.3
	REL8_1_7:1.3
	REL8_2_2:1.4
	REL8_0_10:1.3
	REL8_1_6:1.3
	REL8_2_1:1.4
	REL8_2_STABLE:1.4.0.2
	REL8_2_0:1.4
	REL8_2_RC1:1.4
	REL8_2_BETA3:1.4
	REL8_2_BETA2:1.4
	REL8_1_5:1.3
	REL8_0_9:1.3
	REL8_2_BETA1:1.4
	REL8_0_8:1.3
	REL8_1_4:1.3
	REL8_0_7:1.3
	REL8_1_3:1.3
	REL8_0_6:1.3
	REL8_1_2:1.3
	REL8_0_5:1.3
	REL8_1_1:1.3
	REL8_1_STABLE:1.3.0.6
	REL8_1_0:1.3
	REL8_1_0RC1:1.3
	REL8_1_0BETA4:1.3
	REL8_1_0BETA3:1.3
	REL8_0_4:1.3
	REL8_1_0BETA2:1.3
	REL8_1_0BETA1:1.3
	REL8_0_3:1.3
	REL8_0_2:1.3
	REL8_0_1:1.3
	REL8_0_STABLE:1.3.0.4
	REL8_0_0:1.3.0.2
	REL8_0_0RC5:1.3
	REL8_0_0RC4:1.3
	REL8_0_0RC3:1.3
	REL8_0_0RC2:1.3
	REL8_0_0RC1:1.3
	REL8_0_0BETA5:1.3
	REL8_0_0BETA4:1.3
	REL8_0_0BETA3:1.3
	REL8_0_0BETA2:1.3
	REL8_0_0BETA1:1.2;
locks; strict;
comment	@# @;


1.8
date	2008.11.25.20.28.29;	author alvherre;	state Exp;
branches;
next	1.7;

1.7
date	2008.03.21.13.23.28;	author momjian;	state Exp;
branches;
next	1.6;

1.6
date	2008.03.20.17.55.15;	author momjian;	state Exp;
branches;
next	1.5;

1.5
date	2007.03.13.00.33.42;	author tgl;	state Exp;
branches;
next	1.4;

1.4
date	2006.06.16.18.42.23;	author tgl;	state Exp;
branches;
next	1.3;

1.3
date	2004.08.25.18.43.43;	author tgl;	state Exp;
branches;
next	1.2;

1.2
date	2004.07.31.00.45.40;	author tgl;	state Exp;
branches;
next	1.1;

1.1
date	2004.07.17.03.30.10;	author tgl;	state Exp;
branches;
next	;


desc
@@


1.8
log
@Use ResourceOwners in the snapshot manager, instead of attempting to track them
by hand.  As an added bonus, the new code is smaller and more understandable,
and the ugly loops are gone.

This had been discussed all along but never implemented.  It became clear that
it really needed to be fixed after a bug report by Pavan Deolasee.
@
text
@$PostgreSQL: pgsql/src/backend/utils/resowner/README,v 1.7 2008/03/21 13:23:28 momjian Exp $

Notes About Resource Owners
===========================

ResourceOwner objects are a concept invented to simplify management of
query-related resources, such as buffer pins and table locks.  These
resources need to be tracked in a reliable way to ensure that they will
be released at query end, even if the query fails due to an error.
Rather than expecting the entire executor to have bulletproof data
structures, we localize the tracking of such resources into a single
module.

The design of the ResourceOwner API is modeled on our MemoryContext API,
which has proven very flexible and successful in preventing memory leaks.
In particular we allow ResourceOwners to have child ResourceOwner objects
so that there can be forests of the things; releasing a parent
ResourceOwner acts on all its direct and indirect children as well.

(It is tempting to consider unifying ResourceOwners and MemoryContexts
into a single object type, but their usage patterns are sufficiently
different that this is probably not really a helpful thing to do.)

We create a ResourceOwner for each transaction or subtransaction as
well as one for each Portal.  During execution of a Portal, the global
variable CurrentResourceOwner points to the Portal's ResourceOwner.
This causes operations such as ReadBuffer and LockAcquire to record
ownership of the acquired resources in that ResourceOwner object.

When a Portal is closed, any remaining resources (typically only locks)
become the responsibility of the current transaction.  This is represented
by making the Portal's ResourceOwner a child of the current transaction's
ResourceOwner.  resowner.c automatically transfers the resources to the
parent object when releasing the child.  Similarly, subtransaction
ResourceOwners are children of their immediate parent.

We need transaction-related ResourceOwners as well as Portal-related ones
because transactions may initiate operations that require resources (such
as query parsing) when no associated Portal exists yet.


API Overview
------------

The basic operations on a ResourceOwner are:

* create a ResourceOwner

* associate or deassociate some resource with a ResourceOwner

* release a ResourceOwner's assets (free all owned resources, but not the
  owner object itself)

* delete a ResourceOwner (including child owner objects); all resources
  must have been released beforehand

Locks are handled specially because in non-error situations a lock should
be held until end of transaction, even if it was originally taken by a
subtransaction or portal.  Therefore, the "release" operation on a child
ResourceOwner transfers lock ownership to the parent instead of actually
releasing the lock, if isCommit is true.

Currently, ResourceOwners contain direct support for recording ownership of
buffer pins, lmgr locks, and catcache, relcache, plancache, tupdesc, and
snapshot references.  Other objects can be associated with a ResourceOwner by
recording the address of the owning ResourceOwner in such an object.  There is
an API for other modules to get control during ResourceOwner release, so that
they can scan their own data structures to find the objects that need to be
deleted.

Whenever we are inside a transaction, the global variable
CurrentResourceOwner shows which resource owner should be assigned
ownership of acquired resources.  Note however that CurrentResourceOwner
is NULL when not inside any transaction (or when inside a failed
transaction).  In this case it is not valid to acquire query-lifespan
resources.

When unpinning a buffer or releasing a lock or cache reference,
CurrentResourceOwner must point to the same resource owner that was current
when the buffer, lock, or cache reference was acquired.  It would be possible
to relax this restriction given additional bookkeeping effort, but at present
there seems no need.

Code that transiently changes CurrentResourceOwner should generally use a
PG_TRY construct to ensure that the previous value of CurrentResourceOwner
is restored if control is lost during an error exit.
@


1.7
log
@More README src cleanups.
@
text
@d1 1
a1 1
$PostgreSQL: pgsql/src/backend/utils/resowner/README,v 1.6 2008/03/20 17:55:15 momjian Exp $
d64 5
a68 5
buffer pins, lmgr locks, and catcache, relcache, plancache, and tupdesc
references.  Other objects can be associated with a ResourceOwner by recording
the address of the owning ResourceOwner in such an object.  There is an API
for other modules to get control during ResourceOwner release, so that they
can scan their own data structures to find the objects that need to be
@


1.6
log
@Make source code READMEs more consistent.  Add CVS tags to all README files.
@
text
@d1 1
a1 1
$PostgreSQL: pgsql/src/backend/utils/resowner/README,v 1.5 2007/03/13 00:33:42 tgl Exp $
d4 1
a4 1
---------------------------
@


1.5
log
@First phase of plan-invalidation project: create a plan cache management
module and teach PREPARE and protocol-level prepared statements to use it.
In service of this, rearrange utility-statement processing so that parse
analysis does not assume table schemas can't change before execution for
utility statements (necessary because we don't attempt to re-acquire locks
for utility statements when reusing a stored plan).  This requires some
refactoring of the ProcessUtility API, but it ends up cleaner anyway,
for instance we can get rid of the QueryContext global.

Still to do: fix up SPI and related code to use the plan cache; I'm tempted to
try to make SQL functions use it too.  Also, there are at least some aspects
of system state that we want to ensure remain the same during a replan as in
the original processing; search_path certainly ought to behave that way for
instance, and perhaps there are others.
@
text
@d1 1
a1 1
$PostgreSQL: pgsql/src/backend/utils/resowner/README,v 1.4 2006/06/16 18:42:23 tgl Exp $
d3 1
a3 1
Notes about resource owners
d42 1
a42 1
API overview
@


1.4
log
@Fix problems with cached tuple descriptors disappearing while still in use
by creating a reference-count mechanism, similar to what we did a long time
ago for catcache entries.  The back branches have an ugly solution involving
lots of extra copies, but this way is more efficient.  Reference counting is
only applied to tupdescs that are actually in caches --- there seems no need
to use it for tupdescs that are generated in the executor, since they'll go
away during plan shutdown by virtue of being in the per-query memory context.
Neil Conway and Tom Lane
@
text
@d1 1
a1 1
$PostgreSQL: pgsql/src/backend/utils/resowner/README,v 1.3 2004/08/25 18:43:43 tgl Exp $
d63 7
a69 6
Currently, ResourceOwners contain direct support for recording ownership
of buffer pins, lmgr locks, and catcache, relcache, and tupdesc references.
Other objects can be associated with a ResourceOwner by recording the address
of the owning ResourceOwner in such an object.  There is an API for other
modules to get control during ResourceOwner release, so that they can scan
their own data structures to find the objects that need to be deleted.
@


1.3
log
@Revise ResourceOwner code to avoid accumulating ResourceOwner objects
for every command executed within a transaction.  For long transactions
this was a significant memory leak.  Instead, we can delete a portal's
or subtransaction's ResourceOwner immediately, if we physically transfer
the information about its locks up to the parent owner.  This does not
fully solve the leak problem; we need to do something about counting
multiple acquisitions of the same lock in order to fix it.  But it's a
necessary step along the way.
@
text
@d1 1
a1 1
$PostgreSQL: pgsql-server/src/backend/utils/resowner/README,v 1.2 2004/07/31 00:45:40 tgl Exp $
d64 3
a66 3
of buffer pins, lmgr locks, and catcache and relcache references.  Other
objects can be associated with a ResourceOwner by recording the address of
the owning ResourceOwner in such an object.  There is an API for other
@


1.2
log
@Restructure error handling as recently discussed.  It is now really
possible to trap an error inside a function rather than letting it
propagate out to PostgresMain.  You still have to use AbortCurrentTransaction
to clean up, but at least the error handling itself will cooperate.
@
text
@d1 1
a1 1
$PostgreSQL: pgsql-server/src/backend/utils/resowner/README,v 1.1 2004/07/17 03:30:10 tgl Exp $
d33 3
a35 2
ResourceOwner.  Similarly, subtransaction ResourceOwners are children of
their immediate parent.
d57 6
@


1.1
log
@Invent ResourceOwner mechanism as per my recent proposal, and use it to
keep track of portal-related resources separately from transaction-related
resources.  This allows cursors to work in a somewhat sane fashion with
nested transactions.  For now, cursor behavior is non-subtransactional,
that is a cursor's state does not roll back if you abort a subtransaction
that fetched from the cursor.  We might want to change that later.
@
text
@d1 1
a1 1
$PostgreSQL$
d75 4
@

