Asynchronous SendReceive() in an Agent

Storing a local heap copy of transient data

If the agent plug-in cannot guarantee that a variable to be passed in the asynchronous SendReceive() call still be in scope when the agent server comes to access and use it, then the agent plug-in must store a local heap copy of the data and pass this in the call instead. It is the responsibility of the agent plug-in to maintain this heap memory and delete it when appropriate. Depending on how and when the agent server uses the memory, it may be safe to delete the memory after the asynchronous call has been accepted, or not until the asynchronous request has completed.

For example, an agent plug-in could implement the ContentAccess::CAgentManager::NotifyStatusChange() API as illustrated below. Note that for this API, the agent plug-in can make no assumption about the scope of the descriptor passed to aURI.

void CTestAgentManager::NotifyStatusChange(const TDesC& aURI, TEventMask aMask, TRequestStatus& aStatus)
        {       
        HBufC* uri = aURI.Alloc();
        if(uri)
                {
                // store the heap variable in a local array
                iAsyncDataArray.Append(uri); // takes ownership of uri
                SendReceive(EManagerNotifyStatusChange, TIpcArgs(uri,aMask),aStatus);           
                }
        }

Following the asynchronous call with a synchronous call

Alternatively, the agent plug-in can use the variables that are in scope at the time of the asynchronous SendReceive() call if it makes a synchronous SendReceive() call afterwards, within the same function scope, as illustrated below. The synchronous message can be a 'no operation' in the agent server.

void CTestAgentManager::NotifyStatusChange(const TDesC& aURI, TEventMask aMask, TRequestStatus& aStatus)
        {       
        SendReceive(EManagerNotifyStatusChange, TIpcArgs(&aURI,aMask),aStatus);
        // this call doesn't have to be immediately after the asynchronous call, but within this function
        SendReceive(ENoOp,TIpcArgs(NULL));
        } 

The synchronous call causes the message queue to be flushed into the agent server before the thread returns from the function and unwinds the call stack. The intention is that the agent server only completes the second (synchronous) message after receiving and doing initial processing of the first (asynchronous) message, which may include, for example, reading the uri descriptor.

However, an obvious disadvantage of this pattern is that it incurs a second IPC call and so may degrade performance.

Moreover, there are several caveats which must hold true in order for the pattern to work:

• The kernel delivers messages in the order that they are sent (this is currently true).

• The agent server is guaranteed to finish processing the first message before completing the second message. This requires understanding of the agent server implementation.

• After initial processing of the first (asynchronous) message, the agent server does not need to access the memory supplied in the message again. This requires understanding of the agent server implementation.

• The synchronous call is a request that has no effect on the state of the agent server - a 'no operation' may or may not be possible.

For these reasons, this pattern must only be used as a last resort - for example, if the agent plug-in cannot store member data in its class for compatibility reasons.