Difference between revisions of "Manual:DIL Manual/wait()"

From DikuMUD Wiki
Jump to navigation Jump to search
(XML import)
(checked against the compiler and the interpreter; example compiles)
Line 1: Line 1:
−
<span id="bpwait"></span>
+
= wait() =
−
wait ( i : integer , dilexp )
+
'''Procedure.''' Stops the program until an event of the given kinds comes, for which a condition holds.
−
    i : Message class to accept, see SFB_* in values.h and/or vme.h
 
−
    dilexp : Expression that has to be TRUE or not null to accept message.
 
−
    result: Waits for a command, matching the flagset, and satisfies the
 
−
            expression. When using the 'wait()' command, the first argument
 
−
            is an integer, that tells what classes of messages to wait for.
 
−
            Each message class is represented by a bit named as described in
 
−
            the chapter on messages.
 
−
'''Example:'''
 
  
−
    wait (SFB_TICK|SFB_MSG, TRUE)
+
wait(events : integer, condition)
−
    /* Will accept a message, either from another DIL program or a
 
−
      timer message. As the second argument is always TRUE, any
 
−
      such message will reactivate the DIL program.
 
−
    */
 
  
−
'''Example:'''
+
Every program spends most of its life here. <code>wait()</code> always stops the program; it
 +
goes on only with an event of one of the kinds in <code>events</code> (the <code>SFB_</code>
 +
values in vme.h, joined with <code>|</code>) for which <code>condition</code> is true. At each
 +
such event the program wakes, the condition is worked out again, and if it is false the program
 +
goes back to waiting. The built-ins <code>activator</code>, <code>medium</code>,
 +
<code>target</code>, <code>power</code>, <code>argument</code> and <code>command()</code>
 +
describe the event, so the condition can test them.
  
−
  wait (SFB_CMD, command("transmutate"))
+
{| class="wikitable"
−
  /* waits for an command entered named 'transmutate'.
+
! Value !! Event
−
      Activates the DIL program, that then can block the command, or
+
|-
−
      let it pass (and then let the game produce the normal error
+
| <code>SFB_CMD</code> || A command typed by someone near the unit, before it runs (it can still be blocked)
−
      message for unknown commands).
+
|-
−
  */
+
| <code>SFB_DONE</code> || A command that has been carried out
−
<span id="bpwait"></span>
+
|-
−
wait ( i : integer , dilexp )
+
| <code>SFB_PRE</code> || The step before some actions, e.g. a spell about to hit
−
    i : Message class to accept, see SFB_* in values.h and/or vme.h
+
|-
−
    dilexp : Expression that has to be TRUE or not null to accept message.
+
| <code>SFB_TICK</code> || The unit's heartbeat
−
    result: Waits for a command, matching the flagset, and satisfies the
+
|-
−
            expression. When using the 'wait()' command, the first argument
+
| <code>SFB_RANTIME</code> || With <code>SFB_TICK</code>: the tick comes at a random time around the heartbeat
−
            is an integer, that tells what classes of messages to wait for.
+
|-
−
            Each message class is represented by a bit named as described in
+
| <code>SFB_MSG</code> || A message from another program (<code>send</code>, <code>sendto</code>, <code>sendtoall</code>, <code>sendtoalldil</code>)
−
            the chapter on messages.
+
|-
−
'''Example:'''
+
| <code>SFB_COM</code> || A combat round
 +
|-
 +
| <code>SFB_DEAD</code> || A death nearby
 +
|-
 +
| <code>SFB_EDIT</code> || The end of an editor started with <code>beginedit()</code>
 +
|-
 +
| <code>SFB_PROMPT</code> || The player's prompt being made
 +
|}
  
−
    wait (SFB_TICK|SFB_MSG, TRUE)
+
<code>pause;</code> is <code>wait(SFB_TICK | SFB_RANTIME, TRUE)</code>, a macro in wmacros.h.
−
    /* Will accept a message, either from another DIL program or a
 
−
      timer message. As the second argument is always TRUE, any
 
−
      such message will reactivate the DIL program.
 
−
    */
 
  
−
'''Example:'''
+
== Parameters ==
 +
{| class="wikitable"
 +
! Name !! Type !! Meaning
 +
|-
 +
| events || integer || The kinds of event to wake for.
 +
|-
 +
| condition || any || True to go on: a non-zero integer, a unit or string that isn't null, a list that isn't empty.
 +
|}
  
−
  wait (SFB_CMD, command("transmutate"))
