Struct MainThreadMarker

pub struct MainThreadMarker { /* private fields */ }

A marker type for functionality only available on the main thread.

The main thread is a system-level property on Apple/Darwin platforms, and has extra capabilities not available on other threads. This is usually relevant when using native GUI frameworks, where most operations must be done on the main thread.

This type enables you to manage that capability. By design, it is neither Send nor Sync, and can only be created on the main thread, meaning that if you have an instance of this, you are guaranteed to be on the main thread / have the “main-thread capability”.

The main function will run on the main thread. This type can also be used with #![no_main] or other such cases where Rust is not defining the binary entry point.

See the following links for more information on main-thread-only APIs:

• Are the Cocoa Frameworks Thread Safe?
• About Threaded Programming
• Thread Safety Summary
• Technical Note TN2028 - Threading Architectures
• Thread Management
• Swift’s @MainActor
• Main Thread Only APIs on OS X
• Mike Ash’ article on thread safety

Main Thread Checker

Xcode provides a tool called the “Main Thread Checker” which verifies that UI APIs are being used from the correct thread. This is not as principled as MainThreadMarker, but is helpful for catching mistakes.

You can use this tool on macOS by loading libMainThreadChecker.dylib into your process using DYLD_INSERT_LIBRARIES:

DYLD_INSERT_LIBRARIES=/Applications/Xcode.app/Contents/Developer/usr/lib/libMainThreadChecker.dylib MTC_RESET_INSERT_LIBRARIES=0 cargo run

If you’re not running your binary through Cargo, you can omit MTC_RESET_INSERT_LIBRARIES.

DYLD_INSERT_LIBRARIES=/Applications/Xcode.app/Contents/Developer/usr/lib/libMainThreadChecker.dylib target/debug/myapp

If you’re developing for iOS, you probably better off enabling the tool in Xcode’s own UI.

See this excellent blog post for details on further configuration options.

Examples

Retrieve the main thread marker in different situations.

use objc2::MainThreadMarker;

fn main() {
    // The thread that `fn main` runs on is the main thread.
    assert!(MainThreadMarker::new().is_some());

    // Subsequently spawned threads are not the main thread.
    std::thread::spawn(|| {
        assert!(MainThreadMarker::new().is_none());
    }).join().unwrap();
}

Use when accessing APIs that are only safe to use on the main thread.

use objc2::MainThreadMarker;
use objc2_app_kit::NSApplication;

fn main() {
    // Create a new MainThreadMarker.
    let mtm = MainThreadMarker::new().expect("must be on the main thread");

    // NSApplication is only usable on the main thread,
    // so we need to pass the marker as an argument.
    let app = NSApplication::sharedApplication(mtm);

    // Do something with the application
    // app.run();
}

Create a static that is only usable on the main thread. This is similar to a thread-local, but can be more efficient because it doesn’t handle multiple threads.

See also dispatch2::MainThreadBound.

use objc2::MainThreadMarker;
use std::cell::UnsafeCell;

struct SyncUnsafeCell<T>(UnsafeCell<T>);

unsafe impl<T> Sync for SyncUnsafeCell<T> {}

static MAIN_THREAD_ONLY_VALUE: SyncUnsafeCell<i32> = SyncUnsafeCell(UnsafeCell::new(0));

fn set(value: i32, _mtm: MainThreadMarker) {
    // SAFETY: We have an instance of `MainThreadMarker`, so we know that
    // we're running on the main thread (and thus do not need any
    // synchronization, since the only accesses to this value is from the
    // main thread).
    unsafe { *MAIN_THREAD_ONLY_VALUE.0.get() = value };
}

fn get(_mtm: MainThreadMarker) -> i32 {
    // SAFETY: Same as above.
    unsafe { *MAIN_THREAD_ONLY_VALUE.0.get() }
}

fn main() {
    let mtm = MainThreadMarker::new().expect("must be on the main thread");
    set(42, mtm);
    assert_eq!(get(mtm), 42);
}

Implementations

impl MainThreadMarker

pub fn new() -> Option<MainThreadMarker>

Construct a new MainThreadMarker.

Returns None if the current thread was not the main thread.

Example

Check whether the current thread is the main thread.

use objc2::MainThreadMarker;

if MainThreadMarker::new().is_some() {
    // Is the main thread
} else {
    // Not the main thread
}

pub const unsafe fn new_unchecked() -> MainThreadMarker

Construct a new MainThreadMarker without first checking whether the current thread is the main one.

Safety

The current thread must be the main thread.

Alternatively, you may create this briefly if you know that a an API is safe in a specific case, but is not marked so. If you do that, you must ensure that any use of the marker is actually safe to do from another thread than the main one.

pub fn alloc<T>(self) -> Allocated<T>

where T: ClassType,

Allocate a new instance of the specified class on the main thread.

This can be useful in certain situations, such as generic contexts where you don’t know whether the class is main thread or not, but usually you should prefer MainThreadOnly::alloc.

Trait Implementations

impl Clone for MainThreadMarker

fn clone(&self) -> MainThreadMarker

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for MainThreadMarker

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

Formats the value using the given formatter.

impl<T> From<&T> for MainThreadMarker

where T: MainThreadOnly + ?Sized,

Get a MainThreadMarker from a main-thread-only object.

This is a shorthand for MainThreadOnly::mtm.

fn from(obj: &T) -> MainThreadMarker

Converts to this type from the input type.

impl Hash for MainThreadMarker

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 MainThreadMarker

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

This method returns an Ordering between self and other.

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 PartialEq for MainThreadMarker

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

Tests for self and other values to be equal, and is used by ==.

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 PartialOrd for MainThreadMarker

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

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

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 Copy for MainThreadMarker

impl Eq for MainThreadMarker

impl StructuralPartialEq for MainThreadMarker