h6. [[Programmer's Reference Manuals]] h6(. » Events RISC OS uses events to inform tasks that something specific has occurred. Each event is assigned an _event number_. These are typically generated by [[OS_GenerateEvent]] when RISC OS services an interrupt. h3. Enabling events Events are disabled by default, because of the significant processor overhead involved. Events can be enabled or disabled individually if required. For each event number, a counter keeps track of how many requests have been made to enable it. As long as the counter remains above zero, RISC OS will always generate the event when appropriate. An event will only be disabled after equal numbers of [[OS_Byte 13|disable event]] and [[OS_Byte 14|enable event]] calls have been made. This ensures that the system always generates the event if at least one task requires it. On a reset, the event counters are set to zero (although some modules may still need an event and hence increment the appropriate event counter). In addition to the Operating System generating event numbers, it is also possible for developers to generate their own (code 9), or if required, request their own event code (see "Allocate":http://www.riscosopen.org/content/allocate pages). h3. Using events To use an event, the following steps must taken: * The event vector must first be claimed by calling [[OS_Claim]] * [[OS_Byte 14]] is called to enable the event The purpose of claiming the vector is to assign a new routine that must be called when the event occurs. Because multiple tasks may claim the same event, the routine is added to the list of routines that must be called. If you wish to add multiple 'identical' routines, use [[OS_AddToVector]]. [[Software Vectors]] provides more information on the use of vectors. When an event is no longer required, the follow steps must be taken: * Disable the appropriate event(s) by calling [[OS_Byte 13]] * Release the event vector by calling [[OS_Release]] h3. Handling routines Any routine dealing with events must do so very quickly, so the OS can continue with the previous task as quickly as possible. Ideally events are handled so quickly that users never realise their task has been temporarily halted. If a routine cannot deal with an event quickly, it should re-enable interrupts (as they are always disabled when entering a routine). They must then be disabled before passing on or intercepting the call. The routine should also ensure that the processing of one event is completed before it starts processing another. The routine is always entered in a non-user processor mode. h3. Error handling Routines that handle events must _only_ call the error-returning SWI calls (that is, SWI calls that have their "X-bit":link1 set). If an error is returned to the routine, appropriate action must be taken within the routine. It may be useful to store an error indicator, so that the next call to an appropriate SWI (one in the module that provides the routine) will generate an error. h4. See also * [[Event Numbers]] * [[OS_AddToVector]] * [[OS_Byte 13]] * [[OS_Byte 14]] * [[OS_Claim]] * [[OS_GenerateEvent]] * [[OS_Release]] * [[Software Vectors]] * "SWI 24-bit Address Field":link1 [link1]Introduction%20To%20SWIs#address