Events

Programmer's Reference Manuals

» 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.

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 disable event and 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 pages).

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

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.

Error handling

Routines that handle events must only call the error-returning SWI calls (that is, SWI calls that have their X-bit 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.

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