Quelle  lib.rs

/*
 * Copyright (c) 2025 Google Inc. All rights reserved
 *
 * Permission is hereby granted, free of charge, to any person obtaining
 * a copy of this software and associated documentation files
 * (the "Software"), to deal in the Software without restriction,
 * including without limitation the rights to use, copy, modify, merge,
 * publish, distribute, sublicense, and/or sell copies of the Software,
 * and to permit persons to whom the Software is furnished to do so,
 * subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */

#![no_std]

pub use crate::sys::event_client_notify_handled;
pub use crate::sys::event_source_create;
pub use crate::sys::event_source_open;
pub use crate::sys::event_source_publish;
pub use crate::sys::event_source_signal;
use alloc::ffi::CString;
use alloc::vec::Vec;
use core::ffi::CStr;
use core::ptr::null;
use core::ptr::null_mut;
use peer_id::Uuid;
use rust_support::handle::handle;
use rust_support::handle::handle_close;
use rust_support::Error as LkError;

type Result<T> = core::result::Result<T, LkError>;

mod sys {
    #![allow(unused)]
    #![allow(non_camel_case_types)]
    use peer_id::{uuid, uuid_t};
    use rust_support::handle::handle;
    include!(env!("BINDGEN_INC_FILE"));
}

/// An event source which owns the buffer for its name, the UUIDs allowed to access it and the
/// backing event_source object. Dropping this closes the handle which destroys the backing
/// event_source.
#[derive(Debug)]
pub struct EventSource {
    evt_handle: *mut handle,
    // The following are not accessed but need to be stored to ensure they live as long as the
    // event_source.
    _evt_name: CString,
    _uuids: Vec<Uuid>,
}

// SAFETY: Once created the only modifications to EventSource allowed are publishing and signaling
// which may both happen concurrently from multiple threads since the backing event_source object
// grabs locks for both these functions.
unsafe impl Sync for EventSource {}

// SAFETY: EventSource may be sent between threads since any thread is allowed to publish and signal
// it, not just the thread that created it.
unsafe impl Send for EventSource {}

impl EventSource {
    /// Creates a new event_source object.
    ///
    /// The event name must be unique otherwise an error is returned.
    pub fn create(evt_name: CString, uuids: Vec<Uuid>) -> Result<Self> {
        let mut evt_handle = null_mut();
        // SAFETY: The pointer to the name lives as long as needed since it's owned by the returned
        // Self and moving it in the return value does not change the address it points to. The
        // pointer to the UUIDs lives long enough since it is owned by the EventSource. The
        // reference to the event handle out parameter also lives as long as needed since it's a
        // local in this function.
        let rc = unsafe {
            event_source_create(
                evt_name.as_ptr(),
                null(), /* event_source_ops */
                null(), /* ops_arg */
                uuids.as_ptr(),
                uuids.len().try_into().unwrap(), /* usize to u32 conversion should not fail */
                0,                               /* reserved flag MBZ */
                &mut evt_handle,
            )
        };
        if rc < 0 {
            LkError::from_lk(rc)?;
        }
        Ok(Self { evt_handle, _evt_name: evt_name, _uuids: uuids })
    }

    /// Publish the event source to allow clients to open it.
    pub fn publish(&self) -> Result<()> {
        // SAFETY: evt_handle is a handle pointer initialized by event_source_create.
        let rc = unsafe { event_source_publish(self.evt_handle) };
        if rc < 0 {
            LkError::from_lk(rc)?;
        }
        Ok(())
    }

    /// Signal an event.
    ///
    /// Signaling without publishing does nothing since clients cannot open the event_source before
    /// it's published.
    pub fn signal(&self) -> Result<()> {
        // SAFETY: evt_handle is a handle pointer initialized by event_source_create.
        let rc = unsafe { event_source_signal(self.evt_handle) };
        if rc < 0 {
            LkError::from_lk(rc)?;
        }
        Ok(())
    }

    pub fn handle(&self) -> *mut handle {
        self.evt_handle
    }
}

impl Drop for EventSource {
    fn drop(&mut self) {
        // SAFETY: evt_handle is a handle pointer initialized by event_source_create.
        unsafe { handle_close(self.evt_handle) }
    }
}

/// An event source client which owns the backing event_client object.
/// Dropping this closes the handle which destroys the backing event_client.
#[derive(Debug)]
pub struct EventClient {
    evt_handle: *mut handle,
}

// SAFETY: Once created the only modification to EventClient allowed is notifying the source which
// may both happen concurrently from multiple threads since the backing event_client object grabs
// a lock for this function.
unsafe impl Sync for EventClient {}

// SAFETY: EventClient may be sent between threads since any thread is allowed to notify the source,
// not just the thread that created it.
unsafe impl Send for EventClient {}

impl EventClient {
    /// Open a published event source.
    pub fn open(evt_name: &CStr, uuid: Uuid) -> Result<Self> {
        let mut evt_handle = null_mut();
        // SAFETY: The pointers to the UUID and name only need to live for the lifetime of the call
        // to event_source_open since they are only used to lookup the existing event. The reference
        // to the event handle out parameter also lives as long as needed since it's a local in this
        // function.
        let rc = unsafe {
            event_source_open(
                &uuid as *const Uuid,
                evt_name.as_ptr(),
                evt_name.to_bytes_with_nul().len(),
                0, /* reserved flag MBZ */
                &mut evt_handle,
            )
        };
        if rc < 0 {
            LkError::from_lk(rc)?;
        }
        Ok(Self { evt_handle })
    }

    /// Notify the event source that the client has handled the signal.
    pub fn notify_handled(&self) -> Result<()> {
        // SAFETY: evt_handle is a handle pointer initialized by event_source_open.
        let rc = unsafe { event_client_notify_handled(self.evt_handle) };
        if rc < 0 {
            LkError::from_lk(rc)?;
        }
        Ok(())
    }

    pub fn handle(&self) -> *mut handle {
        self.evt_handle
    }
}

impl Drop for EventClient {
    fn drop(&mut self) {
        // SAFETY: evt_handle is a handle pointer initialized by event_source_open.
        unsafe { handle_close(self.evt_handle) }
    }
}