diff -r ebc84c812384 -r 46218c8b8afa Symbian3/PDK/Source/GUID-3A4947BD-1BEB-521C-BEDF-738064E83FE6.dita --- a/Symbian3/PDK/Source/GUID-3A4947BD-1BEB-521C-BEDF-738064E83FE6.dita Thu Mar 11 15:24:26 2010 +0000 +++ b/Symbian3/PDK/Source/GUID-3A4947BD-1BEB-521C-BEDF-738064E83FE6.dita Thu Mar 11 18:02:22 2010 +0000 @@ -1,58 +1,58 @@ - - - - - -Cancelling -an asynchronous requestThis document describes how to cancel an asynchronous request. -

Most asynchronous service providers support a cancel function. This allows -an outstanding request to be cancelled before it is complete.

-

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.

-

In all cases, the correct user protocol for cancellation is:

- // 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; - } -
Notes
    -

  • A cancel should only -be issued from the thread that issued the request.

    • -

  • It is convention that -cancel functions provided by asynchronous service providers have Cancel somewhere -in the name, but need not necessarily be called Cancel().

    • -

  • An asynchronous service -provider must make certain guarantees about cancellation:

      -

    • it must complete quickly — -otherwise, the User::WaitForRequest() above would take a -long time to complete, and cause the program to become unresponsive

      • -

    • it must not violate -the guarantee that each request produces precisely one signal

      • -
    • -

  • 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.

    • -

  • 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.

    • -
+ + + + + +Cancelling +an asynchronous requestThis document describes how to cancel an asynchronous request. +

Most asynchronous service providers support a cancel function. This allows +an outstanding request to be cancelled before it is complete.

+

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.

+

In all cases, the correct user protocol for cancellation is:

+ // 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; + } +
Notes
    +

  • A cancel should only +be issued from the thread that issued the request.

    • +

  • It is convention that +cancel functions provided by asynchronous service providers have Cancel somewhere +in the name, but need not necessarily be called Cancel().

    • +

  • An asynchronous service +provider must make certain guarantees about cancellation:

      +

    • it must complete quickly — +otherwise, the User::WaitForRequest() above would take a +long time to complete, and cause the program to become unresponsive

      • +

    • it must not violate +the guarantee that each request produces precisely one signal

      • +
    • +

  • 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.

    • +

  • 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.

    • +
 \ No newline at end of file