Struct glib::MainContext [−][src]
pub struct MainContext(_);
Expand description
The GMainContext
struct is an opaque data
type representing a set of sources to be handled in a main loop.
Implementations
Dispatches all pending sources.
You must have successfully acquired the context with
acquire()
before you may call this function.
Determines whether this thread holds the (recursive)
ownership of this MainContext
. This is useful to
know before waiting on another thread that may be
blocking to get ownership of self
.
Returns
true
if current thread is owner of self
.
Runs a single iteration for the given main loop. This involves
checking to see if any event sources are ready to be processed,
then if no events sources are ready and may_block
is true
, waiting
for a source to become ready, then dispatching the highest priority
events sources that are ready. Otherwise, if may_block
is false
sources are not waited to become ready, only those highest priority
events sources will be dispatched (if any), that are ready at this
given moment without further waiting.
Note that even when may_block
is true
, it is still possible for
iteration()
to return false
, since the wait may
be interrupted for other reasons than an event source becoming ready.
may_block
whether the call may block.
Returns
true
if events were dispatched.
Pops self
off the thread-default context stack (verifying that
it was on the top of the stack).
Acquires self
and sets it as the thread-default context for the
current thread. This will cause certain asynchronous operations
(such as most [gio][gio]-based I/O) which are
started in this thread to run under self
and deliver their
results to its main loop, rather than running under the global
default context in the main thread. Note that calling this function
changes the context returned by thread_default()
,
not the one returned by default()
, so it does not affect
the context used by functions like g_idle_add()
.
Normally you would call this function shortly after creating a new
thread, passing it a MainContext
which will be run by a
MainLoop
in that thread, to set a new default context for all
async operations in that thread. In this case you may not need to
ever call pop_thread_default()
, assuming you want the
new MainContext
to be the default for the whole lifecycle of the
thread.
If you don’t have control over how the new thread was created (e.g.
in the new thread isn’t newly created, or if the thread life
cycle is managed by a GThreadPool
), it is always suggested to wrap
the logic that needs to use the new MainContext
inside a
push_thread_default()
/ pop_thread_default()
pair, otherwise threads that are re-used will end up never explicitly
releasing the MainContext
reference they hold.
In some cases you may want to schedule a single operation in a
non-default context, or temporarily use a non-default context in
the main thread. In that case, you can wrap the call to the
asynchronous operation inside a
push_thread_default()
/
pop_thread_default()
pair, but it is up to you to
ensure that no other asynchronous operations accidentally get
started while the non-default context is active.
Beware that libraries that predate this function may not correctly
handle being used from a thread with a thread-default context. Eg,
see g_file_supports_thread_contexts()
.
If self
is currently blocking in iteration()
waiting for a source to become ready, cause it to stop blocking
and return. Otherwise, cause the next invocation of
iteration()
to return without blocking.
This API is useful for low-level control over MainContext
; for
example, integrating it with main loop implementations such as
MainLoop
.
Another related use for this function is when implementing a main loop with a termination condition, computed from multiple threads:
⚠️ The following code is in C ⚠️
#define NUM_TASKS 10
static gint tasks_remaining = NUM_TASKS; // (atomic)
...
while (g_atomic_int_get (&tasks_remaining) != 0)
g_main_context_iteration (NULL, TRUE);
Then in a thread:
⚠️ The following code is in C ⚠️
perform_work();
if (g_atomic_int_dec_and_test (&tasks_remaining))
g_main_context_wakeup (NULL);
Returns the global default main context. This is the main context
used for main loop functions when a main loop is not explicitly
specified, and corresponds to the “main” main loop. See also
thread_default()
.
Returns
the global default main context.
Gets the thread-default MainContext
for this thread. Asynchronous
operations that want to be able to be run in contexts other than
the default one should call this method or
ref_thread_default()
to get a MainContext
to add
their GSources
to. (Note that even in single-threaded
programs applications may sometimes want to temporarily push a
non-default context, so it is not safe to assume that this will
always return None
if you are running in the default thread.)
If you need to hold a reference on the context, use
ref_thread_default()
instead.
Returns
the thread-default MainContext
, or
None
if the thread-default context is the global default context.
Gets the thread-default MainContext
for this thread, as with
thread_default()
, but also adds a reference to
it with g_main_context_ref()
. In addition, unlike
thread_default()
, if the thread-default context
is the global default context, this will return that MainContext
(with a ref added to it) rather than returning None
.
Returns
the thread-default MainContext
. Unref
with g_main_context_unref()
when you are done with it.
Prepares to poll sources within a main loop. The resulting information for polling is determined by calling g_main_context_query ().
You must have successfully acquired the context with
acquire()
before you may call this function.
Returns
true
if some source is ready to be dispatched
prior to polling.
priority
location to store priority of highest priority source already ready.
Finds a Source
given a pair of context and ID.
It is a programmer error to attempt to look up a non-existent source.
More specifically: source IDs can be reissued after a source has been
destroyed and therefore it is never valid to use this function with a
source ID which may have already been removed. An example is when
scheduling an idle to run in another thread with g_idle_add()
: the
idle may already have run and been removed by the time this function
is called on its (now invalid) source ID. This source ID may have
been reissued, leading to the operation being performed against the
wrong source.
source_id
the source ID, as returned by g_source_get_id()
.
Returns
the Source
Invokes func
on the main context.
Invokes a function in such a way that self
is owned during the
invocation of function
.
If self
is None
then the global default main context — as
returned by default()
— is used.
If self
is owned by the current thread, function
is called
directly. Otherwise, if self
is the thread-default main context
of the current thread and acquire()
succeeds, then
function
is called and [release()
][Self::release()] is called
afterwards.
In any other case, an idle source is created to call function
and
that source is attached to self
(presumably to be run in another
thread). The idle source is attached with G_PRIORITY_DEFAULT
priority. If you want a different priority, use
g_main_context_invoke_full()
.
Note that, as with normal idle functions, function
should probably
return false
. If it returns true
, it will be continuously run in a
loop (and may prevent this call from returning).
function
function to call
pub fn invoke_with_priority<F>(&self, priority: Priority, func: F) where
F: FnOnce() + Send + 'static,
pub fn invoke_with_priority<F>(&self, priority: Priority, func: F) where
F: FnOnce() + Send + 'static,
Invokes func
on the main context with the given priority.
Invokes func
on the main context.
Different to invoke()
, this does not require func
to be
Send
but can only be called from the thread that owns the main context.
This function panics if called from a different thread than the one that owns the main context.
pub fn invoke_local_with_priority<F>(&self, priority: Priority, func: F) where
F: FnOnce() + 'static,
pub fn invoke_local_with_priority<F>(&self, priority: Priority, func: F) where
F: FnOnce() + 'static,
Invokes func
on the main context with the given priority.
Different to invoke_with_priority()
, this does not require func
to be
Send
but can only be called from the thread that owns the main context.
This function panics if called from a different thread than the one that owns the main context.
Calls closure with context configured as the thread default one.
Thread default context is changed in panic-safe manner by calling
push_thread_default
before calling closure
and pop_thread_default
afterwards regardless
of whether closure panicked or not.
Tries to become the owner of the specified context.
If some other thread is the owner of the context,
returns false
immediately. Ownership is properly
recursive: the owner can require ownership again
and will release ownership when [release()
][Self::release()]
is called as many times as acquire()
.
You must be the owner of a context before you
can call prepare()
, g_main_context_query()
,
g_main_context_check()
, dispatch()
.
Returns
true
if the operation succeeded, and
this thread is now the owner of self
.
Creates a channel for a main context.
The Receiver
has to be attached to a main context at a later time, together with a
closure that will be called for every item sent to a Sender
.
The Sender
can be cloned and both the Sender
and Receiver
can be sent to different
threads as long as the item type implements the Send
trait.
When the last Sender
is dropped the channel is removed from the main context. If the
Receiver
is dropped and not attached to a main context all sending to the Sender
will fail.
The returned Sender
behaves the same as std::sync::mpsc::Sender
.
Creates a synchronous channel for a main context with a given bound on the capacity of the channel.
The Receiver
has to be attached to a main context at a later time, together with a
closure that will be called for every item sent to a SyncSender
.
The SyncSender
can be cloned and both the SyncSender
and Receiver
can be sent to different
threads as long as the item type implements the Send
trait.
When the last SyncSender
is dropped the channel is removed from the main context. If the
Receiver
is dropped and not attached to a main context all sending to the SyncSender
will fail.
The returned SyncSender
behaves the same as std::sync::mpsc::SyncSender
.
Spawn a new infallible Future
on the main context.
This can be called from any thread and will execute the future from the thread
where main context is running, e.g. via a MainLoop
.
Spawn a new infallible Future
on the main context.
The given Future
does not have to be Send
.
This can be called only from the thread where the main context is running, e.g.
from any other Future
that is executed on this main context, or after calling
push_thread_default
or acquire
on the main context.
Spawn a new infallible Future
on the main context, with a non-default priority.
This can be called from any thread and will execute the future from the thread
where main context is running, e.g. via a MainLoop
.
pub fn spawn_local_with_priority<F: Future<Output = ()> + 'static>(
&self,
priority: Priority,
f: F
)
pub fn spawn_local_with_priority<F: Future<Output = ()> + 'static>(
&self,
priority: Priority,
f: F
)
Spawn a new infallible Future
on the main context, with a non-default priority.
The given Future
does not have to be Send
.
This can be called only from the thread where the main context is running, e.g.
from any other Future
that is executed on this main context, or after calling
push_thread_default
or acquire
on the main context.
Runs a new, infallible Future
on the main context and block until it finished, returning
the result of the Future
.
The given Future
does not have to be Send
or 'static
.
This must only be called if no MainLoop
or anything else is running on this specific main
context.
Trait Implementations
Spawns a future that will be run to completion. Read more
fn status_local(&self) -> Result<(), SpawnError>
fn status_local(&self) -> Result<(), SpawnError>
Determines whether the executor is able to spawn new tasks. Read more
This method tests for self
and other
values to be equal, and is used
by ==
. Read more
This method tests for !=
.
This method returns an ordering between self
and other
values if one exists. Read more
This method tests less than (for self
and other
) and is used by the <
operator. Read more
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
Returns the type identifier of Self
.
Auto Trait Implementations
Blanket Implementations
Mutably borrows from an owned value. Read more
Returns a SendValue
clone of self
.
impl<'a, T, C> FromValueOptional<'a> for T where
C: ValueTypeChecker<Error = ValueTypeMismatchOrNoneError>,
T: FromValue<'a, Checker = C>,