Subject: Re: [PATCH] Update README for Resource Owners
To: Andres Freund <andres@anarazel.de>
References: <5AC806D1.1090608@anastigmatix.net>
 <20180406235209.k2gfizjfi2xczo6z@alap3.anarazel.de>
Cc: PostgreSQL Hackers <pgsql-hackers@postgresql.org>
From: Chapman Flack <chap@anastigmatix.net>
Message-ID: <5AC80E90.5000407@anastigmatix.net>
Date: Fri, 6 Apr 2018 20:19:28 -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: <20180406235209.k2gfizjfi2xczo6z@alap3.anarazel.de>
Content-Type: multipart/mixed;
 boundary="------------090105000607020506010908"
Precedence: bulk

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

On 04/06/18 19:52, Andres Freund wrote:
> On 2018-04-06 19:46:25 -0400, Chapman Flack wrote:
>> Hasn't been updated as built-in support grew for temp files, DSM segments,
>> and JIT contexts.
>>
>> With enough luck, a README update won't break anything.
> 
> 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.

-Chap

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

From 56c047c5fa963c0c22affdde2ce669ed88693e5a Mon Sep 17 00:00:00 2001
From: Chapman Flack <chap@anastigmatix.net>
Date: Fri, 6 Apr 2018 20:16:42 -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.
---
 src/backend/utils/resowner/README | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/src/backend/utils/resowner/README b/src/backend/utils/resowner/README
index 2998f6b..c01f3bc 100644
--- a/src/backend/utils/resowner/README
+++ b/src/backend/utils/resowner/README
@@ -61,12 +61,16 @@ 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.
 
 Whenever we are inside a transaction, the global variable
 CurrentResourceOwner shows which resource owner should be assigned
-- 
2.7.3


--------------090105000607020506010908--