MIME-Version: 1.0
From: Hiroki Takamatsu <hiroki.takamatsu.my@gmail.com>
Date: Mon, 30 Mar 2026 17:48:10 +0900
Message-ID: 
 <CA+r=ywWUHOPgHp-tegoETpfjiEkE5Ytzi4g9orcKav8bWym+_Q@mail.gmail.com>
Subject: Doc: clarify pg_locks descriptions of classid/objid/objsubid
To: pgsql-docs@postgresql.org
Content-Type: multipart/mixed; boundary="000000000000d41279064e39e9a2"
Archived-At: 
 <https://www.postgresql.org/message-id/CA%2Br%3DywWUHOPgHp-tegoETpfjiEkE5Ytzi4g9orcKav8bWym%2B_Q%40mail.gmail.com>
Precedence: bulk

--000000000000d41279064e39e9a2
Content-Type: multipart/alternative; boundary="000000000000d41277064e39e9a0"

--000000000000d41277064e39e9a0
Content-Type: text/plain; charset="UTF-8"

Hi hackers,

It seems that the descriptions of classid, objid, and objsubid in the
pg_locks documentation are not quite accurate for all lock types.
The documentation currently says these columns are null if the lock
target is not a general database object.
However, pg_lock_status() (lockfuncs.c) also populates these columns
for other lock types, including advisory locks,
speculative insertion locks, and apply transaction locks.
The detailed prose below the table already describes
some of these uses, so the table entries and the prose seem to be
inconsistent.

The attached patch:

1. rewrites each column description to scope it to the general database
   object case, instead of making a false claim about NULL behavior for
   all other lock types;
2. adds a pointer to the detailed per-lock-type prose below; and
3. documents that apply transaction locks show the subscription OID in
   objid.

I chose not to enumerate all non-object lock types in the column
descriptions, since that seemed easy to let drift again as new lock
types are added.

Do you think?

Regards,
Hiroki Takamatsu

--000000000000d41277064e39e9a0
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr">Hi hackers,<br><br>It seems that the descriptions of class=
id, objid, and objsubid in the<br>pg_locks documentation are not quite accu=
rate for all lock types.<br>The documentation currently says these columns =
are null if the lock<br>target is not a general database object.<br>However=
, pg_lock_status() (lockfuncs.c) also populates these columns <br>for other=
 lock types, including advisory locks, <br>speculative insertion locks, and=
 apply transaction locks.<br>The detailed prose below the table already des=
cribes <br>some of these uses, so the table entries and the prose seem to b=
e<br>inconsistent.<br><br>The attached patch:<br><br>1. rewrites each colum=
n description to scope it to the general database<br>=C2=A0 =C2=A0object ca=
se, instead of making a false claim about NULL behavior for<br>=C2=A0 =C2=
=A0all other lock types;<br>2. adds a pointer to the detailed per-lock-type=
 prose below; and<br>3. documents that apply transaction locks show the sub=
scription OID in<br>=C2=A0 =C2=A0objid.<br><br>I chose not to enumerate all=
 non-object lock types in the column <br>descriptions, since that seemed ea=
sy to let drift again as new lock<br>types are added.<br><br>Do you think?<=
br><br>Regards,<br>Hiroki Takamatsu<br><br></div>

--000000000000d41277064e39e9a0--

--000000000000d41279064e39e9a2
Content-Type: application/octet-stream;
	name="0001-clarify-pg_locks-descriptions-of-classid-objid-objsu.patch"
Content-Disposition: attachment;
	filename="0001-clarify-pg_locks-descriptions-of-classid-objid-objsu.patch"
Content-Transfer-Encoding: base64
Content-ID: <f_mncwbuzc0>
X-Attachment-Id: f_mncwbuzc0

