Cancellation of AIO Operations

When one or more requests are asynchronously processed it might be useful in some situations to cancel a selected operation, e.g., if it becomes obvious that the written data is not anymore accurate and would have to be overwritten soon. As an example assume an application, which writes data in files in a situation where new incoming data would have to be written in a file which will be updated by an enqueued request. The POSIX AIO implementation provides such a function but this function is not capable to force the cancellation of the request. It is up to the implementation to decide whether it is possible to cancel the operation or not. Therefore using this function is merely a hint.

Function: int aio_cancel (int fildes, struct aiocb *aiocbp)

The aio_cancel function can be used to cancel one or more outstanding requests. If the aiocbp parameter is NULL the function tries to cancel all outstanding requests which would process the file descriptor fildes (i.e.,, whose aio_fildes member is fildes). If aiocbp is not NULL the very specific request pointed to by aiocbp is tried to be cancelled.

For requests which were successfully cancelled the normal notification about the termination of the request should take place. I.e., depending on the struct sigevent object which controls this, nothing happens, a signal is sent or a thread is started. If the request cannot be cancelled it terminates the usual way after performing te operation.

After a request is successfully cancelled a call to aio_error with a reference to this request as the parameter will return ECANCELED and a call to aio_return will return @math{-1}. If the request wasn't cancelled and is still running the error status is still EINPROGRESS.

The return value of the function is AIO_CANCELED if there were requests which haven't terminated and which successfully were cancelled. If there is one or more request left which couldn't be cancelled the return value is AIO_NOTCANCELED. In this case aio_error must be used to find out which of the perhaps multiple requests (in aiocbp is NULL) wasn't successfully cancelled. If all requests already terminated at the time aio_cancel is called the return value is AIO_ALLDONE.

If an error occurred during the execution of aio_cancel the function returns @math{-1} and sets errno to one of the following values.

EBADF

The file descriptor fildes is not valid.

ENOSYS

aio_cancel is not implemented.

When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is in fact aio_cancel64 since the LFS interface transparently replaces the normal implementation.

Function: int aio_cancel64 (int fildes, struct aiocb *aiocbp)

This function is similar to aio_cancel with the only difference that the argument is a reference to a variable of type struct aiocb64.

When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is available under the name aio_cancel and so transparently replaces the interface for small files on 32 bit machines.

Go to the first, previous, next, last section, table of contents.