Horton

Thread

Commits

  1. doc: Add new section describing fast-path locking

  1. [PATCH] doc: clarify pg_stat_lock.fastpath_exceeded scope

    Tatsuya Kawata <kawatatatsuya0913@gmail.com> — 2026-06-13T04:15:49Z

    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.

(*1) [PATCH] pg_stat_lock: add blocker mode dimension
https://www.postgresql.org/message-id/flat/CAHza6qeixfLeM3AqEkjgkE%2BBAqxB%3D5p227fo6JR60cG4mj8O8A%40mail.gmail.com#3592fb428248b200452b900468dc6d65

Regards,
Tatsuya Kawata

  2. Re: [PATCH] doc: clarify pg_stat_lock.fastpath_exceeded scope

    Bertrand Drouvot <bertranddrouvot.pg@gmail.com> — 2026-06-15T14:17:18Z

    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

  3. Re: [PATCH] doc: clarify pg_stat_lock.fastpath_exceeded scope

    Michael Paquier <michael@paquier.xyz> — 2026-06-16T03:42:46Z

    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

  4. Re: [PATCH] doc: clarify pg_stat_lock.fastpath_exceeded scope

    Tatsuya Kawata <kawatatatsuya0913@gmail.com> — 2026-06-20T09:14:59Z

    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

  5. Re: [PATCH] doc: clarify pg_stat_lock.fastpath_exceeded scope

    Bertrand Drouvot <bertranddrouvot.pg@gmail.com> — 2026-06-22T05:05:20Z

    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

  6. Re: [PATCH] doc: clarify pg_stat_lock.fastpath_exceeded scope

    Tatsuya Kawata <kawatatatsuya0913@gmail.com> — 2026-06-22T11:34:12Z

    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

  7. Re: [PATCH] doc: clarify pg_stat_lock.fastpath_exceeded scope

    Bertrand Drouvot <bertranddrouvot.pg@gmail.com> — 2026-06-23T04:07:39Z

    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

  8. Re: [PATCH] doc: clarify pg_stat_lock.fastpath_exceeded scope

    Michael Paquier <michael@paquier.xyz> — 2026-06-23T06:42:02Z

    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

  9. Re: [PATCH] doc: clarify pg_stat_lock.fastpath_exceeded scope

    Tatsuya Kawata <kawatatatsuya0913@gmail.com> — 2026-06-27T14:14:16Z

    Hi Bertrand-san, Michael-san,

Thanks for the additional review!

> 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.

Fixed.


> 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.

Thanks for the detailed thought.  I looked at that paragraph.  I was
hoping to fold the two together, but the content did not seem to
overlap, so I limited the change to adding a link as you suggested.

v4 attached.

Regards,
Tatsuya Kawata

  10. Re: [PATCH] doc: clarify pg_stat_lock.fastpath_exceeded scope

    Michael Paquier <michael@paquier.xyz> — 2026-06-29T00:31:36Z

    On Sat, Jun 27, 2026 at 11:14:16PM +0900, Tatsuya Kawata wrote:
> Thanks for the detailed thought.  I looked at that paragraph.  I was
> hoping to fold the two together, but the content did not seem to
> overlap, so I limited the change to adding a link as you suggested.

I'm finding that rather acceptable.  Bertrand-san, what do you think?
--
Michael

  11. Re: [PATCH] doc: clarify pg_stat_lock.fastpath_exceeded scope

    Bertrand Drouvot <bertranddrouvot.pg@gmail.com> — 2026-06-29T04:52:32Z

    Hi,

On Mon, Jun 29, 2026 at 09:31:36AM +0900, Michael Paquier wrote:
> On Sat, Jun 27, 2026 at 11:14:16PM +0900, Tatsuya Kawata wrote:
> > Thanks for the detailed thought.  I looked at that paragraph.  I was
> > hoping to fold the two together, but the content did not seem to
> > overlap, so I limited the change to adding a link as you suggested.
> 
> I'm finding that rather acceptable.  Bertrand-san, what do you think?

Yeah. I just wonder if we should mention it does not apply to shared relation
while at it.

Regards,

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

  12. Re: [PATCH] doc: clarify pg_stat_lock.fastpath_exceeded scope

    Michael Paquier <michael@paquier.xyz> — 2026-06-29T06:00:42Z

    On Mon, Jun 29, 2026 at 04:52:32AM +0000, Bertrand Drouvot wrote:
> Yeah. I just wonder if we should mention it does not apply to shared relation
> while at it.

[... checks code ...]

EligibleForRelationFastPath() tells that, yes.  An extra mention would
be nice, good catch.  Better than having to guess from the code.
--
Michael

  13. Re: [PATCH] doc: clarify pg_stat_lock.fastpath_exceeded scope

    Michael Paquier <michael@paquier.xyz> — 2026-07-01T01:09:14Z

    On Mon, Jun 29, 2026 at 04:52:32AM +0000, Bertrand Drouvot wrote:
> Yeah. I just wonder if we should mention it does not apply to shared relation
> while at it.

Added a sentence about shared relations in the second paragraph, and
applied the result on HEAD.
--
Michael

  14. Re: [PATCH] doc: clarify pg_stat_lock.fastpath_exceeded scope

    Tatsuya Kawata <kawatatatsuya0913@gmail.com> — 2026-07-01T15:36:35Z

    Hi Michael-san, Bertrand-san,

> Added a sentence about shared relations in the second paragraph, and
> applied the result on HEAD.
Thank you for the commit, and for all the reviews throughout the
thread. The final result is much better than what I started with.

Regards,
Tatsuya Kawata