install_int_ex(3alleg4)

💖 install_int_ex — the timer bestie 💖

okay so real talk, we're in the Allegro game programming library manual, and this page is about install_int_ex, which is genuinely one of the most iconic little functions in here. it's giving "set it and forget it" but for timers. let's get into it 🕰️✨

---

✨ SYNOPSIS ✨

#include <allegro.h>

int install_int_ex(void (*proc)(), int speed);

---

🌸 DESCRIPTION 🌸

so what does it actually do? it adds a function to the list of user timer handlers. and if that function is already installed, it doesn't double up — instead it retroactively adjusts its speed, like it makes it as though the speed change happened precisely at the last tick. time travel but make it legal 💅

the speed is given in hardware clock ticks, and there are 1193181 of those bad boys per second. yes, that exact number, no cap.

you do not have to do that math yourself though, bestie, because there are macros that convert from other time formats into hardware clock ticks:

SECS_TO_TIMER(secs)  - give the number of seconds between
                       each tick
MSEC_TO_TIMER(msec)  - give the number of milliseconds
                       between ticks
BPS_TO_TIMER(bps)    - give the number of ticks each second
BPM_TO_TIMER(bpm)    - give the number of ticks per minute

periodt. use those, save your brain cells 🧠✨

---

🚨 the timer limit is real. there can only be sixteen timers in use at a time. and some other parts of Allegro need to install handlers of their own — specifically the GUI code, the mouse pointer display routines, rest(), the FLI player, and the MIDI player. so like… don't be greedy, avoid using too many at the same time 🫶

also super chill of it: if you call this routine without having first installed the timer module, install_timer() gets called automatically. it's got your back fr fr.

---

🦋 about your handler function 🦋

your function gets called by the Allegro interrupt handler, not directly by the processor. so it can just be a normal C function — no special wrapper needed, we love that for us.

but (and this is the important part, bestie, do not skip this) it's called in an interrupt context, which imposes a LOT of restrictions on what you can do in it. your handler:

• should not use large amounts of stack
• must not make any calls to the operating system
• must not use C library functions
• must not contain any floating point code
• must execute very quickly

don't try to do lots of complicated code in a timer handler. as a general rule you should just set some flags and respond to those later in your main control loop. that's the vibe. keep it tiny, keep it fast 🔥

---

💀 the DOS protected mode situation 💀

okay this part is scary but it's real and you need to know it.

in a DOS protected mode environment like DJGPP, memory is virtualised and can be swapped to disk. due to the non-reentrancy of DOS, if a disk swap occurs inside an interrupt handler, the system will die a painful death 😭 not me being dramatic, that's literally what the manual says.

so you need to make sure you lock all the memory (both code and data) that is touched inside timer routines. Allegro will lock everything it uses, but you are responsible for locking your handler functions.

these macros can be used to simplify this task:

• LOCK_VARIABLE(variable)
• END_OF_FUNCTION(function_name)
• END_OF_STATIC_FUNCTION(function_name)
• LOCK_FUNCTION(function_name)

for example, if you want an interrupt handler that increments a counter variable, you should write:

volatile int counter;

void my_timer_handler()
{
   counter++;
}

END_OF_FUNCTION(my_timer_handler)

and in your initialisation code you should lock the memory:

LOCK_VARIABLE(counter);
LOCK_FUNCTION(my_timer_handler);

obviously this can get awkward if you use complicated data structures and call other functions from within your handler, so you should try to keep your interrupt routines as simple as possible. simple = slay, complicated = chaos 🌈

---

👑 RETURN VALUE 👑

• returns zero on success 🎀
• returns a negative number if there is no room to add a new user timer 😭

---

🌟 SEE ALSO 🌟

go read these next, they're all connected, iykyk:

• install_timer(3alleg4)
• remove_int(3alleg4)
• install_int(3alleg4)
• install_param_int_ex(3alleg4)
• excamera(3alleg4)
• exsprite(3alleg4)
• extimer(3alleg4)
• exunicod(3alleg4)
• exupdate(3alleg4)

---

and that's the whole page bestie!! this one's from the Allegro manual, version 4.4.3, dated back in the day when install_int_ex(3alleg4) was the headline. stay locked, stay fast, and lock your memory before your system dies a painful death 💖✨🎀🦋💅