dispatch2/
lib.rs

1//! # Apple's Dispatch (Grand Central Dispatch)
2//!
3//! This crate provides a safe and sound interface to Apple's Grand Central
4//! dispatch.
5//!
6//! See [Apple's documentation](https://developer.apple.com/documentation/dispatch)
7//! and [the source code for libdispatch](https://github.com/swiftlang/swift-corelibs-libdispatch)
8//! for more details.
9//!
10//! ## Example
11//!
12//! ```
13//! use dispatch2::{DispatchQueue, DispatchQueueAttr};
14//!
15//! let queue = DispatchQueue::new("example_queue", DispatchQueueAttr::SERIAL);
16//! queue.exec_async(|| println!("Hello"));
17//! queue.exec_sync(|| println!("World"));
18//! ```
19#![no_std]
20#![allow(unreachable_patterns)]
21#![warn(missing_docs)]
22#![warn(missing_debug_implementations)]
23#![warn(clippy::undocumented_unsafe_blocks)]
24#![warn(clippy::missing_safety_doc)]
25// Update in Cargo.toml as well.
26#![doc(html_root_url = "https://docs.rs/dispatch2/0.3.0")]
27
28#[cfg(not(feature = "alloc"))]
29compile_error!("The `alloc` feature currently must be enabled.");
30
31extern crate alloc;
32
33#[cfg(feature = "std")]
34extern crate std;
35
36#[macro_use]
37mod macros;
38
39use core::cell::UnsafeCell;
40use core::marker::{PhantomData, PhantomPinned};
41
42mod data;
43#[allow(clippy::undocumented_unsafe_blocks, unreachable_pub)]
44mod generated;
45mod group;
46mod io;
47#[cfg(feature = "objc2")]
48mod main_thread_bound;
49mod object;
50mod once;
51mod queue;
52mod retained;
53mod semaphore;
54mod source;
55mod time;
56mod utils;
57mod workloop;
58
59/// Wait error.
60#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord)]
61#[non_exhaustive]
62pub enum WaitError {
63    /// The given timeout value will result in an overflow when converting to dispatch time.
64    TimeOverflow,
65    /// The operation timed out.
66    Timeout,
67}
68
69pub use self::data::DispatchData;
70#[cfg(feature = "block2")]
71pub use self::generated::{
72    _dispatch_data_destructor_free, _dispatch_data_destructor_munmap, dispatch_block_cancel,
73    dispatch_block_create, dispatch_block_create_with_qos_class, dispatch_block_notify,
74    dispatch_block_perform, dispatch_block_t, dispatch_block_testcancel, dispatch_block_wait,
75    dispatch_data_applier_t, dispatch_io_handler_t, dispatch_read, dispatch_write,
76};
77pub use self::generated::{
78    dispatch_allow_send_signals, dispatch_fd_t, dispatch_get_specific, dispatch_once_t,
79    DispatchAutoReleaseFrequency, _dispatch_source_type_data_add, _dispatch_source_type_data_or,
80    _dispatch_source_type_data_replace, _dispatch_source_type_mach_recv,
81    _dispatch_source_type_mach_send, _dispatch_source_type_memorypressure,
82    _dispatch_source_type_proc, _dispatch_source_type_read, _dispatch_source_type_signal,
83    _dispatch_source_type_timer, _dispatch_source_type_vnode, _dispatch_source_type_write,
84    DISPATCH_API_VERSION,
85};
86pub use self::group::{DispatchGroup, DispatchGroupGuard};
87pub use self::io::{
88    DispatchIO, DispatchIOCloseFlags, DispatchIOIntervalFlags, DispatchIOStreamType,
89};
90#[cfg(feature = "objc2")]
91pub use self::main_thread_bound::{run_on_main, MainThreadBound};
92pub(crate) use self::object::dispatch_object_s;
93pub use self::object::{
94    DispatchObject, DispatchQoS, QualityOfServiceClassFloorError, QOS_MIN_RELATIVE_PRIORITY,
95};
96pub use self::once::DispatchOnce;
97pub use self::queue::{
98    dispatch_main, DispatchQueue, DispatchQueueAttr, DispatchQueueGlobalPriority,
99    GlobalQueueIdentifier, QueueAfterError,
100};
101pub use self::retained::DispatchRetained;
102pub use self::semaphore::{DispatchSemaphore, DispatchSemaphoreGuard};
103pub use self::source::{
104    dispatch_source_mach_recv_flags_t, dispatch_source_mach_send_flags_t,
105    dispatch_source_memorypressure_flags_t, dispatch_source_proc_flags_t,
106    dispatch_source_timer_flags_t, dispatch_source_type_s, dispatch_source_type_t,
107    dispatch_source_vnode_flags_t, DispatchSource,
108};
109pub use self::time::DispatchTime;
110pub use self::workloop::DispatchWorkloop;
111
112// Helper type
113type OpaqueData = UnsafeCell<PhantomData<(*const UnsafeCell<()>, PhantomPinned)>>;
114
115/// Deprecated alias for [`DispatchGroup`].
116#[deprecated = "renamed to DispatchGroup"]
117pub type Group = DispatchGroup;
118
119/// Deprecated alias for [`DispatchOnce`].
120#[deprecated = "renamed to DispatchOnce"]
121pub type Once = DispatchOnce;
122
123/// Deprecated alias for [`DispatchQueue`].
124#[deprecated = "renamed to DispatchQueue"]
125pub type Queue = DispatchQueue;
126
127/// Deprecated alias for [`DispatchSemaphore`].
128#[deprecated = "renamed to DispatchSemaphore"]
129pub type Semaphore = DispatchSemaphore;
130
131/// Deprecated alias for [`DispatchWorkloop`].
132#[deprecated = "renamed to DispatchWorkloop"]
133pub type WorkloopQueue = DispatchWorkloop;
134
135#[cfg_attr(target_vendor = "apple", link(name = "System", kind = "dylib"))]
136#[cfg_attr(not(target_vendor = "apple"), link(name = "dispatch", kind = "dylib"))]
137extern "C" {}
138
139/// The prototype of functions submitted to dispatch queues.
140///
141/// This is deliberately `extern "C"`, since libdispatch doesn't support
142/// unwinding in handler functions, and this gives us better error messages
143/// if that does happen.
144#[allow(non_camel_case_types)]
145pub type dispatch_function_t = extern "C" fn(*mut core::ffi::c_void);
dispatch2/lib.rs

dispatch2/
lib.rs
