xenstore_rs/
lib.rs

1//! Xenstore implementation for Rust.
2//!
3//! Xenstore is a shared database protocol for Xen domains used for
4//! Xen PV devices (xenbus), guest agents, toolstack, ...
5//!
6//! Check docs/misc/xenstore.txt in xen source code for detailed informations.
7
8pub(crate) mod wire;
9
10#[cfg(not(target_os = "windows"))]
11#[cfg(feature = "unix")]
12pub mod unix;
13
14#[cfg(not(target_os = "windows"))]
15#[cfg(feature = "async-tokio")]
16pub mod tokio;
17
18use std::io;
19
20/// Xenstore base trait.
21/// All xenstore implementations must implement this trait.
22pub trait Xs {
23    /// Try to list the files of a directory.
24    fn directory(&self, path: &str) -> io::Result<Vec<Box<str>>>;
25
26    /// Read a node.
27    fn read(&self, path: &str) -> io::Result<Box<str>>;
28
29    /// Write a node.
30    fn write(&self, path: &str, data: &str) -> io::Result<()>;
31
32    /// Remove a node.
33    fn rm(&self, path: &str) -> io::Result<()>;
34}
35
36/// Xenstore transaction capability trait.
37///
38/// A transaction can be created with [XsTransaction::transaction] as a [XsTransactionSpan].
39/// This span can be used to make operation within this transaction and be effective
40/// only if the transaction is commited ([XsTransactionSpan::commit]).
41///
42/// If you want to discard the transaction and make its changes effective, use
43/// [XsTransactionSpan::commit].
44///
45/// # Drop
46///
47/// [Drop] is called on a transaction, it is aborted.
48pub trait XsTransaction: Xs {
49    type Span: Xs; // + 'static ?
50
51    fn transaction(&self) -> io::Result<Self::Span>;
52}
53
54/// Refer to [XsTransaction] for more information.
55pub trait XsTransactionSpan: Xs {
56    /// Commit a transaction.
57    fn commit(self) -> io::Result<()>;
58}
59
60/// [`Xs`] async variant.
61#[cfg(feature = "async")]
62#[trait_variant::make(AsyncXs: Send)]
63pub trait LocalAsyncXs {
64    /// Try to list the files of a directory.
65    async fn directory(&self, path: &str) -> io::Result<Vec<Box<str>>>;
66
67    /// Read a node.
68    async fn read(&self, path: &str) -> io::Result<Box<str>>;
69
70    /// Write a node.
71    async fn write(&self, path: &str, data: &str) -> io::Result<()>;
72
73    /// Remove a node.
74    async fn rm(&self, path: &str) -> io::Result<()>;
75}
76
77/// [`XsTransaction`] async variant.
78#[cfg(feature = "async")]
79#[trait_variant::make(AsyncXsTransaction: Send)]
80pub trait LocalAsyncXsTransaction: AsyncXs {
81    type Span: Xs;
82
83    async fn transaction(&self) -> io::Result<Self::Span>;
84}
85
86/// [`XsTransactionSpan`] async variant.
87#[cfg(feature = "async")]
88#[trait_variant::make(AsyncXsTransactionSpan: Send)]
89pub trait LocalAsyncXsTransactionSpan: Xs {
90    /// Commit a transaction.
91    async fn commit(self) -> io::Result<()>;
92}
93
94/// Xenstore watch capability trait.
95#[cfg(feature = "async")]
96#[trait_variant::make(AsyncWatch: Send)]
97pub trait LocalAsyncWatch {
98    /// Create a [`futures::Stream`] yielding paths of updated nodes/subnodes.
99    async fn watch(
100        &self,
101        path: &str,
102    ) -> io::Result<impl futures::Stream<Item = Box<str>> + Unpin + 'static>;
103}
xenstore_rs/lib.rs

xenstore_rs/
lib.rs
