Rewrite Enum and add {ISpanFormattable}.TryFormat

[stephentoub]

Fixes#57881
Fixes#76157
Fixes#76398
Fixes#29266

This rewrites Enum to change how it stores the values data. Rather than having a non-generic EnumInfo that stores a ulong[] array of all values, there’s a generic EnumInfo that stores a TUnderlyingType[]. Then based on the enum’s type, every entry point maps to an underlying TUnderlyingType and invokes a generic method with that TUnderlyingType, e.g. Enum.IsDefined(…) and Enum.IsDefined(typeof(TEnum), …) will look up the TUnderlyingValue and then invoke Enum.IsDefinedPrimitive(typeof(TEnum)). In this way, a) we store an array strongly typed to the underlying value rather than storing the worst case ulong[], and b) we share implementations across generic and non-generic entrypoints while not having full generic specialization for every TEnum; worst case, we have only one generic specialization per underlying type, of which only 8 are expressible in C#. The generic entrypoints are able to do the mapping very efficiently, thanks to the recently added enum-based intrinsics. The non-generic entrypoints use the same switches on TypeCode/CorElementType they do today when doing e.g. ToUInt64.

@jkotas, I hope this meets your desires as expressed in #71590 (comment). If I've misinterpreted or you were hoping for something else, please let me know. There, you quoted the TryFormat method increasing working set by 7.5kb, which I was able to repro. With this PR, it's ~3.5kb with tiered compilation off... with tiered compilation enables, it's actually more, at ~9.5kb. Part of the issue appears to be how the repro itself is structured and how it interacts with JIT inlining, which is to say, not well; the JIT gives up inlining very early on, and that looks to contribute meaningfully to the size (plus little optimization happening in tier 0, hence the large number).

This also adds the static Enum.TryFormat as well as changing Enum to implement ISpanFormattable, with ISpanFormattable.TryFormat as an explicit implementation. These both share the same underlying TUnderlyingValue-based generic implementation, with just the entrypoint methods differing as to how the TUnderlyingValue mapping is done. And then that Enum.TryFormat is used in multiple interpolated string handlers to avoid boxing the enum; today it’ll be boxed as part of using its IFormattable implementation, and with this change, it both won’t be boxed and will call through the optimized generic path. This uses typeof(T).IsEnum, which is now a JIT intrinsic that’ll become a const true/false.

Overall, performance improves, in particular for the generic methods. Some of the non-generics get better as well. However, there is a repeatable regression here for other non-generic methods, in particular the non-generic Parse methods, and I haven’t been able to root cause that yet. @jkotas or @EgorBo, if you see anything obvious here, please let me know.

This includes the initial commit from #71590, although the primary thing still around from that are the tests that were added. Thanks, @heathbm.

@tannergooding and/or @dakersnar, if you could help look at the use of generic math, that'd be welcome.

I have a set of changes I plan to PR to dotnet/performance. Here are the results of those tests locally:

