'\" -*- coding: UTF-8 -*-
.if \n(.g .ds T< \\FC
.if \n(.g .ds T> \\F[\n[.fam]]
.de URL
\\$2 \(la\\$1\(ra\\$3
..
.if \n(.g .mso www.tmac
.TH "SLONIK WAIT FOR EVENT" 7 "22 September 2023" "" "Slony-I 2.2.11 Documentation"
.SH NAME
WAIT FOR EVENT \- Have Slonik script wait for previous event to complete 
.SH SYNOPSIS
'nh
.fi
.ad l
\*(T<\fBWAIT FOR EVENT (options);\fR\*(T> \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
'in \n(.iu-\nxu
.ad b
'hy
.SH DESCRIPTION
Waits for event Confirmation.
.PP
Slonik remembers the last event
generated on every node during script execution (events generated
by earlier calls are currently not checked). In certain situations
it is necessary that events generated on one node (such as
\fBCREATE SET\fR) are processed on another node
before issuing more commands (for instance, \fBSLONIK SUBSCRIBE SET\fR(7)). \fBWAIT FOR EVENT\fR
may be used to cause the slonik script
to wait for confirmation of an event, which hopefully means that
the subscriber node is ready for the next action.
.PP
\fBWAIT FOR EVENT\fR must be called outside of
any \fBtry\fR block in order to work, since new
confirm messages don't become visible within a transaction.
.TP 
\*(T<ORIGIN = ival | ALL \*(T>
The origin of the event(s) to wait for.
.TP 
\*(T<CONFIRMED = ival | ALL \*(T>
The node ID of the receiver that must confirm the event(s).
.TP 
\*(T<WAIT ON = ival \*(T>
The ID of the node where the \(lqsl_confirm\(rq [not available as a man page] table
is to be checked.
.TP 
\*(T<TIMEOUT = ival \*(T>
The number of seconds to wait. Default is 600
(10 minutes). \fBTIMEOUT = 0\fR causes the script
to wait indefinitely.
.SH EXAMPLE
.nf
\*(T<WAIT FOR EVENT (
  ORIGIN = ALL,
  CONFIRMED = ALL,
  WAIT ON = 1
);
    \*(T>
.fi
.SH "LOCKING BEHAVIOUR "
No application-visible locking should take place. 
.SH "VERSION INFORMATION "
This command was introduced in Slony-I 1.0 
.PP
In version 2.0, the default value for \fBWAIT ON\fR
was removed, so a node must be specified.
.SH "ODDITIES "
Not all events return
interesting results. For instance, many people have run afoul of
problems with \fBSLONIK SUBSCRIBE SET\fR(7), when subscribing a
new set. Be aware (and beware!) that a \fBSLONIK SUBSCRIBE SET\fR(7) request will return the event
confirmation almost immediately, even though there might be several
hours of work to do before the subscription is ready. The trouble
with \fBSLONIK SUBSCRIBE SET\fR(7) is that it is processed as
\fItwo\fR events, one on the origin node, with a
second event, to enable the subscription, on the subscriber.
.PP
In order to more reliably monitor from within a \fBslonik\fR(1) script that \fBSLONIK SUBSCRIBE SET\fR(7) is
complete, you may submit a \fBSLONIK SYNC\fR(7) event after
the subscription, and have the WAIT request wait on the
\fBSYNC\fR event, as follows. 
.PP
.nf
\*(T<     # Assuming that node 1 is the origin for set 999 that has direct subscribers 2 and 3
     SUBSCRIBE SET (ID = 999, PROVIDER = 1, RECEIVER = 2);
     WAIT FOR EVENT (ORIGIN = 1, CONFIRMED = ALL, WAIT ON=1);
     SUBSCRIBE SET (ID = 999, PROVIDER = 1, RECEIVER = 3);
     WAIT FOR EVENT (ORIGIN = 1, CONFIRMED = ALL, WAIT ON=1);
     MERGE SET ( ID = 1, ADD ID = 999, ORIGIN = 1 );
    \*(T>
.fi