Document the use of non-short-circuiting | operator in Char::IsAsciiLetterOrDigit

[jww3]

Added the following comment to clarify the rationale for using | over || in Char::IsAsciiLetterOrDigit.

// Use of the non-short-circuiting logical OR operator (|) here is an intentional optimization.
// It avoids a low-level branch instruction.  (In other words, the overhead of branching
// is greater than the cost of simply executing IsBetween.)

[huoyaoyuan]

This can lead to the right-hand side of the expression being evaluated unnecessarily.

The JIT is able to optimize this case because the functions in two branches are trivial.

https://sharplab.io/#v2:EYLgxg9gTgpgtADwGwBYA0AXEBDAzgWwB8ABAJgEYBYAKGIGYACMhgYQYG8aHunHjykDYBAgAbBgElcAQVxgAlvIAyMDBhhQAFGAAW2KAzABKBgF4AfA00BXeQDsMRzdoaEGABgSl3JuAwDk2P4mADymAQBe/gx+gf4A3Fw89EwCQiLiUgBCqgDuMDB22noGYGiGJQz49hJ2YKLWuPIAbjDluvpV2Ai19Y0tMCYWSdw29o4uftV2vQ1NraHhYw5O+N2z/a0xVTV1cwNGidQ8DCO8qYLCYpIycooqahoA8lAAIvIA5vIYxZ3GZpYpLIFMpVOotP83Nk8gUimUAu5/OV/ABOYJHE5nFL8S4ZG7A+5g55vT7fUi/UpDQG3EEPcHaEyEKG4HIYfKFbTIxHItGHGgAXyAA===

| and || provides the same assembly code, but || generates slightly longer IL.

[PaulusParssinen]

This is intentional, see https://github.com/dotnet/runtime/pull/69318/files#r872595998

[jww3]

Ah, I see. Thanks for clarifying! Maybe we should add a comment so that we don't keep revisiting this?

[PaulusParssinen]

In my opinion it does warrant a comment so people don't need to pull out sharplab/disasmo to check why it's like this 😆

I think the rationale here is that the input is not considered to be predictable so we don't try have our stupidly smart modern branch predictors predict it(?). If one case is more common the checks could be ordered and the other version could be tiny bit faster (I think this sorta cmov data-dependecy issue vs a branch in a loop.. but kinda not as the current version doesn't even need conditional mov so it's even better like this..)

Also the IL is much nicer for the importer in the branchless version.

[huoyaoyuan]

Those operators evaluate the right-hand operand only if it's necessary.

In this case, branching itself has more overhead than evaluating either branch.
For short-circuiting, we usually care more about the side effect of evaluating a branch, including triggering NullReferenceException.

This can be a common sense of advanced optimization, but sometimes I can't notice it.

[jww3]

Thanks! I'll convert this PR into just a PR to add an explanatory comment.

[huoyaoyuan]

The comment looks too verbose for users who can understand it. The position is also questionable with xml doc.

I'd suggest a trailing comment on the same line, just saying "use arithmetic or to avoid branching" or similar.

[jww3]

Tests seem to be failing for an unrelated reason. (In the end, all I did was add a comment.) I don't seem to have permission to schedule a retry of the tests.

Any advice would be appreciated.

[stephentoub]

Thanks. There are a variety of places we use | like this, which is part of its raison d'etre. Why without a comment is there an assumption that it's a mistake and why is this particular use special so as to warrant a dedicated comment?

[jww3]

When I do a quick search through this repo for " | ", I don't see many instances of | being used for boolean operations.

If there were hundreds (or even dozens) of similar usage patterns, I'd agree that it's a common-enough practice as to not warrant any clarification.

It seems, however, there are only a few.

The net effect is that the codebase exhibits these occasional inconsistencies. Mentally, when you encounter one, it gives you pause: "Wait. That doesn't look right. Why's that?"

Maybe you remember why it's that way. Maybe you have to jog your memory. Maybe you're stumped. (Most people would be stumped.)

Either way, you've wasted time contemplating it and you're likely to do it all over again when you re-encounter it at some in the future.

A simple comment here short-circuits (pun intended) that whole mental exercise.

If there are indeed only a few such instances within this repo, I'd be happy to amend this PR to cover those as well.

[stephentoub]

Thanks. Personally, I still don't believe this is valuable. The only reason to use a | here is for the exact reason the comment would state.

[jww3]

My guess is that most C# programmers aren't even aware that this is valid syntax for a boolean expression.

If you put yourself in their 👞👞 ...?