Symbian3/PDK/Source/GUID-3A4947BD-1BEB-521C-BEDF-738064E83FE6.dita
changeset 5 f345bda72bc4
parent 3 46218c8b8afa
child 14 578be2adaf3e
--- a/Symbian3/PDK/Source/GUID-3A4947BD-1BEB-521C-BEDF-738064E83FE6.dita	Tue Mar 30 11:42:04 2010 +0100
+++ b/Symbian3/PDK/Source/GUID-3A4947BD-1BEB-521C-BEDF-738064E83FE6.dita	Tue Mar 30 11:56:28 2010 +0100
@@ -1,58 +1,58 @@
-<?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-3A4947BD-1BEB-521C-BEDF-738064E83FE6" xml:lang="en"><title>Cancelling
-an asynchronous request</title><shortdesc>This document describes how to cancel an asynchronous request.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
-<p>Most asynchronous service providers support a cancel function. This allows
-an outstanding request to be cancelled before it is complete. </p>
-<p>A single thread that is waiting for a single asynchronous request to complete
-cannot cancel that request because the thread is asleep until it completes.
-However, when multiple requests are outstanding, the handling of a request
-completion may involve cancelling some or all of the other outstanding requests.</p>
-<p>In all cases, the correct user protocol for cancellation is:</p>
-<codeblock id="GUID-849238B9-205F-56ED-8958-B28F7604108C" xml:space="preserve">    // only cancel if we know that there is
-    // an outstanding request
-if (requestIssued)
-    {
-        // Issue cancel to service provider
-    provider.cancel();
-
-        // Wait for it complete (it must complete)
-    User::WaitForRequest(requestStatus);
-
-        // Now note that request is no longer outstanding
-    requestIssued=EFalse;
-    }</codeblock>
-<section id="GUID-13C429B3-7FEF-4A2E-991C-767908F0AA5E"><title>Notes</title> <ul>
-<li id="GUID-A905DF5E-2AAA-59F8-B817-D10FBD947B9A"><p>A cancel should only
-be issued from the thread that issued the request.</p> </li>
-<li id="GUID-F4500BC1-6FDF-5D7D-8E62-641246AAE051"><p>It is convention that
-cancel functions provided by asynchronous service providers have <codeph>Cancel</codeph> somewhere
-in the name, but need not necessarily be called <codeph>Cancel()</codeph>.</p> </li>
-<li id="GUID-8383581F-B687-5BBE-8F7E-71EC4360A7E0"><p>An asynchronous service
-provider must make certain guarantees about cancellation:</p> <ul>
-<li id="GUID-0383D830-FB83-5707-9FE3-60360ACA9395"><p>it must complete quickly —
-otherwise, the <codeph>User::WaitForRequest()</codeph> above would take a
-long time to complete, and cause the program to become unresponsive</p> </li>
-<li id="GUID-0266E0CB-DC3B-597F-8662-B9AA4AAF35C3"><p>it must not violate
-the guarantee that each request produces precisely one signal</p> </li>
-</ul> </li>
-<li id="GUID-C7C67368-C52D-5830-98FC-DA0AD31917DC"><p>The service provider
-does not have to guarantee to cancel the actual request: it may already have
-completed — asynchronously, by definition — by the time the client
-thread issues the cancel.</p> </li>
-<li id="GUID-2290B823-B990-5A35-87DB-4BEC312C440E"><p>Although the cancel
-must return quickly, the service initiated by the request may not have completed.
-For instance, if data were requested from a network drive, it may not be returned
-until after the cancel. Because of the cancel, the service provider must discard
-such data.</p> </li>
-</ul> </section>
+<?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-3A4947BD-1BEB-521C-BEDF-738064E83FE6" xml:lang="en"><title>Cancelling
+an asynchronous request</title><shortdesc>This document describes how to cancel an asynchronous request.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p>Most asynchronous service providers support a cancel function. This allows
+an outstanding request to be cancelled before it is complete. </p>
+<p>A single thread that is waiting for a single asynchronous request to complete
+cannot cancel that request because the thread is asleep until it completes.
+However, when multiple requests are outstanding, the handling of a request
+completion may involve cancelling some or all of the other outstanding requests.</p>
+<p>In all cases, the correct user protocol for cancellation is:</p>
+<codeblock id="GUID-849238B9-205F-56ED-8958-B28F7604108C" xml:space="preserve">    // only cancel if we know that there is
+    // an outstanding request
+if (requestIssued)
+    {
+        // Issue cancel to service provider
+    provider.cancel();
+
+        // Wait for it complete (it must complete)
+    User::WaitForRequest(requestStatus);
+
+        // Now note that request is no longer outstanding
+    requestIssued=EFalse;
+    }</codeblock>
+<section id="GUID-13C429B3-7FEF-4A2E-991C-767908F0AA5E"><title>Notes</title> <ul>
+<li id="GUID-A905DF5E-2AAA-59F8-B817-D10FBD947B9A"><p>A cancel should only
+be issued from the thread that issued the request.</p> </li>
+<li id="GUID-F4500BC1-6FDF-5D7D-8E62-641246AAE051"><p>It is convention that
+cancel functions provided by asynchronous service providers have <codeph>Cancel</codeph> somewhere
+in the name, but need not necessarily be called <codeph>Cancel()</codeph>.</p> </li>
+<li id="GUID-8383581F-B687-5BBE-8F7E-71EC4360A7E0"><p>An asynchronous service
+provider must make certain guarantees about cancellation:</p> <ul>
+<li id="GUID-0383D830-FB83-5707-9FE3-60360ACA9395"><p>it must complete quickly —
+otherwise, the <codeph>User::WaitForRequest()</codeph> above would take a
+long time to complete, and cause the program to become unresponsive</p> </li>
+<li id="GUID-0266E0CB-DC3B-597F-8662-B9AA4AAF35C3"><p>it must not violate
+the guarantee that each request produces precisely one signal</p> </li>
+</ul> </li>
+<li id="GUID-C7C67368-C52D-5830-98FC-DA0AD31917DC"><p>The service provider
+does not have to guarantee to cancel the actual request: it may already have
+completed — asynchronously, by definition — by the time the client
+thread issues the cancel.</p> </li>
+<li id="GUID-2290B823-B990-5A35-87DB-4BEC312C440E"><p>Although the cancel
+must return quickly, the service initiated by the request may not have completed.
+For instance, if data were requested from a network drive, it may not be returned
+until after the cancel. Because of the cancel, the service provider must discard
+such data.</p> </li>
+</ul> </section>
 </conbody></concept>
\ No newline at end of file