glib

Struct Source

source
pub struct Source { /* private fields */ }
Expand description

The GSource struct is an opaque data type representing an event source. The GSource struct is an opaque data type representing an event source.

GLib type: Shared boxed type with reference counted clone semantics.

Implementations§

source§

impl Source

source

pub fn as_ptr(&self) -> *mut GSource

Return the inner pointer to the underlying C value.

source

pub unsafe fn from_glib_ptr_borrow(ptr: &*mut GSource) -> &Self

Borrows the underlying C value.

source§

impl Source

source

pub fn add_child_source(&self, child_source: &Source)

Adds @child_source to @self as a “polled” source; when @self is added to a #GMainContext, @child_source will be automatically added with the same priority, when @child_source is triggered, it will cause @self to dispatch (in addition to calling its own callback), and when @self is destroyed, it will destroy @child_source as well. (@self will also still be dispatched if its own prepare/check functions indicate that it is ready.)

If you don’t need @child_source to do anything on its own when it triggers, you can call g_source_set_dummy_callback() on it to set a callback that does nothing (except return true if appropriate).

@self will hold a reference on @child_source while @child_source is attached to it.

This API is only intended to be used by implementations of #GSource. Do not call this API on a #GSource that you did not create.

§child_source

a second #GSource that @self should “poll” Adds @child_source to @self as a “polled” source; when @self is added to a #GMainContext, @child_source will be automatically added with the same priority, when @child_source is triggered, it will cause @self to dispatch (in addition to calling its own callback), and when @self is destroyed, it will destroy @child_source as well. (@self will also still be dispatched if its own prepare/check functions indicate that it is ready.)

If you don’t need @child_source to do anything on its own when it triggers, you can call g_source_set_dummy_callback() on it to set a callback that does nothing (except return true if appropriate).

@self will hold a reference on @child_source while @child_source is attached to it.

This API is only intended to be used by implementations of #GSource. Do not call this API on a #GSource that you did not create.

§child_source

a second #GSource that @self should “poll”

source

pub fn destroy(&self)

source

pub fn can_recurse(&self) -> bool

Checks whether a source is allowed to be called recursively. see g_source_set_can_recurse().

§Returns

whether recursion is allowed. Checks whether a source is allowed to be called recursively. see g_source_set_can_recurse().

§Returns

whether recursion is allowed.

source

pub fn context(&self) -> Option<MainContext>

Gets the #GMainContext with which the source is associated.

You can call this on a source that has been destroyed, provided that the #GMainContext it was attached to still exists (in which case it will return that #GMainContext). In particular, you can always call this function on the source returned from g_main_current_source(). But calling this function on a source whose #GMainContext has been destroyed is an error.

§Returns

the #GMainContext with which the source is associated, or None if the context has not yet been added to a source. Gets the #GMainContext with which the source is associated.

You can call this on a source that has been destroyed, provided that the #GMainContext it was attached to still exists (in which case it will return that #GMainContext). In particular, you can always call this function on the source returned from g_main_current_source(). But calling this function on a source whose #GMainContext has been destroyed is an error.

§Returns

the #GMainContext with which the source is associated, or None if the context has not yet been added to a source.

source

pub fn name(&self) -> Option<GString>

Gets a name for the source, used in debugging and profiling. The name may be #NULL if it has never been set with g_source_set_name().

§Returns

the name of the source Gets a name for the source, used in debugging and profiling. The name may be #NULL if it has never been set with g_source_set_name().

§Returns

the name of the source

source

pub fn priority(&self) -> i32

Gets the priority of a source.

§Returns

the priority of the source Gets the priority of a source.

§Returns

the priority of the source

source

pub fn ready_time(&self) -> i64

Gets the “ready time” of @self, as set by g_source_set_ready_time().

Any time before or equal to the current monotonic time (including 0) is an indication that the source will fire immediately.

§Returns

the monotonic ready time, -1 for “never” Gets the “ready time” of @self, as set by g_source_set_ready_time().

Any time before or equal to the current monotonic time (including 0) is an indication that the source will fire immediately.

§Returns

the monotonic ready time, -1 for “never”

source

pub fn time(&self) -> i64

Gets the time to be used when checking this source. The advantage of calling this function over calling g_get_monotonic_time() directly is that when checking multiple sources, GLib can cache a single value instead of having to repeatedly get the system monotonic time.

The time here is the system monotonic time, if available, or some other reasonable alternative otherwise. See g_get_monotonic_time().

§Returns

the monotonic time in microseconds Gets the time to be used when checking this source. The advantage of calling this function over calling g_get_monotonic_time() directly is that when checking multiple sources, GLib can cache a single value instead of having to repeatedly get the system monotonic time.