Method	Toolchain	value	format	text	Mean	Ratio	Code Size	Allocated	Alloc Ratio
HasFlag	\main\corerun.exe	?	?	?	0.0000 ns	?	12 B	-	?
HasFlag	\pr\corerun.exe	?	?	?	0.0119 ns	?	12 B	-	?
Compare	\main\corerun.exe	?	?	?	0.0004 ns	?	11 B	-	?
Compare	\pr\corerun.exe	?	?	?	0.0142 ns	?	11 B	-	?
GetName_NonGeneric_Flags	\main\corerun.exe	?	?	?	24.5866 ns	1.00	430 B	24 B	1.00
GetName_NonGeneric_Flags	\pr\corerun.exe	?	?	?	36.9405 ns	1.50	235 B	24 B	1.00
IsDefined_Generic_Flags	\main\corerun.exe	?	?	?	6.4346 ns	1.00	202 B	-	NA
IsDefined_Generic_Flags	\pr\corerun.exe	?	?	?	5.4740 ns	0.85	194 B	-	NA
IsDefined_Generic_NonFlags	\main\corerun.exe	?	?	?	3.5333 ns	1.00	202 B	-	NA
IsDefined_Generic_NonFlags	\pr\corerun.exe	?	?	?	1.7395 ns	0.49	194 B	-	NA
GetName_Generic_Flags	\main\corerun.exe	?	?	?	8.4323 ns	1.00	1,298 B	-	NA
GetName_Generic_Flags	\pr\corerun.exe	?	?	?	6.9253 ns	0.82	625 B	-	NA
GetName_Generic_NonFlags	\main\corerun.exe	?	?	?	5.2012 ns	1.00	763 B	-	NA
GetName_Generic_NonFlags	\pr\corerun.exe	?	?	?	3.6108 ns	0.69	625 B	-	NA
GetNames_Generic	\main\corerun.exe	?	?	?	14.5402 ns	1.00	231 B	64 B	1.00
GetNames_Generic	\pr\corerun.exe	?	?	?	14.0541 ns	0.96	241 B	64 B	1.00
GetValues_Generic	\main\corerun.exe	?	?	?	349.5134 ns	1.00	69 B	168 B	1.00
GetValues_Generic	\pr\corerun.exe	?	?	?	11.0484 ns	0.03	163 B	48 B	0.29
GetValuesAsUnderlyingType_Generic	\main\corerun.exe	?	?	?	34.9357 ns	1.00	783 B	144 B	1.00
GetValuesAsUnderlyingType_Generic	\pr\corerun.exe	?	?	?	16.9793 ns	0.49	215 B	144 B	1.00
GetValuesAsUnderlyingType_NonGeneric	\main\corerun.exe	?	?	?	34.8806 ns	1.00	73 B	144 B	1.00
GetValuesAsUnderlyingType_NonGeneric	\pr\corerun.exe	?	?	?	24.0148 ns	0.69	73 B	144 B	1.00
ToString_NonFlags_Small	\main\corerun.exe	-1	?	?	30.4135 ns	1.00	313 B	56 B	1.00
ToString_NonFlags_Small	\pr\corerun.exe	-1	?	?	27.6264 ns	0.91	665 B	56 B	1.00
ToString_Flags	\main\corerun.exe	32	?	?	29.4235 ns	1.00	313 B	56 B	1.00
ToString_Flags	\pr\corerun.exe	32	?	?	25.2869 ns	0.87	665 B	56 B	1.00
StringFormat	\main\corerun.exe	32	?	?	338.9915 ns	1.00	331 B	352 B	1.00
StringFormat	\pr\corerun.exe	32	?	?	245.3310 ns	0.72	331 B	88 B	0.25
InterpolateIntoString	\main\corerun.exe	32	?	?	244.6292 ns	1.00	1,890 B	352 B	1.00
InterpolateIntoString	\pr\corerun.exe	32	?	?	130.7233 ns	0.54	2,068 B	64 B	0.18
InterpolateIntoSpan_Flags	\main\corerun.exe	32	?	?	169.0338 ns	1.00	492 B	288 B	1.00
InterpolateIntoSpan_Flags	\pr\corerun.exe	32	?	?	90.0121 ns	0.55	492 B	-	0.00
InterpolateIntoStringBuilder_Flags	\main\corerun.exe	32	?	?	214.4654 ns	1.00	286 B	288 B	1.00
InterpolateIntoStringBuilder_Flags	\pr\corerun.exe	32	?	?	110.9654 ns	0.53	286 B	24 B	0.08
ToString_Flags	\main\corerun.exe	36	?	?	29.8668 ns	1.00	313 B	56 B	1.00
ToString_Flags	\pr\corerun.exe	36	?	?	25.2438 ns	0.85	665 B	56 B	1.00
ToString_NonFlags_Large	\main\corerun.exe	42	?	?	21.9036 ns	1.00	313 B	56 B	1.00
ToString_NonFlags_Large	\pr\corerun.exe	42	?	?	17.2329 ns	0.79	665 B	56 B	1.00
InterpolateIntoSpan_NonFlags	\main\corerun.exe	42	?	?	165.0200 ns	1.00	492 B	288 B	1.00
InterpolateIntoSpan_NonFlags	\pr\corerun.exe	42	?	?	94.0216 ns	0.57	492 B	-	0.00
InterpolateIntoStringBuilder_NonFlags	\main\corerun.exe	42	?	?	177.5868 ns	1.00	286 B	288 B	1.00
InterpolateIntoStringBuilder_NonFlags	\pr\corerun.exe	42	?	?	115.2136 ns	0.65	286 B	24 B	0.08
ToString_Format_NonFlags	\main\corerun.exe	7	G	?	15.0427 ns	1.00	428 B	24 B	1.00
ToString_Format_NonFlags	\pr\corerun.exe	7	G	?	11.5376 ns	0.77	1,444 B	24 B	1.00
ToString_Format_NonFlags	\main\corerun.exe	8	F	?	25.9959 ns	1.00	428 B	24 B	1.00
ToString_Format_NonFlags	\pr\corerun.exe	8	F	?	23.0378 ns	0.88	1,444 B	24 B	1.00
ToString_Format_Flags_Large	\main\corerun.exe	All		?	15.4803 ns	1.00	428 B	24 B	1.00
ToString_Format_Flags_Large	\pr\corerun.exe	All		?	17.4866 ns	1.13	1,444 B	24 B	1.00
ToString_Format_Flags_Large	\main\corerun.exe	All	d	?	17.6032 ns	1.00	428 B	56 B	1.00
ToString_Format_Flags_Large	\pr\corerun.exe	All	d	?	19.6840 ns	1.11	1,444 B	56 B	1.00
ToString_Format_Flags_Large	\main\corerun.exe	All	f	?	17.1029 ns	1.00	428 B	24 B	1.00
ToString_Format_Flags_Large	\pr\corerun.exe	All	f	?	16.0028 ns	0.93	1,444 B	24 B	1.00
ToString_Format_Flags_Large	\main\corerun.exe	All	g	?	16.6692 ns	1.00	428 B	24 B	1.00
ToString_Format_Flags_Large	\pr\corerun.exe	All	g	?	16.4078 ns	0.98	1,444 B	24 B	1.00
ToString_Format_Flags_Large	\main\corerun.exe	All	x	?	24.2053 ns	1.00	428 B	64 B	1.00
ToString_Format_Flags_Large	\pr\corerun.exe	All	x	?	22.7144 ns	0.94	1,415 B	64 B	1.00
ToString_NonFlags_Small	\main\corerun.exe	TopDirectoryOnly	?	?	11.9013 ns	1.00	313 B	24 B	1.00
ToString_NonFlags_Small	\pr\corerun.exe	TopDirectoryOnly	?	?	11.7533 ns	0.98	665 B	24 B	1.00
ToString_NonFlags_Small	\main\corerun.exe	AllDirectories	?	?	11.7413 ns	1.00	313 B	24 B	1.00
ToString_NonFlags_Small	\pr\corerun.exe	AllDirectories	?	?	11.4765 ns	0.97	665 B	24 B	1.00
ToString_NonFlags_Large	\main\corerun.exe	Control	?	?	11.6787 ns	1.00	313 B	24 B	1.00
ToString_NonFlags_Large	\pr\corerun.exe	Control	?	?	11.6246 ns	1.00	665 B	24 B	1.00
ToString_NonFlags_Large	\main\corerun.exe	Format	?	?	12.5915 ns	1.00	313 B	24 B	1.00
ToString_NonFlags_Large	\pr\corerun.exe	Format	?	?	11.6680 ns	0.93	665 B	24 B	1.00
ToString_Format_NonFlags	\main\corerun.exe	Monday	g	?	13.4477 ns	1.00	428 B	24 B	1.00
ToString_Format_NonFlags	\pr\corerun.exe	Monday	g	?	12.7797 ns	0.94	1,444 B	24 B	1.00
ToString_Format_NonFlags	\main\corerun.exe	Friday	X	?	23.2332 ns	1.00	428 B	64 B	1.00
ToString_Format_NonFlags	\pr\corerun.exe	Friday	X	?	21.5598 ns	0.93	1,415 B	64 B	1.00
ToString_NonFlags_Large	\main\corerun.exe	OtherNotAssigned	?	?	11.4982 ns	1.00	313 B	24 B	1.00
ToString_NonFlags_Large	\pr\corerun.exe	OtherNotAssigned	?	?	11.4304 ns	0.99	665 B	24 B	1.00
Parse_Flags	\main\corerun.exe	?	?	Red	65.6035 ns	1.00	2,224 B	24 B	1.00
Parse_Flags	\pr\corerun.exe	?	?	Red	81.8236 ns	1.25	1,155 B	24 B	1.00
TryParseGeneric_Flags	\main\corerun.exe	?	?	Red	28.3974 ns	1.00	1,229 B	-	NA
TryParseGeneric_Flags	\pr\corerun.exe	?	?	Red	26.7545 ns	0.94	142 B	-	NA
StringFormat	\main\corerun.exe	Red	?	?	302.1524 ns	1.00	331 B	232 B	1.00
StringFormat	\pr\corerun.exe	Red	?	?	227.2187 ns	0.75	331 B	96 B	0.41
InterpolateIntoString	\main\corerun.exe	Red	?	?	166.0809 ns	1.00	1,890 B	232 B	1.00
InterpolateIntoString	\pr\corerun.exe	Red	?	?	116.3095 ns	0.70	2,068 B	72 B	0.31
InterpolateIntoSpan_Flags	\main\corerun.exe	Red	?	?	118.7156 ns	1.00	492 B	160 B	1.00
InterpolateIntoSpan_Flags	\pr\corerun.exe	Red	?	?	75.4937 ns	0.64	492 B	-	0.00
InterpolateIntoStringBuilder_Flags	\main\corerun.exe	Red	?	?	146.0972 ns	1.00	286 B	160 B	1.00
InterpolateIntoStringBuilder_Flags	\pr\corerun.exe	Red	?	?	100.1058 ns	0.69	286 B	24 B	0.15
ToString_Flags	\main\corerun.exe	Yellow	?	?	16.1928 ns	1.00	313 B	24 B	1.00
ToString_Flags	\pr\corerun.exe	Yellow	?	?	16.5742 ns	1.03	665 B	24 B	1.00
StringFormat	\main\corerun.exe	Red, Green	?	?	353.5309 ns	1.00	331 B	416 B	1.00
StringFormat	\pr\corerun.exe	Red, Green	?	?	267.8539 ns	0.76	331 B	136 B	0.33
InterpolateIntoString	\main\corerun.exe	Red, Green	?	?	211.1244 ns	1.00	1,890 B	416 B	1.00
InterpolateIntoString	\pr\corerun.exe	Red, Green	?	?	148.7505 ns	0.70	2,068 B	112 B	0.27
InterpolateIntoSpan_Flags	\main\corerun.exe	Red, Green	?	?	168.5889 ns	1.00	492 B	304 B	1.00
InterpolateIntoSpan_Flags	\pr\corerun.exe	Red, Green	?	?	105.7041 ns	0.63	492 B	-	0.00
InterpolateIntoStringBuilder_Flags	\main\corerun.exe	Red, Green	?	?	184.5203 ns	1.00	286 B	304 B	1.00
InterpolateIntoStringBuilder_Flags	\pr\corerun.exe	Red, Green	?	?	120.3897 ns	0.66	286 B	24 B	0.08
Parse_Flags	\main\corerun.exe	?	?	Red, Orange, Yellow, Green, Blue	129.7943 ns	1.00	2,224 B	24 B	1.00
Parse_Flags	\pr\corerun.exe	?	?	Red, Orange, Yellow, Green, Blue	142.8291 ns	1.10	1,155 B	24 B	1.00
TryParseGeneric_Flags	\main\corerun.exe	?	?	Red, Orange, Yellow, Green, Blue	86.5051 ns	1.00	1,229 B	-	NA
TryParseGeneric_Flags	\pr\corerun.exe	?	?	Red, Orange, Yellow, Green, Blue	85.1191 ns	0.99	142 B	-	NA
ToString_Flags	\main\corerun.exe	Red, Orange, Yellow, Green, Blue	?	?	53.6118 ns	1.00	313 B	112 B	1.00
ToString_Flags	\pr\corerun.exe	Red, Orange, Yellow, Green, Blue	?	?	49.1623 ns	0.92	665 B	112 B	1.00
ToString_Format_NonFlags	\main\corerun.exe	Sunday		?	11.8233 ns	1.00	428 B	24 B	1.00
ToString_Format_NonFlags	\pr\corerun.exe	Sunday		?	13.5119 ns	1.14	1,444 B	24 B	1.00
ToString_Format_NonFlags	\main\corerun.exe	Tuesday	d	?	9.2690 ns	1.00	428 B	24 B	1.00
ToString_Format_NonFlags	\pr\corerun.exe	Tuesday	d	?	10.0484 ns	1.08	1,444 B	24 B	1.00
ToString_Format_NonFlags	\main\corerun.exe	Thursday	f	?	18.3243 ns	1.00	428 B	24 B	1.00
ToString_Format_NonFlags	\pr\corerun.exe	Thursday	f	?	17.4421 ns	0.95	1,444 B	24 B	1.00
InterpolateIntoSpan_NonFlags	\main\corerun.exe	Orange, Yellow	?	?	167.9801 ns	1.00	492 B	328 B	1.00
InterpolateIntoSpan_NonFlags	\pr\corerun.exe	Orange, Yellow	?	?	101.7104 ns	0.60	492 B	-	0.00
InterpolateIntoStringBuilder_NonFlags	\main\corerun.exe	Orange, Yellow	?	?	185.5282 ns	1.00	286 B	328 B	1.00
InterpolateIntoStringBuilder_NonFlags	\pr\corerun.exe	Orange, Yellow	?	?	121.8469 ns	0.66	286 B	24 B	0.07
ToString_Format_NonFlags	\main\corerun.exe	Saturday	D	?	9.1248 ns	1.00	428 B	24 B	1.00
ToString_Format_NonFlags	\pr\corerun.exe	Saturday	D	?	10.2981 ns	1.13	1,444 B	24 B	1.00
ToString_NonFlags_Large	\main\corerun.exe	UppercaseLetter	?	?	11.5365 ns	1.00	313 B	24 B	1.00
ToString_NonFlags_Large	\pr\corerun.exe	UppercaseLetter	?	?	11.5044 ns	1.00	665 B	24 B	1.00
ToString_Format_NonFlags	\main\corerun.exe	Wednesday	x	?	22.9680 ns	1.00	428 B	64 B	1.00
ToString_Format_NonFlags	\pr\corerun.exe	Wednesday	x	?	21.8983 ns	0.95	1,415 B	64 B	1.00
ToString_Flags	\main\corerun.exe	Yellow, Blue	?	?	35.6940 ns	1.00	313 B	72 B	1.00
ToString_Flags	\pr\corerun.exe	Yellow, Blue	?	?	32.8618 ns	0.92	665 B	72 B	1.00

