Document what the "rep; nop" x86 assembler sequence is actually equivalent

to, and what it is intended to do.

diff --git a/src/include/storage/s_lock.h b/src/include/storage/s_lock.h
index 5e504b36e0448b39e2eb513b03cdf883b32b0875..3783b79fa5db18dc0794aeebe4ccc553167f474e 100644 (file)
--- a/src/include/storage/s_lock.h
+++ b/src/include/storage/s_lock.h
@@ -66,7 +66,7 @@
  * Portions Copyright (c) 1996-2004, PostgreSQL Global Development Group
  * Portions Copyright (c) 1994, Regents of the University of California
  *
- *   $PostgreSQL: pgsql/src/include/storage/s_lock.h,v 1.131 2004/09/24 01:48:43 tgl Exp $
+ *   $PostgreSQL: pgsql/src/include/storage/s_lock.h,v 1.132 2004/10/06 23:41:59 neilc Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -138,6 +138,29 @@ tas(volatile slock_t *lock)
 static __inline__ void
 spin_delay(void)
 {
+   /*
+    * This sequence is equivalent to the PAUSE instruction ("rep" is
+    * ignored by old IA32 processors if the following instruction is
+    * not a string operation); the IA-32 Architecture Software
+    * Developer's Manual, Vol. 3, Section 7.7.2 describes why using
+    * PAUSE in the inner loop of a spin lock is necessary for good
+    * performance:
+    *
+    *     The PAUSE instruction improves the performance of IA-32
+    *     processors supporting Hyper-Threading Technology when
+    *     executing spin-wait loops and other routines where one
+    *     thread is accessing a shared lock or semaphore in a tight
+    *     polling loop. When executing a spin-wait loop, the
+    *     processor can suffer a severe performance penalty when
+    *     exiting the loop because it detects a possible memory order
+    *     violation and flushes the core processor's pipeline. The
+    *     PAUSE instruction provides a hint to the processor that the
+    *     code sequence is a spin-wait loop. The processor uses this
+    *     hint to avoid the memory order violation and prevent the
+    *     pipeline flush. In addition, the PAUSE instruction
+    *     de-pipelines the spin-wait loop to prevent it from
+    *     consuming execution resources excessively.
+    */
    __asm__ __volatile__(
        " rep; nop          \n");
 }