vpp-plugin 0.2.2

A framework for writing high-performance, reliable VPP plugins in Rust.
Documentation 
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

//! VPP vlib main structure wrapper
//!
//! This module contains abstractions around VPP's `vlib_main_t` structure.
//! It provides safe access to the main VPP library context.

use std::ops::Deref;

use crate::bindings::vlib_main_t;

pub mod sync;

/// Reference to VPP per-thread main library context
///
/// This is a safe wrapper around `vlib_main_t`, providing access to its fields.
///
/// A `&mut MainRef` is equivalent to a `vlib_main_t *` in C (a `*mut vlib_main_t` in Rust).
///
/// See also [`BarrierHeldMainRef`] for a variant that indicates the caller holds the
/// main thread barrier.
#[repr(transparent)]
pub struct MainRef(foreign_types::Opaque);

impl MainRef {
    /// Creates a `&mut MainRef` directly from a pointer
    ///
    /// # Safety
    /// - The pointer must be valid and a properly initialised `vlib_main_t` for the thread.
    /// - The pointer must stay valid and the contents must not be mutated for the duration of the
    ///   lifetime of the returned object.
    /// - The `vlib_main_t` must have been created by VPP at startup and not manually by the
    ///   caller, as many datastructures size the memory they allocate by the number of threads
    ///   at startup and are subsequently indexed by thread index.
    pub unsafe fn from_ptr_mut<'a>(ptr: *mut vlib_main_t) -> &'a mut Self {
        // SAFETY: caller must ensure the safety requirements are met
        unsafe { &mut *(ptr as *mut _) }
    }

    /// Returns the raw pointer to the underlying `vlib_main_t`
    pub fn as_ptr(&self) -> *mut vlib_main_t {
        self as *const _ as *mut _
    }

    /// Returns the 0-based thread index of this VPP main context
    pub fn thread_index(&self) -> u16 {
        // SAFETY: as long as `self` is a valid `MainRef`, so is the pointer dereference
        unsafe { (*self.as_ptr()).thread_index }
    }
}

/// Reference to VPP per-thread main library context with barrier held
///
/// This is a safe wrapper around `vlib_main_t`, providing access to its fields.
///
/// A `&mut BarrierHeldMainRef` is equivalent to a `vlib_main_t *` in C (a `*mut vlib_main_t` in
/// Rust).
///
/// See also [`MainRef`] for a variant without the constraint that the caller holds the
/// main thread barrier.
pub struct BarrierHeldMainRef(MainRef);

impl BarrierHeldMainRef {
    /// Creates a `&mut BarrierHeldMainRef` directly from a pointer
    ///
    /// # Safety
    /// - All the safety requirements of [`MainRef::from_ptr_mut`] apply.
    /// - Additionally, the caller must that no other thread is concurrently accessing VPP data
    ///   structures. This is typically ensured by holding the main thread barrier, but also
    ///   applies during initialisation before worker threads are started or shutdown after
    ///   worker threads are stopped.
    pub unsafe fn from_ptr_mut<'a>(ptr: *mut vlib_main_t) -> &'a mut Self {
        // SAFETY: caller must ensure the safety requirements are met
        unsafe {
            // Sanity check: barrier should only ever be held on main thread
            debug_assert!((*ptr).thread_index == 0);
            &mut *(ptr as *mut _)
        }
    }
}

impl Deref for BarrierHeldMainRef {
    type Target = MainRef;

    fn deref(&self) -> &Self::Target {
        &self.0
    }
}