argdata 0.1.2

Argdata: A binary serialization format.
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
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

use std::os::raw::c_int;

/// A file descriptor of the current process.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct Fd(pub c_int);

/// A file descriptor in some argdata.
#[derive(Clone, Copy)]
pub struct EncodedFd<T> {
	pub(crate) raw: u32,
	pub(crate) convert_fd: T,
}

/// An error indicating that the encoded fd number is invalid:
/// It doesn't refer to any file descriptor.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct InvalidFd;

/// Something that can convert encoded fd numbers to actual Fds.
pub trait ConvertFd: Sync {
	/// Converts an encoded fd number to an actual Fd.
	fn convert_fd(&self, raw: u32) -> Result<Fd, InvalidFd>;
}

/// The identity conversion: Convert numbers to Fds with the exact same number.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Identity;

/// Don't provide any access to Fds. Every conversion will fail.
///
/// Use this if the encoded numbers (if any) do not correspond to any real file
/// descriptors of this process.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct NoConvert;

/// Convert encoded fd numbers to Fds using the given function.
#[derive(Clone, Copy)]
pub struct ConvertFdFn<F: Fn(u32) -> Result<Fd, InvalidFd>>(pub F);

impl<T: ConvertFd> EncodedFd<T> {
	/// Create an EncodedFd that will convert `raw` to an `Fd` using `convert_fd`.
	pub fn new(raw: u32, convert_fd: T) -> EncodedFd<T> {
		EncodedFd { raw, convert_fd }
	}

	/// The 32-bit file descriptor number exactly as encoded in the raw argdata.
	pub fn raw_encoded_number(&self) -> u32 {
		self.raw
	}

	/// Converts this to a valid file descriptor, if possible.
	///
	/// On failure, the raw encoded number is returned as an error.
	pub fn to_fd(&self) -> Result<Fd, u32> {
		self.convert_fd
			.convert_fd(self.raw)
			.map_err(|InvalidFd| self.raw)
	}
}

impl ConvertFd for Identity {
	fn convert_fd(&self, fd: u32) -> Result<Fd, InvalidFd> {
		Ok(Fd(fd as c_int))
	}
}

impl ConvertFd for NoConvert {
	fn convert_fd(&self, _: u32) -> Result<Fd, InvalidFd> {
		Err(InvalidFd)
	}
}

impl<F> ConvertFd for ConvertFdFn<F>
where
	F: Fn(u32) -> Result<Fd, InvalidFd> + Sync,
{
	fn convert_fd(&self, fd: u32) -> Result<Fd, InvalidFd> {
		self.0(fd)
	}
}

impl<'a, T> ConvertFd for &'a T
where
	T: ConvertFd + 'a + ?Sized,
{
	fn convert_fd(&self, fd: u32) -> Result<Fd, InvalidFd> {
		(*self).convert_fd(fd)
	}
}

/// Something that can convert actual Fds to encoded fd numbers.
pub trait FdMapping {
	fn map(&mut self, fd: Fd) -> u32;
}

/// Will number the encoded fds sequentially, storing the actual Fds in the
/// vector at the index of the encoded fd.
///
/// No duplicates will be stored, as (indexes of) existing Fds in the vector
/// are (re)used.
impl FdMapping for Vec<Fd> {
	fn map(&mut self, new_fd: Fd) -> u32 {
		for (i, fd) in self.iter().enumerate() {
			if fd.0 == new_fd.0 {
				return i as u32;
			}
		}
		let new_i = self.len() as u32;
		self.push(new_fd);
		new_i
	}
}

impl<T> std::fmt::Debug for EncodedFd<T> {
	fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
		write!(f, "EncodedFd(0x{:08X})", self.raw)
	}
}