--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-B7B7F611-BCA0-498F-BEC1-16B276F680D5.dita Wed Mar 31 11:11:55 2010 +0100
@@ -0,0 +1,200 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
+<!-- This component and the accompanying materials are made available under the terms of the License
+"Eclipse Public License v1.0" which accompanies this distribution,
+and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
+<!-- Initial Contributors:
+ Nokia Corporation - initial contribution.
+Contributors:
+-->
+<!DOCTYPE concept
+ PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept id="GUID-B7B7F611-BCA0-498F-BEC1-16B276F680D5" xml:lang="en"><title>Calling
+Symbian Asynchronous APIs in Applications</title><shortdesc/><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p>When porting an P.I.P.S.-based C or C++ application on top of Symbian C++,
+the developer may need to make use of Symbian asynchronous APIs. If asynchronous
+APIs are made use of in an P.I.P.S. application, the application needs to
+wait for the completion of the asynchronous API. This can be done in two ways:
+ <ul>
+<li><p>Wait for the asynchronous request to complete. This can be achieved
+by making use of <codeph>User::WaitForRequest(iStatus)</codeph>; where <codeph>iStatus</codeph> is
+the <codeph>TRequestSemaphore</codeph> used by the asynchronous API. </p></li>
+<li><p>Call the asynchronous API in an active object, run an active scheduler,
+and let the active scheduler wait for the asynchronous operation to complete. </p></li>
+</ul></p>
+<p><b>The problems with these approaches are: </b></p>
+<p>The open source application would get blocked till the asynchronous operation
+completes in the first approach. In the second approach, the active scheduler
+would be running in a wait loop, checking for asynchronous API completion.
+Even in this case, the P.I.P.S. application would not be able to perform any
+other operations outside the active scheduler framework.</p>
+<p>The asynchronous APIs could be called in a separate process, and the P.I.P.S.
+application could communicate with this process by making use of the client/server
+framework of Symbian or by making use of other P.I.P.S. IPC mechanisms. However,
+making a different process for calling asynchronous APIs might pose a performance
+hit.</p>
+<p>One of the ways to solve these problems is to call the asynchronous APIs
+in a separate thread.</p>
+<p><b>Example:</b></p>
+<codeblock xml:space="preserve">class CActiveThread: public CActive
+{
+public:
+
+ enum TState
+ {
+ EInitialized = 0x0,
+ EDoFirst = 0x1,
+ EDoSecond = 0x2,
+ EDoThird = 0x4,
+ ECompleted = 0x8
+ };
+
+ // thread startup routine
+ static int StartMyThread(void* thisptr);
+ // leaving variant of the thread startup routine
+ static int StartMyThreadL(void* thisptr);
+ // Helper function to start the thread
+ void StartThread();
+ // Do Function
+ void DoFunction(TState aState );
+
+ // CActive Functions
+ void RunL();
+ void DoCancel();
+
+ // Constructors and destructor
+ static CActiveThread* NewL();
+ CActiveThread ();
+ void ConstructL();
+ ~ CActiveThread();
+
+private:
+
+ // Active Scheduler
+ CActiveSchedulerWait *iWait;
+ // Command/State
+ TInt iState;
+ TRequestStatus iThreadExitWait;
+ // my thread handle
+ RThread iActiveThread;
+ sem_t iSem;
+};
+</codeblock>
+<p>The <codeph>StartThread</codeph> member function of <xref href="GUID-7968C6B4-3247-335A-845B-3D196E2EB14C.dita"><apiname>CActiveThread</apiname></xref> creates
+the thread which runs the active scheduler. <codeph>StartMyThread</codeph> is
+the entry point function for the new thread that starts an active scheduler
+and sets up the clean up stack. To call an asynchronous function, <codeph>DoFunction()</codeph> needs
+to be called with the corresponding state. The parent thread signals the child
+thread using the child thread’s thread request semaphore. When the thread
+request semaphore is signaled, the child thread wakes up, calls the corresponding
+asynchronous API in <codeph>RunL()</codeph> based on the <codeph>iState</codeph> and
+again goes back to the active scheduler wait loop. </p>
+<p>To synchronize between the parent thread and the child thread, a semaphore
+can be used as shown in the following code snippet. </p>
+<codeblock xml:space="preserve">CActiveThread* CActiveThread::NewL()
+{
+CActiveThread* self = new (ELeave) CActiveThread();
+self->ConstructL();
+return self;
+}
+
+CActiveThread::CActiveThread():CActive(EPriorityStandard),iState(EInitialized)
+{
+}
+
+void CActiveThread::ConstructL()
+{
+// semaphore for Synching
+sem_init(&iSem,0,0);
+}
+
+void CActiveThread::StartThread()
+{
+//Create Thread
+TInt err = iActiveThread.Create( KThreadName(),&CActiveThread::StartMyThread, KDefaultStackSize, NULL, (TAny*)this );
+iActiveThread.Logon( iThreadExitWait );
+iActiveThread.Resume();
+sem_wait(&iSem );
+}
+
+int CActiveThread::StartMyThread( void* ptr )
+{
+CActiveScheduler* scheduler = new (ELeave) CActiveScheduler();
+CActiveScheduler::Install(scheduler);
+CTrapCleanup* pCleanup = CTrapCleanup::New();
+TRAPD(err, StartMyThreadL(ptr));
+}
+
+int CActiveThread::StartMyThreadL( void* ptr )
+{
+CActiveThread *thisptr = (CActiveThread*)ptr;
+CActiveScheduler::Add(thisptr);
+thisptr->iWait = new (ELeave) CActiveSchedulerWait();
+thisptr->iState = EInitialized;
+thisptr->iStatus = KRequestPending;
+thisptr->SetActive();
+sem_post( &(thisptr->iSem ));
+thisptr->iWait->Start();
+}
+
+ void CActiveThread::RunL()
+ {
+ switch ( iState )
+ {
+ case EDoFirst:
+ // Call 1st asynchronous function
+ break;
+
+ case EDoSecond:
+ // Call 2nd asynchronous function
+ break;
+
+ case EDoThird:
+ // Call 3rd asynchronous function
+ break;
+
+ case ECompleted:
+ iWait->AsyncStop();
+ return;
+ }
+
+iStatus = KRequestPending;
+SetActive();
+// wake up the waiting thread
+sem_post(&iSem);
+}
+
+void CActiveThread::DoCancel()
+{
+}
+
+void CActiveThread::DoFunction(TState aState )
+{
+iState = aState;
+TRequestStatus *reqPtr = &iStatus;
+iActiveThread.RequestComplete( reqPtr, KErrNone );
+sem_wait(&iSem);
+}
+
+CActiveThread::~CActiveThread()
+{
+if ( iState != EInitialized )
+ {
+ iState = ECompleted;
+ TRequestStatus *reqPtr = &iStatus;
+ iActiveThread.RequestComplete( reqPtr, KErrNone );
+ User::WaitForRequest( iThreadExitWait);
+ }
+sem_destroy(&iSem);
+}
+</codeblock>
+<p><b>Using <xref href="GUID-7968C6B4-3247-335A-845B-3D196E2EB14C.dita"><apiname>CActiveThread</apiname></xref>:</b></p>
+<codeblock xml:space="preserve">iMyAsyncIf = CActiveThread::NewL();
+iMyAsyncIf->StartThread();
+iMyAsyncIf->DoFunction(EDoFirst);
+</codeblock>
+<p><b>Limitations: </b></p>
+<p>In this approach, only the parent thread communicates with the child thread.
+There is no way for the child thread to communicate with the parent thread.
+ </p>
+</conbody></concept>
\ No newline at end of file