REBOL 3 Functions: do-commands

Description

High speed command! block evaluation for extensions.

Originally created to evaluate graphics rendering commands, it can be used for any external sequence of commands that require maximum speed (e.g. high speed math processing such as FFTs, image processing, audio processing.)

Special Evaluation Method

The greater speed of command blocks is obtained through the use of a special evaluation method:

• Evaluation is strictly linear. Sub-expressions, control branching, and recursion are not allowed so no stack management is required.
• Arguments are already reduced to their final values (or variables that hold those values.)
• Special variations of function arguments are not allowed. Only word and 'word forms are allowed.
• Arguments must appear in the correct order and no optional arguments are allowed.
• Arguments are placed directly within the command argument frame, not on the primary evaluator stack.

Why is it Useful?

In subsystems like the R3 GUI, graphical elements are rendered by generating semi-static draw blocks either during style definition (definition of a button), face instantiation (creating an instance of a button), or face state modification (eg. hovering over a button).

The advantage of the static form of such draw blocks is that they require no further evaluation, hence take no additional memory or CPU time. In fact, the state of the GUI at any specific time is simply a sequence of draw block renderings. Therefore, a fast method of calling draw functions can greatly speed-up the rendering time of the GUI.

For special draw dialects (like the one used in the GUI) where optional or datatype-ordered arguments are allowed, a conversion from the dialect block to the command block is required. However, this conversion was already being performed in order to reduce the run-time overhead of the dialects (to avoid the NxM argument reordering penalty), so no additional overhead is incurred.

General Form

The general form is:

do-commands [
    command1 arg11 arg12
    command2 arg21 arg22 arg23
    result: command3 arg31
    ...
]

Notice that set-words for results are allowed. In addition, the result of the final command will be returned from the do-commands function.

Argument Requirements

Command blocks are written in a reduced minimal form. They consist of one or more commands followed by their arguments. The arguments must be actual values or variables; sub-expressions and operators are not allowed. If necessary, use reduce with /only or compose to preprocess command blocks.

For example, you can write:

line 0x0 100x100
line 100x100 200x200

and the command can also be variables:

line start1 end1
line start2 end2

Sub expressions are not allowed:

line 0x0 base + 10   ; error
line 0x0 add base 10 ; error

However, if necessary you can escape to parens for sub-expressions, but it reduces run-time performance:

line 0x0 (base + 10) ; ok, but slow

Errors

An error will occur if any value other than a command is found:

multiply 10 20
** Script error: expected command! not multiply

An error will also occur if an argument is not of the correct datatype, or if the block ends before all of its actual arguments are provided.