RnJvbSBiMjQ0MTI5YzJlYzc3YWE5NmJlNDIzZDZlODU5YzI5ZjFlMzE5YjBlIE1vbiBTZXAgMTcg
MDA6MDA6MDAgMjAwMQ0KRnJvbTogSGlyb2tpIFRha2FtYXRzdSA8aGlyb2tpLnRha2FtYXRzdS5t
eUBnbWFpbC5jb20+DQpEYXRlOiBNb24sIDMwIE1hciAyMDI2IDA3OjEzOjI1ICswMDAwDQpTdWJq
ZWN0OiBbUEFUQ0hdIGNsYXJpZnkgcGdfbG9ja3MgZGVzY3JpcHRpb25zIG9mIGNsYXNzaWQvb2Jq
aWQvb2Jqc3ViaWQNCg0KLS0tDQogZG9jL3NyYy9zZ21sL3N5c3RlbS12aWV3cy5zZ21sIHwgMjEg
KysrKysrKysrKysrKy0tLS0tLS0tDQogMSBmaWxlIGNoYW5nZWQsIDEzIGluc2VydGlvbnMoKyks
IDggZGVsZXRpb25zKC0pDQoNCmRpZmYgLS1naXQgYS9kb2Mvc3JjL3NnbWwvc3lzdGVtLXZpZXdz
LnNnbWwgYi9kb2Mvc3JjL3NnbWwvc3lzdGVtLXZpZXdzLnNnbWwNCmluZGV4IDllZTFhMmJmYzZh
Li5hNzIyOTU4MDFiNyAxMDA2NDQNCi0tLSBhL2RvYy9zcmMvc2dtbC9zeXN0ZW0tdmlld3Muc2dt
bA0KKysrIGIvZG9jL3NyYy9zZ21sL3N5c3RlbS12aWV3cy5zZ21sDQpAQCAtMTkwNSw4ICsxOTA1
LDkgQEAgQU5EIGMxLnBhdGhbYzIubGV2ZWxdID0gYzIucGF0aFtjMi5sZXZlbF07DQogICAgICAg
IChyZWZlcmVuY2VzIDxsaW5rIGxpbmtlbmQ9ImNhdGFsb2ctcGctY2xhc3MiPjxzdHJ1Y3RuYW1l
PnBnX2NsYXNzPC9zdHJ1Y3RuYW1lPjwvbGluaz4uPHN0cnVjdGZpZWxkPm9pZDwvc3RydWN0Zmll
bGQ+KQ0KICAgICAgIDwvcGFyYT4NCiAgICAgICA8cGFyYT4NCi0gICAgICAgT0lEIG9mIHRoZSBz
eXN0ZW0gY2F0YWxvZyBjb250YWluaW5nIHRoZSBsb2NrIHRhcmdldCwgb3IgbnVsbCBpZiB0aGUN
Ci0gICAgICAgdGFyZ2V0IGlzIG5vdCBhIGdlbmVyYWwgZGF0YWJhc2Ugb2JqZWN0DQorICAgICAg
IEZvciBhIGdlbmVyYWwgZGF0YWJhc2Ugb2JqZWN0LCB0aGUgT0lEIG9mIHRoZSBzeXN0ZW0gY2F0
YWxvZw0KKyAgICAgICBjb250YWluaW5nIHRoZSBsb2NrIHRhcmdldC4NCisgICAgICAgVGhpcyBj
b2x1bW4gaXMgYWxzbyB1c2VkIGZvciBvdGhlciBsb2NrIHR5cGVzOyBzZWUgYmVsb3cuDQogICAg
ICAgPC9wYXJhPjwvZW50cnk+DQogICAgICA8L3Jvdz4NCiANCkBAIC0xOTE2LDggKzE5MTcsOSBA
QCBBTkQgYzEucGF0aFtjMi5sZXZlbF0gPSBjMi5wYXRoW2MyLmxldmVsXTsNCiAgICAgICAgKHJl
ZmVyZW5jZXMgYW55IE9JRCBjb2x1bW4pDQogICAgICAgPC9wYXJhPg0KICAgICAgIDxwYXJhPg0K
LSAgICAgICBPSUQgb2YgdGhlIGxvY2sgdGFyZ2V0IHdpdGhpbiBpdHMgc3lzdGVtIGNhdGFsb2cs
IG9yIG51bGwgaWYgdGhlDQotICAgICAgIHRhcmdldCBpcyBub3QgYSBnZW5lcmFsIGRhdGFiYXNl
IG9iamVjdA0KKyAgICAgICBGb3IgYSBnZW5lcmFsIGRhdGFiYXNlIG9iamVjdCwgdGhlIE9JRCBv
ZiB0aGUgbG9jayB0YXJnZXQgd2l0aGluDQorICAgICAgIGl0cyBzeXN0ZW0gY2F0YWxvZy4NCisg
ICAgICAgVGhpcyBjb2x1bW4gaXMgYWxzbyB1c2VkIGZvciBvdGhlciBsb2NrIHR5cGVzOyBzZWUg
YmVsb3cuDQogICAgICAgPC9wYXJhPjwvZW50cnk+DQogICAgICA8L3Jvdz4NCiANCkBAIC0xOTI2
LDExICsxOTI4LDEyIEBAIEFORCBjMS5wYXRoW2MyLmxldmVsXSA9IGMyLnBhdGhbYzIubGV2ZWxd
Ow0KICAgICAgICA8c3RydWN0ZmllbGQ+b2Jqc3ViaWQ8L3N0cnVjdGZpZWxkPiA8dHlwZT5pbnQy
PC90eXBlPg0KICAgICAgIDwvcGFyYT4NCiAgICAgICA8cGFyYT4NCi0gICAgICAgQ29sdW1uIG51
bWJlciB0YXJnZXRlZCBieSB0aGUgbG9jayAodGhlDQorICAgICAgIEZvciBhIGdlbmVyYWwgZGF0
YWJhc2Ugb2JqZWN0LCB0aGUgY29sdW1uIG51bWJlciB0YXJnZXRlZCBieSB0aGUNCisgICAgICAg
bG9jayAodGhlDQogICAgICAgIDxzdHJ1Y3RmaWVsZD5jbGFzc2lkPC9zdHJ1Y3RmaWVsZD4gYW5k
IDxzdHJ1Y3RmaWVsZD5vYmppZDwvc3RydWN0ZmllbGQ+IHJlZmVyIHRvIHRoZQ0KICAgICAgICB0
YWJsZSBpdHNlbGYpLA0KLSAgICAgICBvciB6ZXJvIGlmIHRoZSB0YXJnZXQgaXMgc29tZSBvdGhl
ciBnZW5lcmFsIGRhdGFiYXNlIG9iamVjdCwNCi0gICAgICAgb3IgbnVsbCBpZiB0aGUgdGFyZ2V0
IGlzIG5vdCBhIGdlbmVyYWwgZGF0YWJhc2Ugb2JqZWN0DQorICAgICAgIG9yIHplcm8gaWYgdGhl
IHRhcmdldCBpcyBzb21lIG90aGVyIGdlbmVyYWwgZGF0YWJhc2Ugb2JqZWN0Lg0KKyAgICAgICBU
aGlzIGNvbHVtbiBpcyBhbHNvIHVzZWQgZm9yIG90aGVyIGxvY2sgdHlwZXM7IHNlZSBiZWxvdy4N
CiAgICAgICA8L3BhcmE+PC9lbnRyeT4NCiAgICAgIDwvcm93Pg0KIA0KQEAgLTIwNTMsNyArMjA1
Niw5IEBAIEFORCBjMS5wYXRoW2MyLmxldmVsXSA9IGMyLnBhdGhbYzIubGV2ZWxdOw0KICAgPHBh
cmE+DQogICAgQXBwbHkgdHJhbnNhY3Rpb24gbG9ja3MgYXJlIHVzZWQgaW4gcGFyYWxsZWwgbW9k
ZSB0byBhcHBseSB0aGUgdHJhbnNhY3Rpb24NCiAgICBpbiBsb2dpY2FsIHJlcGxpY2F0aW9uLiBU
aGUgcmVtb3RlIHRyYW5zYWN0aW9uIElEIGlzIGRpc3BsYXllZCBpbiB0aGUNCi0gICA8c3RydWN0
ZmllbGQ+dHJhbnNhY3Rpb25pZDwvc3RydWN0ZmllbGQ+IGNvbHVtbi4gVGhlIDxzdHJ1Y3RmaWVs
ZD5vYmpzdWJpZDwvc3RydWN0ZmllbGQ+DQorICAgPHN0cnVjdGZpZWxkPnRyYW5zYWN0aW9uaWQ8
L3N0cnVjdGZpZWxkPiBjb2x1bW4uICBUaGUgT0lEIG9mIHRoZSBzdWJzY3JpcHRpb24gaXMNCisg
ICBkaXNwbGF5ZWQgaW4gdGhlIDxzdHJ1Y3RmaWVsZD5vYmppZDwvc3RydWN0ZmllbGQ+IGNvbHVt
bi4NCisgICBUaGUgPHN0cnVjdGZpZWxkPm9ianN1YmlkPC9zdHJ1Y3RmaWVsZD4NCiAgICBkaXNw
bGF5cyB0aGUgbG9jayBzdWJ0eXBlIHdoaWNoIGlzIDAgZm9yIHRoZSBsb2NrIHVzZWQgdG8gc3lu
Y2hyb25pemUgdGhlDQogICAgc2V0IG9mIGNoYW5nZXMsIGFuZCAxIGZvciB0aGUgbG9jayB1c2Vk
IHRvIHdhaXQgZm9yIHRoZSB0cmFuc2FjdGlvbiB0bw0KICAgIGZpbmlzaCB0byBlbnN1cmUgY29t
bWl0IG9yZGVyLg0KLS0gDQoyLjQ3LjMNCg==
--000000000000d41279064e39e9a2--