third_party/wayland-commons/src/lib.rs

//! Common definitions for wayland
//!
//! This crate hosts common type and traits used to represent wayland messages
//! and routines in the `wayland-client` and `wayland-server` crates.
//!
//! This notably includes the `Interface` trait, which can exhaustively describe
//! any wayland interface. Its implementations are intended to be generated by the
//! `wayland-scanner` crate.
//!
//! The principal user-facing definition provided by this crate is the `Implementation`
//! trait, which as a user of `wayland-client` or `wayland-server` you will be using
//! to define objects able to handle the messages your program receives. Note that
//! this trait is auto-implemented for closures with appropriate signature, for
//! convenience.

#![warn(missing_docs, missing_debug_implementations)]

#[macro_use]
extern crate nix;

use std::os::raw::c_void;
use wayland_sys::common as syscom;

pub mod debug;
pub mod filter;
pub mod map;
pub mod socket;
pub mod user_data;
pub mod wire;

pub use smallvec::smallvec;

/// A group of messages
///
/// This represents a group of message that can be serialized on the protocol wire.
/// Typically the set of events or requests of a single interface.
///
/// Implementations of this trait are supposed to be
/// generated using the `wayland-scanner` crate.
pub trait MessageGroup: Sized {
    /// Wire representation of this MessageGroup
    const MESSAGES: &'static [wire::MessageDesc];
    /// The wrapper type for ObjectMap allowing the mapping of Object and
    /// NewId arguments to the object map during parsing.
    type Map;
    /// The opcode of this message
    fn opcode(&self) -> u16;
    /// Whether this message is a destructor
    ///
    /// If it is, once send or receive the associated object cannot be used any more.
    fn is_destructor(&self) -> bool;
    /// The minimal object version for which this message exists
    fn since(&self) -> u32;
    /// Retrieve the child `Object` associated with this message if any
    fn child<Meta: self::map::ObjectMetadata>(
        opcode: u16,
        version: u32,
        meta: &Meta,
    ) -> Option<crate::map::Object<Meta>>;
    /// Construct a message from its raw representation
    // -- The lint is allowed because fixing it would be a breaking change --
    #[allow(clippy::result_unit_err)]
    fn from_raw(msg: wire::Message, map: &mut Self::Map) -> Result<Self, ()>;
    /// Turn this message into its raw representation
    fn into_raw(self, send_id: u32) -> wire::Message;
    /// Construct a message of this group from its C representation
    ///
    /// # Safety
    ///
    /// The pointers provided to this function must all be valid pointers from
    /// `libwayland-client`
    // -- The lint is allowed because fixing it would be a breaking change --
    #[allow(clippy::result_unit_err)]
    unsafe fn from_raw_c(
        obj: *mut c_void,
        opcode: u32,
        args: *const syscom::wl_argument,
    ) -> Result<Self, ()>;
    /// Build a C representation of this message
    ///
    /// It can only be accessed from the provided closure, and this consumes
    /// the message.
    // -- The lint is allowed because fixing it would be a breaking change --
    #[allow(clippy::wrong_self_convention)]
    fn as_raw_c_in<F, T>(self, f: F) -> T
    where
        F: FnOnce(u32, &mut [syscom::wl_argument]) -> T;
}

/// The description of a wayland interface
///
/// Implementations of this trait are supposed to be
/// generated using the `wayland-scanner` crate.
pub trait Interface: 'static {
    /// Set of requests associated to this interface
    ///
    /// Requests are messages from the client to the server
    type Request: MessageGroup + 'static;
    /// Set of events associated to this interface
    ///
    /// Events are messages from the server to the client
    type Event: MessageGroup + 'static;
    /// Name of this interface
    const NAME: &'static str;
    /// Maximum supported version of this interface
    ///
    /// This is the maximum version supported by the protocol specification currently
    /// used by this library, and should not be used as-is in your code, as a version
    /// change can subtly change the behavior of some objects.
    ///
    /// Server are supposed to be able to handle all versions from 1 to the one they
    /// advertise through the registry, and clients can choose any version among the
    /// ones the server supports.
    const VERSION: u32;
    /// Pointer to the C representation of this interface
    fn c_interface() -> *const syscom::wl_interface;
}

/// An empty enum representing a MessageGroup with no messages
#[derive(Debug)]
pub enum NoMessage {}

#[cfg(not(tarpaulin_include))]
impl MessageGroup for NoMessage {
    const MESSAGES: &'static [wire::MessageDesc] = &[];
    type Map = ();
    fn is_destructor(&self) -> bool {
        match *self {}
    }
    fn opcode(&self) -> u16 {
        match *self {}
    }
    fn since(&self) -> u32 {
        match *self {}
    }
    fn child<M: self::map::ObjectMetadata>(_: u16, _: u32, _: &M) -> Option<crate::map::Object<M>> {
        None
    }
    fn from_raw(_: wire::Message, _: &mut ()) -> Result<Self, ()> {
        Err(())
    }
    fn into_raw(self, _: u32) -> wire::Message {
        match self {}
    }
    unsafe fn from_raw_c(
        _obj: *mut c_void,
        _opcode: u32,
        _args: *const syscom::wl_argument,
    ) -> Result<Self, ()> {
        Err(())
    }
    fn as_raw_c_in<F, T>(self, _f: F) -> T
    where
        F: FnOnce(u32, &mut [syscom::wl_argument]) -> T,
    {
        match self {}
    }
}

/// Stores a value in a threadafe container that
/// only lets you access it from its owning thread
///
/// If the ThreadGuard is dropped from the wrong thread,
/// the underlying value will be leaked.
#[derive(Debug)]
pub struct ThreadGuard<T: ?Sized> {
    thread: std::thread::ThreadId,
    val: std::mem::ManuallyDrop<T>,
}

impl<T> ThreadGuard<T> {
    /// Create a new ThreadGuard wrapper
    pub fn new(val: T) -> ThreadGuard<T> {
        ThreadGuard { val: std::mem::ManuallyDrop::new(val), thread: std::thread::current().id() }
    }
}

impl<T: ?Sized> ThreadGuard<T> {
    /// Access the underlying value
    ///
    /// Panics if done on the wrong thread
    pub fn get(&self) -> &T {
        self.try_get().expect("Attempted to access a ThreadGuard contents from the wrong thread.")
    }

    /// Mutably access the underlying value
    ///
    /// Panics if done on the wrong thread
    pub fn get_mut(&mut self) -> &mut T {
        self.try_get_mut()
            .expect("Attempted to access a ThreadGuard contents from the wrong thread.")
    }

    /// Try to access the underlying value
    ///
    /// Returns `None` if done on the wrong thread
    pub fn try_get(&self) -> Option<&T> {
        if self.thread == ::std::thread::current().id() {
            Some(&self.val)
        } else {
            None
        }
    }

    /// Try to mutably access the underlying value
    ///
    /// Returns `None` if done on the wrong thread
    pub fn try_get_mut(&mut self) -> Option<&mut T> {
        if self.thread == ::std::thread::current().id() {
            Some(&mut self.val)
        } else {
            None
        }
    }
}

impl<T: ?Sized> Drop for ThreadGuard<T> {
    fn drop(&mut self) {
        // We can only actually perform the drop if we are on the right thread
        // otherwise it may be racy, so we just leak the value
        if self.thread == ::std::thread::current().id() {
            unsafe { std::mem::ManuallyDrop::drop(&mut self.val) }
        }
    }
}

unsafe impl<T: ?Sized> Send for ThreadGuard<T> {}
unsafe impl<T: ?Sized> Sync for ThreadGuard<T> {}