[ghost]

Note regarding the new-api-needs-documentation label:

This serves as a reminder for when your PR is modifying a ref *.cs file and adding/modifying public APIs, to please make sure the API implementation in the src *.cs file is documented with triple slash comments, so the PR reviewers can sign off that change.

[ghost]

I couldn't figure out the best area label to add to this PR. If you have write-permissions please help me learn by adding exactly one area label.

[jkotas]

With this PR, it's ~3.5kb with tiered compilation off... with tiered compilation enables, it's actually more, at ~9.5kb.

I have pushed a change that reduces this to 6.5kb with tiered compilation enabled and 1058 bytes with tiered compilation disabled. It can be further reduced to 894 bytes by copy&pasting TryFormatUnconstrained implementation into TryFormat instead of depending on the JIT inliner to do it for you. I have not done it in my commit, but it may be worth doing. It should not actually increase the IL size thanks to IL body folding. Both methods should have identical IL and this copy&paste would be actually a tiny IL size reduction.

[stephentoub]

I have pushed a change that reduces this to 6.5kb with tiered compilation enabled and 1058 bytes with tiered compilation disabled.

Thanks. Would you recommend looking to replace Unsafe.As in other places like this as well (separate from this PR)? Or you view this as a temporary thing until inlining can be improved?

[jkotas]

