Struct Cancellable

pub struct Cancellable { /* private fields */ }

GCancellable allows operations to be cancelled.

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

Signals

cancelled

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 already returned.

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: g_cancellable_connect() and g_cancellable_disconnect() which protect against problems like this.

An example of how to us this:

⚠️ The following code is in C ⚠️

    // 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.

Implements

CancellableExt, [trait@glib::ObjectExt], CancellableExtManual

GLib type: GObject with reference counted clone semantics.

Implementations

impl Cancellable

pub const NONE: Option<&'static Cancellable> = None

pub fn new() -> Cancellable

Creates a new #GCancellable object.

Applications that want to start one or more operations that should be cancellable should create a #GCancellable and pass it to the operations.

One #GCancellable can be used in multiple consecutive operations or in multiple concurrent operations.

Returns

a #GCancellable.

pub fn current() -> Option<Cancellable>

Gets the top cancellable from the stack.

Returns

a #GCancellable from the top of the stack, or None if the stack is empty.

Trait Implementations

impl Clone for Cancellable

fn clone(&self) -> Self

Makes a clone of this shared reference.

This increments the strong reference count of the object. Dropping the object will decrement it again.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Cancellable

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Cancellable

fn default() -> Self

Returns the “default value” for a type.

impl HasParamSpec for Cancellable

type ParamSpec = ParamSpecObject

type SetValue = Cancellable

Preferred value to be used as setter for the associated ParamSpec.

type BuilderFn = fn(_: &str) -> ParamSpecObjectBuilder<'_, Cancellable>

fn param_spec_builder() -> Self::BuilderFn

impl Hash for Cancellable

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Hashes the memory address of this object.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Cancellable

fn cmp(&self, other: &Self) -> Ordering

Comparison for two GObjects.

Compares the memory addresses of the provided objects.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl ParentClassIs for Cancellable

type Parent = Object

impl<OT: ObjectType> PartialEq<OT> for Cancellable

fn eq(&self, other: &OT) -> bool

Equality for two GObjects.

Two GObjects are equal if their memory addresses are equal.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<OT: ObjectType> PartialOrd<OT> for Cancellable

fn partial_cmp(&self, other: &OT) -> Option<Ordering>

Partial comparison for two GObjects.

Compares the memory addresses of the provided objects.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for Cancellable

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for Cancellable

impl Send for Cancellable

impl Sync for Cancellable