self to cancelled, and will emit the
Cancellable::cancelled signal. (However, see the warning about
race conditions in the documentation for that signal if you are
planning to connect to it.)
This function is thread-safe. In other words, you can safely call
it from a thread other than the one running the operation that was
None, this function returns immediately for convenience.
The convention within GIO is that cancelling an asynchronous
operation causes it to complete asynchronously. That is, if you
cancel the operation from the same thread in which it is running,
then the operation's
GAsyncReadyCallback will not be invoked until
the application returns to the main loop.
fn disconnect(&self, handler_id: c_ulong)
Disconnects a handler from a cancellable instance similar to
g_signal_handler_disconnect. Additionally, in the event that a
signal handler is currently running, this call will block until the
handler has finished. Calling this function from a
Cancellable::cancelled signal handler will therefore result in a
This avoids a race condition where a thread cancels at the
same time as the cancellable operation is finished and the
signal handler is removed. See
details on how to use this.
0 this function does
Handler id of the handler to be disconnected, or
Gets the file descriptor for a cancellable job. This can be used to
implement cancellable operations on Unix systems. The returned fd will
turn readable when
self is cancelled.
You are not supposed to read from the fd yourself, just check for
readable status. Reading to unset the readable status is done
After a successful return from this function, you should use
CancellableExt::release_fd to free up resources allocated for
the returned file descriptor.
A valid file descriptor.
-1 if the file descriptor
is not supported, or on errors.
fn is_cancelled(&self) -> bool
Checks if a cancellable job has been cancelled.
self is cancelled,
FALSE if called with
None or if item is not cancelled.
self off the cancellable stack (verifying that
is on the top of the stack).
self onto the cancellable stack. The current
cancellable can then be received using
This is useful when implementing cancellable operations in code that does not allow you to pass down the cancellable object.
This is typically called automatically by e.g.
so you rarely have to call this yourself.
Releases a resources previously allocated by
For compatibility reasons with older releases, calling this function
is not strictly required, the resources will be automatically freed
self is finalized. However, the
block scarce file descriptors until it is finalized if this function
is not called. This can cause the application to run out of file
descriptors when many
GCancellables are used at the same time.
fn set_error_if_cancelled(&self) -> Result<(), Error>
self is cancelled, sets the error to notify
that the operation was cancelled.
self was cancelled,
false if it was not
fn connect_cancelled<F: Fn(&Self) + Send + Sync + 'static>(
) -> SignalHandlerId
) -> SignalHandlerId
Emitted when the operation has been cancelled.
Can be used by implementations of cancellable operations. If the operation is cancelled from another thread, the signal will be emitted in the thread that cancelled the operation, not the thread that is running the operation.
Note that disconnecting from this signal (or any signal) in a
multi-threaded program is prone to race conditions. For instance
it is possible that a signal handler may be invoked even after
a call to
g_signal_handler_disconnect for that handler has
There is also a problem when cancellation happens right before connecting to the signal. If this happens the signal will unexpectedly not be emitted, and checking before connecting to the signal leaves a race condition where this is still happening.
In order to make it safe and easy to connect handlers there
are two helper functions:
CancellableExt::disconnect which protect against problems
An example of how to us this:
// Make sure we don't do unnecessary work if already cancelled if (g_cancellable_set_error_if_cancelled (cancellable, error)) return; // Set up all the data needed to be able to handle cancellation // of the operation my_data = my_data_new (...); id = 0; if (cancellable) id = g_cancellable_connect (cancellable, G_CALLBACK (cancelled_handler) data, NULL); // cancellable operation here... g_cancellable_disconnect (cancellable, id); // cancelled_handler is never called after this, it is now safe // to free the data my_data_free (my_data);
Note that the cancelled signal is emitted in the thread that the user cancelled from, which may be the main thread. So, the cancellable signal should not do something that can block.