Implement cudax::cufile

[davebayer]

This PR implements wrappers of CUfileHandle_t and related APIs.

It introduces:

1. cudax::cufile type which handles opening/closing the native file handle and registering/deregistering of the cuFile file handle. It owns both of these resources.
2. cudax::cufile_ref type that is a lightweight non-owning wrapper for the cuFile file handle. It doesn't own the resources (with exception below).
3. cuda::cufile_driver.[de]register_native_handle(...) -> cuda::cufile_ref that can be used for manual registration of the native file handle. It has basically the same semantics as new/delete.

So, right now these are the scenarios are covered:

1. the user has some legacy code from where he gets the CUfileHandle_t -> he can use cuda::cufile_ref with our APIs.
2. the user has some code that gives him the native file handle, but he doesn't own the native file handle -> he can use cuda::cufile_driver.register_native_handle(...).
3. the user wants us to open the native file handle for him as well -> he can use cuda::cufile

We might introduce a third option: cuda::scoped_cufile or something similar, that would be constructible from cuda::cufile_ref and would deregister the handle when going out of scope, but I would wait with it.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[jvera-nvidia]

do we really need to retrieve the opening mode?
I'm a bit worried on non-standard things in the bindings for when eventually cufile is windows supported.

[jvera-nvidia]

I'm not sure we need this... its two ways of doing the same (this vs constructor) and this actually is forbidden if the constructor was already called. I'd vote to remove this one.

[davebayer]

But for example std::fstream also implements the .open(...) method. I'd like to stay as close as what is common in the standard as possible

[jvera-nvidia]

but we can always implement it later if needed... I don't see why this is needed; we are not trying to stay close to fstream either, are we?

[davebayer]

That's true, but I'd like to provide tools users are used to have. Consider this:

cuda::cufile file;
// ...
file = cuda::cufile{filename, open_mode}; // open the file
// ...
file = cuda::cufile{}; // close the file

You have a situation like this, when you want to have the object in not opened state. Then, to open the file, you must create another object and move assign it to the original object. And if you want to close the file with detection whether it was closed or not, you must (again) move assign a new default constructed object.

In my opinion this is not a good design. I'd like to do:

cuda::cufile file;
// ...
file.open(filename, open_mode); // open the file
// ...
file.close(); // close the file

[jvera-nvidia]

Fair enough, those are valid points. I was unsure we needed it but as you said the easier of use and known methods are totally valid and I think it's good to have! Enviado desde Outlook para Android<https://aka.ms/AAb9ysg>

________________________________ From: David Bayer ***@***.***> Sent: Thursday, October 16, 2025 9:15:39 PM To: NVIDIA/cccl ***@***.***> Cc: Javier Vera ***@***.***>; Comment ***@***.***> Subject: Re: [NVIDIA/cccl] Implement `cudax::cufile` (PR #6122) @davebayer commented on this pull request.

________________________________ In cudax/include/cuda/experimental/__cufile/cufile.cuh<#6122 (comment)>:

+ _CCCL_HOST_API void open(const char* __filename, cufile_open_mode __open_mode)

+ { + if (is_open()) + { + ::cuda::std::__throw_runtime_error("File is already opened."); + } + + __native_handle_ = __open_file(__filename, __make_oflags(__open_mode)); + + try + { + __cufile_handle_ = __register_cufile_handle(__native_handle_); + } + catch (...) + { + __close_file(::cuda::std::exchange(__native_handle_, __invalid_native_handle)); + throw; + } + } That's true, but I'd like to provide tools users are used to have. Consider this: cuda::cufile file; // ... file = cuda::cufile{filename, open_mode}; // open the file // ... file = cuda::cufile{}; // close the file You have a situation like this, when you want to have the object in not opened state. Then, to open the file, you must create another object and move assign it to the original object. And if you want to close the file with detection whether it was closed or not, you must (again) move assign a new default constructed object. — Reply to this email directly, view it on GitHub<#6122 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/BSUF2R623U6KWV3NPWPNYAL3X7VFXAVCNFSM6AAAAACIGCYCK2VHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZTGNBWGYZDKOJZGA>. You are receiving this because you commented.Message ID: ***@***.***>

[pciolkosz]

Could correct flags be non-zero here? Internet says to do:
fcntl(fd, F_GETFD) != -1 || errno != EBADF;
For this use case probably just the first part is ok

[davebayer]

Oh yeah, you are right

[davebayer]

Waiting for https://github.com/nv-gha-runners/roadmap/issues/318

[davebayer]

Waiting for https://github.com/nv-gha-runners/roadmap/issues/318

As discussed internally, we will just build the tests for now, we will run those tests once the support is added. I tested it locally with CUDA 12.9 and 13.0 and both compiled & ran fine.

[github-actions]

🥳 CI Workflow Results

🟩 Finished in 12h 12m: Pass: 100%/261 | Total: 3d 16h | Max: 1h 41m | Hits: 99%/379106

See results here.