Add CaptureMask support - #34
Conversation
Change contains: - Ability to call RegisterCaptureMask() for a given name and an optional Telemetry Zone display color - Automatically assign a color if one is not provided Part of: https://fenriscreations.atlassian.net/browse/PLAT-11474
Changed: - enum class Color => CcpColor - namespace CcpColor => ColorUtil
Change includes: - Expose CcpGetRegisteredCaptureMasks() from core - Add/change test coverage for CaptureMasks tests - Rename existing CaptureMasks variables to state they are for "registered" CaptureMasks Part of: https://fenriscreations.atlassian.net/browse/PLAT-11475
Will give us the option of a O(1) lookup for display color once we change telemetry to mark zones based on CaptureMask bit.
Change contains: - Two overloads of CcpSetActiveCaptureMask() function - An exported CcpGetActiveCaptureMask() function - Support for an "all" active CaptureMask - Support for lazy-register of active CaptureMasks by name via a list of pending ones. Part of: https://fenriscreations.atlassian.net/browse/PLAT-11481
Make sure we can verify the color associated with a Zone from the TracyTestClient in tests.
Done because of build problems on v143/v145 vs v141 identified by ccptoebeans.
Add CaptureMaksBit overloads for: - TelemetryZone constructor - CcpTelemetryEnterZone() Make sure tests reflect the new reality. Part of: https://fenriscreations.atlassian.net/browse/PLAT-11476
…pport # Conflicts: # include/CcpTelemetry.h
Rename: CcpGetCaptureMasks() To: CcpGetRegisteredCaptureMasks()
|
|
Legal hasn't advised on an updated statement yet, so we stick with `CCP ehf.`.
…es for a given color value To avoid unnecessary memory copies of the underlying string data, and to avoid surprises in seeing `CcpColorToString( CcpColor::Cyan )` return `Aqua`.
Instead, have `Color` as a default-parameter that is piped through. This alone shouldn't have required a separately overloaded implementation. Also, stop lower-casing the input name, because it causes a mismatch between what is passed into the system as "display name" versus what comes back out of the system. Additionally, remove the `all` special case handling. Enabling all capture masks can be done by passing in all capture masks. Having a sentinel value that represents a possible legal value is bound to cause surprising behaviour down the line. Sentinel values should be flagged explicitly, e.g. an alternative would have been to have an explicit function like `CcpCaptureEverything()` function. Furthermore, this simplifies initialization of pre-registered captureMasks: why run a lambda function during static initialization stage when we have initializer lists?
For type-safe constants instead of preprocessor text replacement.
As opposed to the generic `std::string`.
Surprised this didn't crash; it's undefined behaviour, and a debugging session revealed that at least on macOS this access arbitrary memory.
Naming is hard. This avoids confusion with `TelemetryZone`.
ccp-serpent
left a comment
ccp-serpent
left a comment
There was a problem hiding this comment.
The code reads much better. I've requested a minor optimization and one bit of refactoring. The outstanding observations regarding the documentation will also need addressing prior to approval.
Global search-and-replace is not a great tool.
Because everything runs in the same process, and the network communuication should go over the loopback adapter, the 100ms timeout ought to be more than enough. It can be increased again should need be, but the trade off is overall test execution time: there is no way to test "absence" of a telemetry event (e.g. something has _not_ happened) other than to let the timeout expire.
The motivation here is to prevent users of `CcpTelemetryZone` from being "bad citizens", e.g. passing arbitrarily constructed `CcpProfilerCategory` instances into it. It also unlocks a bunch of further simplifications, among other: - there are significantly fewer copies of `CcpProfilerCategory` going around - the bitmask calculation, while already cheap with the handle abstraction, is now happening only once, upon creation of a category - less sanity checks and lookups required when creating a `CcpTelemetryZone` because no invalid values can be passed in (an "empty" `CcpProfilerCategory` is the worst input, but that simply means such a zone won't be captured) - it removes a "clever workaround" that the handle approach required for the old `TMCM_CPP` / `TMCM_GENERAL` constants
Naming is hard. This is consistent with the rest of the exposed API.
Those functions are either potentially dangerous, limited in functionality, or both.
There were a few issues with building the documentation: 1. The output location for the documentation was not scoped correctly, and mismatching between what the `Breathe` plugin expected vs. where `doxygen` actually wrote the files to. 2. The doxygen build step failed when the output directory did not yet exist. So now that will get created accordingly. 3. Doxygen was not told about preprocessor macros, so it generated documentation for the wrong code. 4. The default doxygen configuration from the template does not apply here because the repository does not follow the same folder structure. Therefore, the inputs had to be adjusted. 5. Doxygen needs `BUILTIN_STL_SUPPORT` enabled or a tag file. But there is no tag file, so enabling the support it is.
…d of `std::vector<std::string>` This fixes the last remaining inconsistency in the public API and massively simplifies the implementation. It nudges users towards `CcpTelemetryRegisterCategory` / `CcpTelemetryGetRegisteredCategories` as well in order to get the required information.
This has been broken for a long time. There is an argument to remove that option since it is never built on CI. But until such a decision is made, this should work, too.
Curious that this went unnoticed until now. Turns out, there was no test for the new constructor.
AI generated, needs some refinement.
Missing preprocessor definition forwarding and lack of their resolution by doxygen caused a lot of confusion for Sphinx' "Breathe" plugin. "Breathe" was also not configured for `.cpp` files. Furthermore, setting doxygen to `EXTRACT_ALL` leaks a lot of internal symbols into the documentation, some of them which confuse Breathe, like the double occurrence of various static variables.
Similar argument as for disabling `EXTRACT_ALL`: There is a lot of noise in the documentation. Additionally, Breathe complains about duplicate symbols because it will see some of them in two separate XML files generated by doxygen.
Minor edits to improve wording and strip out unnecessary details.
While it is currently a 64 bit mask that is utilizied underneath the hood, then that is no useful information for the user of telemetry, as the bitmask is never exposed. Everything is abstracted away and hidden behind a `CcpTelemetryCategory`
There was a problem hiding this comment.
Overall the quality of the code is much better. All of my comments relating to the documentation have been addressed, with the exception of one instance outlined in a comment below.
I'd like to question why we're extending our CcpTelemetry.cpp source with all this markup for documenting the C-API. The markup is not very readable when it's not being displayed on a web-page, and it's at least doubled the size of the source code.
My opinion is that the readability of the source code has gone down significantly with these additions. I have to stress though that that's just an opinion and I will respect points made to the contrary, but I'm curious to have a discussion on the topic. Additionally, I'd like to refer to how scheduler documents its' C-API which circumvents the issues I've listed.
Additionally, there are no internal or external backlinks inside the generated API reference in the documentation. I'm not sure that's possible with just the doxygen generated xml referenced in sphinx using the .. doxygenfile:: directive. But this could be somewhat remedied by following scheduler's example.
I have to amend part of my review. I was wrong when stating that carbon-scheduler circumvents the issue, if it can be called that. In fact it uses similar markup when documenting the API, so we have a precedent for this pattern. There may be an argument case for having heavier documentation, like the markup featuring code examples, included in the |
As per code review feedback.
Thanks for the clarification! 🙂 There is a need to consolidate and adapt our existing documentation guidelines. Especially now that we use |
5 participants
Change includes: