postgresql/src/backend/replication
Heikki Linnakangas 89fd72cbf2 Introduce a pipe between postmaster and each backend, which can be used to
detect postmaster death. Postmaster keeps the write-end of the pipe open,
so when it dies, children get EOF in the read-end. That can conveniently
be waited for in select(), which allows eliminating some of the polling
loops that check for postmaster death. This patch doesn't yet change all
the loops to use the new mechanism, expect a follow-on patch to do that.

This changes the interface to WaitLatch, so that it takes as argument a
bitmask of events that it waits for. Possible events are latch set, timeout,
postmaster death, and socket becoming readable or writeable.

The pipe method behaves slightly differently from the kill() method
previously used in PostmasterIsAlive() in the case that postmaster has died,
but its parent has not yet read its exit code with waitpid(). The pipe
returns EOF as soon as the process dies, but kill() continues to return
true until waitpid() has been called (IOW while the process is a zombie).
Because of that, change PostmasterIsAlive() to use the pipe too, otherwise
WaitLatch() would return immediately with WL_POSTMASTER_DEATH, while
PostmasterIsAlive() would claim it's still alive. That could easily lead to
busy-waiting while postmaster is in zombie state.

Peter Geoghegan with further changes by me, reviewed by Fujii Masao and
Florian Pflug.
2011-07-08 18:44:07 +03:00
..
libpqwalreceiver IDENTIFY_SYSTEM now returns 3 fields, not 2 2011-02-06 07:46:14 +01:00
.gitignore Add .gitignore to silence git complaints about parser/scanner output files. 2011-01-15 16:05:28 -05:00
Makefile Add missing -I switch for VPATH builds. 2011-06-22 13:20:03 -04:00
README Replication README updates. 2011-03-10 08:59:59 -05:00
basebackup.c Message style improvements 2011-07-08 07:37:04 +03:00
repl_gram.y Implement NOWAIT option for BASE_BACKUP command 2011-02-09 10:59:53 +01:00
repl_scanner.l Implement NOWAIT option for BASE_BACKUP command 2011-02-09 10:59:53 +01:00
syncrep.c Introduce a pipe between postmaster and each backend, which can be used to 2011-07-08 18:44:07 +03:00
walreceiver.c Introduce a pipe between postmaster and each backend, which can be used to 2011-07-08 18:44:07 +03:00
walreceiverfuncs.c pgindent run before PG 9.1 beta 1. 2011-04-10 11:42:00 -04:00
walsender.c Introduce a pipe between postmaster and each backend, which can be used to 2011-07-08 18:44:07 +03:00

README

src/backend/replication/README

Walreceiver - libpqwalreceiver API
----------------------------------

The transport-specific part of walreceiver, responsible for connecting to
the primary server, receiving WAL files and sending messages, is loaded
dynamically to avoid having to link the main server binary with libpq.
The dynamically loaded module is in libpqwalreceiver subdirectory.

The dynamically loaded module implements four functions:


bool walrcv_connect(char *conninfo, XLogRecPtr startpoint)

Establish connection to the primary, and starts streaming from 'startpoint'.
Returns true on success.

bool walrcv_receive(int timeout, unsigned char *type, char **buffer, int *len)

Retrieve any message available through the connection, blocking for
maximum of 'timeout' ms. If a message was successfully read, returns true,
otherwise false. On success, a pointer to the message payload is stored in
*buffer, length in *len, and the type of message received in *type. The
returned buffer is valid until the next call to walrcv_* functions, the
caller should not attempt freeing it.

void walrcv_send(const char *buffer, int nbytes)

Send a message to XLOG stream.

void walrcv_disconnect(void);

Disconnect.


This API should be considered internal at the moment, but we could open it
up for 3rd party replacements of libpqwalreceiver in the future, allowing
pluggable methods for receiveing WAL.

Walreceiver IPC
---------------

When the WAL replay in startup process has reached the end of archived WAL,
recoverable using recovery_command, it starts up the walreceiver process
to fetch more WAL (if streaming replication is configured).

Walreceiver is a postmaster subprocess, so the startup process can't fork it
directly. Instead, it sends a signal to postmaster, asking postmaster to launch
it. Before that, however, startup process fills in WalRcvData->conninfo,
and initializes the starting point in WalRcvData->receiveStart.

As walreceiver receives WAL from the master server, and writes and flushes
it to disk (in pg_xlog), it updates WalRcvData->receivedUpto and signals
the startup process to know how far WAL replay can advance.

Walreceiver sends information about replication progress to the master server
whenever either it writes or flushes new WAL, or the specified interval elapses.
This is used for reporting purpose.

Walsender IPC
-------------

At shutdown, postmaster handles walsender processes differently from regular
backends. It waits for regular backends to die before writing the
shutdown checkpoint and terminating pgarch and other auxiliary processes, but
that's not desirable for walsenders, because we want the standby servers to
receive all the WAL, including the shutdown checkpoint, before the master
is shut down. Therefore postmaster treats walsenders like the pgarch process,
and instructs them to terminate at PM_SHUTDOWN_2 phase, after all regular
backends have died and bgwriter has written the shutdown checkpoint.

When postmaster accepts a connection, it immediately forks a new process
to handle the handshake and authentication, and the process initializes to
become a backend. Postmaster doesn't know if the process becomes a regular
backend or a walsender process at that time - that's indicated in the
connection handshake - so we need some extra signaling to let postmaster
identify walsender processes.

When walsender process starts up, it marks itself as a walsender process in
the PMSignal array. That way postmaster can tell it apart from regular
backends.

Note that no big harm is done if postmaster thinks that a walsender is a
regular backend; it will just terminate the walsender earlier in the shutdown
phase. A walsenders will look like a regular backends until it's done with the
initialization and has marked itself in PMSignal array, and at process
termination, after unmarking the PMSignal slot.

Each walsender allocates an entry from the WalSndCtl array, and tracks
information about replication progress. User can monitor them via
statistics views.


Walsender - walreceiver protocol
--------------------------------

See manual.