From 3d21f08bccd316c3850a1943c1ee1e381dab1588 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Mon, 10 Oct 2016 15:11:33 -0400 Subject: [PATCH] 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. --- doc/src/sgml/runtime.sgml | 83 +++++++++++++++++++++++---------------- 1 file changed, 50 insertions(+), 33 deletions(-) diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml index 88ec120841f..a8efb3d006d 100644 --- 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 - Illegal system call error upon server start. In - that case there is no alternative but to reconfigure your + 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 .) 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. -- 2.30.2