Would you recommend looking to replace Unsafe.As in other places like this as well (separate from this PR)?

Yes, I do not see any downsides. It is only possible when the source is stackallocated or in unmanaged memory.

Or you view this as a temporary thing until inlining can be improved?

It is not inlining problem. The problem is that the runtime has to materialize the generic Unsafe.As instantiations before the JIT can recognize them as intrinsics. It is hard to do something about it. If we were to do something about it, I think it would best to do that as IL-to-IL optimization pass at build time.

[DaZombieKiller]

Would it be worthwhile to replace usages of Unsafe.SizeOf<T>() with sizeof(T) across the BCL as well, now that C# 11 allows that for all types?

[jkotas]

Would it be worthwhile to replace usages of Unsafe.SizeOf() with sizeof(T) across the BCL as well, now that C# 11 allows that for all types?

Yes: #78741

[radical]

re:WasmBuildTests failures, these are some Blazor AOT builds getting oomkill'ed when linking. I have seen these before, and have an open issue for similar tests. I will investigate these separately, and this PR doesn't need to be blocked.

[steveisok]

The iOS & tvOS legs are failing to AOT System.Net.Http.Json. Need to investigate further to determine if it's related to this PR or not.

error : Precompiling failed for /tmp/helix/working/C0EE0A28/w/B12009A0/e/publish/System.Net.Http.Json.dll with exit code 139.

