Added free Python function as_usm_memory(obj)

[oleksandr-pavlyk]

Used the Cython static method from _Memmory.get_pointer_type in the added function,
as well as in the method get_usm_type.

Added docstrings.

In [1]: import dpctl, dpctl.memory as dpm, dpctl.memory._memory as dpm_m

In [2]: import dpctl.tensor as dpt

In [3]: X = dpt.usm_ndarray((4, 5))

In [4]: dpm_m.as_usm_memory(X)
Out[4]: <SYCL(TM) USM-device allocation of 160 bytes at 0xffffd556aa5f0000>

In [5]: X.usm_data
Out[5]: <SYCL(TM) USM-device allocation of 160 bytes at 0xffffd556aa5f0000>

In [6]: class Duck_USMAllocation:
   ...:     def __init__(self, buf, syclobj):
   ...:         self.buf_ = buf
   ...:         self.syclobj_ = syclobj
   ...:

In [7]: class Duck_USMAllocation:
   ...:     def __init__(self, buf, syclobj):
   ...:         self.buf_ = buf
   ...:         self.syclobj_ = syclobj
   ...:     @Property
   ...:     def __sycl_usm_array_interface__(self):
   ...:         iface = self.buf_.__sycl_usm_array_interface__
   ...:         iface['syclobj'] = self.syclobj_
   ...:         return iface
   ...:

In [8]: d = Duck_USMAllocation(X, X.sycl_device.filter_string)

In [9]: dpm_m.as_usm_memory(d)
Out[9]: <SYCL(TM) USM-device allocation of 160 bytes at 0xffffd556aa5f0000>

In [10]: Out[9].get_usm_type()
Out[10]: 'device'

[DrTodd13]

@oleksandr-pavlyk In the general case where you have sycl_usm_array_interface but don't know if it came from dpctl.memory, what should be the sycl_context that we pass?

[oleksandr-pavlyk]

@oleksandr-pavlyk In the general case where you have sycl_usm_array_interface but don't know if it came from dpctl.memory, what should be the sycl_context that we pass?

if hasattr(obj, '__sycl_usm_array_interface__'):
     sua_iface = getattr(obj, '__sycl_usm_array_interface__')
     ptr, writeable = sua_iface['data']
     syclobj = sua_iface['syclobj']
     usm_type = dpctl.memory._memory.get_usm_pointer_type(ptr, syclobj)

This will work if syclobj is either a dpctl.SyclContext, or dpctl.SyclQueue, but not for other possible values of syclobj entry in the interface. I will need to extend get_usm_pointer_type to process other possibilities too, in particular extracting queue/context from capsules without renaming them.

Really, I may be solving a wrong problem here. Maybe I just need a stand-alone function to convert an object exposing __sycl_usm_array_interface__ to one of the memory bytes containers: MemoryUSMShared, etc.

In other words, maybe all we need is to expose _Memory._cinit_other as a stand-alone function?

Which of these would be more useful?

[oleksandr-pavlyk]

@DrTodd13 I added dpctl.memory.create_MemoryUSM(sua_obj) which will create the allocation of the correct type:

In [1]: import dpctl, dpctl.memory as dpm, dpctl.memory._memory as dpm_m

In [2]: import dpctl.tensor as dpt

In [3]: X = dpt.usm_ndarray((4, 5))

In [4]: dpm_m.create_MemoryUSM(X)
Out[4]: <SYCL(TM) USM-device allocation of 160 bytes at 0xffffd556aa5f0000>

In [5]: X.usm_data
Out[5]: <SYCL(TM) USM-device allocation of 160 bytes at 0xffffd556aa5f0000>

In [6]: class Duck_USMAllocation:
   ...:     def __init__(self, buf, syclobj):
   ...:         self.buf_ = buf
   ...:         self.syclobj_ = syclobj
   ...:

In [7]: class Duck_USMAllocation:
   ...:     def __init__(self, buf, syclobj):
   ...:         self.buf_ = buf
   ...:         self.syclobj_ = syclobj
   ...:     @Property
   ...:     def __sycl_usm_array_interface__(self):
   ...:         iface = self.buf_.__sycl_usm_array_interface__
   ...:         iface['syclobj'] = self.syclobj_
   ...:         return iface
   ...:

In [8]: d = Duck_USMAllocation(X, X.sycl_device.filter_string)

In [9]: dpm_m.create_MemoryUSM(d)
Out[9]: <SYCL(TM) USM-device allocation of 160 bytes at 0xffffd556aa5f0000>

[oleksandr-pavlyk]

Feel free to suggest a better name than create_MemoryUSM.

[oleksandr-pavlyk]

Will rename dpctl.memory.create_MemoryUSM to dpctl.memory.as_usm_memory.

I will also remove dpctl.memory._memory.get_usm_pointer_type, since querying the type of USM allocation exposed by suai_obj can be queried as mem = dpctl.memory.as_usm_memory(obj); mem.get_usm_type().