Update user docs for switch to POSIX semaphores.

Since commit ecb0d20a9 hasn't crashed and burned, here's the promised
docs update for it.

In addition to explaining that Linux and FreeBSD ports now use POSIX
semaphores, I did some wordsmithing on pre-existing wording; in
particular trying to clarify which SysV parameters need to be set with
an eye to total usage across all applications.

diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 88ec120841f7a3ce86743a7c34923fe4dbd50941..a8efb3d006db789e8fa2698c4890b7e1f5a36e5d 100644 (file)
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -605,27 +605,47 @@ psql: could not connect to server: No such file or directory
    
 
    
-    Shared memory and semaphores are collectively referred to as
-    System V
-    IPC (together with message queues, which are not
-    relevant for PostgreSQL).  Except on
-    Windows, where PostgreSQL
-    provides its own replacement implementation of these facilities, these
-    facilities are required in order to run
-    PostgreSQL.
+    PostgreSQL requires the operating system to provide
+    inter-process communication (IPC) features, specifically
+    shared memory and semaphores.  Unix-derived systems typically provide
+    System V IPC,
+    POSIX IPC, or both.
+    Windows has its own implementation of
+    these features and is not discussed here.
    
 
    
     The complete lack of these facilities is usually manifested by an
-    <errorname>Illegal system call error upon server start. In
-    that case there is no alternative but to reconfigure your
+    <quote>Illegal system call error upon server
+    start.  In that case there is no alternative but to reconfigure your
     kernel.  PostgreSQL won't work without them.
     This situation is rare, however, among modern operating systems.
    
 
    
-    When PostgreSQL exceeds one of the various hard
-    IPC limits, the server will refuse to start and
+    Upon starting the server, PostgreSQL normally allocates
+    a very small amount of System V shared memory, as well as a much larger
+    amount of POSIX (mmap) shared memory.
+    In addition a significant number of semaphores, which can be either
+    System V or POSIX style, are created at server startup.  Currently,
+    POSIX semaphores are used on Linux and FreeBSD systems while other
+    platforms use System V semaphores.
+   
+
+   
+    
+     Prior to PostgreSQL 9.3, only System V shared memory
+     was used, so the amount of System V shared memory required to start the
+     server was much larger.  If you are running an older version of the
+     server, please consult the documentation for your server version.
+    
+   
+
+   
+    System V IPC features are typically constrained by
+    system-wide allocation limits.
+    When PostgreSQL exceeds one of these limits,
+    the server will refuse to start and
     should leave an instructive error message describing the problem
     and what to do about it. (See also 
     linkend="server-start-failures">.) The relevant kernel
@@ -634,15 +654,6 @@ psql: could not connect to server: No such file or directory
     them, however, vary. Suggestions for some platforms are given below.
    
 
-   
-     
-       Prior to PostgreSQL 9.3, the amount of System V shared
-       memory required to start the server was much larger.  If you are running
-       an older version of the server, please consult the documentation for
-       your server version.
-     
-   
-
    
     <systemitem class="osname">System V</> <acronym>IPC</> Parameters
 
@@ -651,7 +662,7 @@ psql: could not connect to server: No such file or directory
       
        Name
        Description
-       Reasonable values
+       Values needed to run one PostgreSQL instance
       
      
 
@@ -659,7 +670,7 @@ psql: could not connect to server: No such file or directory
       
        SHMMAX
        Maximum size of shared memory segment (bytes)
-       at least 1kB (more if running many copies of the server)
+       at least 1kB, but the default is usually much higher
       
 
       
@@ -671,7 +682,9 @@ psql: could not connect to server: No such file or directory
       
        SHMALL
        Total amount of shared memory available (bytes or pages)
-       if bytes, same as SHMMAX; if pages, ceil(SHMMAX/PAGE_SIZE)
+       same as SHMMAX if bytes,
+        or ceil(SHMMAX/PAGE_SIZE) if pages,
+        plus room for other applications
       
 
       
@@ -689,7 +702,7 @@ psql: could not connect to server: No such file or directory
        
         SEMMNI
         Maximum number of semaphore identifiers (i.e., sets)
-        at least ceil((max_connections + autovacuum_max_workers + max_worker_processes + 5) / 16)
+        at least ceil((max_connections + autovacuum_max_workers + max_worker_processes + 5) / 16) plus room for other applications
        
 
        
@@ -725,9 +738,8 @@ psql: could not connect to server: No such file or directory
     (typically 48 bytes, on 64-bit platforms) for each copy of the server.
     On most modern operating systems, this amount can easily be allocated.
     However, if you are running many copies of the server, or if other
-    applications are also using System V shared memory, it may be necessary
-    to increase SHMMAX, the maximum size in bytes of a shared
-    memory segment, or SHMALL, the total amount of System V shared
+    applications are also using System V shared memory, it may be necessary to
+    increase SHMALL, which is the total amount of System V shared
     memory system-wide.  Note that SHMALL is measured in pages
     rather than bytes on many systems.
    
@@ -742,6 +754,7 @@ psql: could not connect to server: No such file or directory
    
 
    
+    When using System V semaphores,
     PostgreSQL uses one semaphore per allowed connection
     (), allowed autovacuum worker process
     () and allowed background
@@ -779,15 +792,19 @@ psql: could not connect to server: No such file or directory
    
 
    
-    The SEMMSL parameter, which determines how many
-    semaphores can be in a set, must be at least 17 for
+    Various other settings related to semaphore undo, such as
+    SEMMNU and SEMUME, do not affect
     PostgreSQL.
    
 
    
-    Various other settings related to semaphore undo, such as
-    SEMMNU and SEMUME, do not affect
-    PostgreSQL.
+    When using POSIX semaphores, the number of semaphores needed is the
+    same as for System V, that is one semaphore per allowed connection
+    (), allowed autovacuum worker process
+    () and allowed background
+    process ().
+    On the platforms where this option is preferred, there is no specific
+    kernel limit on the number of POSIX semaphores.