Incorrect description of xmax and xip in functions docs

On Fri, 2008-09-05 at 16:14 +0100, Simon Riggs wrote:

http://developer.postgresql.org/pgdocs/postgres/functions-info.html

xip_list is described as

"Active txids at the time of the snapshot... "

This is incorrect. The xip_list is the list of transactions that are in
progress *and* less than xmax. There may be transactions in progress
with an xid higher than xmax. This will happen frequently in fact. This
is because xmax is defined as the highest/latest completed xid, not the
highest running xid.

Note that there is no way to discover the list of running xids at the
time of the snapshot, from the data we hold about snapshots. Nor can the
snapshot data be used to monitor the number of transactions in progress.

Anyone disagree? If not, I'll patch.

My rewording would be:
"Active txids at the time of the snapshot. The list includes only those
active txids between xmin and xmax; there may be active txids higher
than xmax. A txid that is xmin <= txid < xmax and not in this list was
already completed at the time of the snapshot, and thus either visible
or dead according to its commit status. The list does not include txids
of subtransactions."

And for txid_visible_in_snapshot() comment added:
"Function should not be used with subtransaction xids. It is possible
that this function will return a true result for a subtransaction xid
that was actually still in progress at the time of the snapshot".

--
Simon Riggs www.2ndQuadrant.com
PostgreSQL Training, Services and Support

Simon Riggs wrote:

On Fri, 2008-09-05 at 16:14 +0100, Simon Riggs wrote:

http://developer.postgresql.org/pgdocs/postgres/functions-info.html

xip_list is described as

"Active txids at the time of the snapshot... "

This is incorrect. The xip_list is the list of transactions that are in
progress *and* less than xmax. There may be transactions in progress
with an xid higher than xmax. This will happen frequently in fact. This
is because xmax is defined as the highest/latest completed xid, not the
highest running xid.

Note that there is no way to discover the list of running xids at the
time of the snapshot, from the data we hold about snapshots. Nor can the
snapshot data be used to monitor the number of transactions in progress.

Anyone disagree? If not, I'll patch.

My rewording would be:
"Active txids at the time of the snapshot. The list includes only those
active txids between xmin and xmax; there may be active txids higher
than xmax. A txid that is xmin <= txid < xmax and not in this list was
already completed at the time of the snapshot, and thus either visible
or dead according to its commit status. The list does not include txids
of subtransactions."

Applied, and attached.

And for txid_visible_in_snapshot() comment added:
"Function should not be used with subtransaction xids. It is possible
that this function will return a true result for a subtransaction xid
that was actually still in progress at the time of the snapshot".

I think the cleaner solution is to throw an appropriate error if a
subtransaction xid is used, rather than adding documentation.

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

+ If your life is a hard drive, Christ can be your backup. +

On Sat, 2008-09-06 at 21:31 -0400, Bruce Momjian wrote:

Applied, and attached.

Thanks.

And for txid_visible_in_snapshot() comment added:
"Function should not be used with subtransaction xids. It is possible
that this function will return a true result for a subtransaction xid
that was actually still in progress at the time of the snapshot".

I think the cleaner solution is to throw an appropriate error if a
subtransaction xid is used, rather than adding documentation.

Or maybe check subtrans for it, as it really should be doing.

--
Simon Riggs www.2ndQuadrant.com
PostgreSQL Training, Services and Support

Simon Riggs wrote:

On Sat, 2008-09-06 at 21:31 -0400, Bruce Momjian wrote:

Applied, and attached.

Thanks.

And for txid_visible_in_snapshot() comment added:
"Function should not be used with subtransaction xids. It is possible
that this function will return a true result for a subtransaction xid
that was actually still in progress at the time of the snapshot".

I think the cleaner solution is to throw an appropriate error if a
subtransaction xid is used, rather than adding documentation.

Or maybe check subtrans for it, as it really should be doing.

Yea, that's what I meant. You can't be sure everyone is going to read
the documentation but they are sure to see the function results or error
message.

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

+ If your life is a hard drive, Christ can be your backup. +

On Sun, 2008-09-07 at 08:31 -0400, Bruce Momjian wrote:

Simon Riggs wrote:

On Sat, 2008-09-06 at 21:31 -0400, Bruce Momjian wrote:

