Struct gio::Cancellable

#[repr(transparent)]
pub struct Cancellable { /* private fields */ }

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, glib::ObjectExt, CancellableExtManual

Implementations

impl Cancellable

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

pub fn new() -> Cancellable

Creates a new Cancellable object.

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

One Cancellable can be used in multiple consecutive operations or in multiple concurrent operations.

Returns

a Cancellable.

pub fn current() -> Option<Cancellable>

Gets the top cancellable from the stack.

Returns

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

Trait Implementations

impl Clone for Cancellable

fn clone(&self) -> Self

Returns a copy of the value.

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 Display for Cancellable

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

Formats the value using the given formatter.

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,

Feeds this value into the given Hasher.

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

This method returns an Ordering between self and other.

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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere Self: Sized + PartialOrd<Self>,

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

This method tests for self and other values to be equal, and is used by ==.

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

This method 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>

This method returns an ordering between self and other values if one exists.

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method 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