From 2cb67c4c306f77782d9e6077c9d41630f3f6cbac Mon Sep 17 00:00:00 2001
From: Robert Haas <rhaas@postgresql.org>
Date: Thu, 7 Jan 2010 02:41:16 +0000
Subject: [PATCH] Improve a couple of comments relating to large object
 snapshot management.

---
 src/backend/catalog/aclchk.c         | 17 ++++++-----------
 src/backend/catalog/pg_largeobject.c | 10 ++++++----
 2 files changed, 12 insertions(+), 15 deletions(-)

diff --git a/src/backend/catalog/aclchk.c b/src/backend/catalog/aclchk.c
index 6c16fd6a6e..d1b287c039 100644
--- a/src/backend/catalog/aclchk.c
+++ b/src/backend/catalog/aclchk.c
@@ -8,7 +8,7 @@
  *
  *
  * IDENTIFICATION
- *	  $PostgreSQL: pgsql/src/backend/catalog/aclchk.c,v 1.160 2010/01/05 21:53:58 rhaas Exp $
+ *	  $PostgreSQL: pgsql/src/backend/catalog/aclchk.c,v 1.161 2010/01/07 02:41:15 rhaas Exp $
  *
  * NOTES
  *	  See acl.h.
@@ -3515,16 +3515,11 @@ pg_language_aclmask(Oid lang_oid, Oid roleid,
 /*
  * Exported routine for examining a user's privileges for a largeobject
  *
- * The reason why this interface has an argument of snapshot is that
- * we apply a snapshot available on lo_open(), not SnapshotNow, when
- * it is opened as read-only mode.
- * If we could see the metadata and data from inconsistent viewpoint,
- * it will give us much confusion. So, we need to provide an interface
- * which takes an argument of snapshot.
- *
- * If the caller refers a large object with a certain snapshot except
- * for SnapshotNow, its permission checks should be also applied in
- * the same snapshot.
+ * When a large object is opened for reading, it is opened relative to the
+ * caller's snapshot, but when it is opened for writing, it is always relative
+ * to SnapshotNow, as documented in doc/src/sgml/lobj.sgml.  This function
+ * takes a snapshot argument so that the permissions check can be made relative
+ * to the same snapshot that will be used to read the underlying data.
  */
 AclMode
 pg_largeobject_aclmask_snapshot(Oid lobj_oid, Oid roleid,
diff --git a/src/backend/catalog/pg_largeobject.c b/src/backend/catalog/pg_largeobject.c
index c2982e3071..d27b20ede3 100644
--- a/src/backend/catalog/pg_largeobject.c
+++ b/src/backend/catalog/pg_largeobject.c
@@ -8,7 +8,7 @@
  *
  *
  * IDENTIFICATION
- *	  $PostgreSQL: pgsql/src/backend/catalog/pg_largeobject.c,v 1.36 2010/01/02 16:57:36 momjian Exp $
+ *	  $PostgreSQL: pgsql/src/backend/catalog/pg_largeobject.c,v 1.37 2010/01/07 02:41:16 rhaas Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -251,9 +251,11 @@ LargeObjectAlterOwner(Oid loid, Oid newOwnerId)
  * We don't use the system cache to for large object metadata, for fear of
  * using too much local memory.
  *
- * Note that LargeObjectExists always scans the system catalog
- * with SnapshotNow, so it is unavailable to use to check
- * existence in read-only accesses.
+ * This function always scans the system catalog using SnapshotNow, so it
+ * should not be used when a large object is opened in read-only mode (because
+ * large objects opened in read only mode are supposed to be viewed relative
+ * to the caller's snapshot, whereas in read-write mode they are relative to
+ * SnapshotNow).
  */
 bool
 LargeObjectExists(Oid loid)
-- 
2.40.0