Merge pull request #5 from JadKHaddad/feat/echo

Exposed internal functions and fields

Author: JadKHaddad

.github/workflows/spellcheck.yaml .github/workflows/spellcheck.yml.github/workflows/spellcheck.yaml renamed to .github/workflows/spellcheck.yml

@@ -37,6 +37,11 @@ tracing-subscriber = { version = "0.3.18", features = ["env-filter"] }
 all-features = true
 rustdoc-args = ["--cfg", "docsrs"]
 
+[[example]]
+name = "echo"
+path = "examples/echo.rs"
+required-features = []
+
 [[example]]
 name = "zerocopy"
 path = "examples/zerocopy.rs"

framez/Cargo.toml

@@ -0,0 +1,67 @@
+//! This example shows how to reuse the read and write buffers without splitting the `Framed` instance.
+//!
+//! ```not_rust
+//! cargo run --example echo
+//! ```
+
+use core::error::Error;
+
+use embedded_io_adapters::tokio_1::FromTokio;
+use framez::{Framed, codec::lines::StrLines, next, send};
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn Error>> {
+    tracing_subscriber::fmt()
+        .with_env_filter("server=info,client=info")
+        .init();
+
+    let (server, client) = tokio::io::duplex(16);
+
+    let read_buf = &mut [0u8; 1024];
+    let write_buf = &mut [0u8; 1024];
+    let mut server = Framed::new(StrLines::new(), FromTokio::new(server), read_buf, write_buf);
+
+    let server = async move {
+        while let Some(item) = next!(server).transpose()? {
+            tracing::info!(target: "server", item, "received frame");
+
+            // echo the item back
+            send!(server, item)?;
+
+            if item == "Close" {
+                tracing::info!(target: "server", "closing connection");
+
+                break;
+            }
+        }
+
+        Ok::<(), Box<dyn Error>>(())
+    };
+
+    let read_buf = &mut [0u8; 1024];
+    let write_buf = &mut [0u8; 1024];
+    let mut client = Framed::new(StrLines::new(), FromTokio::new(client), read_buf, write_buf);
+
+    let client = async move {
+        let items = ["Hello, world!", "How are you?", "Goodbye!", "Close"];
+
+        for item in items {
+            tracing::info!(target: "client", item, "sending frame");
+
+            client.send(item).await?;
+        }
+
+        while let Some(item) = next!(client).transpose()? {
+            tracing::info!(target: "client", item, "received frame");
+        }
+
+        Ok::<(), Box<dyn Error>>(())
+    };
+
+    let (server_result, client_result) = tokio::join!(server, client);
+
+    server_result?;
+    client_result?;
+
+    Ok(())
+}

framez/examples/echo.rs

