install_int_ex(3alleg4) 					  Allegro manual					   install_int_ex(3alleg4)

NAME

       install_int_ex - Adds or modifies a timer. Allegro game programming library.

SYNOPSIS

       #include <allegro.h>

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

DESCRIPTION

       Adds a function to the list of user timer handlers or, if it is already installed, retroactively adjusts its speed (i.e makes as though the
       speed change occurred precisely at the last tick). The speed is given in hardware clock ticks, of which there are 1193181 a second. You can
       convert from other time formats to hardware clock ticks with the macros:

	  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

       There  can  only  be  sixteen  timers  in use at a time, and some other parts of Allegro (the GUI code, the mouse pointer display routines,
       rest(), the FLI player, and the MIDI player) need to install handlers of their own, so you should avoid using too many at the same time. If
       you call this routine without having first installed the timer module, install_timer() will be called automatically.

       Your  function will be called by the Allegro interrupt handler and not directly by the processor, so it can be a normal C function and does
       not need a special wrapper. You should be aware, however, that it will be called in an interrupt context, which imposes a lot  of  restric-
       tions on what you can do in it. It should not use large amounts of stack, it must not make any calls to the operating system, use C library
       functions, or contain any floating point code, and it must execute very quickly. Don't try to do lots of complicated code in a  timer  han-
       dler: as a general rule you should just set some flags and respond to these later in your main control loop.

       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, 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 han-
       dler  functions.  The  macros  LOCK_VARIABLE  (variable),  END_OF_FUNCTION  (function_name),  END_OF_STATIC_FUNCTION  (function_name),  and
       LOCK_FUNCTION  (function_name)  can  be used to simplify this task. 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.

RETURN VALUE

       Returns zero on success, or a negative number if there is no room to add a new user timer.

SEE ALSO

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

Allegro 							   version 4.4.2					   install_int_ex(3alleg4)