Event processing functions

execDeleteEvent()

Function prototype:

boolean execDeleteEvent(word or byte Event);

Parameters: Event posted event to be cancelled

Returns: true if an event of that number was found and cancelled or false if not.

This function searches all the queues from the highest priority (event at the front of the queue) to the lowest and substitutes an event number of zero in every occurrence it finds.

It is recommended only to use this function if no other means of achieving this result can be done (i.e. it is best not to post the event in the first place if it is possible that it may need to be deleted). This is because it comparatively time-consuming, although its efficiency is optimised by the fact that the event queues are contiguous, and therefore it just searches the entire array of all the queues from start to finish.

Typically, this operation is performed when the source of an event is disabled (e.g. an interrupt routine or timer) and it is required to ensure that there are no events outstanding from that source.

execIsQueueFull()

Function prototype:

boolean execIsQueueFull(byte Priority);

Parameters: Priority indicates which queue

Returns: true if the queue is full (cannot be posted to) or false if it is not. The same criteria are applied as per execPostPriorityEvent.

execPostEvent()

Function prototype:

boolean execPostEvent(word or byte Event);

Parameters: Event event number to post

Returns: true if it succeeded or false if it failed. It will fail if the queue is already full or if the event is not valid.

Events are processed in order of the priority of the queue on which it is placed.

If the event queue system only supports byte events, then the high order byte of the event is ignored.

execPostInputEvents()

Function prototype:

boolean execPostInputEvents(word NewInputs, 
    word *OldInputs,
    word *ValidatedInputs,
    struct execInputEvents *EventDefinitions);

Parameters: NewInputs inputs at current poll (16 bits)
OldInputs pointer to inputs at last poll ValidatedInputs pointer to filtered (validated) input states
EventDefinitions pointer to input event definition table

Returns: true if it succeeded or false if it failed. It will fail if any of the events in the event definition table are invalid (all valid events will be posted, however), or if any event could not be posted because its queue was full.

This function is used to post events based on 16 bit inputs contained in a word.

Only those bits indicated by 1’s in the bit mask in the input event definition table are affected. This is so that bits within a particular input word can be processed at different scan rates and priorities.

For each bit, the appropriate high or low event is generated if that bit in the new inputs is the same as in the old inputs but different from the validated inputs. This therefore implements single stage software debounce.

If software debounce is not required, let OldInputs point to NewInputs as well, hence any change in state will appear to have occurred on successive iterations and will hence cause ValidatedInputs to change immediately on a change in state.

When the events have been posted, NewInputs is copied to OldInputs.

If a queue cannot be posted to, then the old inputs for the affected bits are not updated to the new values. That is, it will give further opportunities for the event to be posted when this function is next called with a new set of inputs (provided the relevant input does not change).

execPostPriorityEvent()

Function prototype:

boolean execPostPriorityEvent(word or byte Event, byte Priority);

Parameters: Event event number to post
Priority queue priority to post to

Returns: true if it succeeded or false if it failed. The same criteria are applied as per execPostEvent. Additionally, it will fail if an invalid queue priority is passed.

The functionality is identical to execPostEvent, except that the event priority (and hence event queue) is overridden.