Activity

1. mdboom

   added

   enhancementAny code-related improvementsAny code-related improvements

   RFCPlans and announcementsPlans and announcements

   cuda.coreEverything related to the cuda.core moduleEverything related to the cuda.core module

   on Apr 30, 2026
2. mdboom commented on Apr 30, 2026

   

   mdboom

   on Apr 30, 2026

   ContributorAuthor

   More actions

   Note that the above list is just where strings are used where enums could be, not the opposite, where we use enums but strings are not accepted. We could also produce that list.

   My proposed solution:

   • Everywhere we accept something "enum like", the type is SpecificEnum | str. (SpecificEnum | Literal[...] would be better from a type perspective, but IMHO is not worth the repeating yourself burden).
   • Everywhere we return something "enum like", we return an enum, and str(enum) gives a string.

   This seems to address type checking much better than what we have today, and also reduces a class of errors where it is easier to mis-spell a string than an enum value.

   It also gives users a fast path (using enums) that using strings may not have.
3. leofang

   added a parent issue on Apr 30, 2026

   • Audit cuda.core API for 1.0 release #1919
4. leofang

   assigned

   mdboom

   on May 1, 2026
5. leofang

   added this to the cuda.core v1.0.0 milestone on May 1, 2026
6. leofang

   added

   P0High priority - Must do!High priority - Must do!

   on May 1, 2026
7. mdboom commented on May 1, 2026

   

   mdboom

   on May 1, 2026

   Last edited by mdboom

   ContributorAuthor

   More actions

   From a user/API perspective, I think consensus from the meeting is that it would be ideal to support both strings and enums, i.e.

   call_func(MyEnum.VALUE)
   get_result() == MyEnum.VALUE
   

   and

   call_func("value")
   get_result() == "value"
   

   would be equivalent and supported everywhere "logically enum-like things" would be needed.

   It is desirable to give type checkers and linters as much as they can to deal with here. Much of that will be theoretical today, since we don't have .pyi files, but we should plan for a future where we do.

   We have two sets of enums in cuda-core: (A) those that are internal to cuda-core and exist only for the Pythonic layer and (B) those that are re-exposures of C-style int enums from CUDA libraries (usually through cuda.bindings). The enum implementation does not need to be the same in both cases (it's an implementation detail), but having a consistent interface across all of them seems desirable (especially whether they implicitly convert to/from strings), so the user doesn't have to know which type of enum they are dealing with.

   After doing a bunch of benchmarking of alternatives, I've reached the following conclusion:

   (A) Existing cuda-core enums

   The stdlib enum.StrEnum does not have the performance issues of enum.IntEnum, and is every bit as fast as using strings. For the existing cuda-core enum-like-things using strings that don't need to map directly to C (int) enums, this is the right choice. It will allow both strings or StrEnum at all of our call sites with basically zero overhead. Making this change, our users can decide whether they prefer enums or strings and the type checking vs. convenience tradeoffs.

   Extending FastEnum slightly to use them for the above purpose adds about 40ns of overhead vs. StrEnum. Unlike FastEnum, StrEnum values do not have docstrings, so the doc pages can only list their values, not add explanations of what each value means. I think we treat this as a doc build problem: it would better to extend/fix Sphinx somehow to make that work than pay a runtime penalty just to have good docs. 🙃

   (B) Re-exposed C-style enums

   These are currently using FastEnum, since they are integer values. These do not currently implicitly convert to/from strings, but can be easily extended to do so. The performance penalty of doing that accepting either a string or a FastEnum at each call site is around 40ns. I think it is worth that to have a consistent interface for all of our enums across cuda-core.

   Urgency?

   All of this is a little complex and risky to get squeezed in right before the 1.0 release. So what happens if we don't and instead do it later?

   Fundamentally, we are /extending/ the set of values our functions can accept, which is not API breaking.

   For argument types of type (A), we would be going from str to str | Enum (or in some cases we have Literal["a", "b", "c"] which would go to str | Enum). Type (B) would go from Enum to Enum | str.

   For returning values, we would be going from str to Enum, and we would have to ensure that result == "value" would continue to work. If we need to retain isinstance(result, str) or result is "value", that may not be possible. That seems fine to me, barring XKCD 1172.

   What we couldn't do later (easily) is decide that we want to remove uses of strings and use only enums everywhere (or conversely for type (B) accept only strings everywhere).

   I think I'm ok to commit to that much and not try to rush this through (though I think it is generally a good idea to do this).
8. mdboom commented on May 1, 2026

   

   mdboom

   on May 1, 2026

   ContributorAuthor

   More actions

   I think we treat this as a doc build problem: it would better to extend/fix Sphinx somehow to make that work than pay a runtime penalty just to have good docs.

   FWIW: It's ugly but this works:

   class SourceType(StrEnum):
       CXX = "c++"
       PTX = "ptx"
       NVVM = "nvvm"
   
   SourceType.CXX.__doc__ = "C++ source code."
   
9. mdboom

   added a commit that references this issue on May 5, 2026

   Fix NVIDIA#1995: Use StrEnum for enum-like strings

   This issue will close once commit 4d1ddb4 is merged into the 'main' branch.

   4d1ddb4
10. mdboom

    closed this as completedin cec0efbon May 5, 2026
11. mdboom

    added a commit that references this issue on May 5, 2026

    Fix NVIDIA#1995: Use StrEnum for enum-like strings (NVIDIA#2016)

    ...

    This issue will close once commit cec0efb is merged into the 'main' branch.

    cec0efb