|
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-C3AC4F95-67E9-5F1D-8CF0-F6B209319EC0" xml:lang="en"><title>What |
|
13 asynchronous service providers do</title><shortdesc>This document describes the purpose of asynchronous service providers.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <section id="GUID-3653AC36-81A4-4207-B174-1EBBCCA43E65"><title>Request functions and the request status</title> <p>An asynchronous |
|
15 service provider offers one or more <i>request functions</i>. </p> <p>Only |
|
16 one request on a service provider can be outstanding at any one time. A <i>request |
|
17 function</i> is one that takes a <codeph>TRequestStatus&</codeph> parameter |
|
18 or, in rare cases, a <codeph>TRequestStatus*</codeph> parameter.</p> <p>When |
|
19 a request function is called (or when the asynchronous service provider is |
|
20 constructed, opened or initialized), the handle of the client thread is noted |
|
21 by the asynchronous service provider, so it knows which thread made the request. |
|
22 A panic results if any other thread tries to use the asynchronous service |
|
23 provider — for instance, to call its cancel function, or to issue another |
|
24 request — since the client of an asynchronous service provider is assumed |
|
25 to be a single thread.</p> <p>The asynchronous service provider's request |
|
26 function:</p> <ul> |
|
27 <li id="GUID-DB0F6F6D-DC43-568F-B675-5EEEE1EB0E2F"><p>first sets the value |
|
28 of the passed <codeph>TRequestStatus</codeph> to <codeph>KRequestPending</codeph> </p> </li> |
|
29 <li id="GUID-A1745B0E-E46F-5541-BE62-CE7B23864767"><p>then initiates the request, |
|
30 which may complete any time later.</p> </li> |
|
31 </ul> <p>There are several typical cases:</p> <ul> |
|
32 <li id="GUID-E82051C8-83B0-5263-8359-40A3DB47D694"><p>the request completes |
|
33 normally some time after the request function has returned.</p> </li> |
|
34 <li id="GUID-C061E1FA-2B91-5A1F-B2CA-9FA2AD668412"><p>the request completes |
|
35 during the request function call, either because the request completes immediately, |
|
36 or because of an error such as bad parameters meaning that the request cannot |
|
37 even be initiated.</p> </li> |
|
38 <li id="GUID-EEDCAE49-4BAE-52FE-B33D-0AD288671624"><p>some other type of abnormal |
|
39 completion such as cancellation, which can occur either during the request |
|
40 function call or later.</p> </li> |
|
41 </ul> </section> |
|
42 <section id="GUID-73EEA278-054A-4393-8264-5DBD2DB88A4A"><title>Thread request semaphore</title> <p>When a request completes, |
|
43 the client thread’s request semaphore is signalled to indicate completion.</p> <p>Each |
|
44 thread has a single request semaphore. A thread which uses asynchronous services |
|
45 must have a program whose main loop waits on the thread’s request semaphore |
|
46 for any outstanding request to complete.</p> <p>When any request completes, |
|
47 the thread program must identify which of the outstanding requests has completed. |
|
48 It does this by checking the <codeph>TRequestStatus</codeph> object associated |
|
49 with each outstanding request and, if its value is not <codeph>KRequestPending</codeph>, |
|
50 the program knows that the request is complete and can handle the completion |
|
51 of that request.</p> </section> |
|
52 <section id="GUID-D1A4AE55-CD75-43E5-AD4D-AA5BDDEF7FD5"><title>Cancel functions</title> <p>All asynchronous service providers |
|
53 provide one or more <i>cancel functions</i>, which cancel any outstanding |
|
54 request.</p> <p>Because of the asynchronous nature of requests, a cancel function |
|
55 may be called after the request has actually completed. For this reason, a |
|
56 cancel function should be viewed as a request for <i>early completion</i>. |
|
57 If you issue a cancel, the asynchronous service provider may complete the |
|
58 request abnormally by posting <codeph>KErrCancel</codeph> in the request status |
|
59 object, or it may complete the request normally by posting an appropriate |
|
60 completion code.</p> </section> |
|
61 <section id="GUID-7C8829A7-9FDB-46FA-A9E2-692E90398371"><title>See also</title> <p><xref href="GUID-E6D9F8CA-F293-5CE6-93C4-5FEC5EBCB2E9.dita">Asynchronous |
|
62 service provider's responsibilities</xref>.</p> </section> |
|
63 </conbody></concept> |