1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

    12 <concept id="GUID-3A4947BD-1BEB-521C-BEDF-738064E83FE6" xml:lang="en"><title>Cancelling

    13 an asynchronous request</title><shortdesc>This document describes how to cancel an asynchronous request.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <p>Most asynchronous service providers support a cancel function. This allows

    15 an outstanding request to be cancelled before it is complete. </p>

    16 <p>A single thread that is waiting for a single asynchronous request to complete

    17 cannot cancel that request because the thread is asleep until it completes.

    18 However, when multiple requests are outstanding, the handling of a request

    19 completion may involve cancelling some or all of the other outstanding requests.</p>

    20 <p>In all cases, the correct user protocol for cancellation is:</p>

    21 <codeblock id="GUID-849238B9-205F-56ED-8958-B28F7604108C" xml:space="preserve">    // only cancel if we know that there is

    22     // an outstanding request

    23 if (requestIssued)

    24     {

    25         // Issue cancel to service provider

    26     provider.cancel();

    27 

    28         // Wait for it complete (it must complete)

    29     User::WaitForRequest(requestStatus);

    30 

    31         // Now note that request is no longer outstanding

    32     requestIssued=EFalse;

    33     }</codeblock>

    34 <section id="GUID-13C429B3-7FEF-4A2E-991C-767908F0AA5E"><title>Notes</title> <ul>

    35 <li id="GUID-A905DF5E-2AAA-59F8-B817-D10FBD947B9A"><p>A cancel should only

    36 be issued from the thread that issued the request.</p> </li>

    37 <li id="GUID-F4500BC1-6FDF-5D7D-8E62-641246AAE051"><p>It is convention that

    38 cancel functions provided by asynchronous service providers have <codeph>Cancel</codeph> somewhere

    39 in the name, but need not necessarily be called <codeph>Cancel()</codeph>.</p> </li>

    40 <li id="GUID-8383581F-B687-5BBE-8F7E-71EC4360A7E0"><p>An asynchronous service

    41 provider must make certain guarantees about cancellation:</p> <ul>

    42 <li id="GUID-0383D830-FB83-5707-9FE3-60360ACA9395"><p>it must complete quickly —

    43 otherwise, the <codeph>User::WaitForRequest()</codeph> above would take a

    44 long time to complete, and cause the program to become unresponsive</p> </li>

    45 <li id="GUID-0266E0CB-DC3B-597F-8662-B9AA4AAF35C3"><p>it must not violate

    46 the guarantee that each request produces precisely one signal</p> </li>

    47 </ul> </li>

    48 <li id="GUID-C7C67368-C52D-5830-98FC-DA0AD31917DC"><p>The service provider

    49 does not have to guarantee to cancel the actual request: it may already have

    50 completed — asynchronously, by definition — by the time the client

    51 thread issues the cancel.</p> </li>

    52 <li id="GUID-2290B823-B990-5A35-87DB-4BEC312C440E"><p>Although the cancel

    53 must return quickly, the service initiated by the request may not have completed.

    54 For instance, if data were requested from a network drive, it may not be returned

    55 until after the cancel. Because of the cancel, the service provider must discard

    56 such data.</p> </li>

    57 </ul> </section>

    58 </conbody></concept>