aclrtMemExportToShareableHandle

Description

Export the physical memory handle obtained by the current process through the aclrtMallocPhysical API so that the physical memory can be shared with other processes.

This API must be used together with the following APIs to implement memory sharing. The following uses processes A and B as an example to describe the process of calling the physical memory sharing API between two processes.

1. In process A:
   1. Call aclrtMallocPhysical to allocate physical memory.

      Call aclrtMemGetAllocationGranularity to obtain the memory granularity, and then call aclrtMallocPhysical to allocate the physical memory. The size is aligned based on the obtained memory granularity to save memory.

      To allocate virtual memory with consecutive addresses and maximize the use of physical memory, you can call the aclrtReserveMemAddress and aclrtMapMem APIs to allocate virtual memory and establish the mapping between the virtual memory and physical memory. For details, see the description of the corresponding APIs.

   2. Call aclrtMemExportToShareableHandle to export the physical memory handle and output shareableHandle.
   3. Obtain the ID of process B and call aclrtMemSetPidToShareableHandle to add the ID of process B to the trustlist.
   4. Call aclrtFreePhysical to free the physical memory.

      All processes involving shared memory need to free the physical memory. The physical memory is released only after all processes involving memory sharing complete the release operation. After the physical memory is released, the referenced allocated memory is released back to the operating system. If the handle is used later, undefined behavior occurs.

2. In process B:
   1. Call aclrtDeviceGetBareTgid to obtain the ID of process B.

      This API has been adapted to the physical machine and VM scenarios when obtaining the process ID. You only need to call it to obtain the process ID and then configure other APIs to share the physical memory. If you do not call this API to obtain the process ID, an exception may occur when you use the process ID.

   2. Call aclrtMemImportFromShareableHandle to obtain the information in shareableHandle and return the handle to the process.

      Before calling aclrtMemImportFromShareableHandle, ensure that the physical memory to be shared exists and cannot be released in advance.

      To allocate virtual memory with consecutive addresses and maximize the use of physical memory addresses, you can call the aclrtReserveMemAddress and aclrtMapMem APIs to allocate virtual memory and establish the mapping between the virtual memory and physical memory. For details, see the description of the corresponding APIs.

   3. Call aclrtFreePhysical to free the physical memory.

Restrictions

• This API is not supported in the Ascend RC form.

  Currently, the following models support the Ascend RC form:

  • Atlas 200/300/500 Inference Product

• Only the physical memory on the device can be shared.
• Physical memory can be shared across devices.

  Cross-device physical memory sharing supports only the following models and must be used together with the aclrtDeviceEnablePeerAccess API:

  Atlas Training Series Product

• After the memory is used, call the aclrtFreePhysical API to release the physical memory in a timely manner to destroy the shareableHandle. If a process is still using shareableHandle, execute the destruction task after shareableHandle is used.
• There is a one-to-one mapping between handles and shareableHandles. In the same process, one-to-many or many-to-one mapping is not allowed. Otherwise, an error is reported. For example, if this API is repeatedly called to export data, an error is reported.
• Computing power allocation and grouping are not supported.

Prototype

aclError aclrtMemExportToShareableHandle(aclrtDrvMemHandle handle, aclrtMemHandleType handleType, uint64_t flags, uint64_t *shareableHandle)

Parameters

Returns

The value 0 indicates success, and other values indicate failure. For details, see aclError.