Suspends the current task, and resumes it after at least <seconds> seconds. (If <seconds> is not provided, the task is suspended indefinitely; such a task can only be resumed by use of the `resume()' function.) When the task is resumed, it will have a full quota of ticks and seconds. This function is useful for programs that run for a long time or require a lot of ticks. If <seconds> is negative, then E_INVARG is raised. `Suspend()' returns zero unless it was resumed via `resume()' in which case it returns the second argument given to that function.
In some sense, this function forks the `rest' of the executing task. However, there is a major difference between the use of `suspend(<seconds>)' and the use of the `fork (<seconds>)'. The `fork' statement creates a new task (a "forked task") while the currently-running task still goes on to completion, but a `suspend()' suspends the currently-running task (thus making it into a "suspended task"). This difference may be best explained by the following examples, in which one verb calls another:
Consider `#0:caller_A', which calls `#0:callee_A'. Such a task would assign 1 to `#0.prop', call `#0:callee_A', fork a new task, return to `#0:caller_A', and assign 2 to `#0.prop', ending this task. Five seconds later, if the forked task had not been killed, then it would begin to run; it would assign 3 to `#0.prop' and then stop. So, the final value of `#0.prop' (i.e., the value after more than 5 seconds) would be 3.
Now consider `#0:caller_B', which calls `#0:callee_B' instead of `#0:callee_A'. This task would assign 1 to `#0.prop', call `#0:callee_B', and suspend. Five seconds later, if the suspended task had not been killed, then it would resume; it would assign 3 to `#0.prop', return to `#0:caller', and assign 2 to `#0.prop', ending the task. So, the final value of `#0.prop' (i.e., the value after more than 5 seconds) would be 2.
A suspended task, like a forked task, can be described by the `queued_tasks()' function and killed by the `kill_task()' function. Suspending a task does not change its task id. A task can be suspended again and again by successive calls to `suspend()'.
Once `suspend()' has been used in a particular task, then the `read()' function will always raise E_PERM in that task. For more details, see the description of `read()'.
By default, there is no limit to the number of tasks any player may suspend, but such a limit can be imposed from within the database. See the chapter in the LambdaMOO Programmers Manual on server assumptions about the database for details.