modules/zstd: Add Buffer use-case example

This commit adds a simple test that shows, how one can use the Buffer
struct inside a Proc.

Internal-tag: [#50221]
Signed-off-by: Robert Winkler <[email protected]>

Author: rw1nkler

xls/modules/zstd/buffer.x

@@ -358,3 +358,94 @@ pub fn buffer_new<BSIZE: u32>() -> Buffer<BSIZE> {
 fn test_buffer_new() {
     assert_eq(buffer_new<u32:32>(), Buffer { contents: u32:0, length: u32:0 });
 }
+
+// Example use case
+//
+// The Buffer structure can be used to collect enough data that is required
+// for the next steps to proceed. The next steps may consume variable or
+// constant amount of data. In the simplest use-case scenario, one can use
+// it to combine smaller transactions into bigger ones.
+
+type Buffer64 = Buffer<64>;
+
+proc BufferExampleUsage {
+    input_r: chan<u32> in;
+    output_s: chan<u48> out;
+
+    config(
+        input_r: chan<u32> in,
+        output_s: chan<u48> out
+    ) { (input_r, output_s) }
+
+    init { Buffer64 { contents: u64:0, length: u32:0 } }
+
+    next(tok: token, buffer: Buffer64) {
+        let (tok, recv_data) = recv(tok, input_r);
+        let buffer = buffer_append<u32:64>(buffer, recv_data);
+
+        if buffer.length >= u32:48 {
+            let (buffer, data_to_send) = buffer_sized_pop<u32:64, u32:48>(buffer);
+            let tok = send(tok, output_s, data_to_send);
+            buffer
+        } else {
+            buffer
+        }
+    }
+}
+
+const NUMBER_OF_TESTED_TRANSACTIONS = u32:30;
+
+struct BufferExampleUsageTestState {
+    recv_count: u32,
+    send_count: u32
+}
+
+#[test_proc]
+proc BufferExampleUsageTest {
+    terminator: chan<bool> out;
+    data32_s: chan<u32> out;
+    data48_r: chan<u48> in;
+
+    config(terminator: chan<bool> out) {
+        let (data32_s, data32_r) = chan<u32>;
+        let (data48_s, data48_r) = chan<u48>;
+        spawn BufferExampleUsage(data32_r, data48_s);
+        (terminator, data32_s, data48_r)
+    }
+
+    init {
+        BufferExampleUsageTestState {
+            recv_count: u32:0,
+            send_count: u32:0
+        }
+    }
+
+    next(tok: token, state: BufferExampleUsageTestState) {
+        let data_to_send = match state.send_count % u32:3 {
+            u32:0 => u32:0xDEADBEEF,
+            u32:1 => u32:0xBEEFCAFE,
+            u32:2 => u32:0xCAFEDEAD,
+            _ => fail!("impossible_case", u32:0),
+        };
+        let tok = send(tok, data32_s, data_to_send);
+        let send_count = state.send_count + u32:1;
+
+        let (tok, received_data, valid) = recv_non_blocking(tok, data48_r, u48:0);
+        let recv_count = if valid {
+            let recv_count = state.recv_count + u32:1;
+            trace_fmt!("received data: {:#x}, recv_count {}, send_count {}",
+            received_data, recv_count, send_count);
+            assert_eq(received_data, u48:0xCAFE_DEAD_BEEF);
+            recv_count
+        } else {
+            state.recv_count
+        };
+
+        assert_eq(u32:32 * (send_count - u32:1) / u32:48, recv_count);
+
+        let do_send = (state.send_count == NUMBER_OF_TESTED_TRANSACTIONS - u32:1);
+        send_if(tok, terminator, do_send, true);
+
+        BufferExampleUsageTestState { recv_count, send_count }
+    }
+}