#$EPIC: wait.txt,v 1.5 2006/08/30 19:28:30 sthalik Exp $
======Synopsis:======
__wait__ [for] [%<process>]|[-cmd <command>] \\
__wait__ for =<fd>

======Description:======
__WAIT__ is a convenient means for executing a series of commands and
ensuring that those commands are run in the desired sequence.  The
command can make the client wait for the completion of server or
subprocess output.

Use of __WAIT__ is almost always avoidable, see section Other Notes below.

The simplest form is __WAIT__ with no arguments.  When run after a server
query, the client will not execute further commands (within an alias;
does not apply to the input line) until all server output has been
received.

If used as /wait for, it will execute the command, and halt until a server
reply is detected.

When waiting on an [[exec command|EXEC]]ed subprocess, the client will
block until the subprocess has completed.  This effectively disables the
the entire client (and can even cause it to ping timeout from the
server).

The last form allows for a series of commands to be executed in no
particular order.  This is most useful when a particular command needs
to be issued, but subsequent commands don't rely on its contents or
timing.

When waiting on an [[exec command|EXEC]]ed subprocess _with_ a -cmd
option, the command will return immediately, and the command will be
executed when the process finishes.  This will be as if the [[exec
command|EXEC]] command had been given a -end flag with the same command.

__WAIT for =fd__ waits for a [[DCC]] or $[[connect function|connect]]
identified by //fd// to be completed.

======Options:======
   -cmd <commands>   execute the given commands at the end of the alias/exec.

======Examples:======
To add a header and footer to a channel's ban list:
      alias banlist {
         echo *** Begin ban list for #blah (generated $stime($time()))
         mode #blah +b
         wait
         echo *** End ban list for #blah
      }

To run a subprocess, and wait before doing anything else:
      alias localusers {
         echo *** Getting list of local users...
         exec -name who who
         wait %who
         echo *** Finished subshell `who' listing
      }

The second command will actually finish before the first:
      alias backwards {
         wait -cmd echo this appears last
         echo this appears first
      }

======Known Issues:======
__WAIT__ turns a non-blocking operation into a blocking one. This
is almost always a bad idea, as it prevents the client from doing
other things. At best, it is inefficient, at worst it can completely
lock up the client. Use with care, and avoid if possible.

======Other Notes:======
If multiple __WAIT__s are pending at once, they will all return once the last
one is completed, to ensure that no data is lost.

Using __WAIT__ for server queries is useful.  However, there are often times
then it is not the most efficient way to do something.  When possible,
hooking server numerics that marks the end of a message is preferred, as
it is generally more reliable.

Using __wait__(5) or __wait__(5) __for__ and /[[redirect]] is a Bad Thing(tm),
so don't do it.