Matthew Craven authored Jul 30, 2023 and Marge Bot committed Aug 04, 2023

Fixes #17900; fixes #20195.

The existing "can_fail" and "has_side_effects" primop attributes
that previously governed this were used in inconsistent and
confusingly-documented ways, especially with regard to raising
exceptions.  This patch replaces them with a single "effect"
attribute, which has four possible values: NoEffect, CanFail,
ThrowsException, and ReadWriteEffect.  These are described in
Note [Classifying primop effects].

A substantial amount of related documentation has been re-drafted
for clarity and accuracy.

In the process of making this attribute format change for literally
every primop, several existing mis-classifications were detected and
corrected.  One of these mis-classifications was tagToEnum#, which
is now considered CanFail; this particular fix is known to cause a
regression in performance for derived Enum instances.  (See #23782.)
Fixing this is left as future work.

New primop attributes "cheap" and "work_free" were also added,
and...