Latest updates and changes

[thewoodfish]

Breaking Changes in the Latest Version

In the latest version of our library, we have introduced two major updates that bring significant improvements but also include breaking changes:

1. Better Handling Interface for Network Events:

   • Old Method: Previously, users had to implement a network events trait to define event handler functions.
   • New Method: Now, events are simply pushed into an internal buffer that can be polled and consumed to get events.
   • Advantages: This approach prevents potential deadlocks and makes it easier to delay the firing of handlers. It also allows different handlers to manage the same events at the point of consumption.
   • Downside: Events can be lost if the queue becomes full and overflows.

2. Separation of Application Data from the Network Layer:

   • Old Method: The application layer used to pass state to the network, which would keep and expose it back.
   • New Method: The network layer is now pure and independent of any application data and state. It strictly handles network operations without storing or managing any data state.
   • Advantages: This separation ensures a clean and independent network layer that is focused solely on handling network events.

These updates are significant and introduce breaking changes. Please refer to the updated documentation for guidance on how to migrate to the new version.

[sacha-l]

Really awesome changes, adding more elegance and robustness to the foundations. Decoupling the AppState from Core makes things a lot more breathable.

Here's a first pass of revision. Everything in this review is really just documentation cosmetics. I made a commit to update some of the docs on the variants (was easier than to do in the Github UI). Before merging this PR and because it contains major breaking changes, I will do another pass on this for:

1. Testing all core library code again
2. Running the examples

Wanted to get this first review in quick. Cheers!

[sacha-l]

@thewoodfish : can you go ahead an commit my suggestions or comment on anything I may've missed please? 🙏🏻

Then I'll be able to pull locally and make some additional amendments in a separate commit as part of my second review.

[sacha-l]

For code review and test coverage [WIP]. Tests to write around events are pushed into an internal buffer that gets polled.

    1. Test for Polling works
    2. Test for limits of internal buffer 
    3. Test consuming different events and using them works as expected
    4. Test for deadlock situation handled with elegance works 
    5. Test that different handles to manage the same event works

More to consider: updates / end-user docs for adapting to breaking changes -- these need updating.