rflow 0.1.2

Text protocol for embedded apps
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
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

#![ doc = include_str!( concat!( env!( "CARGO_MANIFEST_DIR" ), "/", "README.md" ) ) ]
#![deny(missing_docs)]

use core::fmt;
use std::{net::ToSocketAddrs, time::Duration};

use once_cell::sync::Lazy;

mod server;
pub use server::Server;

mod client;
pub use client::{Client, ConnectionOptions};

#[cfg(feature = "async")]
mod client_async;
#[cfg(feature = "async")]
pub use client_async::ClientAsync;

#[cfg(feature = "locking-default")]
use parking_lot::{Condvar, Mutex, RawMutex};

#[cfg(feature = "locking-rt")]
use parking_lot_rt::{Condvar, Mutex, RawMutex};

#[cfg(feature = "locking-rt-safe")]
use rtsc::pi::{Condvar, Mutex, RawMutex};

const GREETING: &str = "RFLOW";
const HEADERS_TRANSMISSION_END: &str = "---";

const API_VERSION: u8 = 1;

const DEFAULT_INCOMING_QUEUE_SIZE: usize = 128;
const DEFAULT_OUTGOING_QUEUE_SIZE: usize = 128;

const DEFAULT_TIMEOUT: Duration = Duration::from_secs(5);

static DEFAULT_SERVER: Lazy<Server> = Lazy::new(|| Server::new(DEFAULT_TIMEOUT));

/// Serve the default server
pub fn serve(addr: impl ToSocketAddrs + std::fmt::Debug) -> Result<(), Error> {
    DEFAULT_SERVER.serve(addr)
}

/// Spawn the default server as a separate thread and return the data channel
pub fn spawn(addr: impl ToSocketAddrs + std::fmt::Debug) -> Result<server::FrameReceiver, Error> {
    let listener = std::net::TcpListener::bind(addr)?;
    std::thread::spawn(move || {
        DEFAULT_SERVER
            .serve_with_listener(listener)
            .expect("RFlow server error");
    });
    DEFAULT_SERVER.take_data_channel()
}

/// Send a message to the default server's clients
pub fn send(data: impl ToString) {
    DEFAULT_SERVER.send(data);
}

/// Take the default server data channel
pub fn take_data_channel() -> Result<server::FrameReceiver, Error> {
    DEFAULT_SERVER.take_data_channel()
}

/// Direction of the message (client)
#[derive(Copy, Clone, Eq, PartialEq, Debug)]
pub enum Direction {
    /// Client-to-server message
    ClientToServer,
    /// Server-to-client message
    ServerToClient,
    /// Unknown, use the last known direction
    Last,
}

impl Direction {
    /// Get direction as bytes
    #[inline]
    pub fn as_bytes(self) -> &'static [u8] {
        self.as_str().as_bytes()
    }
    /// Get direction as string
    pub fn as_str(self) -> &'static str {
        match self {
            Self::ClientToServer => ">>>",
            Self::ServerToClient => "<<<",
            Self::Last => unreachable!(),
        }
    }
    /// Get direction as char
    pub fn as_char(self) -> char {
        match self {
            Self::ClientToServer => '>',
            Self::ServerToClient => '<',
            Self::Last => unreachable!(),
        }
    }
}

impl fmt::Display for Direction {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.as_str())
    }
}

/// Error type
#[derive(thiserror::Error, Debug)]
pub enum Error {
    /// Data channel is already taken
    #[error("Data channel is already taken")]
    DataChannelTaken,
    /// All I/O errors
    #[error("IO error: {0}")]
    Io(#[from] std::io::Error),
    #[error("Unsupported API version: {0}")]
    /// Unsupported API version
    ApiVersion(u8),
    /// Invalid data
    #[error("Invalid data")]
    InvalidData,
    /// Invalid TCP/IP address/host name/port
    #[error("Invalid address")]
    InvalidAddress,
    /// Timed out
    #[error("Timed out")]
    Timeout,
}

#[cfg(feature = "async")]
impl From<tokio::time::error::Elapsed> for Error {
    fn from(_: tokio::time::error::Elapsed) -> Self {
        Self::Timeout
    }
}