← Back to branch summary

~ubuntu-branches/ubuntu/precise/postgresql-9.1/precise-security

« back to all changes in this revision

Viewing changes to src/backend/utils/resowner/README

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2011-05-11 10:41:53 UTC
  • Revision ID: james.westby@ubuntu.com-20110511104153-psbh2o58553fv1m0
Tags: upstream-9.1~beta1
Import upstream version 9.1~beta1

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/backend/utils/resowner/README
 
1
src/backend/utils/resowner/README
 
2
 
 
3
Notes About Resource Owners
 
4
===========================
 
5
 
 
6
ResourceOwner objects are a concept invented to simplify management of
 
7
query-related resources, such as buffer pins and table locks.  These
 
8
resources need to be tracked in a reliable way to ensure that they will
 
9
be released at query end, even if the query fails due to an error.
 
10
Rather than expecting the entire executor to have bulletproof data
 
11
structures, we localize the tracking of such resources into a single
 
12
module.
 
13
 
 
14
The design of the ResourceOwner API is modeled on our MemoryContext API,
 
15
which has proven very flexible and successful in preventing memory leaks.
 
16
In particular we allow ResourceOwners to have child ResourceOwner objects
 
17
so that there can be forests of the things; releasing a parent
 
18
ResourceOwner acts on all its direct and indirect children as well.
 
19
 
 
20
(It is tempting to consider unifying ResourceOwners and MemoryContexts
 
21
into a single object type, but their usage patterns are sufficiently
 
22
different that this is probably not really a helpful thing to do.)
 
23
 
 
24
We create a ResourceOwner for each transaction or subtransaction as
 
25
well as one for each Portal.  During execution of a Portal, the global
 
26
variable CurrentResourceOwner points to the Portal's ResourceOwner.
 
27
This causes operations such as ReadBuffer and LockAcquire to record
 
28
ownership of the acquired resources in that ResourceOwner object.
 
29
 
 
30
When a Portal is closed, any remaining resources (typically only locks)
 
31
become the responsibility of the current transaction.  This is represented
 
32
by making the Portal's ResourceOwner a child of the current transaction's
 
33
ResourceOwner.  resowner.c automatically transfers the resources to the
 
34
parent object when releasing the child.  Similarly, subtransaction
 
35
ResourceOwners are children of their immediate parent.
 
36
 
 
37
We need transaction-related ResourceOwners as well as Portal-related ones
 
38
because transactions may initiate operations that require resources (such
 
39
as query parsing) when no associated Portal exists yet.
 
40
 
 
41
 
 
42
API Overview
 
43
------------
 
44
 
 
45
The basic operations on a ResourceOwner are:
 
46
 
 
47
* create a ResourceOwner
 
48
 
 
49
* associate or deassociate some resource with a ResourceOwner
 
50
 
 
51
* release a ResourceOwner's assets (free all owned resources, but not the
 
52
  owner object itself)
 
53
 
 
54
* delete a ResourceOwner (including child owner objects); all resources
 
55
  must have been released beforehand
 
56
 
 
57
Locks are handled specially because in non-error situations a lock should
 
58
be held until end of transaction, even if it was originally taken by a
 
59
subtransaction or portal.  Therefore, the "release" operation on a child
 
60
ResourceOwner transfers lock ownership to the parent instead of actually
 
61
releasing the lock, if isCommit is true.
 
62
 
 
63
Currently, ResourceOwners contain direct support for recording ownership of
 
64
buffer pins, lmgr locks, and catcache, relcache, plancache, tupdesc, and
 
65
snapshot references.  Other objects can be associated with a ResourceOwner by
 
66
recording the address of the owning ResourceOwner in such an object.  There is
 
67
an API for other modules to get control during ResourceOwner release, so that
 
68
they can scan their own data structures to find the objects that need to be
 
69
deleted.
 
70
 
 
71
Whenever we are inside a transaction, the global variable
 
72
CurrentResourceOwner shows which resource owner should be assigned
 
73
ownership of acquired resources.  Note however that CurrentResourceOwner
 
74
is NULL when not inside any transaction (or when inside a failed
 
75
transaction).  In this case it is not valid to acquire query-lifespan
 
76
resources.
 
77
 
 
78
When unpinning a buffer or releasing a lock or cache reference,
 
79
CurrentResourceOwner must point to the same resource owner that was current
 
80
when the buffer, lock, or cache reference was acquired.  It would be possible
 
81
to relax this restriction given additional bookkeeping effort, but at present
 
82
there seems no need.
 
83
 
 
84
Code that transiently changes CurrentResourceOwner should generally use a
 
85
PG_TRY construct to ensure that the previous value of CurrentResourceOwner
 
86
is restored if control is lost during an error exit.