Geas Home | Play the Game

2.3.4 Alarms: Asynchronous function execution

Sometimes it's desirable to postpone execution of code a while and sometimes you want things to happen regularly. The gamedriver counts something called evaluation cost, or eval cost. It's simply a way of measuring the amount of CPU cost an object uses. Any given object is only allowed a certain amount of eval cost per execution chain. When that amount is used up, the object aborts. How the eval cost is computed isn't very important, it's set so that the game shouldn't be held up too long. However, the existence of eval cost makes a bit of special programming necessary. When you have very heavy computations you need to do, they simply won't fit within the maximum allowed eval cost, so you need to cut the job up in chunks and do it bit by bit.

All of this adds up to a need for a function that allows you to do things regularly, or with delays. The alarm functionality will do this for you. The efun set_alarm() will allow you to create a delayed alarm, possibly repeating, that will call a given function as you decide.

int set_alarm(float delay, float repeat, function alarm_func) remove_alarm(int alarm_id) mixed get_alarm(int alarm_id) mixed get_all_alarms()

The function returns a unique alarm number for that alarm and that object that you can use later to manipulate the specific alarm. You can retrieve info for the alarm with the efun get_alarm(), remove it with remove_alarm() or even get info about all alarms in an object with the efun get_all_alarms(). The latter function is mostly used when you either haven't bothered to save the alarm ids, or when you want to display info about the object. The efun set_alarm() allows you both to define a delay until the function is called the first time, and a delay between repetitive calls. Every alarm call will start with an eval cost at 0.

NB! A word of caution here... Since the function gets called asynchronously in respect to a user of the object, both this_player() and this_interactive() might return undefined values. Sometimes 0, sometimes the object you expect, sometimes another value. So, don't rely on what they return, instead stick the object you want to use in a variable before starting the sequence and use that. Remember this since some efuns rely on a defined this_player() value. A lot of tricky bugs has been traced back to this particular problem in the past, so beware!

IMPORTANT! READ THIS CAREFULLY!

It's very easy to fall to the temptation to split a heavy job into several alarm calls with fast repetition rates. However, this is NOT the intended use for this efun. A deadly sin is to have an alarm function that generates repeating alarms within a repeating alarm. The amount of alarms will then grow exponentially and the ENTIRE GAME will stop almost immediately. This is so incredibly stupid as to be a demoting offense, so make sure you do things RIGHT the first time. In general, delays between repeating alarms should be greater than one second, preferably two, as well as delays to single alarms.

The alarm functions will be demonstrated more extensively in chapter three.