Add dpctl::memory::usm_memory constructor from external allocation

usm_memory(
    void *usm_ptr,
    size_t nbytes,
    sycl::queue &q,
    std::shared_ptr<void> shptr)

usm_ptr: Pointer to USM allocation

nbytes:  is the size of allocation in bytes

q : sycl::queue associated with this allocation in Python.

shptr: Smart pointer with custom deleter that deallocates
       the USM allocation.

Author: oleksandr-pavlyk

dpctl/apis/include/dpctl4pybind11.hpp

@@ -748,6 +748,64 @@ class usm_memory : public py::object
             throw py::error_already_set();
     }
 
+    /*! @brief Create usm_memory object from shared pointer that manages
+     *  lifetime of the USM allocation.
+     */
+    usm_memory(void *usm_ptr,
+               size_t nbytes,
+               const sycl::queue &q,
+               std::shared_ptr<void> shptr)
+    {
+        auto const &api = ::dpctl::detail::dpctl_capi::get();
+        DPCTLSyclUSMRef usm_ref = reinterpret_cast<DPCTLSyclUSMRef>(usm_ptr);
+        sycl::queue *q_ptr = new sycl::queue(q);
+        if (!q_ptr) {
+            throw std::bad_alloc();
+        }
+        DPCTLSyclQueueRef QRef = reinterpret_cast<DPCTLSyclQueueRef>(q_ptr);
+
+        auto vacuous_destructor = []() {};
+        py::object mock_owner = py::capsule(vacuous_destructor);
+
+        // create memory object owned by mock_owner, it is a new reference
+        PyObject *_memory =
+            api.Memory_Make_(usm_ref, nbytes, QRef, mock_owner.ptr());
+
+        bool is_ok =
+            (PyObject_TypeCheck(
+                 _memory, ::dpctl::detail::dpctl_capi::get().Py_MemoryType_) !=
+             0);
+
+        if (is_ok) {
+            std::shared_ptr<void> *opaque_ptr =
+                new std::shared_ptr<void>(shptr);
+            if (!opaque_ptr) {
+                Py_DECREF(_memory);
+                delete q_ptr;
+                throw std::bad_alloc();
+            }
+            Py_MemoryObject *memobj =
+                reinterpret_cast<Py_MemoryObject *>(_memory);
+            // replace mock_owner capsule as the owner
+            memobj->refobj = Py_None;
+            // set opaque ptr field, usm_memory now knowns that USM is managed
+            // by smart pointer
+            memobj->_opaque_ptr = reinterpret_cast<void *>(opaque_ptr);
+
+            // _memory will delete created copies of sycl::queue, and
+            // std::shared_ptr and the deleter of the shared_ptr<void> is
+            // supposed to free the USM allocation
+            m_ptr = _memory;
+        }
+        else {
+            delete q_ptr;
+            Py_DECREF(_memory);
+
+            throw std::runtime_error(
+                "Internal error: _Memory object created did not pass check");
+        }
+    }
+
     sycl::queue get_queue() const
     {
         Py_MemoryObject *mem_obj = reinterpret_cast<Py_MemoryObject *>(m_ptr);