hl-engine 0.1.0

Safe Rust lifecycle API for the standalone HL Linux guest engine
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
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147

#![allow(unsafe_code)]
use std::{
    ffi::{c_char, c_int, c_void},
    fs::File,
    os::fd::FromRawFd,
};

#[repr(C)]
pub(crate) struct Process {
    _private: [u8; 0],
}
#[derive(Debug)]
pub(crate) struct Handle(*mut Process);
// SAFETY: activation processes have no thread affinity. The safe wrapper never
// exposes the pointer, provides no concurrent access, and destroys it exactly once.
unsafe impl Send for Handle {}
#[repr(C)]
pub(crate) struct Streams {
    pub input: i32,
    pub output: i32,
    pub error: i32,
}
#[repr(C)]
#[derive(Clone, Copy)]
pub(crate) struct EngineExit {
    pub abi: u32,
    pub size: u32,
    pub kind: u32,
    pub guest_status: i32,
    pub detail: u64,
}
impl Default for EngineExit {
    fn default() -> Self {
        Self {
            abi: 4,
            size: 24,
            kind: 0,
            guest_status: 0,
            detail: 0,
        }
    }
}

unsafe extern "C" {
    pub(crate) fn hl_activation_start_with_stdio(
        executable: *const c_char,
        guest: u32,
        config: *const c_char,
        streams: *const Streams,
        process: *mut *mut Process,
    ) -> i32;
    pub(crate) fn hl_activation_wait(process: *mut Process, exit: *mut EngineExit) -> i32;
    pub(crate) fn hl_activation_try_wait(
        process: *mut Process,
        ready: *mut u32,
        exit: *mut EngineExit,
    ) -> i32;
    pub(crate) fn hl_activation_kill(process: *mut Process) -> i32;
    pub(crate) fn hl_activation_process_destroy(process: *mut Process);
    pub(crate) fn hl_activation_process_id(process: *const Process, id: *mut u64) -> i32;
    fn pipe(descriptors: *mut c_int) -> c_int;
    fn fcntl(descriptor: c_int, command: c_int, ...) -> c_int;
}

pub(crate) fn start(
    executable: &std::ffi::CStr,
    guest: u32,
    config: &std::ffi::CStr,
    streams: &Streams,
) -> Result<Handle, i32> {
    let mut process = std::ptr::null_mut();
    let status = unsafe {
        hl_activation_start_with_stdio(
            executable.as_ptr(),
            guest,
            config.as_ptr(),
            streams,
            &mut process,
        )
    };
    if status == 0 && !process.is_null() {
        Ok(Handle(process))
    } else {
        Err(status)
    }
}
pub(crate) fn wait(process: &Handle) -> Result<EngineExit, i32> {
    let mut exit = EngineExit::default();
    let status = unsafe { hl_activation_wait(process.0, &mut exit) };
    if status == 0 {
        Ok(exit)
    } else {
        Err(status)
    }
}
pub(crate) fn try_wait(process: &Handle) -> Result<Option<EngineExit>, i32> {
    let mut ready = 0;
    let mut exit = EngineExit::default();
    let status = unsafe { hl_activation_try_wait(process.0, &mut ready, &mut exit) };
    if status != 0 {
        Err(status)
    } else if ready == 0 {
        Ok(None)
    } else {
        Ok(Some(exit))
    }
}
pub(crate) fn kill(process: &Handle) -> Result<(), i32> {
    let status = unsafe { hl_activation_kill(process.0) };
    if status == 0 {
        Ok(())
    } else {
        Err(status)
    }
}
#[allow(clippy::needless_pass_by_value)] // Consumption enforces exactly-once destruction.
pub(crate) fn destroy(process: Handle) {
    unsafe { hl_activation_process_destroy(process.0) }
}
pub(crate) fn process_id(process: &Handle) -> Result<u64, i32> {
    let mut id = 0;
    let status = unsafe { hl_activation_process_id(process.0, &mut id) };
    if status == 0 {
        Ok(id)
    } else {
        Err(status)
    }
}
pub(crate) fn pipe_pair() -> std::io::Result<(File, File)> {
    const F_SETFD: c_int = 2;
    const FD_CLOEXEC: c_int = 1;
    let mut descriptors = [-1, -1];
    if unsafe { pipe(descriptors.as_mut_ptr()) } != 0 {
        return Err(std::io::Error::last_os_error());
    }
    let read = unsafe { File::from_raw_fd(descriptors[0]) };
    let write = unsafe { File::from_raw_fd(descriptors[1]) };
    if unsafe { fcntl(descriptors[0], F_SETFD, FD_CLOEXEC) } != 0
        || unsafe { fcntl(descriptors[1], F_SETFD, FD_CLOEXEC) } != 0
    {
        return Err(std::io::Error::last_os_error());
    }
    Ok((read, write))
}

const _: () = assert!(std::mem::size_of::<EngineExit>() == 24);
const _: () = assert!(std::mem::size_of::<*mut c_void>() == std::mem::size_of::<usize>());