I/O Cancellation

To prevent application failure, or the appearance of application failure due to an unresponsive I/O operation, Windows Vista® provides an updated API for I/O cancellation. This topic provides guidance about when to use this feature, which native functions are contained in this API, and which I/O operations can be cancelled using this feature. For more information, see "Canceling Pending I/O Operations" in the Windows SDK.

General Guidelines

Support for I/O cancellation requires either the use of asynchronous (non-blocking) I/O functions, such as CreateFile, or multithreaded applications, so that the synchronous I/O operation and I/O cancellation can be located in separate threads.

A good general rule is that operations requiring more than two seconds to complete should provide feedback to the user in the form of progress or other status indicators, and implement I/O cancellation. This is particularly true for an application's user interface (UI). No UI threads should be blocked by any I/O, wait, or other operations (even lengthy compute operations) for a perceptible amount of time. Again, multithreading is recommended.

As long as underlying file system or device driver requests are guaranteed to complete within a few seconds, support for I/O cancellation does not imply nor require that they be cancelable. However, unless the behavior of lower level software is well known, it is important not to make assumptions about access latencies. Operations such as remote accesses can unpredictably take unexpectedly long times.

It is important that applications also handle the case where a cancellation operation does not succeed. This can happen for a number of reasons, including drivers that do not honor Microsoft's I/O completion specification, race conditions in accessing a resource, or interactions with other applications. Code modules not actually part of an application's code can still directly or indirectly cause applications to become non-responsive. Examples of such modules include:

  • Dialog boxes, including Common Dialog Boxes

  • DLLs and run-time library functions

  • Both out-of-process applications and servers—such as COM servers, RPC servers, and spoolers—and in-process plug-ins and extensions

Such modules should provide an API to support cancellation requests from the top-level application, including the passing of cancellation requests through to other dependent modules.

It may also be useful for these modules to implement their own I/O cancellation mechanism for long-running operations. If the module provides a user interface, it should provide a cancellation UI.

I/O Cancellation APIs

For Windows Vista, only Win32® interfaces exist for supporting I/O cancellation. .NET Framework 3.0 applications can access this functionality through interoperability support in the Windows SDK. For more information, see the Interoperability & Migration section of this document.

The three Win32 I/O cancellation functions are defined in Winbase.h (accessed through Windows.h) and their implementations are found in Kernel32.lib. Any application handling I/O cancellation should listen for a WM_CANCEL event. The three functions are:

  • CancelIo—available in both Windows XP and Windows Server 2003, cancels all pending, asynchronous (opened with FILE_FLAG_OVERLAPPED) I/O operations issued by the calling thread for a specified file handle. Its signature is BOOL CancelIo(HANDLE hFile);The function does not cancel synchronous I/O operations, operations in other threads, nor can it cancel a specific I/O operation. For more information, see CancelIo in the Windows SDK.

  • CancelIoEx—new to Windows Vista, marks as canceled all pending asynchronous I/O or designated pending I/O for the specified file handle in the current process, not just the current thread. Its signature is BOOL CancelIoEx( HANDLE hFile, LPOVERLAPPED lpOverlapped); CancelIloEx can support selective cancellation of I/O operations on a given file handle.

    By supplying a non-null pointer (lpOverlapped) to an OVERLAPPED structure, only I/O requests issued with the supplied overlapped structure are marked as canceled. If the pointer is null, all I/O requests for the file handle are canceled.

    CancelIoEx does not wait for all the canceled operations to complete, and it is therefore necessary to wait for the ultimate completion of the canceled I/O operation and check its return code. If the I/O operation was properly canceled, it will return a status of ERROR_OPERATION_ABORTED.

  • CancelSynchronousloEx—new to Windows Vista, marks as canceled all pending synchronous I/O operations issued by the specified thread. Its signature is BOOL CancelSynchronousIo(HANDLE hThread); CancelSynchronousloEx does not wait for all the canceled operations to complete. It is therefore necessary to check the completion status of the I/O operations to be canceled.

Cancelable File I/O APIs

Not all APIs support cancellation. The following list indicates which is and which is not.

API

Cancelable

Comment

AreFileApisANSI

n/a

n/a

CheckNameLegalDOS8Dot3

n/a

n/a

CloseHandle

n/a

n/a

CopyFile

No

Use CopyFileEx.

CopyFileEx

Yes

Can cancel with progress routine by returning PROGRESS_CANCEL or can pass in variable pbCancel and set to TRUE elsewhere to cause cancellation.

CreateFile

Yes

n/a

CreateHardLink

Yes

n/a

DeleteFile

Yes

n/a

FindClose

Yes

n/a

FindFirstFile

Yes

n/a

FindFirstFileEx

Yes

n/a

FindFirstStreamW

Yes

n/a

FindNextFile

Yes

n/a

FindNextStreamW

Yes

n/a

GetBinaryType

Yes

n/a

GetCompressedFileSize

Yes

n/a

GetFileAttributes

Yes

n/a

GetFileAttributesEx

Yes

n/a

GetFileInformationByHandle

Yes

n/a

GetFileSize

Yes

n/a

GetFileSizeEx

Yes

n/a

GetFileTime

Yes

n/a

GetFileType

Yes

n/a

GetFullPathName

Yes

n/a

GetLongPathName

Yes

n/a

GetShortPathName

Yes

n/a

GetTempFileName

Yes

n/a

GetTempPath

Yes

n/a

MoveFile

No

Use MoveFileWithProgress.

MoveFileEx

No

Use MoveFileWithProgress.

MoveFileWithProgress

Yes

Progress routine can return PROGRESS_STOP or PROGRESS_CANCEL to stop the operation. Does not support Boolean cancel like CopyFile.

ReplaceFile

No

Does a handful of stream copies which are not cancelable.

SearchPath

Yes

n/a

SetFileApisToANSI

n/a

n/a

SetFileApisToOEM

n/a

n/a

SetFileAttributes

Yes

n/a

SetFileSecurity

Yes

n/a

SetFileShortName

Yes

n/a

SetFileName

Yes

n/a

SetFileTime

Yes

n/a

SetFileValidData

Yes

n/a

CreateIoCompletionPort

n/a

n/a

FlushFileBuffers

Yes

n/a

GetQueuedCompletionStatus

Yes

User-mode wait can be interrupted.

LockFile

Yes

n/a

LockFileEx

Yes

n/a

PostQueuedCompletionStatus

n/a

n/a

ReadFile

Yes

n/a

ReadFileEx

Yes

n/a

ReadFileScatter

Yes

n/a

SetEndOfFile

Yes

n/a

SetFilePointer

Yes

n/a

SetFilePointerEx

Yes

n/a

UnlockFile

Yes

n/a

UnlockFileEx

Yes

n/a

WriteFileGather

Yes

n/a

CreateFileMapping

Yes

n/a

FlushViewOfFile

Yes

n/a

MapViewOfFile

Yes

n/a

MapViewOfFileEx

Yes

n/a

OpenFileMapping

n/a

n/a

UnmapViewOfFile

n/a

n/a

WalkTree

Partially

WalkTree itself does not support cancellation, but it uses an enumeration callback function to do the "walking". This callback function could be used to support cancellation and stop enumeration if canceled.

DeleteTree

No

Callback function for WalkTree that does not support cancellation.

Community Additions

Show:
© 2014 Microsoft