Warm standby patch

I'm submitting this patch in attempt to clarify some issues with the
warm standby documentation which caused some confusion in our
organization and which have been recently discussed on the admin list.

I apologize for posting twice, but I noticed that my pseudo-code
was unnecessarily long and complex, and the two return points might
offend some people.

-Kevin


Index: backup.sgml
===================================================================
RCS file: /projects/cvsroot/pgsql/doc/src/sgml/backup.sgml,v
retrieving revision 2.98
diff -c -r2.98 backup.sgml
*** backup.sgml	29 Jun 2007 15:46:21 -0000	2.98
--- backup.sgml	29 Jun 2007 21:59:56 -0000
***************
*** 1402,1411 ****
      server. Normal recovery processing would request a file from the
      WAL archive, reporting failure if the file was unavailable.  For
      standby processing it is normal for the next file to be
!     unavailable, so we must be patient and wait for it to appear. A
!     waiting restore_command</> can be written as a custom
      script that loops after polling for the existence of the next WAL
!     file. There must also be some way to trigger failover, which
      should interrupt the restore_command</>, break the loop
      and return a file-not-found error to the standby server. This
      ends recovery and the standby will then come up as a normal
--- 1402,1423 ----
      server. Normal recovery processing would request a file from the
      WAL archive, reporting failure if the file was unavailable.  For
      standby processing it is normal for the next file to be
!     unavailable, so we must be patient and wait for it to appear.
!    
! 
!    
!     A waiting restore_command</> can be written as a custom
      script that loops after polling for the existence of the next WAL
!     file. The script will occassionally be invoked with a request for
!     a file other than a WAL file.  Such a request can be identified
!     by a file name which is anything except 24 hexadecimal characters.
!     If the requested file is available, it should be copied; otherwise
!     the script should return a file-not-found error.  This does not
!     always terminate recovery mode.
!    
! 
!    
!     There must also be some way to trigger failover, which
      should interrupt the restore_command</>, break the loop
      and return a file-not-found error to the standby server. This
      ends recovery and the standby will then come up as a normal
***************
*** 1415,1430 ****
     
      Pseudocode for a suitable restore_command</> is:
  
! triggered = false;
! while (!NextWALFileReady() && !triggered)
! {
!     sleep(100000L);         /* wait for ~0.1 sec */
!     if (CheckForExternalTrigger())
!         triggered = true;
! }
! if (!triggered)
!         CopyWALFileForRecovery();
  
     
  
     
--- 1427,1443 ----
     
      Pseudocode for a suitable restore_command</> is:
  
! if (RequestedFileIsWALFile())
!     while (!NextWALFileReady() && !CheckForExternalTrigger())
!         sleep(pollingInterval);
! return CopyFileForRecovery();
  
+     where CopyFileForRecovery() will return a file-not-found error when
+     the file doesn't exist, and zero for success when the copy succeeds.
+     If a large number is returned, the recovery process will interpret
+     this as indicating catastrophic failure, and will terminate the
+     standby instance of PostgreSQL, rather
+     than switching to a "ready" state.