cdefs.h: Add back comment about branch prediction

[imp]

Summary

Add back, with some minor editing, the comments about branch prediction,
when to use it, etc.

Requested by: jhb
Sponsored by: Netflix

[jhb]

It did occur to me after I sent my earlier e-mail that while it's probably good to document this here, it probably belongs in style(9) in some form as well.

sys/sys/cdefs.h

326

maybe?

[imp]

simplify, and move some info into style(9)

[imp]

sys/sys/cdefs.h

326

Yup.

[jhb]

share/man/man9/style.9

904

I would keep some of the old language about only using in paths that run frequently (not sure that "performance critical" alone implies that?).

905

I feel like some guidance on how to (not) nest these is also useful, that is I think the best practice (but this wasn't in the old comment) is to use a single hint for an entire if () expression, not multiple hints joined with operators, etc.

Maybe amend this to:

The
.Fn __predict_true
and
.Fn __predict_false
branch prediction hints should...

and then start this sentence with:

When using branch prediction hints,
atypical error conditions should use
.Fn __predict_false
(document any exceptions).
...

Currently I think it reads like it wants to encourage __predict_false.

[imp]

update with jhb's suggestions. Hopefully I got them right

[imp]

share/man/man9/style.9

904

Tried to update with this suggestion. It's good.

905

Good suggestion. Hopefully what I did captures this and deemphasizes things enough.

[brooks]

sys/sys/cdefs.h

329

Consider adding a slight emphasis on measurement rather than just vibes