Subject: Re: [PATCH] Update README for Resource Owners
To: Andres Freund <andres@anarazel.de>
References: <5AC806D1.1090608@anastigmatix.net>
 <20180406235209.k2gfizjfi2xczo6z@alap3.anarazel.de>
 <5AC80E90.5000407@anastigmatix.net>
Cc: PostgreSQL Hackers <pgsql-hackers@postgresql.org>
From: Chapman Flack <chap@anastigmatix.net>
Message-ID: <5AC81AA3.6090604@anastigmatix.net>
Date: Fri, 6 Apr 2018 21:10:59 -0400
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101
 Thunderbird/38.7.0
MIME-Version: 1.0
In-Reply-To: <5AC80E90.5000407@anastigmatix.net>
Content-Type: multipart/mixed;
 boundary="------------020006050904060308080302"
Precedence: bulk

This is a multi-part message in MIME format.
--------------020006050904060308080302
Content-Type: text/plain; charset=windows-1252
Content-Transfer-Encoding: 7bit

On 04/06/18 20:19, Chapman Flack wrote:
> On 04/06/18 19:52, Andres Freund wrote:
>> Wouldn't it be a better idea not to have a list there, that's guaranteed
>> to get out of date?
> 
> That might look like this, then.
> 
> But I'm not sure how bad it is to have a list. How often does ResourceOwner
> get taught a new type? It took nine years to grow these last three.

It also seemed worth documenting that the release callbacks are called
for *every* ResourceOwnerRelease, but can consult CurrentResourceOwner to
learn what owner is really being released.

-Chap

--------------020006050904060308080302
Content-Type: text/x-patch;
 name="0001-Update-README-for-Resource-Owners-v3.patch"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
 filename="0001-Update-README-for-Resource-Owners-v3.patch"

From 6541f1b5c28ede3bf0e88bb34d6a4eedc5731cab Mon Sep 17 00:00:00 2001
From: Chapman Flack <chap@anastigmatix.net>
Date: Fri, 6 Apr 2018 21:08:02 -0400
Subject: [PATCH] Update README for Resource Owners.

Built-in support for three more categories of owned object has accreted
without mention in the README.

Also explain that the release callbacks are global, and can consult
CurrentResourceOwner to determine the owner being released.
---
 src/backend/utils/resowner/README | 20 ++++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)

diff --git a/src/backend/utils/resowner/README b/src/backend/utils/resowner/README
index 2998f6b..5049e7c 100644
--- a/src/backend/utils/resowner/README
+++ b/src/backend/utils/resowner/README
@@ -61,12 +61,20 @@ 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.
+several types of resource managed in the core, with the three operations
+ResourceOwnerEnlarge<Foo>Refs(), ResourceOwnerRemember<Foo>Ref(), and
+ResourceOwnerForget<Foo>Ref() for each type. The first ensures there is room
+for at least one more entry of the type, and is separate from Remember...
+so that out-of-memory can be detected before the resource is acquired.
+
+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.
+Such callbacks are registered globally, not to a specific ResourceOwner, and
+will be called during every ResourceOwnerRelease; to determine which owner is
+being released, they can refer to CurrentResourceOwner, which points to it
+while the callbacks are invoked.
 
 Whenever we are inside a transaction, the global variable
 CurrentResourceOwner shows which resource owner should be assigned
-- 
2.7.3


--------------020006050904060308080302--