Whole document tree
| GnomeVFS - Filesystem Abstraction library | |||
|---|---|---|---|
| <<< Previous Page | Home | Up | Next Page >>> |
Handling cancellation
As VFS operations might be very long, especially in the case of transient errors (such as a network server that has gone down), the GNOME Virtual File System Library provides a standard way for handling cancellation of VFS operations.
The GnomeVFSCancellation object
The object that encapsulates this functionality is GnomeVFSCancellation. Most implementation functions get a pointer to such an object, and are expected to use this object to recognize when an operation should be interrupted.
The most simple way to check for a cancellation request is to poll the object with gnome_vfs_cancellation_check():
gboolean gnome_vfs_cancellation_check (GnomeVFSCancellation *cancellation); |
This function will return a nonzero value if the current operation should be cancelled.
Notice that cancellation is an asynchronous operation that might happen outside your function, in parallel with the code that you are writing. For example, in the case of threads, the request will be set in the master thread; in the case of slave CORBA-driven processes, the request will be activated by a Unix signal. So you can expect a cancellation request to happen (and consequently be signalled in GnomeVFSCancellation) at any time.
For this reason, you should be calling this function periodically, whenever you are going to perform several iterations of the same task, or execute a single expensive task. When the function returns a nonzero value, the correct way to react is:
Clean things up so that the result of the operations that have been performed are all cancelled.
>Return the GNOME_VFS_ERROR_CANCELLED error code.
But there are some other situations in which you want to be able to interrupt a I/O operation when a cancellation request is performed. In such cases, polling is not a viable option.
For this reason, GnomeVFSCancellation provides an alternative way of sending notifications, using a file descriptor. To use this feature, you should use the following function:
gint gnome_vfs_cancellation_get_fd (GnomeVFSCancellation *cancellation); |
When this function is called, it will return an open file descriptor, which is the read-side of a pipe. The pipe will be given a character from the write side as soon as a cancellation request is sent. For this reason, you can check for a cancellation by using the select() system call: as soon as select reports that some data is available on the file descriptor, you know that a cancellation is being requested.
For example, if you are reading from a file descriptor and you want to check for a pending cancellation at the same time, you can set up selectfor checking if data is available on both the cancellation file descriptor and the file descriptor you are reading from.
Dealing with EINTR
In order to maximize the chance of cancelling an operation immediately, the GNOME Virtual File System can sends a signal to the asynchronous thread or process. This does not happen on all the systems and setups, though.
The result of this is that, if a process is in the middle of a Unix system call while receiving this signal, the system call might be interrupted and return a EINTR error.
For this reason, when you receive EINTR you should check if a cancellation request is pending, using gnome_vfs_cancellation_check() on the GnomeVFSCancellation object that the implementation function received:
If a cancellation is indeed pending (gnome_vfs_cancellation_check() returns a nonzero value), you should cancel the operation, cleaning up all the effects, and return GNOME_VFS_ERROR_INTERRUPTED or GNOME_VFS_ERROR_CANCELLED
Otherwise, retry the system call as you would normally do.
| <<< Previous Page | Home | Up | Next Page >>> |
| Implementing an access method in practice | Basic guidelines for writing a module | ||