Handle file descriptor ownership and update documents for GDS

[gigony]

• Close the file descriptor if the file descriptor is owned by the object.
• Update GDS example in the Jupyter notebook.

from cucim.clara.filesystem import CuFileDriver
import cucim.clara.filesystem as fs
import os, cupy as cp, torch

# Create a CuPy array with size 10 (in bytes)
cp_arr = cp.ones(10, dtype=cp.uint8)
# Create a PyTorch array with size 10 (in bytes)
cuda0 = torch.device('cuda:0')
torch_arr = torch.ones(10, dtype=torch.uint8, device=cuda0)

# Using CuFileDriver
# (Opening a file with O_DIRECT flag is required for GDS)
fno = os.open("input.raw", os.O_RDONLY | os.O_DIRECT)
with CuFileDriver(fno) as fd:
  # Read 8 bytes starting from file offset 0 into buffer offset 2
  read_count = fd.pread(cp_arr, 8, 0, 2)
  # Read 10 bytes starting from file offset 3
  read_count = fd.pread(torch_arr, 10, 3)
os.close(fno)

# Another way of opening file with cuFile
with fs.open("output.raw", "w") as fd:
  # Write 10 bytes from cp_array to file starting from offset 5
  write_count = fd.pwrite(cp_arr, 10, 5)
  #############################################
  # <=== file descriptor created by fs.open() would be closed when exiting the scope
  #############################################

Fixes #233

[jakirkham]

Should we check fd too? Is there any risk it is undefined?

[gigony]

Thanks @jakirkham for the feedback!
Will update to make sure to check fd (fd >= 0. It's default value is -1)

[jakirkham]

Might be worth writing this to use a context manager (with statement). Just a thought 🙂

Edit: Though I guess we are illustrating this below

[gigony]

Thanks for the review!

This is to showcase the different ways to call the methods.
Here, I couldn't use with statement for os.close(fno) because Python's built-in os.open() returns int type and there is no context manager available.

[jakirkham]

We can always roll our own. Though maybe that's unnecessary for an example.

[gigony]

I am not sure if we want to provide such a wrapper in Python for the file descriptor(int).

with is supported by our API. the recommended way for using it (without close method) is described in the notebook and a description of the GDS reader page so don't need to change here?

https://github.com/NVIDIA/MagnumIO/tree/main/gds/readers/cucim-gds

with fs.open("output.raw", "w") as fd:
    # Write 10 bytes from cp_array to file starting from offset 5
    write_count = fd.pwrite(cp_arr, 10, 5)

[jakirkham]

Thanks Gigon! 😄 Generally looks good. Had a couple questions above 🙂

[jakirkham]

@gpucibot merge

[jakirkham]

Thanks Gigon! 😄