# $EPIC: defer,v 1.2 2005/03/11 04:55:04 jnelson Exp $
Synopsis:
   defer {<stuff>}

Description:
   The DEFER command schedules <stuff> to be executed later on when
   the client is idle, and there is no risk that if <stuff> were to destroy
   something that it would crash the client.

   Any time you want to destroy something, whether it be a DCC, a server,
   a open file, an /on, a window, a log file, etc, you always run the risk
   that some alias further down the stack might have done a /wait or a 
   /pause or a /redirect, and is holding a reference to the thing you want
   to destroy.  It is possible that if you destroy that thing, and then the 
   /wait or /pause or /redirect finishes, that the alias down further in the
   stack might try to use the object, which you destroyed, and thus it will
   crash the client.

   Now, I'm not saying that such cases are "normal" but there are sequencing
   issues that may result in it being dangerous for you to destroy something
   at certain times.  THIS IS ESPECIALLY TRUE INSIDE ONs.  If you find that
   your script can crash the client by deleting something, the first thing
   you should try is to put a /DEFER in front of the command to see if that
   fixes it.

   Obviously, if you /DEFER destroying something, it won't be destroyed
   immediately, so you can't use it in any place where it's important that
   the object is actually destroyed before you continue.

Example 1:
   Here's an example that will malfunction on many versions:

	   ON #401 -1 * { on 401 - }
	   ON ^401 * { echo -- 401 hooked! $*
	   whois doesnotexist

   The reason why this crashes is because the -1 serial numbered on deletes
   both on's, but the /ON system still has a pointer to the second on and
   still intends to run it, even after it's been deleted.  Although this 
   particular bug has been fixed in recent versions, it's an example of the
   kind of destruction that could cause a crash.

   So in the above example, this is the "safer" way:

	   ON #401 -1 * { defer on 401 - }
	   ON ^401 * { echo -- 401 hooked! $*
	   whois doesnotexist

   But obviously this means that the second /on will execute.  (There is no 
   reasonable, portable, crash-proof way to destroy an /on so it will not
   run from a lower numbered serial number.)

Example 2:
   It doesn't matter what you want to do within an /ON WINDOW_* hook, you
   probably should /DEFER it.

History:
   The DEFER command first appeared in EPIC4-0.9.16.

