<?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-B11304D7-284A-5165-9565-F9CC4405E258" xml:lang="en"><title>How
to handle multiple asynchronous requests with a wait loop</title><shortdesc>This document describes how to handle multiple asynchronous requests
with a wait loop.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>A user thread which requires asynchronous services from more than one asynchronous
service provider uses a <i>wait loop</i>.</p>
<p>The allows a thread to issue as many request as are necessary and to handle
their completion. This construction forms the heart of almost all programs
that run under Symbian platform.</p>
<p>A typical program:</p>
<ul>
<li id="GUID-1D4A7780-CC16-5D02-A80E-C1DB031B62A1"><p>waits for any request
to complete by waiting on the thread’s request semaphore.</p> </li>
<li id="GUID-E5AEA62E-4C85-55CD-96DD-02E322D8E238"><p>scans in turn through
the asynchronous service providers for which a request is known to have been
issued and tests the relevant <codeph>TRequestStatus</codeph> for completion;
this is identified by a value other than <codeph>KRequestPending</codeph>.</p> </li>
<li id="GUID-3DA7B3E5-F5CB-5853-A29F-AE78E837B9F0"><p>when the first such
completed request has been identified, handles the completed request, possibly
by issuing a further request to an asynchronous service provider.</p> </li>
<li id="GUID-3A0108AF-7833-5D6C-88C0-6794EC8E0600"><p>goes back to the top
of the wait loop and waits again.</p> </li>
</ul>
<p>As an example, a terminal emulator must work with multiple requests simultaneously,
to deal with:</p>
<ul>
<li id="GUID-9979D5C7-72B1-53E8-BE4F-9D50ECE7AB6B"><p>key presses and user
input in general, to control the action of the program and put characters
on the emulated terminal screen and/or send them to the remote host</p> </li>
<li id="GUID-A091EA85-0697-5C6D-B843-4AB3BFC7ACEC"><p>received data and to
put characters on the emulated terminal screen or perform some control function.</p> </li>
<li id="GUID-CF81C9D8-E73F-5474-9127-10169285B30F"><p>the completion of any
transmit operation that was in progress; if successful, there may be more
data to transmit; if unsuccessful, some recovery action may be necessary</p> </li>
</ul>
<section id="GUID-30FFEA97-13E6-4269-ABD4-F5832E6D4C09"><title>Typical wait loop protocol</title> <p>The typical protocol
of a wait loop is:</p> <ul>
<li id="GUID-5810F6C5-0E37-53B0-AE99-5C9FF0295709"><p>The initialization phase
which issues the first asynchronous requests.</p> </li>
<li id="GUID-A4C2AAD7-EDDE-50B3-9B60-1DC0D7AD84A0"><p>Entry into the main
loop which waits for <i>any</i> of these requests to complete and then handles
the completion of one of them.</p> </li>
<li id="GUID-3119355F-B74D-5AB3-AC77-FD0206411F8F"><p>Detection of conditions
which imply termination of the program. Typically, one of the request completion
handlers sets appropriate flags and the wait loop terminates.</p> </li>
<li id="GUID-F4323300-37BB-5BCD-926C-E3EAB1F8018E"><p>Cleanup and final termination.</p> </li>
</ul> <codeblock id="GUID-D788337C-777D-533A-8832-8B4F669B005E" xml:space="preserve">initialize;
while (!finished())
    {
    wait for one or more requests to complete
    decide which request completed, and handle it
    }
terminate;</codeblock> <p>Note that only one request should be handled per
iteration of the loop. As part of the request completion handling process,
the request may be re-issued, or new requests issued or existing ones cancelled.
If the request cannot be identified, then the thread’s request semaphore has
been signalled invalidly; this is indicative of a programming error, a condition
is known as a stray signal - the wait loop should raise a panic.</p> </section>
<section id="GUID-1487241F-94B2-46BC-BEDD-7079E2ED968D"><title>Multiple outstanding requests</title> <p>In the case of a
terminal emulator which works with multiple outstanding requests, it must
be able to service whichever request completes and must be able to re-issue
a request, if necessary. For example, when one key has been processed, a request
for the next key must be issued.</p> <p>In the following example:</p> <ul>
<li id="GUID-E29D808F-332E-5859-8693-A94C76597BDC"><p>Call <codeph>Initialize()</codeph> to
initialize the emulator.</p> </li>
<li id="GUID-0DAA2678-04D4-584A-80C2-814457662D7B"><p>Implement <codeph>while()</codeph> to
handle events.</p> </li>
<li id="GUID-012E4941-8119-5047-A07B-FC3CB9A1A916"><p>Call the function <codeph>User::WaitForAnyRequest()</codeph> to
wait for any request to complete instead of waiting for a specific request
to complete.</p> </li>
<li id="GUID-412709CA-945B-547F-8D73-7E282BF02223"><p>Identify the particular
request that completed by checking the request status objects for a value
not equal to <codeph>KRequestPending</codeph>.</p> </li>
</ul> <codeblock id="GUID-99FCFA14-81E8-5594-A716-BDE02B237F44" xml:space="preserve">class TerminalEmulator
    {
public:
    void MainLoop(); // main loop
private:
    void Initialize(); // initialize
    void Terminate(); // clean up and terminate
    TBool IsFinished(); // whether finished
private:
    // request status objects
    TRequestStatus iKeyPressed; // whether key pressed
    ...                         // ...etc for other request status
    // handler functions
    void HandleKeyPressed();    // handle key pressed
    ...                         // ... etc other handlers
    ...
    };</codeblock> <codeblock id="GUID-1F3EBBF4-4141-5B4F-9B75-EFD3D820441B" xml:space="preserve">void TerminalEmulator::MainLoop()
    {
    Initialize();         // Initialize emulator
    while (!IsFinished()) // Handle events until finished
        {
        // wait for any request to complete
        User::WaitForAnyRequest();

        // identify and handle the completed request
        if (iKeyPressed!=KRequestPending)
            {
            HandleKeyPressed();
            }
        else if (iReceiveCompleted!=KRequestPending)
                {
                HandleReceiveCompleted();
                }
            else if (iTransmitCompleted!=KRequestPending)
                    {
                    HandleTransmitCompleted();
                    }
                else
                    {
                    // something we weren’t expecting
                    // panic !
                    }
        }
    }</codeblock> <p><b>Note</b> </p> <ul>
<li id="GUID-12F90A7C-738C-5A3D-B4BB-1604B9FA0534"><p>The request status is
set by the service provider to <codeph>KRequestPending</codeph> when a request
is issued. When the request is complete, the service provider uses an operating
system call to set the request status value to some other value — usually
a standard error code — and then to wake up the thread that requested
the service, causing its <codeph>WaitForAnyRequest()</codeph> to complete.</p> </li>
</ul> </section>
</conbody></concept>