[PATCH] doc: clarify pg_stat_lock.fastpath_exceeded scope

Hi,

On Sat, Jun 13, 2026 at 01:15:49PM +0900, Tatsuya Kawata wrote:

Hi,

While developing the pg_stat_lock improvement proposed in (*1), I
noticed that the documentation of the fastpath_exceeded column in
pg_stat_lock could be more explicit about its scope.

The current documentation describes it as:

Number of times a lock of this type could not be acquired via fast
path because the fast path slot limit was exceeded. Increasing
max_locks_per_transaction can reduce this number.

This omits the fact that fast-path locking only applies to relation
locks acquired in the weak modes (AccessShareLock, RowShareLock,
RowExclusiveLock), so the counter is always zero for any other
locktype.

The attached patch adds a short clarification to the pg_stat_lock entry
in monitoring.sgml.

I think that the current documentation is lacking explanation as to what the fast
path means as a whole. So I think that what we could do instead, is to explain
what fast path means (maybe around pg_lock?). Then, we could reference it in
pg_stat_lock if we feel the need.

Thoughts?

Regards,

--
Bertrand Drouvot
PostgreSQL Contributors Team
RDS Open Source Databases
Amazon Web Services: https://aws.amazon.com

On Mon, Jun 15, 2026 at 02:17:18PM +0000, Bertrand Drouvot wrote:

I think that the current documentation is lacking explanation as to what the fast
path means as a whole. So I think that what we could do instead, is to explain
what fast path means (maybe around pg_lock?). Then, we could reference it in
pg_stat_lock if we feel the need.

A more centralized explanation that could then be used as a link from
the page of the view sounds like a good plan here.
--
Michael

Hi Bertrand-san, Michael-san,

Thanks for the feedback. Centralizing the explanation and linking
from views makes sense, so v2 takes that approach.

Specifically, v2:

* Adds a new "Fast-Path Locking" subsection under Explicit Locking
(13.3.1.1, inside Table-Level Locks).

* References the new section from:
- pg_stat_lock.fastpath_exceeded (monitoring.sgml)
- pg_locks.fastpath (system-views.sgml)
- max_locks_per_transaction (config.sgml)

Patch v2 attached.

Regards,
Tatsuya Kawata

Hi Kawata-san,

On Sat, Jun 20, 2026 at 06:14:59PM +0900, Tatsuya Kawata wrote:

Hi Bertrand-san, Michael-san,

Thanks for the feedback. Centralizing the explanation and linking
from views makes sense, so v2 takes that approach.

Thanks for the new version.

--- a/doc/src/sgml/mvcc.sgml
+++ b/doc/src/sgml/mvcc.sgml
@@ -1248,6 +1248,35 @@ ERROR:  could not serialize access due to read/write dependencies among transact
       </tbody>
      </tgroup>
     </table>
+
+    <sect3 id="locking-tables-fast-path">
+     <title>Fast-Path Locking</title>

The location looks ok to me.

+      for eligible locks, fast-path is used only when a per-backend slot is
+      available;

Should we add a description of the consequences of not being able to acquire the
lock in fast-path (when there are no available slots)? For example, we could
say that this is considerably more expensive and may be subject to contention.

Regards,

--
Bertrand Drouvot
PostgreSQL Contributors Team
RDS Open Source Databases
Amazon Web Services: https://aws.amazon.com

Hi Bertrand-san,

Thanks for the review.

Should we add a description of the consequences of not being able to
acquire the lock in fast-path (when there are no available slots)?
For example, we could say that this is considerably more expensive
and may be subject to contention.

Agreed. v3 adds the following paragraph at the end of the Fast-Path
Locking subsection:

+     <para>
+      Acquiring a lock via the main lock table is considerably more
+      expensive than the fast path, and under heavy concurrent lock
+      activity can become a point of contention (observable as the
+      <literal>LockManager</literal> wait event).
+     </para>

Other parts of the patch are unchanged from v2.
v3 attached.

Regards,
Tatsuya Kawata

Hi Kawata-san,

On Mon, Jun 22, 2026 at 08:34:12PM +0900, Tatsuya Kawata wrote:

Hi Bertrand-san,

Thanks for the review.

Should we add a description of the consequences of not being able to
acquire the lock in fast-path (when there are no available slots)?
For example, we could say that this is considerably more expensive
and may be subject to contention.

Agreed. v3 adds the following paragraph at the end of the Fast-Path

Thanks!

Looking closer, I'm not sure that in:

-       lock table
+       lock table.  See <xref linkend="locking-tables-fast-path"/> for
+       details.

the "for details" is needed. Looking at the pg_locks table, it looks like
"(See xxxx)" would be more consistent.

Regards,

--
Bertrand Drouvot
PostgreSQL Contributors Team
RDS Open Source Databases
Amazon Web Services: https://aws.amazon.com

On Tue, Jun 23, 2026 at 04:07:39AM +0000, Bertrand Drouvot wrote:

Looking closer, I'm not sure that in:

-       lock table
+       lock table.  See <xref linkend="locking-tables-fast-path"/> for
+       details.

the "for details" is needed. Looking at the pg_locks table, it looks like
"(See xxxx)" would be more consistent.

Hmm. system-views.sgml has a large paragraph about fast-path locks,
and seems to be the only location in the official docs where the term
is used. I am wondering if the paragraph in view-pg-locks could be
improved and/or shortened with what you are proposing here, even if
most of it points to the inconsistencies one could get when querying
pg_locks due to the volatile nature of fast-path locks... At least a
link on the pg_locks page pointing to this new section could be
something to consider.
--
Michael