branches/zip: Add comments about the lock and latch protection of externally

stored columns (BLOBs).

btr_copy_blob_prefix(), btr_copy_zblob_prefix(),
btr_copy_externally_stored_field_prefix_low(),
btr_copy_externally_stored_field_prefix(),
btr_copy_externally_stored_field(),
btr_rec_copy_externally_stored_field():
Note that the page containing the clustered index record that points to
the BLOB must be latched.

btr_copy_zblob_prefix(): Note that there is no latch on the page, and thus
all accesses to a given page via this function must be covered by the same
set of locks or latches.

btr_copy_zblob_prefix(): Note that the block acquired by
buf_page_get_zip() is protected by an exclusive table lock or
or by a latch on the clustered index record.

btr/btr0cur.c

@@ -4284,7 +4284,8 @@ btr_rec_free_updated_extern_fields(
 }
 
 /***********************************************************************
-Copies the prefix of an uncompressed BLOB. */
+Copies the prefix of an uncompressed BLOB.  The clustered index record
+that points to this BLOB must be protected by a lock or a page latch. */
 static
 ulint
 btr_copy_blob_prefix(
@@ -4344,7 +4345,8 @@ btr_copy_blob_prefix(
 }
 
 /***********************************************************************
-Copies the prefix of a compressed BLOB. */
+Copies the prefix of a compressed BLOB.  The clustered index record
+that points to this BLOB must be protected by a lock or a page latch. */
 static
 void
 btr_copy_zblob_prefix(
@@ -4365,6 +4367,10 @@ btr_copy_zblob_prefix(
 		int		err;
 		ulint		next_page_no;
 
+		/* There is no latch on bpage directly.  Instead,
+		bpage is protected by the B-tree page latch that
+		is being held on the clustered index record, or,
+		in row_merge_copy_blobs(), by an exclusive table lock. */
 		bpage = buf_page_get_zip(space_id, zip_size, page_no);
 
 		if (UNIV_UNLIKELY(!bpage)) {
@@ -4464,7 +4470,9 @@ end_of_blob:
 }
 
 /***********************************************************************
-Copies the prefix of an externally stored field of a record. */
+Copies the prefix of an externally stored field of a record.  The
+clustered index record that points to this BLOB must be protected by a
+lock or a page latch. */
 static
 ulint
 btr_copy_externally_stored_field_prefix_low(
@@ -4512,10 +4520,8 @@ btr_copy_externally_stored_field_prefix_low(
 }
 
 /***********************************************************************
-Copies the prefix of an externally stored field of a record. Parameter
+Copies the prefix of an externally stored field of a record.  The
-data contains a pointer to 'internally' stored part of the field:
+clustered index record must be protected by a lock or a page latch. */
-possibly some data, and the reference to the externally stored part in
-the last BTR_EXTERN_FIELD_REF_SIZE bytes of data. */
 
 ulint
 btr_copy_externally_stored_field_prefix(
@@ -4527,7 +4533,8 @@ btr_copy_externally_stored_field_prefix(
 				zero for uncompressed BLOBs */
 	const byte*	data,	/* in: 'internally' stored part of the
 				field containing also the reference to
-				the external part */
+				the external part; must be protected by
+				a lock or a page latch */
 	ulint		local_len)/* in: length of data, in bytes */
 {
 	ulint	space_id;
@@ -4563,10 +4570,8 @@ btr_copy_externally_stored_field_prefix(
 }
 
 /***********************************************************************
-Copies an externally stored field of a record to mem heap. Parameter
+Copies an externally stored field of a record to mem heap.  The
-data contains a pointer to 'internally' stored part of the field:
+clustered index record must be protected by a lock or a page latch. */
-possibly some data, and the reference to the externally stored part in
-the last BTR_EXTERN_FIELD_REF_SIZE bytes of data. */
 static
 byte*
 btr_copy_externally_stored_field(
@@ -4575,7 +4580,8 @@ btr_copy_externally_stored_field(
 	ulint*		len,	/* out: length of the whole field */
 	const byte*	data,	/* in: 'internally' stored part of the
 				field containing also the reference to
-				the external part */
+				the external part; must be protected by
+				a lock or a page latch */
 	ulint		zip_size,/* in: nonzero=compressed BLOB page size,
 				zero for uncompressed BLOBs */
 	ulint		local_len,/* in: length of data */
@@ -4622,7 +4628,8 @@ byte*
 btr_rec_copy_externally_stored_field(
 /*=================================*/
 				/* out: the field copied to heap */
-	const rec_t*	rec,	/* in: record */
+	const rec_t*	rec,	/* in: record in a clustered index;
+				must be protected by a lock or a page latch */
 	const ulint*	offsets,/* in: array returned by rec_get_offsets() */
 	ulint		zip_size,/* in: nonzero=compressed BLOB page size,
 				zero for uncompressed BLOBs */

buf/buf0buf.c

@@ -1479,7 +1479,12 @@ buf_page_reset_file_page_was_freed(
 #endif /* UNIV_DEBUG_FILE_ACCESSES */
 
 /************************************************************************
-Get read access to a compressed page (usually FIL_PAGE_TYPE_ZBLOB). */
+Get read access to a compressed page (usually FIL_PAGE_TYPE_ZBLOB).
+The page must be released with buf_page_release_zip().
+NOTE: the page is not protected by any latch.  Mutual exclusion has to
+be implemented at a higher level.  In other words, all possible
+accesses to a given page through this function must be protected by
+the same set of mutexes or latches. */
 
 buf_page_t*
 buf_page_get_zip(

include/btr0cur.h

@@ -528,10 +528,8 @@ btr_free_externally_stored_field(
 					data an an X-latch to the index
 					tree */
 /***********************************************************************
-Copies the prefix of an externally stored field of a record. Parameter
+Copies the prefix of an externally stored field of a record.  The
-data contains a pointer to 'internally' stored part of the field:
+clustered index record must be protected by a lock or a page latch. */
-possibly some data, and the reference to the externally stored part in
-the last BTR_EXTERN_FIELD_REF_SIZE bytes of data. */
 
 ulint
 btr_copy_externally_stored_field_prefix(
@@ -543,7 +541,8 @@ btr_copy_externally_stored_field_prefix(
 				zero for uncompressed BLOBs */
 	const byte*	data,	/* in: 'internally' stored part of the
 				field containing also the reference to
-				the external part */
+				the external part; must be protected by
+				a lock or a page latch */
 	ulint		local_len);/* in: length of data, in bytes */
 /***********************************************************************
 Copies an externally stored field of a record to mem heap. */
@@ -552,7 +551,8 @@ byte*
 btr_rec_copy_externally_stored_field(
 /*=================================*/
 				/* out: the field copied to heap */
-	const rec_t*	rec,	/* in: record */
+	const rec_t*	rec,	/* in: record in a clustered index;
+				must be protected by a lock or a page latch */
 	const ulint*	offsets,/* in: array returned by rec_get_offsets() */
 	ulint		zip_size,/* in: nonzero=compressed BLOB page size,
 				zero for uncompressed BLOBs */

include/buf0buf.h

@@ -221,7 +221,11 @@ buf_page_try_get_func(
 
 /************************************************************************
 Get read access to a compressed page (usually FIL_PAGE_TYPE_ZBLOB).
-The page must be released with buf_page_release_zip(). */
+The page must be released with buf_page_release_zip().
+NOTE: the page is not protected by any latch.  Mutual exclusion has to
+be implemented at a higher level.  In other words, all possible
+accesses to a given page through this function must be protected by
+the same set of mutexes or latches. */
 
 buf_page_t*
 buf_page_get_zip(