Crate native_executor 

Native Executor

Platform-native async task executor that leverages OS event loops (GCD, GDK) for optimal performance.

Features

• Platform-native scheduling: Direct GCD integration on Apple platforms
• Priority-aware execution: Background vs default task prioritization
• Thread-local safety: Non-Send future execution with compile-time guarantees
• Thread-safe utilities: LocalValue, OnceValue, MainValue containers
• Zero-cost abstractions: Direct OS API usage, no additional runtime

Installation

Add this to your Cargo.toml:

[dependencies]
native-executor = "0.5"

Quick Start

use native_executor::{spawn_local, timer::Timer};
use std::time::Duration;

// Spawn a task with default priority
let handle = spawn_local(async {
    println!("Starting async task");

    // High-precision timer using platform-native scheduling
    Timer::after(Duration::from_secs(1)).await;

    println!("Task completed after 1 second");
});

// Keep the main thread alive to allow tasks to complete
std::thread::sleep(Duration::from_secs(2));

Core Components

Task Spawning

use native_executor::{spawn, spawn_local, spawn_main, spawn_with_priority, Priority};

spawn(async { /* default priority */ });
spawn_local(async { /* non-Send, main thread */ });
spawn_main(async { /* Send, main thread */ });
spawn_with_priority(async { /* background work */ }, Priority::Background);

Timers

use native_executor::timer::{Timer, sleep};
use std::time::Duration;

Timer::after(Duration::from_millis(100)).await;  // Precise timing
Timer::after_secs(2).await;                      // Convenience method
sleep(1).await;                                  // Simple sleep

Thread-Safe Containers

use native_executor::{LocalValue, OnceValue, MainValue};

// Thread-local access only
let local = LocalValue::new(42);
assert_eq!(*local, 42);

// Single-consumption semantics
let once = OnceValue::new("consume once");
let value = once.take();

// Cross-thread with main-thread execution
let main_val = MainValue::new(String::from("UI data"));
let len = main_val.handle(|s| s.len()).await;

Platform Support

Current: Apple platforms (macOS, iOS, tvOS, watchOS) via Grand Central Dispatch
Planned: Linux (GDK), Android (Looper)

Unsupported platforms fail at compile-time with clear error messages.

Examples

cargo run --example simple_task    # Basic spawning
cargo run --example priority       # Priority control
cargo run --example timers         # High-precision timing
cargo run --example main_thread     # Main thread execution
cargo run --example local_value     # Thread-safe containers

License

This project is licensed under the MIT License.

Modules

mailbox

Mailbox-based message passing for safe cross-thread communication.

timer

Platform-native timers with high precision.

Structs

NativeExecutor

The native executor implementation. A stub executor for unsupported platforms that panics on use.

Enums

Priority

Task execution priority levels for controlling scheduler behavior.

Functions

spawn

Creates a new task with default priority.

spawn_local

Creates a new thread-local task that runs on the main thread.

spawn_main

Creates a new task that executes on the main thread.

spawn_with_priority

Creates a new task with the specified execution priority.