# gio.Cancellable

Thread-safe Operation Cancellation Stack.

## Synopsis

gio.Cancellable
gobject.GObject
gio.Cancellable
cancel
get_fd
is_cancelled
pop_current
push_current
reset
set_error_if_cancelled

    Functions

        gio.cancellable_get_current

## Ancestry

    +-- gobject.GObject
      +-- gio.Cancellable

## Description

The `gio.Cancellable` is a thread-safe operation cancellation stack used throughout GIO to allow for cancellation of synchronous and asynchronous operations.

## Constructor

                gio.Cancellable

Returns :

  a new `gio.Cancellable`.

Creates a new `gio.Cancellable` object.

Applications that want to start one or more operations that should be cancellable should create a `gio.Cancellable` and pass it to the operations.

One `gio.Cancellable` can be used in multiple consecutive operations, but not in multiple concurrent operations.

## Methods

### gio.Cancellable.cancel

                    cancel

The `cancel`() method will set cancellable to cancelled, and will emit the "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 passed the cancellable.

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.

### gio.Cancellable.get_fd

                    get_fd

Returns :

  A valid file descriptor. -1 if the file descriptor is not supported, or on errors.

The `get_fd`() method 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 cancellable is cancelled.

### gio.Cancellable.is_cancelled

                    is_cancelled

Returns :

  `True` if cancellable is cancelled, `False` if called with `None` or if item is not cancelled.

The `get_fd`() method 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 cancellable is cancelled.

### gio.Cancellable.pop_current

                    pop_current

The `pop_current`() method pops cancellable off the cancellable stack (verifying that cancellable is on the top of the stack).

### gio.Cancellable.push_current

                    push_current

The `push_current`() method pushes cancellable onto the cancellable stack. The current cancllable can then be recieved using `gio.cancellable_get_current`().

### gio.Cancellable.reset

                    reset

The `reset`() method resets cancellable to its uncancelled state.

### gio.Cancellable.set_error_if_cancelled

                    set_error_if_cancelled

Returns :

  `True` if cancellable was cancelled, `False` if it was not.

The `set_error_if_cancelled`() method, if the cancellable is cancelled, sets the error to notify that the operation was cancelled.

## Functions

### gio.cancellable_get_current

                    cancellable_get_current

Returns :

  A `gio.Cancellable` from the top of the stack, or `None` if the stack is empty.

The `cancellable_get_current`() function gets the top cancellable from the stack.