+
== Notes ==
−
  /* waits for an command entered named 'transmutate'.
+
* It waits even if the condition is true already.
−
      Activates the DIL program, that then can block the command, or
+
* Every event of the given kinds wakes the program, even one the condition then turns down. '''At every wake each <code>unitptr</code> and <code>extraptr</code> variable that isn't secured becomes null.''' Save what you need from <code>activator</code>, <code>argument</code> and the rest right after the <code>wait</code>, and <code>secure()</code> a unit you want to keep.
−
      let it pass (and then let the game produce the normal error
+
* Other bits are dropped: <code>wait(SFB_SAVE, ...)</code> never wakes. Use <code>interrupt()</code> for such events.
−
      message for unknown commands).
+
* The program also wakes for the events of its <code>interrupt()</code>s, which may jump elsewhere.
−
  */
+
* A condition that fails (a field of a null unit) counts as false. A text field or list entry tested on its own (<code>wait(SFB_TICK, self.title)</code>) counts the wrong way round, as true when the text is empty: compare with <code>""</code> instead.
 +
* A program that runs on without a <code>wait</code> or <code>pause</code> for about 52000 instructions is stopped ("had endless loop" in the zone log).
 +
 
 +
== Example ==
 +
<pre>
 +
dilbegin greeter();
 +
var
 +
  pc : unitptr;
 +
code
 +
{
 +
  heartbeat := PULSE_SEC * 3;
 +
  :start:
 +
  wait(SFB_CMD, command("say") and (activator.type == UNIT_ST_PC) and
 +
                ("hello" in argument));
 +
  pc := activator;
 +
  secure(pc, start);
 +
  pause;                    // let the player's words show first
 +
  exec("say Welcome, " + pc.name + "!", self);
 +
  unsecure(pc);
 +
  goto start;
 +
}
 +
dilend
 +
</pre>
 +
An NPC that welcomes a player who says hello.
 +
 
 +
== See also ==
 +
* [[Manual:DIL Manual/interrupt()|interrupt()]]
 +
* [[Manual:DIL Manual/secure()|secure()]]
 +
* [[Manual:DIL Manual/command()|command()]]
 +
* [[Manual:DIL Manual/heartbeat|heartbeat]]
 +
* [[Manual:DIL Manual/activator|activator]]
 +
* [[Manual:DIL Manual/argument|argument]]

Revision as of 23:22, 14 November 2026

wait()

Procedure. Stops the program until an event of the given kinds comes, for which a condition holds.

wait(events : integer, condition)

Every program spends most of its life here. wait() always stops the program; it goes on only with an event of one of the kinds in events (the SFB_ values in vme.h, joined with |) for which condition is true. At each such event the program wakes, the condition is worked out again, and if it is false the program goes back to waiting. The built-ins activator, medium, target, power, argument and command() describe the event, so the condition can test them.

Value Event
SFB_CMD A command typed by someone near the unit, before it runs (it can still be blocked)
SFB_DONE A command that has been carried out
SFB_PRE The step before some actions, e.g. a spell about to hit
SFB_TICK The unit's heartbeat
SFB_RANTIME With SFB_TICK: the tick comes at a random time around the heartbeat
SFB_MSG A message from another program (send, sendto, sendtoall, sendtoalldil)
SFB_COM A combat round
SFB_DEAD A death nearby
SFB_EDIT The end of an editor started with beginedit()
SFB_PROMPT The player's prompt being made

pause; is wait(SFB_TICK | SFB_RANTIME, TRUE), a macro in wmacros.h.

Parameters

Name Type Meaning
events integer The kinds of event to wake for.
condition any True to go on: a non-zero integer, a unit or string that isn't null, a list that isn't empty.

Notes

  • It waits even if the condition is true already.
  • Every event of the given kinds wakes the program, even one the condition then turns down. At every wake each unitptr and extraptr variable that isn't secured becomes null. Save what you need from activator, argument and the rest right after the wait, and secure() a unit you want to keep.
  • Other bits are dropped: wait(SFB_SAVE, ...) never wakes. Use interrupt() for such events.
  • The program also wakes for the events of its interrupt()s, which may jump elsewhere.
  • A condition that fails (a field of a null unit) counts as false. A text field or list entry tested on its own (wait(SFB_TICK, self.title)) counts the wrong way round, as true when the text is empty: compare with "" instead.
  • A program that runs on without a wait or pause for about 52000 instructions is stopped ("had endless loop" in the zone log).

Example

dilbegin greeter();
var
   pc : unitptr;
code
{
   heartbeat := PULSE_SEC * 3;
   :start:
   wait(SFB_CMD, command("say") and (activator.type == UNIT_ST_PC) and
                 ("hello" in argument));
   pc := activator;
   secure(pc, start);
   pause;                    // let the player's words show first
   exec("say Welcome, " + pc.name + "!", self);
   unsecure(pc);
   goto start;
}
dilend

An NPC that welcomes a player who says hello.

See also