The time here is the system monotonic time, if available, or some other reasonable alternative otherwise. See g_get_monotonic_time().

§Returns

the monotonic time in microseconds

source

pub fn is_destroyed(&self) -> bool

Returns whether @self has been destroyed.

This is important when you operate upon your objects from within idle handlers, but may have freed the object before the dispatch of your idle handler.

⚠️ The following code is in C ⚠️

static gboolean
idle_callback (gpointer data)
{
  SomeWidget *self = data;

  g_mutex_lock (&self->idle_id_mutex);
  // do stuff with self
  self->idle_id = 0;
  g_mutex_unlock (&self->idle_id_mutex);

  return G_SOURCE_REMOVE;
}

static void
some_widget_do_stuff_later (SomeWidget *self)
{
  g_mutex_lock (&self->idle_id_mutex);
  self->idle_id = g_idle_add (idle_callback, self);
  g_mutex_unlock (&self->idle_id_mutex);
}

static void
some_widget_init (SomeWidget *self)
{
  g_mutex_init (&self->idle_id_mutex);

  // ...
}

static void
some_widget_finalize (GObject *object)
{
  SomeWidget *self = SOME_WIDGET (object);

  if (self->idle_id)
    g_source_remove (self->idle_id);

  g_mutex_clear (&self->idle_id_mutex);

  G_OBJECT_CLASS (parent_class)->finalize (object);
}

This will fail in a multi-threaded application if the widget is destroyed before the idle handler fires due to the use after free in the callback. A solution, to this particular problem, is to check to if the source has already been destroy within the callback.

⚠️ The following code is in C ⚠️

static gboolean
idle_callback (gpointer data)
{
  SomeWidget *self = data;

  g_mutex_lock (&self->idle_id_mutex);
  if (!g_source_is_destroyed (g_main_current_source ()))
    {
      // do stuff with self
    }
  g_mutex_unlock (&self->idle_id_mutex);

  return FALSE;
}

Calls to this function from a thread other than the one acquired by the #GMainContext the #GSource is attached to are typically redundant, as the source could be destroyed immediately after this function returns. However, once a source is destroyed it cannot be un-destroyed, so this function can be used for opportunistic checks from any thread.

§Returns

true if the source has been destroyed Returns whether @self has been destroyed.

This is important when you operate upon your objects from within idle handlers, but may have freed the object before the dispatch of your idle handler.

⚠️ The following code is in C ⚠️

static gboolean
idle_callback (gpointer data)
{
  SomeWidget *self = data;

  g_mutex_lock (&self->idle_id_mutex);
  // do stuff with self
  self->idle_id = 0;
  g_mutex_unlock (&self->idle_id_mutex);

  return G_SOURCE_REMOVE;
}

static void
some_widget_do_stuff_later (SomeWidget *self)
{
  g_mutex_lock (&self->idle_id_mutex);
  self->idle_id = g_idle_add (idle_callback, self);
  g_mutex_unlock (&self->idle_id_mutex);
}

static void
some_widget_init (SomeWidget *self)
{
  g_mutex_init (&self->idle_id_mutex);

  // ...
}

static void
some_widget_finalize (GObject *object)
{
  SomeWidget *self = SOME_WIDGET (object);

  if (self->idle_id)
    g_source_remove (self->idle_id);

  g_mutex_clear (&self->idle_id_mutex);

  G_OBJECT_CLASS (parent_class)->finalize (object);
}

This will fail in a multi-threaded application if the widget is destroyed before the idle handler fires due to the use after free in the callback. A solution, to this particular problem, is to check to if the source has already been destroy within the callback.

⚠️ The following code is in C ⚠️

static gboolean
idle_callback (gpointer data)
{
  SomeWidget *self = data;

  g_mutex_lock (&self->idle_id_mutex);
  if (!g_source_is_destroyed (g_main_current_source ()))
    {
      // do stuff with self
    }
  g_mutex_unlock (&self->idle_id_mutex);

  return FALSE;
}

Calls to this function from a thread other than the one acquired by the #GMainContext the #GSource is attached to are typically redundant, as the source could be destroyed immediately after this function returns. However, once a source is destroyed it cannot be un-destroyed, so this function can be used for opportunistic checks from any thread.

§Returns

true if the source has been destroyed

source

pub fn remove_child_source(&self, child_source: &Source)

Detaches @child_source from @self and destroys it.

This API is only intended to be used by implementations of #GSource. Do not call this API on a #GSource that you did not create.

§child_source

a #GSource previously passed to g_source_add_child_source(). Detaches @child_source from @self and destroys it.

This API is only intended to be used by implementations of #GSource. Do not call this API on a #GSource that you did not create.

§child_source

a #GSource previously passed to g_source_add_child_source().