Applied, and attached.

Thanks.

And for txid_visible_in_snapshot() comment added:
"Function should not be used with subtransaction xids. It is possible
that this function will return a true result for a subtransaction xid
that was actually still in progress at the time of the snapshot".

I think the cleaner solution is to throw an appropriate error if a
subtransaction xid is used, rather than adding documentation.

Or maybe check subtrans for it, as it really should be doing.

Yea, that's what I meant. You can't be sure everyone is going to read
the documentation but they are sure to see the function results or error
message.

In fact, neither is possible. We cannot assume subtrans is available on
the system on which the check is made, neither can we identify which
xids are subtransactions and which are not.

The only way is to document it.

--
Simon Riggs www.2ndQuadrant.com
PostgreSQL Training, Services and Support

Simon Riggs wrote:

On Sun, 2008-09-07 at 08:31 -0400, Bruce Momjian wrote:

Simon Riggs wrote:

On Sat, 2008-09-06 at 21:31 -0400, Bruce Momjian wrote:

Applied, and attached.

Thanks.

And for txid_visible_in_snapshot() comment added:
"Function should not be used with subtransaction xids. It is possible
that this function will return a true result for a subtransaction xid
that was actually still in progress at the time of the snapshot".

I think the cleaner solution is to throw an appropriate error if a
subtransaction xid is used, rather than adding documentation.

Or maybe check subtrans for it, as it really should be doing.

Yea, that's what I meant. You can't be sure everyone is going to read
the documentation but they are sure to see the function results or error
message.

In fact, neither is possible. We cannot assume subtrans is available on
the system on which the check is made, neither can we identify which
xids are subtransactions and which are not.

The only way is to document it.

Sorry, I am just getting back to this. Why would we not know if
something is a subtransaction or if subtransactions are supported? Are
you assuming txid_visible_in_snapshot() will be used on different
servers? What are these txid_* functions for anyway?

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

+ If your life is a hard drive, Christ can be your backup. +

On Wed, 2009-01-07 at 20:30 -0500, Bruce Momjian wrote:

The only way is to document it.

Sorry, I am just getting back to this. Why would we not know if
something is a subtransaction or if subtransactions are supported? Are
you assuming txid_visible_in_snapshot() will be used on different
servers? What are these txid_* functions for anyway?

You can derive a snapshot and export it using txid_current_snapshot().
http://developer.postgresql.org/pgdocs/postgres/functions-info.html

You can then check whether an xid is in that snapshot by running
txid_visible_in_snapshot(). However, the check is done assuming that the
xid you are checking is a top-level xid and the answer you get is either
yes or no.

There is no allowance made that the xid supplied as a parameter value
may have been a subtrans of one of the top-level xids listed. So the
answer *ought* to have been true, whereas the function will always
return false.

We cannot extend txid_visible_in_snapshot() to answer correctly because
that information is not held within the snapshot datatype, nor is it
held in regular snapshots currently. So the only way to handle this is
to document the limited scope of the answer this function provides.

--
Simon Riggs www.2ndQuadrant.com
PostgreSQL Training, Services and Support

Simon Riggs wrote:

On Wed, 2009-01-07 at 20:30 -0500, Bruce Momjian wrote:

The only way is to document it.

Sorry, I am just getting back to this. Why would we not know if
something is a subtransaction or if subtransactions are supported? Are
you assuming txid_visible_in_snapshot() will be used on different
servers? What are these txid_* functions for anyway?

You can derive a snapshot and export it using txid_current_snapshot().
http://developer.postgresql.org/pgdocs/postgres/functions-info.html

You can then check whether an xid is in that snapshot by running
txid_visible_in_snapshot(). However, the check is done assuming that the
xid you are checking is a top-level xid and the answer you get is either
yes or no.

There is no allowance made that the xid supplied as a parameter value
may have been a subtrans of one of the top-level xids listed. So the
answer *ought* to have been true, whereas the function will always
return false.

We cannot extend txid_visible_in_snapshot() to answer correctly because
that information is not held within the snapshot datatype, nor is it
held in regular snapshots currently. So the only way to handle this is
to document the limited scope of the answer this function provides.

Thank you for the clarification; I know understand. Patch attached and
applied.

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

+ If your life is a hard drive, Christ can be your backup. +