Add get_cuda_native_handle

[leofang]

Description

closes #564

The performance is comparable to the existing int() approach (O(10) ns):

In [1]: from cuda.bindings import driver

In [3]: s = driver.CUstream(1234)

In [4]: int(s)
Out[4]: 1234

In [6]: from cuda.bindings.utils import get_cuda_native_handle

In [7]: get_cuda_native_handle(s)
Out[7]: 1234

In [8]: %timeit int(s)
44.7 ns ± 1.34 ns per loop (mean ± std. dev. of 7 runs, 10,000,000 loops each)

In [9]: %timeit get_cuda_native_handle(s)
95.1 ns ± 1.06 ns per loop (mean ± std. dev. of 7 runs, 10,000,000 loops each)

Checklist

• New or existing tests cover these changes.
• The documentation is up to date with these changes.

[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.

[leofang]

(added a short benchmark to the PR description)

[leofang]

/ok to test 8970dca

[leofang]

/ok to test 4ca551c

[leofang]

Note: this is a bug fix exposed by the new line 224. Previously, the path variable happened to be right (leaking from the loop variable at line 227), but it's not longer correct after we append one more item to path_list.

[leofang]

Decision to make: Should we raise DeprecationWarning in __int__()? It can be very noisy but it's the only effective way for us to inform users about the deprecation.

[rwgk]

Decision to make: Should we raise DeprecationWarning in __int__()? It can be very noisy but it's the only effective way for us to inform users about the deprecation.

Do we want to give users a grace period, in case they need to support two cuda-bindings versions for a while?

Concretely:

In the next release, deprecate only in the documentation.

Only with the next minor release bump: actually raise DeprecationWarning.

[leofang]

/ok to test 53055e5

[rwgk]

Decision to make: Should we raise DeprecationWarning in __int__()? It can be very noisy but it's the only effective way for us to inform users about the deprecation.

Do we want to give users a grace period, in case they need to support two cuda-bindings versions for a while?

Concretely:

In the next release, deprecate only in the documentation.

Only with the next minor release bump: actually raise DeprecationWarning.

@leofang WDYT about introducing a "Phased deprecations" section somewhere, so we don't forget in the future.

E.g. for this case:

__int__() method for type A, B, C were informally deprecated in cuda-bindings release vX.Y.Z. DeprecationWarning will be raised starting with release vX.Y+1.0.

[github-actions]

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

[leofang]

Yup that's great idea, tracked in #775.