Conversation
dstogov
left a comment
There was a problem hiding this comment.
This doesn't make things more clear.
Actually, when you have to "read" some hex numbers printed during debug session, 0x000003F0 mask is more useful than (((1U << GC_FLAGS_BITS) - 1) << (GC_FLAGS_SHIFT + GC_TYPE_BITS)).
|
Maybe "understandable" is the wrong word? I think the word I am going for is "approachable." Currently, in the docs and existing code, the relationships and how to make changes here are a "dark art" that you either learn through PRs, are taught, or work out through painstaking debugging. This change seeks to make these values a product of their underlying parameters, both documenting how they are calculated as well as their intrinsic dependence on each other. Dumping the actual hex values should be a relatively easy exercise for any developer, should they need to be known. Could this be solved through documentation? Almost certainly. However, documentation rarely survives the first contact with a refactor, and I don't have the ability to update any documentation anyway. So this PR is as close as I can get to documenting how this works and why it is the way it is. |
|
One of the best ways is readable "graphical" comments. For example see: Line 415 in f1b41d7 Line 4099 in f1b41d7 The same is possible for bit-layout. For example: |
While trying to wrap my head around GC and
GC_FLAGS, I found the current setup a bit confusing and brittle. For example, if you want to add a new flag, you'll end up with a very subtle memory leak unless you know to updateGC_ADDRESSand how that affects the GC. Diagnosing this memory leak is not straightforward either.Thus I set out to refactor the macros here to be a bit easier to tune and comprehend; mostly to increase my own understanding of the code. I hope that other people might find it valuable as well, so I also added a full layout explaining more about what is in each part as a hint (depending on why you find yourself there).