Improve a couple of comments relating to large object snapshot management.

robertmhaas · robertmhaas · commit 2cb67c4c306f · 2010-01-07T02:41:16.000Z
diff --git 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
@@ -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)

Original file line number	Diff line number	Diff line change
`@@ -8,7 +8,7 @@`
`8`	`8`	`*`
`9`	`9`	`*`
`10`	`10`	`* IDENTIFICATION`
`11`		`- * $PostgreSQL: pgsql/src/backend/catalog/pg_largeobject.c,v 1.36 2010/01/02 16:57:36 momjian Exp $`
	`11`	`+ * $PostgreSQL: pgsql/src/backend/catalog/pg_largeobject.c,v 1.37 2010/01/07 02:41:16 rhaas Exp $`
`12`	`12`	`*`
`13`	`13`	`*-------------------------------------------------------------------------`
`14`	`14`	`*/`
`@@ -251,9 +251,11 @@ LargeObjectAlterOwner(Oid loid, Oid newOwnerId)`
`251`	`251`	`* We don't use the system cache to for large object metadata, for fear of`
`252`	`252`	`* using too much local memory.`
`253`	`253`	`*`
`254`		`- * Note that LargeObjectExists always scans the system catalog`
`255`		`- * with SnapshotNow, so it is unavailable to use to check`
`256`		`- * existence in read-only accesses.`
	`254`	`+ * This function always scans the system catalog using SnapshotNow, so it`
	`255`	`+ * should not be used when a large object is opened in read-only mode (because`
	`256`	`+ * large objects opened in read only mode are supposed to be viewed relative`
	`257`	`+ * to the caller's snapshot, whereas in read-write mode they are relative to`
	`258`	`+ * SnapshotNow).`
`257`	`259`	`*/`
`258`	`260`	`bool`
`259`	`261`	`LargeObjectExists(Oid loid)`