yannickmontes / com.yannickmontes.yube.relays

Fast, powerful, GC-friendly C# signals/events for Unity.

Relay

Fast, light, GC-friendly C# signals/events for Unity.

---

C# event multicasting is a nice language-level feature, but in Unity's version of Mono, events allocate a lot on addition/removal and aren't always easy to manipulate. Relay aims to address these issues.

• Additional functionality
  • AddOnce() automatically removes a listener after dispatch
  • Guard against duplicate listeners for safety, or disable checking for increased performance
  • Contains() tells you whether a delegate is already subscribed
  • Debug mode helps diagnose "dangling" or "lapsed" listeners - a common cause of GC issues in event-driven architectures
• Minimal allocation using arrays of delegates
  • C# event re-allocates the entire multicast object each time += or -= called
  • Relay uses a dynamic array of singlecast delegates
• Performant addition, removal and dispatch
  • Geometric array resize (like List<>.Add()) amortizes addition costs
  • Dispatch virtually as fast as native multicast
• Battle-tested
  • Heavily used in core code of our game Sublevel Zero on PC, VR, PS4 and Xbox One
  • ~100% unit test coverage (unit tests included)

Read the wiki for detailed instructions.

Relay is inspired by the Signals implementation in StrangeIoC (but drastically improves performance and allocation).

Performance (Tested in Unity 5.6)

Profiled performance comparison of event, Relay and a List of delegates. Each operation is performed 100000 times with 10 listeners. Add Unique means disallowing duplicate listeners.

Time (ms)

Method	Add	Add Unique	Remove	Clear	Dispatch
event	1465	N/A	1155	3.688	67.28
Relay	150.5	318.2	270.0	10.27	79.92
List	183.5	466.0	368.0	9.436	79.00

GC Alloc (MB)

Method	Add	Remove
event	630	530
Relay	38.1	0
List	32.8	0

All other operations are allocation-free. Note that this is worst-case GC performance for Relay (and List) as each loop creates a completely new Relay. Populating and clearing the same Relay 100000 times just allocates 400B initially, while event still allocates 630MB.

Note: Under .NET 4.6 event addition and removal is 2-7x faster than under Unity.

Perf tests and unit tests are included in Relay/Editor.