Struct futures_glib::MainContext

pub struct MainContext { /* fields omitted */ }

Binding to the underlying GMainContext type.

Methods

impl MainContext

fn new() -> MainContext

Creates a new context to execute within.

fn default<F, R>(f: F) -> R where
    F: FnOnce(&MainContext) -> R, 

Acquires a reference to this thread's default 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.

fn thread_default<F, R>(f: F) -> R where
    F: FnOnce(Option<&MainContext>) -> R, 

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 to get a MainContext to add their Sources 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 yield None if you are running in the default thread.)

fn try_lock(&self) -> Option<LockedMainContext>

Attempts to become the owner of the specified context.

If some other thread is the owner of the context, returns Err immediately. Ownership is properly recursive: the owner can require ownership again.

If the context is successfully locked then a locked version is returned, otherwise an Err is returned with this context.

fn is_owner(&self) -> bool

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

fn wakeup(&self)

If context 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.

fn push_thread_default(&self) -> PushThreadDefault

Acquires context and sets it as the thread-default context for the current thread.

This will cause certain asynchronous operations (such as most gio-based I/O) which are started in this thread to run under context 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.

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.

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 ThreadPool), it is always suggested to wrap the logic that needs to use the new MainContext inside push_thread_default block. 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 block, but it is up to you to ensure that no other asynchronous operations accidentally get started while the non-default context is active.

This context will be popped from the default scope when the returned PushThreadDefault value goes out of scope.

Trait Implementations

impl Send for MainContext

impl Sync for MainContext

impl Clone for MainContext

fn clone(&self) -> MainContext

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Drop for MainContext

fn drop(&mut self)

A method called when the value goes out of scope.