Rename CallAsyncWithCallback to CallAsyncWithCompleteCallback

Also add a comment that the function needs to be released by registering
a callback and setting the complete event.

Author: agners

src/controller/python/chip/ChipDeviceCtrl.py

@@ -186,7 +186,7 @@ def __init__(self, deviceProxy: ctypes.c_void_p, dmLib=None):
     def __del__(self):
         if (self._dmLib is not None and hasattr(builtins, 'chipStack') and builtins.chipStack is not None):
             # This destructor is called from any threading context, including on the Matter threading context.
-            # So, we cannot call chipStack.Call or chipStack.CallAsyncWithCallback which waits for the posted work to
+            # So, we cannot call chipStack.Call or chipStack.CallAsyncWithCompleteCallback which waits for the posted work to
             # actually be executed. Instead, we just post/schedule the work and move on.
             builtins.chipStack.PostTaskOnChipThread(lambda: self._dmLib.pychip_FreeOperationalDeviceProxy(self._deviceProxy))
 
@@ -447,7 +447,7 @@ def ConnectBLE(self, discriminator, setupPinCode, nodeid) -> PyChipError:
 
         self.state = DCState.COMMISSIONING
         self._enablePairingCompeleteCallback(True)
-        self._ChipStack.CallAsyncWithCallback(
+        self._ChipStack.CallAsyncWithCompleteCallback(
             lambda: self._dmLib.pychip_DeviceController_ConnectBLE(
                 self.devCtrl, discriminator, setupPinCode, nodeid)
         ).raise_on_error()
@@ -459,7 +459,7 @@ def ConnectBLE(self, discriminator, setupPinCode, nodeid) -> PyChipError:
     def UnpairDevice(self, nodeid: int):
         self.CheckIsActive()
 
-        return self._ChipStack.CallAsyncWithCallback(
+        return self._ChipStack.CallAsyncWithCompleteCallback(
             lambda: self._dmLib.pychip_DeviceController_UnpairDevice(
                 self.devCtrl, nodeid, self.cbHandleDeviceUnpairCompleteFunct)
         ).raise_on_error()
@@ -498,7 +498,7 @@ def EstablishPASESessionBLE(self, setupPinCode: int, discriminator: int, nodeid:
 
         self.state = DCState.RENDEZVOUS_ONGOING
         self._enablePairingCompeleteCallback(True)
-        return self._ChipStack.CallAsyncWithCallback(
+        return self._ChipStack.CallAsyncWithCompleteCallback(
             lambda: self._dmLib.pychip_DeviceController_EstablishPASESessionBLE(
                 self.devCtrl, setupPinCode, discriminator, nodeid)
         )
@@ -508,7 +508,7 @@ def EstablishPASESessionIP(self, ipaddr: str, setupPinCode: int, nodeid: int, po
 
         self.state = DCState.RENDEZVOUS_ONGOING
         self._enablePairingCompeleteCallback(True)
-        return self._ChipStack.CallAsyncWithCallback(
+        return self._ChipStack.CallAsyncWithCompleteCallback(
             lambda: self._dmLib.pychip_DeviceController_EstablishPASESessionIP(
                 self.devCtrl, ipaddr.encode("utf-8"), setupPinCode, nodeid, port)
         )
@@ -518,7 +518,7 @@ def EstablishPASESession(self, setUpCode: str, nodeid: int):
 
         self.state = DCState.RENDEZVOUS_ONGOING
         self._enablePairingCompeleteCallback(True)
-        return self._ChipStack.CallAsyncWithCallback(
+        return self._ChipStack.CallAsyncWithCompleteCallback(
             lambda: self._dmLib.pychip_DeviceController_EstablishPASESession(
                 self.devCtrl, setUpCode.encode("utf-8"), nodeid)
         )
@@ -737,7 +737,7 @@ def OpenCommissioningWindow(self, nodeid: int, timeout: int, iteration: int,
             Returns CommissioningParameters
         '''
         self.CheckIsActive()
-        self._ChipStack.CallAsyncWithCallback(
+        self._ChipStack.CallAsyncWithCompleteCallback(
             lambda: self._dmLib.pychip_DeviceController_OpenCommissioningWindow(
                 self.devCtrl, self.pairingDelegate, nodeid, timeout, iteration, discriminator, option)
         ).raise_on_error()
@@ -1898,7 +1898,7 @@ def Commission(self, nodeid) -> PyChipError:
         self._ChipStack.commissioningCompleteEvent.clear()
         self.state = DCState.COMMISSIONING
 
-        self._ChipStack.CallAsyncWithCallback(
+        self._ChipStack.CallAsyncWithCompleteCallback(
             lambda: self._dmLib.pychip_DeviceController_Commission(
                 self.devCtrl, nodeid)
         )
@@ -2014,7 +2014,7 @@ def CommissionOnNetwork(self, nodeId: int, setupPinCode: int,
         self._ChipStack.commissioningCompleteEvent.clear()
 
         self._enablePairingCompeleteCallback(True)
-        self._ChipStack.CallAsyncWithCallback(
+        self._ChipStack.CallAsyncWithCompleteCallback(
             lambda: self._dmLib.pychip_DeviceController_OnNetworkCommission(
                 self.devCtrl, self.pairingDelegate, nodeId, setupPinCode, int(filterType), str(filter).encode("utf-8") + b"\x00" if filter is not None else None, discoveryTimeoutMsec)
         )
@@ -2038,7 +2038,7 @@ def CommissionWithCode(self, setupPayload: str, nodeid: int, discoveryType: Disc
         self._ChipStack.commissioningCompleteEvent.clear()
 
         self._enablePairingCompeleteCallback(True)
-        self._ChipStack.CallAsyncWithCallback(
+        self._ChipStack.CallAsyncWithCompleteCallback(
             lambda: self._dmLib.pychip_DeviceController_ConnectWithCode(
                 self.devCtrl, setupPayload, nodeid, discoveryType.value)
         )
@@ -2058,7 +2058,7 @@ def CommissionIP(self, ipaddr: str, setupPinCode: int, nodeid: int) -> PyChipErr
         self._ChipStack.commissioningCompleteEvent.clear()
 
         self._enablePairingCompeleteCallback(True)
-        self._ChipStack.CallAsyncWithCallback(
+        self._ChipStack.CallAsyncWithCompleteCallback(
             lambda: self._dmLib.pychip_DeviceController_ConnectIP(
                 self.devCtrl, ipaddr.encode("utf-8"), setupPinCode, nodeid)
         )
@@ -2072,7 +2072,7 @@ def IssueNOCChain(self, csr: Clusters.OperationalCredentials.Commands.CSRRespons
         The NOC chain will be provided in TLV cert format."""
         self.CheckIsActive()
 
-        return self._ChipStack.CallAsyncWithCallback(
+        return self._ChipStack.CallAsyncWithCompleteCallback(
             lambda: self._dmLib.pychip_DeviceController_IssueNOCChain(
                 self.devCtrl, py_object(self), csr.NOCSRElements, len(csr.NOCSRElements), nodeId)
         )

src/controller/python/chip/ChipStack.py

@@ -413,10 +413,11 @@ async def CallAsync(self, callFunct, timeoutMs: int = None):
 
         return await asyncio.wait_for(callObj.future, timeoutMs / 1000 if timeoutMs else None)
 
-    def CallAsyncWithCallback(self, callFunct):
+    def CallAsyncWithCompleteCallback(self, callFunct):
         '''Run a Python function on CHIP stack, and wait for the application specific response.
         This function is a wrapper of PostTaskOnChipThread, which includes some handling of application specific logics.
         Calling this function on CHIP on CHIP mainloop thread will cause deadlock.
+        Make sure to register the necessary callbacks which release the function by setting the completeEvent.
         '''
         # throw error if op in progress
         self.callbackRes = None