Adding an EventPipe README

[noahfalk]

Adding a bit of high level overview on EventPipe + notes that helped me decipher the current C code.

[lateralusX]

Great writeup! Any further suggestions for improving the readability of the library is highly welcomed.

[josalem]

Thanks for the writeup, Noah!

[josalem]

It's worth noting that defining these getters and setters is the equivalent of marking the "member" public. Nothing prevents you from accessing things without a getter/setter though since this is C.

[sywhang]

👍

[noahfalk]

Great writeup! Any further suggestions for improving the readability of the library is highly welcomed.

Sure, I think my main challenges were (1) picking out the small portions of identifiers that were the important distinctive part within otherwise very long names, and (2) the abstractions that made typical datastructures and operations like array, pointer, indexing or derefencing more opaque.

Suggestions:

1. Now that type names show up in functions there is probably good benefit to using more compact naming choices. For example perhaps thread_session_state -> tsession
2. Converging on a single definition of growable array and linked list rather than using wrapper abstractions. (dictionary too, but maybe at lower priority)
3. Where possible avoid using verbose iterator patterns and instead use simple C operators. For example growable array could expose the a T* and a length to use in a for loop with incrementing index variable. Linked list could expose a node with T* next field that can be dereferenced and it is null at the end.
4. Reconsider if we are getting enough value from the getter/setter function pattern vs. directly accessing the fields? If we want a visually distinctive indicator of public/private to catch accidental misuse, perhaps a compact naming convention such as 'all private fields start with _' would suffice?

[lateralusX]

I need to put focus on Mono runtime Diagnostic features at the moment, but could make a pass after that looking into some changes to compact names.

For arrays we already have a len and data functions that can be used directly to iterate arrays. Guess we could complement for similar things for list, but still keep abstraction not exposing the underlying implementations.

We could probably do other things to compact code when using iterators, like having a for loop macro that will take care of begin/end, next, value so you just code the inner parts of the loop having access to the value on each iteration, but no need to write the boiler plait code over and over again.

Getter/Setter have some nice features and capabilities, we have introduce them in Mono as well in some places, but I believe the main issue is increase length in identifiers. If we can make struct member names more compact (but they still need to be clear and understandable) that will of course have positive side effects of the rest of the code. A parallel option could be to change how the getter and setters are used to simplify reading. Instead of:

ep_sequence_point_get_thread_sequence_numbers_ref (instance)

we could do:

ep_sequence_point_get_ref (instance, thread_sequence_numbers)

and compacting some identifiers we could get:

ep_seq_point_get_ref (instance, tseq_nums)

That will turn the getter into a function first taking struct instance as first parameter and field as second, but still keep the logic of getter (and inline function, or direct struct member access under the hood). Personally I think that increase readability a lot since you can just look at the last part to detect operator and the last parameter to see the member.

Alternative:

ep_get_ref (seq_point, instance, tseq_nums)

I believe setters could be done something like this:

ep_seq_point_set (instance, tseq_nums) = 2

Alternative:

ep_set (seq_point, instance, tseq_nums) = 2