sdl3_sys/generated/
thread.rs

1//! SDL offers cross-platform thread management functions. These are mostly
2//! concerned with starting threads, setting their priority, and dealing with
3//! their termination.
4//!
5//! In addition, there is support for Thread Local Storage (data that is unique
6//! to each thread, but accessed from a single key).
7//!
8//! On platforms without thread support (such as Emscripten when built without
9//! pthreads), these functions still exist, but things like [`SDL_CreateThread()`]
10//! will report failure without doing anything.
11//!
12//! If you're going to work with threads, you almost certainly need to have a
13//! good understanding of thread safety measures: locking and synchronization
14//! mechanisms are handled by the functions in SDL_mutex.h.
15
16use super::stdinc::*;
17
18use super::error::*;
19
20use super::properties::*;
21
22use super::atomic::*;
23
24apply_cfg!(#[cfg(any(doc, windows))] => {
25});
26
27/// A unique numeric ID that identifies a thread.
28///
29/// These are different from [`SDL_Thread`] objects, which are generally what an
30/// application will operate on, but having a way to uniquely identify a thread
31/// can be useful at times.
32///
33/// ## Availability
34/// This datatype is available since SDL 3.2.0.
35///
36/// ## See also
37/// - [`SDL_GetThreadID`]
38/// - [`SDL_GetCurrentThreadID`]
39#[repr(transparent)]
40#[derive(Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
41#[cfg_attr(feature = "debug-impls", derive(Debug))]
42pub struct SDL_ThreadID(pub Uint64);
43
44impl ::core::cmp::PartialEq<Uint64> for SDL_ThreadID {
45    #[inline(always)]
46    fn eq(&self, other: &Uint64) -> bool {
47        &self.0 == other
48    }
49}
50
51impl ::core::cmp::PartialEq<SDL_ThreadID> for Uint64 {
52    #[inline(always)]
53    fn eq(&self, other: &SDL_ThreadID) -> bool {
54        self == &other.0
55    }
56}
57
58impl From<SDL_ThreadID> for Uint64 {
59    #[inline(always)]
60    fn from(value: SDL_ThreadID) -> Self {
61        value.0
62    }
63}
64
65#[cfg(feature = "display-impls")]
66impl ::core::fmt::Display for SDL_ThreadID {
67    #[inline(always)]
68    fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
69        <Uint64 as ::core::fmt::Display>::fmt(&self.0, f)
70    }
71}
72
73impl SDL_ThreadID {
74    /// Initialize a `SDL_ThreadID` from a raw value.
75    #[inline(always)]
76    pub const fn new(value: Uint64) -> Self {
77        Self(value)
78    }
79}
80
81impl SDL_ThreadID {
82    /// Get a copy of the inner raw value.
83    #[inline(always)]
84    pub const fn value(&self) -> Uint64 {
85        self.0
86    }
87}
88
89#[cfg(feature = "metadata")]
90impl sdl3_sys::metadata::GroupMetadata for SDL_ThreadID {
91    const GROUP_METADATA: &'static sdl3_sys::metadata::Group =
92        &crate::metadata::thread::METADATA_SDL_ThreadID;
93}
94
95/// Thread local storage ID.
96///
97/// 0 is the invalid ID. An app can create these and then set data for these
98/// IDs that is unique to each thread.
99///
100/// ## Availability
101/// This datatype is available since SDL 3.2.0.
102///
103/// ## See also
104/// - [`SDL_GetTLS`]
105/// - [`SDL_SetTLS`]
106#[repr(transparent)]
107#[derive(Default)]
108#[cfg_attr(feature = "debug-impls", derive(Debug))]
109pub struct SDL_TLSID(pub SDL_AtomicInt);
110
111impl From<SDL_TLSID> for SDL_AtomicInt {
112    #[inline(always)]
113    fn from(value: SDL_TLSID) -> Self {
114        value.0
115    }
116}
117
118impl SDL_TLSID {
119    /// Initialize a `SDL_TLSID` from a raw value.
120    #[inline(always)]
121    pub const fn new(value: SDL_AtomicInt) -> Self {
122        Self(value)
123    }
124}
125
126#[cfg(feature = "metadata")]
127impl sdl3_sys::metadata::GroupMetadata for SDL_TLSID {
128    const GROUP_METADATA: &'static sdl3_sys::metadata::Group =
129        &crate::metadata::thread::METADATA_SDL_TLSID;
130}
131
132/// The SDL thread priority.
133///
134/// SDL will make system changes as necessary in order to apply the thread
135/// priority. Code which attempts to control thread state related to priority
136/// should be aware that calling [`SDL_SetCurrentThreadPriority`] may alter such
137/// state. [`SDL_HINT_THREAD_PRIORITY_POLICY`] can be used to control aspects of
138/// this behavior.
139///
140/// ## Availability
141/// This enum is available since SDL 3.2.0.
142///
143/// ## Known values (`sdl3-sys`)
144/// | Associated constant | Global constant | Description |
145/// | ------------------- | --------------- | ----------- |
146/// | [`LOW`](SDL_ThreadPriority::LOW) | [`SDL_THREAD_PRIORITY_LOW`] | |
147/// | [`NORMAL`](SDL_ThreadPriority::NORMAL) | [`SDL_THREAD_PRIORITY_NORMAL`] | |
148/// | [`HIGH`](SDL_ThreadPriority::HIGH) | [`SDL_THREAD_PRIORITY_HIGH`] | |
149/// | [`TIME_CRITICAL`](SDL_ThreadPriority::TIME_CRITICAL) | [`SDL_THREAD_PRIORITY_TIME_CRITICAL`] | |
150#[repr(transparent)]
151#[derive(Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
152pub struct SDL_ThreadPriority(pub ::core::ffi::c_int);
153
154impl ::core::cmp::PartialEq<::core::ffi::c_int> for SDL_ThreadPriority {
155    #[inline(always)]
156    fn eq(&self, other: &::core::ffi::c_int) -> bool {
157        &self.0 == other
158    }
159}
160
161impl ::core::cmp::PartialEq<SDL_ThreadPriority> for ::core::ffi::c_int {
162    #[inline(always)]
163    fn eq(&self, other: &SDL_ThreadPriority) -> bool {
164        self == &other.0
165    }
166}
167
168impl From<SDL_ThreadPriority> for ::core::ffi::c_int {
169    #[inline(always)]
170    fn from(value: SDL_ThreadPriority) -> Self {
171        value.0
172    }
173}
174
175#[cfg(feature = "debug-impls")]
176impl ::core::fmt::Debug for SDL_ThreadPriority {
177    fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
178        #[allow(unreachable_patterns)]
179        f.write_str(match *self {
180            Self::LOW => "SDL_THREAD_PRIORITY_LOW",
181            Self::NORMAL => "SDL_THREAD_PRIORITY_NORMAL",
182            Self::HIGH => "SDL_THREAD_PRIORITY_HIGH",
183            Self::TIME_CRITICAL => "SDL_THREAD_PRIORITY_TIME_CRITICAL",
184
185            _ => return write!(f, "SDL_ThreadPriority({})", self.0),
186        })
187    }
188}
189
190impl SDL_ThreadPriority {
191    pub const LOW: Self = Self((0 as ::core::ffi::c_int));
192    pub const NORMAL: Self = Self((1 as ::core::ffi::c_int));
193    pub const HIGH: Self = Self((2 as ::core::ffi::c_int));
194    pub const TIME_CRITICAL: Self = Self((3 as ::core::ffi::c_int));
195}
196
197pub const SDL_THREAD_PRIORITY_LOW: SDL_ThreadPriority = SDL_ThreadPriority::LOW;
198pub const SDL_THREAD_PRIORITY_NORMAL: SDL_ThreadPriority = SDL_ThreadPriority::NORMAL;
199pub const SDL_THREAD_PRIORITY_HIGH: SDL_ThreadPriority = SDL_ThreadPriority::HIGH;
200pub const SDL_THREAD_PRIORITY_TIME_CRITICAL: SDL_ThreadPriority = SDL_ThreadPriority::TIME_CRITICAL;
201
202impl SDL_ThreadPriority {
203    /// Initialize a `SDL_ThreadPriority` from a raw value.
204    #[inline(always)]
205    pub const fn new(value: ::core::ffi::c_int) -> Self {
206        Self(value)
207    }
208}
209
210impl SDL_ThreadPriority {
211    /// Get a copy of the inner raw value.
212    #[inline(always)]
213    pub const fn value(&self) -> ::core::ffi::c_int {
214        self.0
215    }
216}
217
218#[cfg(feature = "metadata")]
219impl sdl3_sys::metadata::GroupMetadata for SDL_ThreadPriority {
220    const GROUP_METADATA: &'static sdl3_sys::metadata::Group =
221        &crate::metadata::thread::METADATA_SDL_ThreadPriority;
222}
223
224/// The SDL thread state.
225///
226/// The current state of a thread can be checked by calling [`SDL_GetThreadState`].
227///
228/// ## Availability
229/// This enum is available since SDL 3.2.0.
230///
231/// ## See also
232/// - [`SDL_GetThreadState`]
233///
234/// ## Known values (`sdl3-sys`)
235/// | Associated constant | Global constant | Description |
236/// | ------------------- | --------------- | ----------- |
237/// | [`UNKNOWN`](SDL_ThreadState::UNKNOWN) | [`SDL_THREAD_UNKNOWN`] | The thread is not valid |
238/// | [`ALIVE`](SDL_ThreadState::ALIVE) | [`SDL_THREAD_ALIVE`] | The thread is currently running |
239/// | [`DETACHED`](SDL_ThreadState::DETACHED) | [`SDL_THREAD_DETACHED`] | The thread is detached and can't be waited on |
240/// | [`COMPLETE`](SDL_ThreadState::COMPLETE) | [`SDL_THREAD_COMPLETE`] | The thread has finished and should be cleaned up with [`SDL_WaitThread()`] |
241#[repr(transparent)]
242#[derive(Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
243pub struct SDL_ThreadState(pub ::core::ffi::c_int);
244
245impl ::core::cmp::PartialEq<::core::ffi::c_int> for SDL_ThreadState {
246    #[inline(always)]
247    fn eq(&self, other: &::core::ffi::c_int) -> bool {
248        &self.0 == other
249    }
250}
251
252impl ::core::cmp::PartialEq<SDL_ThreadState> for ::core::ffi::c_int {
253    #[inline(always)]
254    fn eq(&self, other: &SDL_ThreadState) -> bool {
255        self == &other.0
256    }
257}
258
259impl From<SDL_ThreadState> for ::core::ffi::c_int {
260    #[inline(always)]
261    fn from(value: SDL_ThreadState) -> Self {
262        value.0
263    }
264}
265
266#[cfg(feature = "debug-impls")]
267impl ::core::fmt::Debug for SDL_ThreadState {
268    fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
269        #[allow(unreachable_patterns)]
270        f.write_str(match *self {
271            Self::UNKNOWN => "SDL_THREAD_UNKNOWN",
272            Self::ALIVE => "SDL_THREAD_ALIVE",
273            Self::DETACHED => "SDL_THREAD_DETACHED",
274            Self::COMPLETE => "SDL_THREAD_COMPLETE",
275
276            _ => return write!(f, "SDL_ThreadState({})", self.0),
277        })
278    }
279}
280
281impl SDL_ThreadState {
282    /// The thread is not valid
283    pub const UNKNOWN: Self = Self((0 as ::core::ffi::c_int));
284    /// The thread is currently running
285    pub const ALIVE: Self = Self((1 as ::core::ffi::c_int));
286    /// The thread is detached and can't be waited on
287    pub const DETACHED: Self = Self((2 as ::core::ffi::c_int));
288    /// The thread has finished and should be cleaned up with [`SDL_WaitThread()`]
289    pub const COMPLETE: Self = Self((3 as ::core::ffi::c_int));
290}
291
292/// The thread is not valid
293pub const SDL_THREAD_UNKNOWN: SDL_ThreadState = SDL_ThreadState::UNKNOWN;
294/// The thread is currently running
295pub const SDL_THREAD_ALIVE: SDL_ThreadState = SDL_ThreadState::ALIVE;
296/// The thread is detached and can't be waited on
297pub const SDL_THREAD_DETACHED: SDL_ThreadState = SDL_ThreadState::DETACHED;
298/// The thread has finished and should be cleaned up with [`SDL_WaitThread()`]
299pub const SDL_THREAD_COMPLETE: SDL_ThreadState = SDL_ThreadState::COMPLETE;
300
301impl SDL_ThreadState {
302    /// Initialize a `SDL_ThreadState` from a raw value.
303    #[inline(always)]
304    pub const fn new(value: ::core::ffi::c_int) -> Self {
305        Self(value)
306    }
307}
308
309impl SDL_ThreadState {
310    /// Get a copy of the inner raw value.
311    #[inline(always)]
312    pub const fn value(&self) -> ::core::ffi::c_int {
313        self.0
314    }
315}
316
317#[cfg(feature = "metadata")]
318impl sdl3_sys::metadata::GroupMetadata for SDL_ThreadState {
319    const GROUP_METADATA: &'static sdl3_sys::metadata::Group =
320        &crate::metadata::thread::METADATA_SDL_ThreadState;
321}
322
323/// The function passed to [`SDL_CreateThread()`] as the new thread's entry point.
324///
325/// ## Parameters
326/// - `data`: what was passed as `data` to [`SDL_CreateThread()`].
327///
328/// ## Return value
329/// Returns a value that can be reported through [`SDL_WaitThread()`].
330///
331/// ## Availability
332/// This datatype is available since SDL 3.2.0.
333pub type SDL_ThreadFunction = ::core::option::Option<
334    unsafe extern "C" fn(data: *mut ::core::ffi::c_void) -> ::core::ffi::c_int,
335>;
336
337apply_cfg!(#[cfg(doc)] => {
338    unsafe extern "C" {
339        /// Create a new thread with a default stack size.
340        ///
341        /// This is a convenience function, equivalent to calling
342        /// [`SDL_CreateThreadWithProperties`] with the following properties set:
343        ///
344        /// - [`SDL_PROP_THREAD_CREATE_ENTRY_FUNCTION_POINTER`]\: `fn`
345        /// - [`SDL_PROP_THREAD_CREATE_NAME_STRING`]\: `name`
346        /// - [`SDL_PROP_THREAD_CREATE_USERDATA_POINTER`]\: `data`
347        ///
348        /// Note that this "function" is actually a macro that calls an internal
349        /// function with two extra parameters not listed here; they are hidden through
350        /// preprocessor macros and are needed to support various C runtimes at the
351        /// point of the function call. Language bindings that aren't using the C
352        /// headers will need to deal with this.
353        ///
354        /// Usually, apps should just call this function the same way on every platform
355        /// and let the macros hide the details.
356        ///
357        /// ## Parameters
358        /// - `fn`: the [`SDL_ThreadFunction`] function to call in the new thread.
359        /// - `name`: the name of the thread.
360        /// - `data`: a pointer that is passed to `fn`.
361        ///
362        /// ## Return value
363        /// Returns an opaque pointer to the new thread object on success, NULL if the
364        ///   new thread could not be created; call [`SDL_GetError()`] for more
365        ///   information.
366        ///
367        /// ## Thread safety
368        /// It is safe to call this function from any thread.
369        ///
370        /// ## Availability
371        /// This function is available since SDL 3.2.0.
372        ///
373        /// ## See also
374        /// - [`SDL_CreateThreadWithProperties`]
375        /// - [`SDL_WaitThread`]
376        pub fn SDL_CreateThread(r#fn: SDL_ThreadFunction, name: *const ::core::ffi::c_char, data: *mut ::core::ffi::c_void) -> *mut SDL_Thread;
377    }
378
379    unsafe extern "C" {
380        /// Create a new thread with with the specified properties.
381        ///
382        /// These are the supported properties:
383        ///
384        /// - [`SDL_PROP_THREAD_CREATE_ENTRY_FUNCTION_POINTER`]\: an [`SDL_ThreadFunction`]
385        ///   value that will be called at the start of the new thread's life.
386        ///   Required.
387        /// - [`SDL_PROP_THREAD_CREATE_NAME_STRING`]\: the name of the new thread, which
388        ///   might be available to debuggers. Optional, defaults to NULL.
389        /// - [`SDL_PROP_THREAD_CREATE_USERDATA_POINTER`]\: an arbitrary app-defined
390        ///   pointer, which is passed to the entry function on the new thread, as its
391        ///   only parameter. Optional, defaults to NULL.
392        /// - [`SDL_PROP_THREAD_CREATE_STACKSIZE_NUMBER`]\: the size, in bytes, of the new
393        ///   thread's stack. Optional, defaults to 0 (system-defined default).
394        ///
395        /// SDL makes an attempt to report [`SDL_PROP_THREAD_CREATE_NAME_STRING`] to the
396        /// system, so that debuggers can display it. Not all platforms support this.
397        ///
398        /// Thread naming is a little complicated: Most systems have very small limits
399        /// for the string length (Haiku has 32 bytes, Linux currently has 16, Visual
400        /// C++ 6.0 has _nine_!), and possibly other arbitrary rules. You'll have to
401        /// see what happens with your system's debugger. The name should be UTF-8 (but
402        /// using the naming limits of C identifiers is a better bet). There are no
403        /// requirements for thread naming conventions, so long as the string is
404        /// null-terminated UTF-8, but these guidelines are helpful in choosing a name:
405        ///
406        /// <https://stackoverflow.com/questions/149932/naming-conventions-for-threads>
407        ///
408        /// If a system imposes requirements, SDL will try to munge the string for it
409        /// (truncate, etc), but the original string contents will be available from
410        /// [`SDL_GetThreadName()`].
411        ///
412        /// The size (in bytes) of the new stack can be specified with
413        /// [`SDL_PROP_THREAD_CREATE_STACKSIZE_NUMBER`]. Zero means "use the system
414        /// default" which might be wildly different between platforms. x86 Linux
415        /// generally defaults to eight megabytes, an embedded device might be a few
416        /// kilobytes instead. You generally need to specify a stack that is a multiple
417        /// of the system's page size (in many cases, this is 4 kilobytes, but check
418        /// your system documentation).
419        ///
420        /// Note that this "function" is actually a macro that calls an internal
421        /// function with two extra parameters not listed here; they are hidden through
422        /// preprocessor macros and are needed to support various C runtimes at the
423        /// point of the function call. Language bindings that aren't using the C
424        /// headers will need to deal with this.
425        ///
426        /// The actual symbol in SDL is [`SDL_CreateThreadWithPropertiesRuntime`], so
427        /// there is no symbol clash, but trying to load an SDL shared library and look
428        /// for "SDL_CreateThreadWithProperties" will fail.
429        ///
430        /// Usually, apps should just call this function the same way on every platform
431        /// and let the macros hide the details.
432        ///
433        /// ## Parameters
434        /// - `props`: the properties to use.
435        ///
436        /// ## Return value
437        /// Returns an opaque pointer to the new thread object on success, NULL if the
438        ///   new thread could not be created; call [`SDL_GetError()`] for more
439        ///   information.
440        ///
441        /// ## Thread safety
442        /// It is safe to call this function from any thread.
443        ///
444        /// ## Availability
445        /// This function is available since SDL 3.2.0.
446        ///
447        /// ## See also
448        /// - [`SDL_CreateThread`]
449        /// - [`SDL_WaitThread`]
450        pub fn SDL_CreateThreadWithProperties(props: SDL_PropertiesID) -> *mut SDL_Thread;
451    }
452
453    pub const SDL_PROP_THREAD_CREATE_ENTRY_FUNCTION_POINTER: *const ::core::ffi::c_char = c"SDL.thread.create.entry_function".as_ptr();
454
455    pub const SDL_PROP_THREAD_CREATE_NAME_STRING: *const ::core::ffi::c_char = c"SDL.thread.create.name".as_ptr();
456
457    pub const SDL_PROP_THREAD_CREATE_USERDATA_POINTER: *const ::core::ffi::c_char = c"SDL.thread.create.userdata".as_ptr();
458
459    pub const SDL_PROP_THREAD_CREATE_STACKSIZE_NUMBER: *const ::core::ffi::c_char = c"SDL.thread.create.stacksize".as_ptr();
460
461});
462
463apply_cfg!(#[cfg(not(doc))] => {
464    apply_cfg!(#[cfg(any(doc, windows))] => {
465    });
466
467});
468
469apply_cfg!(#[cfg(not(doc))] => {
470});
471
472apply_cfg!(#[cfg(not(doc))] => {
473});
474
475apply_cfg!(#[cfg(not(doc))] => {
476    unsafe extern "C" {
477        /// The actual entry point for [`SDL_CreateThread`].
478        ///
479        /// ## Parameters
480        /// - `fn`: the [`SDL_ThreadFunction`] function to call in the new thread
481        /// - `name`: the name of the thread
482        /// - `data`: a pointer that is passed to `fn`
483        /// - `pfnBeginThread`: the C runtime's _beginthreadex (or whatnot). Can be NULL.
484        /// - `pfnEndThread`: the C runtime's _endthreadex (or whatnot). Can be NULL.
485        ///
486        /// ## Return value
487        /// Returns an opaque pointer to the new thread object on success, NULL if the
488        ///   new thread could not be created; call [`SDL_GetError()`] for more
489        ///   information.
490        ///
491        /// ## Thread safety
492        /// It is safe to call this function from any thread.
493        ///
494        /// ## Availability
495        /// This function is available since SDL 3.2.0.
496        pub fn SDL_CreateThreadRuntime(r#fn: SDL_ThreadFunction, name: *const ::core::ffi::c_char, data: *mut ::core::ffi::c_void, pfnBeginThread: SDL_FunctionPointer, pfnEndThread: SDL_FunctionPointer) -> *mut SDL_Thread;
497    }
498
499    unsafe extern "C" {
500        /// The actual entry point for [`SDL_CreateThreadWithProperties`].
501        ///
502        /// ## Parameters
503        /// - `props`: the properties to use
504        /// - `pfnBeginThread`: the C runtime's _beginthreadex (or whatnot). Can be NULL.
505        /// - `pfnEndThread`: the C runtime's _endthreadex (or whatnot). Can be NULL.
506        ///
507        /// ## Return value
508        /// Returns an opaque pointer to the new thread object on success, NULL if the
509        ///   new thread could not be created; call [`SDL_GetError()`] for more
510        ///   information.
511        ///
512        /// ## Thread safety
513        /// It is safe to call this function from any thread.
514        ///
515        /// ## Availability
516        /// This function is available since SDL 3.2.0.
517        pub fn SDL_CreateThreadWithPropertiesRuntime(props: SDL_PropertiesID, pfnBeginThread: SDL_FunctionPointer, pfnEndThread: SDL_FunctionPointer) -> *mut SDL_Thread;
518    }
519
520    #[cfg(not(windows))]
521    pub const SDL_BeginThreadFunction: SDL_FunctionPointer = unsafe { ::core::mem::transmute::<*const ::core::ffi::c_void, SDL_FunctionPointer>(core::ptr::null()) };
522    #[cfg(not(windows))]
523    pub const SDL_EndThreadFunction: SDL_FunctionPointer = unsafe { ::core::mem::transmute::<*const ::core::ffi::c_void, SDL_FunctionPointer>(core::ptr::null()) };
524    #[cfg(windows)]
525    unsafe extern "cdecl" {
526        fn _beginthreadex(security: *mut ::core::ffi::c_void, stack_size: ::core::ffi::c_uint, start_address: Option<unsafe extern "stdcall" fn(*const ::core::ffi::c_void) -> ::core::ffi::c_uint>, arglist: *mut ::core::ffi::c_void, initflag: ::core::ffi::c_uint, thrdaddr: ::core::ffi::c_uint) -> ::core::primitive::usize;
527        fn _endthreadex(retval: ::core::ffi::c_uint);
528    }
529    #[cfg(windows)]
530    pub const SDL_BeginThreadFunction: SDL_FunctionPointer = unsafe { ::core::mem::transmute::<unsafe extern "cdecl" fn(*mut ::core::ffi::c_void, ::core::ffi::c_uint, Option<unsafe extern "stdcall" fn(*const ::core::ffi::c_void) -> ::core::ffi::c_uint>, *mut ::core::ffi::c_void, ::core::ffi::c_uint, ::core::ffi::c_uint) -> ::core::primitive::usize, SDL_FunctionPointer>(_beginthreadex) };
531    #[cfg(windows)]
532    pub const SDL_EndThreadFunction: SDL_FunctionPointer = unsafe { ::core::mem::transmute::<unsafe extern "cdecl" fn (::core::ffi::c_uint), SDL_FunctionPointer>(_endthreadex) };
533
534    #[inline(always)]
535    pub unsafe fn SDL_CreateThread(r#fn: SDL_ThreadFunction, name: *const ::core::ffi::c_char, data: *mut ::core::ffi::c_void, ) -> *mut SDL_Thread {
536        unsafe { SDL_CreateThreadRuntime((r#fn), (name), (data), SDL_BeginThreadFunction, SDL_EndThreadFunction) }
537    }
538
539
540    #[inline(always)]
541    pub unsafe fn SDL_CreateThreadWithProperties(props: SDL_PropertiesID, ) -> *mut SDL_Thread {
542        unsafe { SDL_CreateThreadWithPropertiesRuntime(props, SDL_BeginThreadFunction, SDL_EndThreadFunction) }
543    }
544
545
546    pub const SDL_PROP_THREAD_CREATE_ENTRY_FUNCTION_POINTER: *const ::core::ffi::c_char = c"SDL.thread.create.entry_function".as_ptr();
547
548    pub const SDL_PROP_THREAD_CREATE_NAME_STRING: *const ::core::ffi::c_char = c"SDL.thread.create.name".as_ptr();
549
550    pub const SDL_PROP_THREAD_CREATE_USERDATA_POINTER: *const ::core::ffi::c_char = c"SDL.thread.create.userdata".as_ptr();
551
552    pub const SDL_PROP_THREAD_CREATE_STACKSIZE_NUMBER: *const ::core::ffi::c_char = c"SDL.thread.create.stacksize".as_ptr();
553
554});
555
556unsafe extern "C" {
557    /// Get the thread name as it was specified in [`SDL_CreateThread()`].
558    ///
559    /// ## Parameters
560    /// - `thread`: the thread to query.
561    ///
562    /// ## Return value
563    /// Returns a pointer to a UTF-8 string that names the specified thread, or
564    ///   NULL if it doesn't have a name.
565    ///
566    /// ## Thread safety
567    /// It is safe to call this function from any thread.
568    ///
569    /// ## Availability
570    /// This function is available since SDL 3.2.0.
571    pub fn SDL_GetThreadName(thread: *mut SDL_Thread) -> *const ::core::ffi::c_char;
572}
573
574unsafe extern "C" {
575    /// Get the thread identifier for the current thread.
576    ///
577    /// This thread identifier is as reported by the underlying operating system.
578    /// If SDL is running on a platform that does not support threads the return
579    /// value will always be zero.
580    ///
581    /// This function also returns a valid thread ID when called from the main
582    /// thread.
583    ///
584    /// ## Return value
585    /// Returns the ID of the current thread.
586    ///
587    /// ## Thread safety
588    /// It is safe to call this function from any thread.
589    ///
590    /// ## Availability
591    /// This function is available since SDL 3.2.0.
592    ///
593    /// ## See also
594    /// - [`SDL_GetThreadID`]
595    pub safe fn SDL_GetCurrentThreadID() -> SDL_ThreadID;
596}
597
598unsafe extern "C" {
599    /// Get the thread identifier for the specified thread.
600    ///
601    /// This thread identifier is as reported by the underlying operating system.
602    /// If SDL is running on a platform that does not support threads the return
603    /// value will always be zero.
604    ///
605    /// ## Parameters
606    /// - `thread`: the thread to query.
607    ///
608    /// ## Return value
609    /// Returns the ID of the specified thread, or the ID of the current thread if
610    ///   `thread` is NULL.
611    ///
612    /// ## Thread safety
613    /// It is safe to call this function from any thread.
614    ///
615    /// ## Availability
616    /// This function is available since SDL 3.2.0.
617    ///
618    /// ## See also
619    /// - [`SDL_GetCurrentThreadID`]
620    pub fn SDL_GetThreadID(thread: *mut SDL_Thread) -> SDL_ThreadID;
621}
622
623unsafe extern "C" {
624    /// Set the priority for the current thread.
625    ///
626    /// Note that some platforms will not let you alter the priority (or at least,
627    /// promote the thread to a higher priority) at all, and some require you to be
628    /// an administrator account. Be prepared for this to fail.
629    ///
630    /// ## Parameters
631    /// - `priority`: the [`SDL_ThreadPriority`] to set.
632    ///
633    /// ## Return value
634    /// Returns true on success or false on failure; call [`SDL_GetError()`] for more
635    ///   information.
636    ///
637    /// ## Thread safety
638    /// It is safe to call this function from any thread.
639    ///
640    /// ## Availability
641    /// This function is available since SDL 3.2.0.
642    pub fn SDL_SetCurrentThreadPriority(priority: SDL_ThreadPriority) -> ::core::primitive::bool;
643}
644
645unsafe extern "C" {
646    /// Wait for a thread to finish.
647    ///
648    /// Threads that haven't been detached will remain until this function cleans
649    /// them up. Not doing so is a resource leak.
650    ///
651    /// Once a thread has been cleaned up through this function, the [`SDL_Thread`]
652    /// that references it becomes invalid and should not be referenced again. As
653    /// such, only one thread may call [`SDL_WaitThread()`] on another.
654    ///
655    /// The return code from the thread function is placed in the area pointed to
656    /// by `status`, if `status` is not NULL.
657    ///
658    /// You may not wait on a thread that has been used in a call to
659    /// [`SDL_DetachThread()`]. Use either that function or this one, but not both, or
660    /// behavior is undefined.
661    ///
662    /// It is safe to pass a NULL thread to this function; it is a no-op.
663    ///
664    /// Note that the thread pointer is freed by this function and is not valid
665    /// afterward.
666    ///
667    /// ## Parameters
668    /// - `thread`: the [`SDL_Thread`] pointer that was returned from the
669    ///   [`SDL_CreateThread()`] call that started this thread.
670    /// - `status`: a pointer filled in with the value returned from the thread
671    ///   function by its 'return', or -1 if the thread has been
672    ///   detached or isn't valid, may be NULL.
673    ///
674    /// ## Thread safety
675    /// It is safe to call this function from any thread, but only a
676    ///   single thread can wait any specific thread to finish.
677    ///
678    /// ## Availability
679    /// This function is available since SDL 3.2.0.
680    ///
681    /// ## See also
682    /// - [`SDL_CreateThread`]
683    /// - [`SDL_DetachThread`]
684    pub fn SDL_WaitThread(thread: *mut SDL_Thread, status: *mut ::core::ffi::c_int);
685}
686
687unsafe extern "C" {
688    /// Get the current state of a thread.
689    ///
690    /// ## Parameters
691    /// - `thread`: the thread to query.
692    ///
693    /// ## Return value
694    /// Returns the current state of a thread, or [`SDL_THREAD_UNKNOWN`] if the thread
695    ///   isn't valid.
696    ///
697    /// ## Thread safety
698    /// It is safe to call this function from any thread.
699    ///
700    /// ## Availability
701    /// This function is available since SDL 3.2.0.
702    ///
703    /// ## See also
704    /// - [`SDL_ThreadState`]
705    pub fn SDL_GetThreadState(thread: *mut SDL_Thread) -> SDL_ThreadState;
706}
707
708unsafe extern "C" {
709    /// Let a thread clean up on exit without intervention.
710    ///
711    /// A thread may be "detached" to signify that it should not remain until
712    /// another thread has called [`SDL_WaitThread()`] on it. Detaching a thread is
713    /// useful for long-running threads that nothing needs to synchronize with or
714    /// further manage. When a detached thread is done, it simply goes away.
715    ///
716    /// There is no way to recover the return code of a detached thread. If you
717    /// need this, don't detach the thread and instead use [`SDL_WaitThread()`].
718    ///
719    /// Once a thread is detached, you should usually assume the [`SDL_Thread`] isn't
720    /// safe to reference again, as it will become invalid immediately upon the
721    /// detached thread's exit, instead of remaining until someone has called
722    /// [`SDL_WaitThread()`] to finally clean it up. As such, don't detach the same
723    /// thread more than once.
724    ///
725    /// If a thread has already exited when passed to [`SDL_DetachThread()`], it will
726    /// stop waiting for a call to [`SDL_WaitThread()`] and clean up immediately. It is
727    /// not safe to detach a thread that might be used with [`SDL_WaitThread()`].
728    ///
729    /// You may not call [`SDL_WaitThread()`] on a thread that has been detached. Use
730    /// either that function or this one, but not both, or behavior is undefined.
731    ///
732    /// It is safe to pass NULL to this function; it is a no-op.
733    ///
734    /// ## Parameters
735    /// - `thread`: the [`SDL_Thread`] pointer that was returned from the
736    ///   [`SDL_CreateThread()`] call that started this thread.
737    ///
738    /// ## Thread safety
739    /// It is safe to call this function from any thread.
740    ///
741    /// ## Availability
742    /// This function is available since SDL 3.2.0.
743    ///
744    /// ## See also
745    /// - [`SDL_CreateThread`]
746    /// - [`SDL_WaitThread`]
747    pub fn SDL_DetachThread(thread: *mut SDL_Thread);
748}
749
750unsafe extern "C" {
751    /// Get the current thread's value associated with a thread local storage ID.
752    ///
753    /// ## Parameters
754    /// - `id`: a pointer to the thread local storage ID, may not be NULL.
755    ///
756    /// ## Return value
757    /// Returns the value associated with the ID for the current thread or NULL if
758    ///   no value has been set; call [`SDL_GetError()`] for more information.
759    ///
760    /// ## Thread safety
761    /// It is safe to call this function from any thread.
762    ///
763    /// ## Availability
764    /// This function is available since SDL 3.2.0.
765    ///
766    /// ## See also
767    /// - [`SDL_SetTLS`]
768    pub fn SDL_GetTLS(id: *mut SDL_TLSID) -> *mut ::core::ffi::c_void;
769}
770
771/// The callback used to cleanup data passed to [`SDL_SetTLS`].
772///
773/// This is called when a thread exits, to allow an app to free any resources.
774///
775/// ## Parameters
776/// - `value`: a pointer previously handed to [`SDL_SetTLS`].
777///
778/// ## Availability
779/// This datatype is available since SDL 3.2.0.
780///
781/// ## See also
782/// - [`SDL_SetTLS`]
783pub type SDL_TLSDestructorCallback =
784    ::core::option::Option<unsafe extern "C" fn(value: *mut ::core::ffi::c_void)>;
785
786unsafe extern "C" {
787    /// Set the current thread's value associated with a thread local storage ID.
788    ///
789    /// If the thread local storage ID is not initialized (the value is 0), a new
790    /// ID will be created in a thread-safe way, so all calls using a pointer to
791    /// the same ID will refer to the same local storage.
792    ///
793    /// Note that replacing a value from a previous call to this function on the
794    /// same thread does _not_ call the previous value's destructor!
795    ///
796    /// `destructor` can be NULL; it is assumed that `value` does not need to be
797    /// cleaned up if so.
798    ///
799    /// ## Parameters
800    /// - `id`: a pointer to the thread local storage ID, may not be NULL.
801    /// - `value`: the value to associate with the ID for the current thread.
802    /// - `destructor`: a function called when the thread exits, to free the
803    ///   value, may be NULL.
804    ///
805    /// ## Return value
806    /// Returns true on success or false on failure; call [`SDL_GetError()`] for more
807    ///   information.
808    ///
809    /// ## Thread safety
810    /// It is safe to call this function from any thread.
811    ///
812    /// ## Availability
813    /// This function is available since SDL 3.2.0.
814    ///
815    /// ## See also
816    /// - [`SDL_GetTLS`]
817    pub fn SDL_SetTLS(
818        id: *mut SDL_TLSID,
819        value: *const ::core::ffi::c_void,
820        destructor: SDL_TLSDestructorCallback,
821    ) -> ::core::primitive::bool;
822}
823
824unsafe extern "C" {
825    /// Cleanup all TLS data for this thread.
826    ///
827    /// If you are creating your threads outside of SDL and then calling SDL
828    /// functions, you should call this function before your thread exits, to
829    /// properly clean up SDL memory.
830    ///
831    /// ## Thread safety
832    /// It is safe to call this function from any thread.
833    ///
834    /// ## Availability
835    /// This function is available since SDL 3.2.0.
836    pub fn SDL_CleanupTLS();
837}
838
839/// The SDL thread object.
840///
841/// These are opaque data.
842///
843/// ## Availability
844/// This datatype is available since SDL 3.2.0.
845///
846/// ## See also
847/// - [`SDL_CreateThread`]
848/// - [`SDL_WaitThread`]
849#[repr(C)]
850pub struct SDL_Thread {
851    _opaque: [::core::primitive::u8; 0],
852}
853
854#[cfg(doc)]
855use crate::everything::*;
sdl3_sys/generated/thread.rs

sdl3_sys/generated/
thread.rs
