Events #

Introduction #

Events let you start a function asynchronously. When an event is broadcast, the event’s callback function is started in its own task (thread), so your main code can continue running at the same time.

Important: An event object stores one callback. If you register another function with the same event object, it replaces the previous callback.

If you want multiple things to happen from one trigger, either:

Call multiple helper functions from a single callback, or
Use multiple event objects and broadcast each one.
Use separate threads to run tasks independently.

In order to create and then use an Event, follow these steps in order:

Create the event with event.
Set the event’s callback using the event name (ex: myEvent(myCallback);).
Broadcast an event:
- broadcast — Triggers all registered functions in an event object to run in parallel.
- broadcastAndWait — Triggers all registered functions in an event object and waits for them to finish before continuing.

Class Constructors #

1 — Creates an event object without a callback function.
event();

2 — Creates an event object with a callback function.
event( void (* callback)(void) );

3 — Creates an event object from another event with a callback function.
event( 
  event v, 
  void (* callback)(void) );

4 — Creates an event object with a callback function that accepts an argument.
event( void (* callback)(void *), void *arg );

5 — Creates an event object from another event with a callback function that accepts an argument.
event( event v, void (* callback)(void *), void *arg );

Class Destructor #

Destroys the event object and releases associated resources.

~event();

Parameters #

Parameter	Type	Description
`callback`	`void (*)(void)`	A function that is previously defined to execute when the event is broadcasted.
`v`	`event`	An existing event object to copy from.
`callback`	`void ()(void )`	A function that accepts a void pointer argument and executes when the event is broadcasted.
`arg`	`void *`	A pointer to data that will be passed to the callback function.

Notes #

An event object stores one callback. If you register another function with the same event object, it replaces the previous callback.
If you want multiple things to happen from one trigger, either:
- Call multiple helper functions from a single callback, or
- Use multiple event objects and broadcast each one.
- Use separate threads to run tasks independently.

Example #

Define the callback function (outside of int main())

// Create a callback function
void onMyEvent() {
  Brain.Screen.print("Callback function executed!");
}

int main() {
  /* vexcodeInit() is only required when using VEXcode.
  Remove vexcodeInit() if compiling in VS Code. */
  vexcodeInit();

  // Create an event called myEvent
  // Set onMyEvent as the callback function
  event myEvent(onMyEvent);
}

Member Functions #

The event class includes the following member functions:

operator — Sets a callback function for the event.
broadcast — Triggers the event’s callback function to run in parallel.
broadcastAndWait — Triggers the event’s callback function and waits for completion.

Before calling any event member functions, an event instance must be created, as shown below:

/* This constructor is required when using VS Code.
Event configuration can be created with or without
a callback function as shown in the examples above. */

// Create an event without a callback
event myEvent;

// Or create an event with a callback
event myEvent(onMyEvent);

operator #

Sets a callback function for the event using the function call operator.

Available Functions

void operator()( void (* callback)() );

Parameters

Parameter	Type	Description
`callback`	`void (*)(void)`	A previously defined callback function that is called automatically when the event is broadcast. The function must match the required callback signature. See Callback Functions for more information.

Return Values

This function does not return a value.

Notes

Setting a callback again replaces the previous callback.
The callback function must have no parameters and return void.

Examples

Define the callback functions (outside of int main())

// Create a callback function
void drawSquare() {
  Brain.Screen.clearScreen();
  Brain.Screen.drawRectangle(40, 40, 120, 120);
}

void drawCircle() {
  Brain.Screen.clearScreen();
  Brain.Screen.drawCircle(100, 100, 60);
}

int main() {
  /* vexcodeInit() is only required when using VEXcode.
  Remove vexcodeInit() if compiling in VS Code. */
  vexcodeInit();

  // Create the event drawEvent
  event drawEvent;

  Brain.Screen.print("Drawing a square...");

  // Set the event to drawSquare
  drawEvent(drawSquare);

  wait(1, seconds);

  // Trigger the event
  drawEvent.broadcast();

  wait(1, seconds);

  Brain.Screen.clearScreen();
  Brain.Screen.setCursor(1, 1);
  Brain.Screen.print("Drawing a circle...");

  // Replace drawSquare with drawCircle
  drawEvent(drawCircle);

  wait(1, seconds);

  // Trigger the event a second time
  drawEvent.broadcast();
}

broadcast #

broadcast starts the event’s callback and continues immediately.

Member Functions

void broadcast();

Parameters

This function does not take any parameters.

Return Values

This function does not return a value.

Examples

Define the callback function (outside of int main())

// Create a callback function
void onMyEvent() {
  Brain.Screen.clearScreen();
  Brain.Screen.setCursor(1, 1);
  Brain.Screen.print("Event fired!");
}

int main() {
  /* vexcodeInit() is only required when using VEXcode.
  Remove vexcodeInit() if compiling in VS Code. */
  vexcodeInit();

  Brain.Screen.print("Broadcasting in 2 seconds...");

  // Create an event called myEvent
  // Set onMyEvent as the callback function
  event myEvent(onMyEvent);

  wait(2, seconds);

  // Trigger the event
  myEvent.broadcast();
}

broadcastAndWait #

Starts the callback and waits until it finishes (or times out).

Available Functions

void broadcastAndWait( int32_t timeout = 60000 );

Parameters

Parameter	Type	Description
`timeout`	`int32_t`	The amount of milliseconds to wait before the code starts executing again (defaults to 60000).

Return Values

This function does not return a value.

Notes

Use this only with callbacks that end (no infinite loops).
This is a waiting function that blocks execution until the callback completes or times out.

Examples

Define the callback function (outside of int main())

// Create a callback function
void startDriving() {
  Drivetrain.drive(forward);
  wait(2, seconds);
}

int main() {
  /* vexcodeInit() is only required when using VEXcode.
  Remove vexcodeInit() if compiling in VS Code. */
  vexcodeInit();

  Brain.Screen.print("Starting drive...");

  event driveEvent(startDriving);
  // Give the event time to be set
  wait(0.25, seconds);

  // Run the event and wait until it finishes
  driveEvent.broadcastAndWait();

  // Stop driving after 2 seconds
  Drivetrain.stop();
  Brain.Screen.clearScreen();
  Brain.Screen.print("Drive complete!");
}