Introduction

Events Usage

In Vortex, data is passed via connections from one content extension to the other.

Communication between modules across a distributed simulation cannot be accomplished with connections, but by using events.

Events are packets of data tagged with a unique id, that is sent from a sender to all of its listeners, across the simulator's nodes.

Events could be used, for example, to launch actions to be executed on a remote node, e.g. save a file locally.

Events Properties

• Events should be punctual, they are not meant to be sent every frames.
• Events are asynchronous; there is no way to accurately predict how much frames will pass between sending the events and receiving the data.
• Events are not synchronized to be sent at the same frame on each node of the simulator
• Event data is sent across the network, avoid sending too much data.

Using Events in your Vortex C++ Application

Creating an EventId

In order to setup events, you need to create an EventId for your event.

Each EventId can only be created once via static function EventManager::createdEventId()

They should be kept in a static variable available to both the sender and the listener.

EventIds are generated from their given names, which must be unique, Duplicated names will result in failure.

Packaging the event's data

Event's data are package using a small helper container called EventData.

The class stores it's data in a vector of bytes.

The user can use the provided insertion and extraction operators to put data into it.

These operators supports basics numerical values (signed/unsigned integers on 8, 12, 32 and 64 bits, float and double), boolean and strings.

Alternatively, the user can provide the bytes as a vector.

Using the Event Manager

The EventManager is an object created by the application and available via the ApplicationContext. 

The manager is used to create listener and send events.

Creating a listener

The receiver of the data needs to setup a listener.

A listener is a callback function registered to the EventManager.  

To create a listener, the user uses function registerListener() on the EventManager by passing the EventId and the callback, the EventManager will return an EventListener.

The EventListener is a reference counted object; as long as the EventListener is referenced, the callback will be called when the EventId is sent.

The listener will be called during the simulation thread with an object EventData.

To stop receiving the event's data, either call unregister() on the EventListener or delete it.

Sending an Event

To send an event, the user first package its data into an EventData.

Thereafter, the user calls sendEvent() on the EventManager, with the EventId and EventData.

The event will be send to all of its listeners, across the simulator's nodes.

static const VxSim::EventId kMyEventId = VxSim::EventManager::createEventId("My Event");
 
...
class MyObjectUsingAListener
{
	EventListener myListener;
	...
	void eventCallback(const VxSim::EventData& data)
	{
		int valueA = 0;
		std::string valueS;
		data >> valueA >> valueS;
		
		processData(valueA, valueS);
	}
	...
	
	void setupListener()
	{
		 myListener = mApp->getContext()->getEventManager()->registerListener(kMyEventId , [this](const VxSim::EventData& data) { this->eventCallback(data); });	
	}
}
...
class MyObjectSendingData
{
	int A;
	std::string S;
	...
	void notify()
	{
		EventData data;
		data << A << S;
 
		 mApp->getContext()->getEventManager()->sendEvent(kMyEventId , data);
	}
}
 

Debugging Events

In the Network Data Page of Vortex Studio Player, monitoring and advanced monitoring of the event can be enabled.

The user can track its own events. User defined events name are seen as "User Event:<event name>".