@@ -13,11 +13,15 @@ use crate::{
 #[derive(Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct Framed<'buf, C, RW> {
-    core: FramedCore<'buf, C, RW, ReadWriteState<'buf>>,
+    /// The core framed implementation.
+    ///
+    /// This field is made public to be used in the [`functions`](crate::functions) module for library authors.
+    /// If you are using this crate as a user, you should probably not care about this field.
+    pub core: FramedCore<'buf, C, RW>,
 }
 
 impl<'buf, C, RW> Framed<'buf, C, RW> {
-    /// Creates a new [`Framed`] with the given `coded` and `reader/writer`.
+    /// Creates a new [`Framed`] with the given `codec` and `reader/writer`.
     #[inline]
     pub const fn new(
         codec: C,
@@ -74,7 +78,7 @@ impl<'buf, C, RW> Framed<'buf, C, RW> {
 
     /// Returns the number of bytes that can be framed.
     #[inline]
-    pub fn framable(&self) -> usize {
+    pub const fn framable(&self) -> usize {
         self.core.framable()
     }
 
@@ -208,15 +212,23 @@ impl<'buf, C, RW> Framed<'buf, C, RW> {
 #[derive(Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct FramedRead<'buf, C, R> {
-    core: FramedCore<'buf, C, R, ReadState<'buf>>,
+    /// The core framed implementation.
+    ///
+    /// This field is made public to be used in the [`functions`](crate::functions) module for library authors.
+    /// If you are using this crate as a user, you should probably not care about this field.
+    pub core: FramedCore<'buf, C, R>,
 }
 
 impl<'buf, C, R> FramedRead<'buf, C, R> {
     /// Creates a new [`FramedRead`] with the given `decoder` and `reader`.
     #[inline]
     pub const fn new(codec: C, reader: R, buffer: &'buf mut [u8]) -> Self {
         Self {
-            core: FramedCore::new(codec, reader, ReadState::new(buffer)),
+            core: FramedCore::new(
+                codec,
+                reader,
+                ReadWriteState::new(ReadState::new(buffer), WriteState::empty()),
+            ),
         }
     }
 
@@ -247,17 +259,29 @@ impl<'buf, C, R> FramedRead<'buf, C, R> {
     /// Consumes the [`FramedRead`] and returns the `codec` and `reader` and state.
     #[inline]
     pub fn into_parts(self) -> (C, R, ReadState<'buf>) {
-        self.core.into_parts()
+        let (codec, reader, state) = self.core.into_parts();
+
+        (codec, reader, state.read)
     }
 
     #[inline]
     /// Creates a new [`FramedRead`] from its parts.
     pub const fn from_parts(codec: C, read: R, state: ReadState<'buf>) -> Self {
         Self {
-            core: FramedCore::from_parts(codec, read, state),
+            core: FramedCore::from_parts(
+                codec,
+                read,
+                ReadWriteState::new(state, WriteState::empty()),
+            ),
         }
     }
 
+    /// Returns the number of bytes that can be framed.
+    #[inline]
+    pub const fn framable(&self) -> usize {
+        self.core.framable()
+    }
+
     /// See [`Framed::maybe_next`].
     pub async fn maybe_next<'this>(
         &'this mut self,
@@ -300,15 +324,23 @@ impl<'buf, C, R> FramedRead<'buf, C, R> {
 #[derive(Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct FramedWrite<'buf, C, W> {
-    core: FramedCore<'buf, C, W, WriteState<'buf>>,
+    /// The core framed implementation.
+    ///
+    /// This field is made public to be used in the [`functions`](crate::functions) module for library authors.
+    /// If you are using this crate as a user, you should probably not care about this field.
+    pub core: FramedCore<'buf, C, W>,
 }
 
 impl<'buf, C, W> FramedWrite<'buf, C, W> {
     /// Creates a new [`FramedWrite`] with the given `encoder` and `writer`.
     #[inline]
     pub const fn new(codec: C, writer: W, buffer: &'buf mut [u8]) -> Self {
         Self {
-            core: FramedCore::new(codec, writer, WriteState::new(buffer)),
+            core: FramedCore::new(
+                codec,
+                writer,
+                ReadWriteState::new(ReadState::empty(), WriteState::new(buffer)),
+            ),
         }
     }
 
@@ -339,14 +371,20 @@ impl<'buf, C, W> FramedWrite<'buf, C, W> {
     /// Consumes the [`FramedWrite`] and returns the `codec` and `writer` and state.
     #[inline]
     pub fn into_parts(self) -> (C, W, WriteState<'buf>) {
-        self.core.into_parts()
+        let (codec, writer, state) = self.core.into_parts();
+
+        (codec, writer, state.write)
     }
 
     #[inline]
     /// Creates a new [`FramedWrite`] from its parts.
     pub const fn from_parts(codec: C, write: W, state: WriteState<'buf>) -> Self {
         Self {
-            core: FramedCore::from_parts(codec, write, state),
+            core: FramedCore::from_parts(
+                codec,
+                write,
+                ReadWriteState::new(ReadState::empty(), state),
+            ),
         }
     }