[stephentoub]

@steveisok, let me know if/how I can help your investigation.

[jkotas]

The iOS & tvOS legs are failing to AOT System.Net.Http.Json.

I have opened #79279 on this.

[stephentoub]

Need to investigate further to determine if it's related to this PR or not.

I tried reverting this in CI, and that revert PR still hits the failures:
https://github.com/dotnet/runtime/pull/79303/checks?check_run_id=9926753891

/tmp/helix/working/AF1E09C5/p/build/apple/AppleApp.targets(91,5): error : Precompiling failed for /tmp/helix/working/AF1E09C5/w/B29C097C/e/publish/System.Net.Http.Json.dll with exit code 139. [/private/tmp/helix/working/AF1E09C5/w/B29C097C/e/publish/ProxyProjectForAOTOnHelix.proj]
/tmp/helix/working/AF1E09C5/p/build/apple/AppleApp.targets(91,5): error : [/private/tmp/helix/working/AF1E09C5/w/B29C097C/e/publish/ProxyProjectForAOTOnHelix.proj]

so it's not this PR.

[JamesNK]

@stephentoub We noticed some enum order changes when updating ASP.NET Core to the latest runtime bits. The dependency update has been blocked for a long time, so it's hard to know precisely when the change happened. This PR might be the cause. See e4745f4 (#45475)

The enum values are fetched with reflection in Swashbuckle here - https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/1b1d3daedea177895062780cf09f1755647775c4/src/Swashbuckle.AspNetCore.SwaggerGen/SchemaGenerator/SchemaGenerator.cs#L292

Was the order change intentional?

[stephentoub]

What are the enum's values and what is the order difference you observed?

[jkotas]

Example:

foreach (var v in Enum.GetValues<MyEnum>())
Console.WriteLine(v);
enum MyEnum
{
A = -1,
B = 0,
C = 1
}

Before this change: B C A
After this change: A B C

Before this change, the values were always sorted as ulongs bit patterns. After this change, the values are sorted using their underlying type - signed, unsigned, floating point.

[stephentoub]

I found it:
https://github.com/dotnet/aspnetcore/blob/e4745f467ed378bec8ab19948085ee9e1ecd9350/src/Grpc/JsonTranscoding/test/Microsoft.AspNetCore.Grpc.Swagger.Tests/Proto/messages.proto#L16
Yes, that's intentional. Previously the values were being sorted as ulongs, which would cause negative values to come after everything else when the enum type was signed. Now they're sorted according to the actual type, so negative values come before the ones that come, you know, after :-)

[stephentoub]

Jan beat me by two minutes.