# Event (signal) functions
[Pre-emptive, soft real-time scheduler]

Events, or signals, are the simplest (and fastest) interprocess communication mechanism. More...

## Defines
#define | BX_EVENT_ALWAYS 0x80000000
| The event that is always set.
## Functions
int | BX_EventPost (BX_PROC *proc, int sigs)
| Sends one or more event signals to a process.
int | BX_EventWait (int wait)
| Wait for one or more events (signals).

## Detailed Description

Events, or signals, are the simplest (and fastest) interprocess communication mechanism.

Each process has 31 1-bit signals. Posting an event to a process means setting one of those bits to 1. Waiting for events suspends the process until at least one bit from a subset of that 31 bits (the subset selected by the process) becomes 1. When the waiting process wakes up, all bits that are set in its selected subset are returned to it (so it knows why it woke up) and then they are reset to 0, ready to accept new signals.
The advantages of this mechanism are that it is very simple and fast, and that it allows you to wait for multiple events at the same time. The disadvantage is that events can be lost. If you post an event (i.e. set a bit to 1) and then post the same event again before the process had a chance to evaluate its signal status, you effectively set a bit to 1 that was already 1, that is, you did nothing. The receiving process will get only one notification even though you posted the event twice.

## Function Documentation

int BX_EventPost | ( | BX_PROC * | proc,
|  | int | sigs |
| ) |  |  |

Sends one or more event signals to a process.

Parameters:

  | proc | Pointer to the process' descriptor
  | sigs | The event set to send

Return values:

  | >0 | Success
  | BX_ERR_OBJECT | The proc argument is not a valid process descriptor

Attention:
  This function can be called from user, ISR or delayed ISR context. This function does not suspend the caller but can cause a context switch if a higher priority process is woken up by the call.

int BX_EventWait | ( | int | wait | ) |

Wait for one or more events (signals).

The function suspends the caller until at least one signal in the argument signal set gets set. If the signal set can not be empty. The function returns all signals that are or became set in the requested set. These signals are also deleted from the pending set. Signals in the pending set that are not in the waiting set are not affected. If the waiting set contains the BX_SIGNAL_ALWAYS signal, then the function will return without suspending the caller even if no signail in the waiting set is present in the pending set.

Parameters:

  | wait | The set of event to wait for. Can't be 0.

Return values:

  | >0 | All events in the wait set that were pending or became active while the process was suspended.
  | =0 | The wait set contained the BX_EVENT_ALWAYS event but no event in the waiting set was in the pending set.
  | BX_ERR_PARAM | Empty wait set was passed to the function.
  | BX_ERR_CONTEXT | The function was called from an ISR context.
  | BX_ERR_SUSPEND | The caller should be suspended but its current protection level is above BX_PROT_COOP.

Attention:
  This function should not be called from an ISR or delayed ISR. This function can suspend the caller.