Function: mem_import_from_shareable_handle

Applicability

Product	Supported (√/x)
Atlas A3 training products/Atlas A3 inference products	√
Atlas A2 training products/Atlas A2 inference products	√
Atlas training products	√
Atlas inference products	√
Atlas 200I/500 A2 inference products	√

Function Usage

Obtains the information in the 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)

Parameter Description

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 Description

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

Restrictions

Atlas 200I/500 A2 inference products: This API is not supported in Ascend RC form.

Before calling this API, ensure that the physical memory to be shared exists and cannot be freed 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. The handle is destroyed only when all processes that call this API destroy the 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 products/Atlas A3 inference products

Atlas A2 training products/Atlas A2 inference products

Atlas training products

Atlas inference products

Parent topic: Memory Management