Function: mem_import_from_shareable_handle

Applicability

Product	Supported
Atlas 350 Accelerator Card	√
Atlas A3 training product/Atlas A3 inference product	√
Atlas A2 training product/Atlas A2 inference product	√
Atlas training product	√
Atlas inference product	√
Atlas 200I/500 A2 inference product	√

Description

Obtains the information in shareable_handle in this process and returns the handle in this process to establish the mapping between virtual addresses and physical addresses in this process. This API can also be used to generate a handle for a specified device.

This API must work with other APIs to implement memory sharing. For details, see the description of acl.rt.mem_export_to_shareable_handle.

Prototype

C Prototype

aclError aclrtMemImportFromShareableHandle(uint64_t shareableHandle, int32_t deviceId, aclrtDrvMemHandle *handle)

Python Function

handle, ret = acl.rt.mem_import_from_shareable_handle(shareable_handle, device_id)

Parameters

Parameter	Description
shareable_handle	Int, shareable handle to be shared. The value must be the same as the value of shareable_handle exported from acl.rt.mem_export_to_shareable_handle.
deviceId	Int, ID of the device for which a handle is to be generated. Must be in the range of [0, Device count – 1]. Call acl.rt.get_device_count to obtain the device count.

Parameter

Description

shareable_handle

Int, shareable handle to be shared.

The value must be the same as the value of shareable_handle exported from acl.rt.mem_export_to_shareable_handle.

deviceId

Int, ID of the device for which a handle is to be generated.

Must be in the range of [0, Device count – 1]. Call acl.rt.get_device_count to obtain the device count.

Return Value

Return Value	Description
handle	Int, physical memory handle to the process.
ret	Int, error code. 0 on success; else, failure.

Restrictions

The Atlas 200I/500 A2 inference product in Ascend RC form does not support this API.

Before calling this API, ensure that the physical memory to be shared exists and cannot be released in advance.
Each handle must correspond to only one shareable handle in the same process. One-to-many or many-to-one mapping is not allowed.
The acl.rt.mem_import_from_shareable_handle and acl.rt.mem_export_to_shareable_handle APIs cannot be called in the same process. Only cross-process calling is supported.
The handle can be exported by calling acl.rt.mem_export_to_shareable_handle on a device, and then the handle on another device can be generated by calling this API.
After the memory is used, call acl.rt.free_physical to destroy the handle in a timely manner. The handle is destroyed only when all processes that call this API destroy shareable_handle.
Physical memory can be shared across devices.
Cross-device physical memory sharing supports only the following models and must be used together with the acl.rt.device_enable_peer_access API:

Atlas A3 training product/Atlas A3 inference product

Atlas A2 training product/Atlas A2 inference product

Atlas training product

Atlas inference product

Parent topic: Memory Management