The Update handler is a special-case handler and extremely important for plugins. Rather than handle an event (eg: how Render handles a redraw event, or how Init handles initialization), the Update handler is provided as a safe and "special" place to execute code.

Many plugins will need to constantly check a condition, then act on it. The check may occur once every second, every minute, every hour or even as many times per second as is possible. A traditional way to achieve this is to create an infinite loop, however creating infinite loops in Windows applications causes random lockups and application failures.

To solve this problem the Update handler is provided. The Update handler is called repeatedly, as quickly as possible, by the Brass plugin framework. On a "standard" system that isn't under heavy CPU load this can potentially be 10 or 20 times per second. Therefore if you need to check a condition, for example: has a file been created, does a registry key exist, you may add the code to this handler and reasonably expect it to be executed faster than if you wrote an infinite loop.

The Update handler does not begin executing until the Init handler has returned. Therefore you can safely perform actions in Init and repeat them in Update (for an ongoing action), and not create a conflict.

From the system point of view the Update handler is multithreaded. This means you can safely stall the handler (prevent it from returning for a period of time) without affecting your plugin, Brass or Windows itself. A good example of this is network access. If you attempt to access a website using the Shiny language statement wopen and there are bad network conditions, a connection could take up to 60 seconds to timeout. Attempt to do this in the Render or Init handlers and your plugin will stall, causing Brass to terminate it. Doing it in the Update handler will ensure any stall doesn't affect the rest of your plugin. Even if the Update handler stalls, the Render handler will continue to be called and your plugin will receive all the normal handler notifications. (Note: if network conditions are favourable it is acceptable to use wopen in other handlers, this was just provided as an example).

Whilst it is possible to create an infinite loop in the Update handler this is not advisable. An infinite loop may look like this:

function Update()
{
    while(true)
    {
        // Infinite loop, bad practice
    }
}

Although this will technically work it is inadvisable. One immediate side effect is that your CPU load will rise to 100%. The Update handler is managed by Brass to specifically provide the fastest continuous calls to Update with no side effects. Because the Update handler itself is an infinite loop, the following code produces an identical result at plugin level:

function Update()
{
    // Still an infinite loop but best practice. Add code here
}

Besides being good practice there are a number of advantages to using the handler itself as an infinite loop. Firstly by allowing the handler to exit and then be called again by Brass you are allowing Brass to clean up after it correctly, rather than forcefully terminating it when the plugin unloads. Second a number of enhancements to the Virtual Machine are in progress, one of which will create a lock-resistant VM. This means that the VM will detect infinite loops and gracefully exit them, preventing your plugin from stalling or crashing. If you specifically code an infinite loop in the Update handler you are removing the benefit of this and similar features.

There are many uses for the Update handler. Please post a technical support request if you require advice on correct usage.

Parameters

None