Debian Codegraph @

src/backend/utils/resowner/README

raw
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 Usage
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 Whenever we are inside a transaction, the global variable
64 CurrentResourceOwner shows which resource owner should be assigned
65 ownership of acquired resources. Note however that CurrentResourceOwner
66 is NULL when not inside any transaction (or when inside a failed
67 transaction). In this case it is not valid to acquire query-lifespan
68 resources.
69
70 When unpinning a buffer or releasing a lock or cache reference,
71 CurrentResourceOwner must point to the same resource owner that was current
72 when the buffer, lock, or cache reference was acquired. It would be possible
73 to relax this restriction given additional bookkeeping effort, but at present
74 there seems no need.
75
76 Adding a new resource type
77 --------------------------
78
79 ResourceOwner can track ownership of many different kinds of resources. In
80 core PostgreSQL it is used for buffer pins, lmgr locks, and catalog cache
81 references, to name a few examples.
82
83 To add a new kind of resource, define a ResourceOwnerDesc to describe it.
84 For example:
85
86 static const ResourceOwnerDesc myresource_desc = {
87 .name = "My fancy resource",
88 .release_phase = RESOURCE_RELEASE_AFTER_LOCKS,
89 .release_priority = RELEASE_PRIO_FIRST,
90 .ReleaseResource = ReleaseMyResource,
91 .DebugPrint = PrintMyResource
92 };
93
94 ResourceOwnerRemember() and ResourceOwnerForget() functions take a pointer
95 to that struct, along with a Datum to represent the resource. The meaning
96 of the Datum depends on the resource type. Most resource types use it to
97 store a pointer to some struct, but it can also be a file descriptor or
98 library handle, for example.
99
100 The ReleaseResource callback is called when a resource owner is released or
101 deleted. It should release any resources (e.g. close files, free memory)
102 associated with the resource. Because the callback is called during
103 transaction abort, it must perform only low-level cleanup with no user
104 visible effects. The callback should not perform operations that could
105 fail, like allocate memory.
106
107 The optional DebugPrint callback is used in the warning at transaction
108 commit, if any resources are leaked. If not specified, a generic
109 implementation that prints the resource name and the resource as a pointer
110 is used.
111
112 There is another API for other modules to get control during ResourceOwner
113 release, so that they can scan their own data structures to find the objects
114 that need to be deleted. See RegisterResourceReleaseCallback function.
115 This used to be the only way for extensions to use the resource owner
116 mechanism with new kinds of objects; nowadays it is easier to define a custom
117 ResourceOwnerDesc struct.
118
119
120 Releasing
121 ---------
122
123 Releasing the resources of a ResourceOwner happens in three phases:
124
125 1. "Before-locks" resources
126
127 2. Locks
128
129 3. "After-locks" resources
130
131 Each resource type specifies whether it needs to be released before or after
132 locks. Each resource type also has a priority, which determines the order
133 that the resources are released in. Note that the phases are performed fully
134 for the whole tree of resource owners, before moving to the next phase, but
135 the priority within each phase only determines the order within that
136 ResourceOwner. Child resource owners are always handled before the parent,
137 within each phase.
138
139 For example, imagine that you have two ResourceOwners, parent and child,
140 as follows:
141
142 Parent
143 parent resource BEFORE_LOCKS priority 1
144 parent resource BEFORE_LOCKS priority 2
145 parent resource AFTER_LOCKS priority 10001
146 parent resource AFTER_LOCKS priority 10002
147 Child
148 child resource BEFORE_LOCKS priority 1
149 child resource BEFORE_LOCKS priority 2
150 child resource AFTER_LOCKS priority 10001
151 child resource AFTER_LOCKS priority 10002
152
153 These resources would be released in the following order:
154
155 child resource BEFORE_LOCKS priority 1
156 child resource BEFORE_LOCKS priority 2
157 parent resource BEFORE_LOCKS priority 1
158 parent resource BEFORE_LOCKS priority 2
159 (locks)
160 child resource AFTER_LOCKS priority 10001
161 child resource AFTER_LOCKS priority 10002
162 parent resource AFTER_LOCKS priority 10001
163 parent resource AFTER_LOCKS priority 10002
164
165 To release all the resources, you need to call ResourceOwnerRelease() three
166 times, once for each phase. You may perform additional tasks between the
167 phases, but after the first call to ResourceOwnerRelease(), you cannot use
168 the ResourceOwner to remember any more resources. You also cannot call
169 ResourceOwnerForget on the resource owner to release any previously
170 remembered resources "in retail", after you have started the release process.
171
172 Normally, you are expected to call ResourceOwnerForget on every resource so
173 that at commit, the ResourceOwner is empty (locks are an exception). If there
174 are any resources still held at commit, ResourceOwnerRelease will print a
175 WARNING on each such resource. At abort, however, we truly rely on the
176 ResourceOwner mechanism and it is normal that there are resources to be
177 released.