Обсуждение: Move description of general lock behaviour out of the "13.3.1. Table-level Locks section"

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/9.4/explicit-locking.html
Description:

Hi

The "13.3.1. Table-level Locks" subsection mentions the following: "Once
acquired, a lock is normally held till end of transaction." (maybe we should
also squeeze a "...till the end of a transaction" in there) According to a
helpful stranger on IRC, this behaviour is also true for row-level locks.

Since this sentence also applies to the row-level locks described in the
following subsection 13.3.2 I think it would be more fitting to move the
paragraph containing this sentence to the introduction of the topic in
section "13.3. Explicit Locking". This would then read something like:

---

13.3. Explicit Locking

PostgreSQL provides various lock modes to control concurrent access to data
in tables. These modes can be used for application-controlled locking in
situations where MVCC does not give the desired behavior. Also, most
PostgreSQL commands automatically acquire locks of appropriate modes to
ensure that referenced tables are not dropped or modified in incompatible
ways while the command executes. (For example, TRUNCATE cannot safely be
executed concurrently with other operations on the same table, so it obtains
an exclusive lock on the table to enforce that.)

Such explicit locks are normally held till the end of a transaction. But if
a lock is acquired after establishing a savepoint, the lock is released
immediately if the savepoint is rolled back to. This is consistent with the
principle that ROLLBACK cancels all effects of the commands since the
savepoint. The same holds for locks acquired within a PL/pgSQL exception
block: an error escape from the block releases locks acquired within it.

To examine a list of the currently outstanding locks in a database server,
use the pg_locks system view. For more information on monitoring the status
of the lock manager subsystem, refer to Chapter 28.

---

What do you think?


Cheers,

Silvan

On Mon, Feb  3, 2020 at 05:04:00PM +0000, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
> 
> Page: https://www.postgresql.org/docs/9.4/explicit-locking.html
> Description:
> 
> Hi
> 
> The "13.3.1. Table-level Locks" subsection mentions the following: "Once
> acquired, a lock is normally held till end of transaction." (maybe we should
> also squeeze a "...till the end of a transaction" in there) According to a

Sorry for the delay in replying.  Yes, this wording needs improvement,
which I have done in the attached patch.

> helpful stranger on IRC, this behavior is also true for row-level locks.
> 
> Since this sentence also applies to the row-level locks described in the
> following subsection 13.3.2 I think it would be more fitting to move the
> paragraph containing this sentence to the introduction of the topic in
> section "13.3. Explicit Locking". This would then read something like:

Uh, we can't move that paragraph up because Page-Level Locks and
Advisory Locks aren't always released on transaction end or rollback. 
What I did do was to mention that row-level locks are released in a
similar way to table-level locks.

Patch attached.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

Hi

On 2020-03-12 21:34, Bruce Momjian wrote:
> On Mon, Feb  3, 2020 at 05:04:00PM +0000, PG Doc comments form wrote:
>> The following documentation comment has been logged on the website:
>> 
>> Page: https://www.postgresql.org/docs/9.4/explicit-locking.html
>> Description:
>> 
>> Hi
>> 
>> The "13.3.1. Table-level Locks" subsection mentions the following: 
>> "Once
>> acquired, a lock is normally held till end of transaction." (maybe we 
>> should
>> also squeeze a "...till the end of a transaction" in there) According 
>> to a
> 
> Sorry for the delay in replying.  Yes, this wording needs improvement,

No problem!


> which I have done in the attached patch.
> 
>> helpful stranger on IRC, this behavior is also true for row-level 
>> locks.
>> 
>> Since this sentence also applies to the row-level locks described in 
>> the
>> following subsection 13.3.2 I think it would be more fitting to move 
>> the
>> paragraph containing this sentence to the introduction of the topic in
>> section "13.3. Explicit Locking". This would then read something like:
> 
> Uh, we can't move that paragraph up because Page-Level Locks and
> Advisory Locks aren't always released on transaction end or rollback.

Ah, I didn't take that into account.


> What I did do was to mention that row-level locks are released in a
> similar way to table-level locks.
> 
> Patch attached.

The patch looks good to me, thanks!


Cheers,

Silvan

Patch applied through 9.5.

---------------------------------------------------------------------------

On Thu, Mar 12, 2020 at 04:34:20PM -0400, Bruce Momjian wrote:
> On Mon, Feb  3, 2020 at 05:04:00PM +0000, PG Doc comments form wrote:
> > The following documentation comment has been logged on the website:
> > 
> > Page: https://www.postgresql.org/docs/9.4/explicit-locking.html
> > Description:
> > 
> > Hi
> > 
> > The "13.3.1. Table-level Locks" subsection mentions the following: "Once
> > acquired, a lock is normally held till end of transaction." (maybe we should
> > also squeeze a "...till the end of a transaction" in there) According to a
> 
> Sorry for the delay in replying.  Yes, this wording needs improvement,
> which I have done in the attached patch.
> 
> > helpful stranger on IRC, this behavior is also true for row-level locks.
> > 
> > Since this sentence also applies to the row-level locks described in the
> > following subsection 13.3.2 I think it would be more fitting to move the
> > paragraph containing this sentence to the introduction of the topic in
> > section "13.3. Explicit Locking". This would then read something like:
> 
> Uh, we can't move that paragraph up because Page-Level Locks and
> Advisory Locks aren't always released on transaction end or rollback. 
> What I did do was to mention that row-level locks are released in a
> similar way to table-level locks.
> 
> Patch attached.
> 
> -- 
>   Bruce Momjian  <bruce@momjian.us>        https://momjian.us
>   EnterpriseDB                             https://enterprisedb.com
> 
> + As you are, so once was I.  As I am, so you will be. +
> +                      Ancient Roman grave inscription +

> diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml
> index f8c9655111..95465d581b 100644
> --- a/doc/src/sgml/mvcc.sgml
> +++ b/doc/src/sgml/mvcc.sgml
> @@ -1039,9 +1039,9 @@ ERROR:  could not serialize access due to read/write dependencies among transact
>       </tip>
>  
>     <para>
> -    Once acquired, a lock is normally held till end of transaction.  But if a
> +    Once acquired, a lock is normally held until the end of the transaction.  But if a
>      lock is acquired after establishing a savepoint, the lock is released
> -    immediately if the savepoint is rolled back to.  This is consistent with
> +    immediately if the savepoint is rolled back.  This is consistent with
>      the principle that <command>ROLLBACK</command> cancels all effects of the
>      commands since the savepoint.  The same holds for locks acquired within a
>      <application>PL/pgSQL</application> exception block: an error escape from the block
> @@ -1178,7 +1178,10 @@ ERROR:  could not serialize access due to read/write dependencies among transact
>       conflicting locks on the same row, even in different subtransactions;
>       but other than that, two transactions can never hold conflicting locks
>       on the same row.  Row-level locks do not affect data querying; they
> -     block only <emphasis>writers and lockers</emphasis> to the same row.
> +     block only <emphasis>writers and lockers</emphasis> to the same
> +     row.  Row-level locks are released at transaction end or during
> +     savepoint rollback, just like table-level locks.
> +
>      </para>
>  
>       <variablelist>


-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +