This is from the help file you picked the best place to start digging most people don't even know this module is in swordfish.
Events, unlike subroutines or functions, cannot be called directly from a user program or module. Instead, you call an event via a variable which holds the address of the event handler routine. For example,
Code:
// event handler type...
type TEvent = event()
// the event handler to call...
event EventHandler()
high(PORTD.0)
end event
// declare event variable...
dim OnEvent as TEvent
OnEvent = EventHandler // assign handler
OnEvent() // call handler
Events are also different from subroutines and functions with respect to their frame allocation, which isn't recycled. This is because event pointers cannot be tracked at compile time, preventing the frame usage for an event from being calculated. Events are therefore allocated their own, unique frame space.
Whilst the non-recycle nature of event frame allocation may appear to be a disadvantage, it's actually extremely useful when used with interrupts. An interrupt cannot risk calling a subroutine or function without proper context saving, because it may damage the frame stack. Events on the other hand have a unique frame space, which makes it safe to execute an event from within a subroutine. There are some caveats though. These are:
A high and low priority interrupt should never call the same event handler.
Although an event frame space is protected, making calls to other subroutines or functions could cause the program to become unstable, in much the same way as an interrupt would.
In short, events allow you to 'plug in' code into an ISR, without having to alter the interrupt logic. However, it should be noted that you should treat an interrupt triggered event handler with the same respect in terms of context saving and usage as you would the main interrupt routine itself.
The following is an example of an interrupt driven module, which fires an event handler when the hardware USART received some data: