1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

//! Sys api.
//!
//! The sys api is exposed by the [SysAPI] trait.
use crate::ffi::collections::NonNullConst;
use crate::ffi::sys::api::SysBinding;
use crate::ffi::Bool;
use crate::fn_caster::FnCaster;
use crate::sys::sync_handler::SyncHandlerAPI;
use std::ffi::CStr;

pub mod sync_handler;

/// Minimal sys api.
pub trait SysAPIMin<'interface> {
    /// Execution of the program is stopped abruptly. The error may be logged.
    fn panic(&self, error: Option<impl AsRef<CStr>>) -> !;

    /// Checks if a function is implemented.
    ///
    /// # Return
    ///
    /// Returns [true] if the function exists, [false] otherwise.
    fn has_function<U>(&self) -> bool
    where
        U: FnCaster;

    /// Fetches a function from the interface.
    ///
    /// # Return
    ///
    /// Function casted to the appropriate type.
    fn get_function<U>(&self, caster: &U) -> Option<<U as FnCaster>::Type>
    where
        U: FnCaster;
}

/// Idiomatic sys api.
pub trait SysAPI<'interface>: SysAPIMin<'interface> {
    /// Sends a termination signal.
    fn shutdown(&mut self) -> !;

    /// Fetches the active synchronization handler.
    ///
    /// # Return
    ///
    /// The active synchronization handler.
    fn get_sync_handler<U>(&self) -> <U as SyncHandlerAPI<'interface>>::Handler
    where
        U: SyncHandlerAPI<'interface>;

    /// Sets a new synchronization handler.
    ///
    /// The default synchronization handler is used, if `handler` is [Option::None].
    ///
    /// # Uses
    ///
    /// This function can be used by modules, that want to provide a more complex
    /// synchronization mechanism than the one presented by the default handler.
    ///
    /// # Swapping
    ///
    /// The swapping occurs in three steps:
    ///
    /// 1. The new synchronization handler is locked.
    /// 2. The new synchronization handler is set as the active synchronization handler.
    /// 3. The old synchronization handler is unlocked.
    ///
    /// # Safety
    ///
    /// Changing the synchronization handler may break some modules,
    /// if they depend on a specific synchronization handler.
    unsafe fn set_sync_handler(&mut self, handler: Option<&impl SyncHandlerAPI<'interface>>);
}

impl<'interface, T> SysAPIMin<'interface> for T
where
    T: SysBinding,
{
    #[inline]
    fn panic(&self, error: Option<impl AsRef<CStr>>) -> ! {
        unsafe {
            <T as SysBinding>::panic(
                self,
                error.map(|err| NonNullConst::from(err.as_ref().to_bytes_with_nul())),
            )
        }
    }

    #[inline]
    fn has_function<U>(&self) -> bool
    where
        U: FnCaster,
    {
        unsafe { <T as SysBinding>::has_function(self, U::ID) == Bool::True }
    }

    #[inline]
    fn get_function<U>(&self, caster: &U) -> Option<<U as FnCaster>::Type>
    where
        U: FnCaster,
    {
        unsafe {
            <T as SysBinding>::get_function(self, U::ID)
                .to_option()
                .map(|func| caster.cast(func))
        }
    }
}

impl<'interface, T> SysAPI<'interface> for T
where
    T: SysBinding,
{
    #[inline]
    fn shutdown(&mut self) -> ! {
        unsafe { <T as SysBinding>::shutdown(self) }
    }

    #[inline]
    fn get_sync_handler<U>(&self) -> <U as SyncHandlerAPI<'interface>>::Handler
    where
        U: SyncHandlerAPI<'interface>,
    {
        unsafe { U::from_interface(<T as SysBinding>::get_sync_handler(self)) }
    }

    #[inline]
    unsafe fn set_sync_handler(&mut self, handler: Option<&impl SyncHandlerAPI<'interface>>) {
        <T as SysBinding>::set_sync_handler(self, handler.map(|handler| handler.to_interface()))
    }
}