source§

impl Source

source

pub fn attach(&self, context: Option<&MainContext>) -> SourceId

Trait Implementations§

source§

impl Clone for Source

source§

fn clone(&self) -> Self

Makes a clone of this shared reference.

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

1.6.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for Source

source§

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

Formats the value using the given formatter. Read more
source§

impl From<Source> for Value

source§

fn from(s: Source) -> Self

Converts to this type from the input type.
source§

impl HasParamSpec for Source

source§

type ParamSpec = ParamSpecBoxed

source§

type SetValue = Source

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

type BuilderFn = fn(_: &str) -> ParamSpecBoxedBuilder<'_, Source>

source§

fn param_spec_builder() -> Self::BuilderFn

source§

impl Hash for Source

source§

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

Feeds this value into the given Hasher. Read more
1.6.0 · source§

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

Feeds a slice of this type into the given Hasher. Read more
source§

impl Ord for Source

source§

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

This method returns an Ordering between self and other. Read more
1.21.0 · source§

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

Compares and returns the maximum of two values. Read more
1.21.0 · source§

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

Compares and returns the minimum of two values. Read more
1.50.0 · source§

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

Restrict a value to a certain interval. Read more
source§

impl PartialEq for Source

source§

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

Tests for self and other values to be equal, and is used by ==.
1.6.0 · source§

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

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

impl PartialOrd for Source

source§

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

This method returns an ordering between self and other values if one exists. Read more
1.6.0 · source§

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

Tests less than (for self and other) and is used by the < operator. Read more
1.6.0 · source§

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

Tests less than or equal to (for self and other) and is used by the <= operator. Read more
1.6.0 · source§

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

Tests greater than (for self and other) and is used by the > operator. Read more
1.6.0 · source§

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

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

impl StaticType for Source

source§

fn static_type() -> Type

Returns the type identifier of Self.
source§

impl Eq for Source

source§

impl Send for Source

source§

impl StructuralPartialEq for Source

source§

impl Sync for Source

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> FromGlibContainerAsVec<<T as GlibPtrDefault>::GlibType, *const GList> for T

source§

impl<T> FromGlibContainerAsVec<<T as GlibPtrDefault>::GlibType, *const GPtrArray> for T

source§

impl<T> FromGlibContainerAsVec<<T as GlibPtrDefault>::GlibType, *const GSList> for T

source§

impl<T> FromGlibContainerAsVec<<T as GlibPtrDefault>::GlibType, *mut GList> for T

source§

impl<T> FromGlibContainerAsVec<<T as GlibPtrDefault>::GlibType, *mut GPtrArray> for T

source§

impl<T> FromGlibContainerAsVec<<T as GlibPtrDefault>::GlibType, *mut GSList> for T

source§

impl<T> FromGlibPtrArrayContainerAsVec<<T as GlibPtrDefault>::GlibType, *const GList> for T

source§

impl<T> FromGlibPtrArrayContainerAsVec<<T as GlibPtrDefault>::GlibType, *const GPtrArray> for T

source§

impl<T> FromGlibPtrArrayContainerAsVec<<T as GlibPtrDefault>::GlibType, *const GSList> for T

source§

impl<T> FromGlibPtrArrayContainerAsVec<<T as GlibPtrDefault>::GlibType, *mut GList> for T

source§

impl<T> FromGlibPtrArrayContainerAsVec<<T as GlibPtrDefault>::GlibType, *mut GPtrArray> for T

source§

impl<T> FromGlibPtrArrayContainerAsVec<<T as GlibPtrDefault>::GlibType, *mut GSList> for T

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> IntoClosureReturnValue for T
where T: Into<Value>,

source§

impl<T> Property for T
where T: HasParamSpec,

source§

type Value = T

source§

impl<T> PropertyGet for T
where T: HasParamSpec,

source§

type Value = T

source§

fn get<R, F>(&self, f: F) -> R
where F: Fn(&<T as PropertyGet>::Value) -> R,

source§

impl<T> StaticTypeExt for T
where T: StaticType,

source§

fn ensure_type()

Ensures that the type has been registered with the type system.
source§

impl<T> ToOwned for T
where T: Clone,

source§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T> ToSendValue for T
where T: Send + ToValue + ?Sized,

source§

fn to_send_value(&self) -> SendValue

Returns a SendValue clone of self.
source§

impl<T> TransparentType for T

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

source§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T> TryFromClosureReturnValue for T
where T: for<'a> FromValue<'a> + StaticType + 'static,

source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<'a, T, C, E> FromValueOptional<'a> for T
where T: FromValue<'a, Checker = C>, C: ValueTypeChecker<Error = ValueTypeMismatchOrNoneError<E>>, E: Error + Send + 'static,