Function: mem_import_from_shareable_handle

Applicable Products

Product	Supported (√/x)
Ascend 950PR	√
Ascend 950DT	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	√
	√

Description

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)

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 Values

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

Constraints

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

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 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: Virtual Memory Management