Provided by: slony1-doc_1.2.20-1_all bug

NAME

       WAIT FOR EVENT - Have Slonik script wait for previous event to complete

SYNOPSIS

       WAIT FOR EVENT (options);

DESCRIPTION

       Waits for event Confirmation.

       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 CREATE SET) are processed on another node before
       issuing more commands (for instance, SLONIK SUBSCRIBE SET(7)). WAIT FOR
       EVENT  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.

       WAIT  FOR  EVENT  must  be  called outside of any try block in order to
       work,  since  new  confirm  messages  don’t  become  visible  within  a
       transaction.

       ORIGIN = ival | ALL
              The origin of the event(s) to wait for.

       CONFIRMED = ival | ALL
              The node ID of the receiver that must confirm the event(s).

       WAIT ON = ival
              The  ID  of  the node where the “sl_confirm” [not available as a
              man page] table is to be checked.

       TIMEOUT = ival
              The number of seconds to wait.  Default  is  600  (10  minutes).
              TIMEOUT = 0 causes the script to wait indefinitely.

EXAMPLE

       WAIT FOR EVENT (
         ORIGIN = ALL,
         CONFIRMED = ALL,
         WAIT ON = 1
       );

LOCKING BEHAVIOUR

       No application-visible locking should take place.

VERSION INFORMATION

       This command was introduced in Slony-I 1.0

       In  version  2.0,  the default value for WAIT ON was removed, so a node
       must be specified.

ODDITIES

       Not all events return interesting results. For  instance,  many  people
       have   run  afoul  of  problems  with  SLONIK  SUBSCRIBE  SET(7),  when
       subscribing a new set. Be aware (and beware!) that a  SLONIK  SUBSCRIBE
       SET(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 SLONIK SUBSCRIBE SET(7) is that
       it is processed as two events, one on the origin node,  with  a  second
       event, to enable the subscription, on the subscriber.

       In  order  to more reliably monitor from within a slonik(1) script that
       SLONIK SUBSCRIBE SET(7) is complete, you may submit  a  SLONIK  SYNC(7)
       event  after  the  subscription,  and have the WAIT request wait on the
       SYNC event, as follows.

            # Assuming that set 1 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);
            SYNC (ID=1);
            WAIT FOR EVENT (ORIGIN = 1, CONFIRMED = ALL, WAIT ON=1);
            MERGE SET ( ID = 1, ADD ID = 999, ORIGIN = 1 );

                                5 January 2010        SLONIK WAIT FOR EVENT(7)