NEW: Add Event to public API

[carterbox]

Downstream packages that want to use Event to type hint their APIs should be able to import Event without accessing private modules.

#469 (comment)

I understand that Events should not be constructed directly, but having __new__() raise a RuntimeError should be sufficient to prevent that.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[carterbox]

Force-pushed to rebase on latest main.

[leofang]

btw we are on code freeze now, we could try to squeeze this in if it does not impact functionality and is an easy fix.

I understand that Events should not be constructed directly, but having __new__() raise a RuntimeError should be sufficient to prevent that.

What are your thoughts on

1. move Event from cuda_core/docs/source/api_private.rst to cuda_core/docs/source/api.rst?
2. apply the same treatment to everything else (ex: Stream)?

This was not done because I worried that people just try to construct them directly, as they are not meant to be an entry point of this module. However, it does feel weird that important objects like these are not explicitly documented, and it takes a few clicks to get to their docs. Typing is one of the straws, too, if not the last.

[rwgk]

Looks good to me.

[rwgk]

/ok to test

[rwgk]

Per offline chat with @leofang: I'll merge this now and will work on api.rst changes separately, after we lift our code freeze.

[github-actions]

Doc Preview CI
Preview removed because the pull request was closed or merged.

[carterbox]

However, it does feel weird that important objects like these are not explicitly documented, and it takes a few clicks to get to their docs. Typing is one of the straws, too, if not the last.

I think this is the main issue. Objects like Event are referenced and you have to use them, but finding the documentation on how to use them has friction.

[rwgk]

However, it does feel weird that important objects like these are not explicitly documented, and it takes a few clicks to get to their docs. Typing is one of the straws, too, if not the last.

I think this is the main issue. Objects like Event are referenced and you have to use them, but finding the documentation on how to use them has friction.

I agree (based on offline chat, I think Leo, too). Did you see my previous comment? — "I'll merge this now and will work on api.rst changes separately, after we lift our code freeze."

I'll send that PR to you for review.

[carterbox]

Did you see my previous comment?

Yes. I was just expressing my agreement. No rush from me on this. I didn't even expect this PR to be merged until next month.

I'll send that PR to you for review.

I'd be happy to review that.

[rwgk]

I didn't even expect this PR to be merged until next month.

Oh, I assumed that it's helpful to you (and in general) to have public access to Event sooner rather than later.