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

@@ -26,7 +26,7 @@ import std
 
 // Structure to hold the buffered data
 pub struct Buffer<CAPACITY: u32> {
-    contents: bits[CAPACITY],
+    content: bits[CAPACITY],
     length: u32
 }
 
@@ -50,19 +50,19 @@ pub fn buffer_can_fit<CAPACITY: u32, DSIZE: u32>(buffer: Buffer<CAPACITY>, data:
 
 #[test]
 fn test_buffer_can_fit() {
-    let buffer = Buffer<u32:32> { contents: u32:0, length: u32:0 };
+    let buffer = Buffer<u32:32> { content: u32:0, length: u32:0 };
     assert_eq(buffer_can_fit(buffer, bits[0]:0), true);
     assert_eq(buffer_can_fit(buffer, u16:0), true);
     assert_eq(buffer_can_fit(buffer, u32:0), true);
     assert_eq(buffer_can_fit(buffer, u33:0), false);
 
-    let buffer = Buffer<u32:32> { contents: u32:0, length: u32:16 };
+    let buffer = Buffer<u32:32> { content: u32:0, length: u32:16 };
     assert_eq(buffer_can_fit(buffer, bits[0]:0), true);
     assert_eq(buffer_can_fit(buffer, u16:0), true);
     assert_eq(buffer_can_fit(buffer, u17:0), false);
     assert_eq(buffer_can_fit(buffer, u32:0), false);
 
-    let buffer = Buffer<u32:32> { contents: u32:0, length: u32:32 };
+    let buffer = Buffer<u32:32> { content: u32:0, length: u32:32 };
     assert_eq(buffer_can_fit(buffer, bits[0]:0), true);
     assert_eq(buffer_can_fit(buffer, u1:0), false);
     assert_eq(buffer_can_fit(buffer, u16:0), false);
@@ -76,19 +76,19 @@ pub fn buffer_has_at_least<CAPACITY: u32>(buffer: Buffer<CAPACITY>, length: u32)
 
 #[test]
 fn test_buffer_has_at_least() {
-    let buffer = Buffer { contents: u32:0, length: u32:0 };
+    let buffer = Buffer { content: u32:0, length: u32:0 };
     assert_eq(buffer_has_at_least(buffer, u32:0), true);
     assert_eq(buffer_has_at_least(buffer, u32:16), false);
     assert_eq(buffer_has_at_least(buffer, u32:32), false);
     assert_eq(buffer_has_at_least(buffer, u32:33), false);
 
-    let buffer = Buffer { contents: u32:0, length: u32:16 };
+    let buffer = Buffer { content: u32:0, length: u32:16 };
     assert_eq(buffer_has_at_least(buffer, u32:0), true);
     assert_eq(buffer_has_at_least(buffer, u32:16), true);
     assert_eq(buffer_has_at_least(buffer, u32:32), false);
     assert_eq(buffer_has_at_least(buffer, u32:33), false);
 
-    let buffer = Buffer { contents: u32:0, length: u32:32 };
+    let buffer = Buffer { content: u32:0, length: u32:32 };
     assert_eq(buffer_has_at_least(buffer, u32:0), true);
     assert_eq(buffer_has_at_least(buffer, u32:16), true);
     assert_eq(buffer_has_at_least(buffer, u32:32), true);
@@ -104,19 +104,19 @@ pub fn buffer_append<CAPACITY: u32, DSIZE: u32> (buffer: Buffer<CAPACITY>, data:
         fail!("not_enough_space", buffer)
     } else {
         Buffer {
-            contents: (data as bits[CAPACITY] << buffer.length) | buffer.contents,
+            content: (data as bits[CAPACITY] << buffer.length) | buffer.content,
             length: DSIZE + buffer.length
         }
     }
 }
 
 #[test]
 fn test_buffer_append() {
-    let buffer = Buffer { contents: u32:0, length: u32:0 };
+    let buffer = Buffer { content: u32:0, length: u32:0 };
     let buffer = buffer_append(buffer, u16:0xBEEF);
-    assert_eq(buffer, Buffer { contents: u32:0xBEEF, length: u32:16 });
+    assert_eq(buffer, Buffer { content: u32:0xBEEF, length: u32:16 });
     let buffer = buffer_append(buffer, u16:0xDEAD);
-    assert_eq(buffer, Buffer { contents: u32:0xDEADBEEF, length: u32:32 });
+    assert_eq(buffer, Buffer { content: u32:0xDEADBEEF, length: u32:32 });
 }
 
 // Returns a new buffer with the `data` appended to the original `buffer` if
@@ -129,7 +129,7 @@ pub fn buffer_append_checked<CAPACITY: u32, DSIZE: u32> (buffer: Buffer<CAPACITY
         BufferResult {
             status: BufferStatus::OK,
             buffer: Buffer {
-                contents: (data as bits[CAPACITY] << buffer.length) | buffer.contents,
+                content: (data as bits[CAPACITY] << buffer.length) | buffer.content,
                 length: DSIZE + buffer.length
             }
         }
@@ -138,18 +138,18 @@ pub fn buffer_append_checked<CAPACITY: u32, DSIZE: u32> (buffer: Buffer<CAPACITY
 
 #[test]
 fn test_buffer_append_checked() {
-    let buffer = Buffer { contents: u32:0, length: u32:0 };
+    let buffer = Buffer { content: u32:0, length: u32:0 };
 
     let result1 = buffer_append_checked(buffer, u16:0xBEEF);
     assert_eq(result1, BufferResult {
         status: BufferStatus::OK,
-        buffer: Buffer { contents: u32:0xBEEF, length: u32:16 }
+        buffer: Buffer { content: u32:0xBEEF, length: u32:16 }
     });
 
     let result2 = buffer_append_checked(result1.buffer, u16:0xDEAD);
     assert_eq(result2, BufferResult {
         status: BufferStatus::OK,
-        buffer: Buffer { contents: u32:0xDEADBEEF, length: u32:32 }
+        buffer: Buffer { content: u32:0xDEADBEEF, length: u32:32 }
     });
 
     let result3 = buffer_append_checked(result2.buffer, u16:0xCAFE);
@@ -173,23 +173,23 @@ pub fn buffer_pop<CAPACITY: u32>(buffer: Buffer<CAPACITY>, length: u32) -> (Buff
         let mask = (bits[CAPACITY]:1 << length) - bits[CAPACITY]:1;
         (
             Buffer {
-                contents: buffer.contents >> length,
+                content: buffer.content >> length,
                 length: buffer.length - length
             },
-            buffer.contents & mask
+            buffer.content & mask
         )
     }
 }
 
 #[test]
 fn test_buffer_pop() {
-    let buffer = Buffer { contents: u32:0xDEADBEEF, length: u32:32 };
+    let buffer = Buffer { content: u32:0xDEADBEEF, length: u32:32 };
     let (buffer, data) = buffer_pop(buffer, u32:16);
     assert_eq(data, u32:0xBEEF);
-    assert_eq(buffer, Buffer { contents: u32:0xDEAD, length: u32:16 });
+    assert_eq(buffer, Buffer { content: u32:0xDEAD, length: u32:16 });
     let (buffer, data) = buffer_pop(buffer, u32:16);
     assert_eq(data, u32:0xDEAD);
-    assert_eq(buffer, Buffer { contents: u32:0, length: u32:0 });
+    assert_eq(buffer, Buffer { content: u32:0, length: u32:0 });
 }
 
 // Returns `length` amount of data from a `buffer`, a new buffer with
@@ -210,30 +210,30 @@ pub fn buffer_pop_checked<CAPACITY: u32> (buffer: Buffer<CAPACITY>, length: u32)
             BufferResult {
                 status: BufferStatus::OK,
                 buffer: Buffer {
-                    contents: buffer.contents >> length,
+                    content: buffer.content >> length,
                     length: buffer.length - length
                 }
             },
-            buffer.contents & mask
+            buffer.content & mask
         )
     }
 }
 
 #[test]
 fn test_buffer_pop_checked() {
-    let buffer = Buffer { contents: u32:0xDEADBEEF, length: u32:32 };
+    let buffer = Buffer { content: u32:0xDEADBEEF, length: u32:32 };
 
     let (result1, data1) = buffer_pop_checked(buffer, u32:16);
     assert_eq(result1, BufferResult {
         status: BufferStatus::OK,
-        buffer: Buffer { contents: u32:0xDEAD, length: u32:16 }
+        buffer: Buffer { content: u32:0xDEAD, length: u32:16 }
     });
     assert_eq(data1, u32:0xBEEF);
 
     let (result2, data2) = buffer_pop_checked(result1.buffer, u32:16);
     assert_eq(result2, BufferResult {
         status: BufferStatus::OK,
-        buffer: Buffer { contents: u32:0, length: u32:0 }
+        buffer: Buffer { content: u32:0, length: u32:0 }
     });
     assert_eq(data2, u32:0xDEAD);
 
@@ -255,13 +255,13 @@ pub fn buffer_fixed_pop<CAPACITY: u32, DSIZE: u32> (buffer: Buffer<CAPACITY>) ->
 
 #[test]
 fn test_buffer_fixed_pop() {
-    let buffer = Buffer { contents: u32:0xDEADBEEF, length: u32:32 };
+    let buffer = Buffer { content: u32:0xDEADBEEF, length: u32:32 };
     let (buffer, data) = buffer_fixed_pop<u32:32, u32:16>(buffer);
     assert_eq(data, u16:0xBEEF);
-    assert_eq(buffer, Buffer { contents: u32:0xDEAD, length: u32:16 });
+    assert_eq(buffer, Buffer { content: u32:0xDEAD, length: u32:16 });
     let (buffer, data) = buffer_fixed_pop<u32:32, u32:16>(buffer);
     assert_eq(data, u16:0xDEAD);
-    assert_eq(buffer, Buffer { contents: u32:0, length: u32:0 });
+    assert_eq(buffer, Buffer { content: u32:0, length: u32:0 });
 }
 
 // Behaves like `buffer_pop_checked` except that the length of the popped data
@@ -273,18 +273,18 @@ pub fn buffer_fixed_pop_checked<CAPACITY: u32, DSIZE: u32> (buffer: Buffer<CAPAC
 
 #[test]
 fn test_buffer_fixed_pop_checked() {
-    let buffer = Buffer { contents: u32:0xDEADBEEF, length: u32:32 };
+    let buffer = Buffer { content: u32:0xDEADBEEF, length: u32:32 };
     let (result1, data1) = buffer_fixed_pop_checked<u32:32, u32:16>(buffer);
     assert_eq(result1, BufferResult {
         status: BufferStatus::OK,
-        buffer: Buffer { contents: u32:0xDEAD, length: u32:16 }
+        buffer: Buffer { content: u32:0xDEAD, length: u32:16 }
     });
     assert_eq(data1, u16:0xBEEF);
 
     let (result2, data2) = buffer_fixed_pop_checked<u32:32, u32:16>(result1.buffer);
     assert_eq(result2, BufferResult {
         status: BufferStatus::OK,
-        buffer: Buffer { contents: u32:0, length: u32:0 }
+        buffer: Buffer { content: u32:0, length: u32:0 }
     });
     assert_eq(data2, u16:0xDEAD);
 
@@ -305,13 +305,13 @@ pub fn buffer_peek<CAPACITY: u32>(buffer: Buffer<CAPACITY>, length: u32) -> bits
         fail!("not_enough_data", bits[CAPACITY]:0)
     } else {
         let mask = (bits[CAPACITY]:1 << length) - bits[CAPACITY]:1;
-        buffer.contents & mask
+        buffer.content & mask
     }
 }
 
 #[test]
 fn test_buffer_peek() {
-    let buffer = Buffer { contents: u32:0xDEADBEEF, length: u32:32 };
+    let buffer = Buffer { content: u32:0xDEADBEEF, length: u32:32 };
     assert_eq(buffer_peek(buffer, u32:0), u32:0);
     assert_eq(buffer_peek(buffer, u32:16), u32:0xBEEF);
     assert_eq(buffer_peek(buffer, u32:32), u32:0xDEADBEEF);
@@ -325,13 +325,13 @@ pub fn buffer_peek_checked<CAPACITY: u32> (buffer: Buffer<CAPACITY>, length: u32
         (BufferStatus::NO_ENOUGH_DATA, bits[CAPACITY]:0)
     } else {
         let mask = (bits[CAPACITY]:1 << length) - bits[CAPACITY]:1;
-        (BufferStatus::OK, buffer.contents & mask)
+        (BufferStatus::OK, buffer.content & mask)
     }
 }
 
 #[test]
 fn test_buffer_peek_checked() {
-    let buffer = Buffer { contents: u32:0xDEADBEEF, length: u32:32 };
+    let buffer = Buffer { content: u32:0xDEADBEEF, length: u32:32 };
 
     let (status1, data1) = buffer_peek_checked(buffer, u32:0);
     assert_eq(status1, BufferStatus::OK);
@@ -352,10 +352,73 @@ fn test_buffer_peek_checked() {
 
 // Creates a new buffer
 pub fn buffer_new<CAPACITY: u32>() -> Buffer<CAPACITY> {
-    Buffer { contents: bits[CAPACITY]:0, length: u32:0 }
+    Buffer { content: bits[CAPACITY]:0, length: u32:0 }
 }
 
 #[test]
 fn test_buffer_new() {
-    assert_eq(buffer_new<u32:32>(), Buffer { contents: u32:0, length: u32:0 });
+    assert_eq(buffer_new<u32:32>(), Buffer { content: u32:0, length: u32:0 });
+}
+
+// Example use case
+//
+// The Buffer structure is meant to aggregate data received from the Proc's
+// channels. This data may be collected in multiple evaluations of the next
+// functions. Once the required amount of data is collected, it can be poped-out
+// in chanks of any length. A simple example that shows how the Buffer structure
+// can be used is presented below. It uses the structure to combine several
+// smaller transactions into bigger ones.
+
+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 { buffer_new<u32:64>() }
+
+    next(tok: token, buffer: Buffer<u32:64>) {
+        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_fixed_pop<u32:64, u32:48>(buffer);
+            let tok = send(tok, output_s, data_to_send);
+            buffer
+        } else {
+            buffer
+        }
+    }
+}
+
+#[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 {}
+
+    next(tok: token, state: ()) {
+        let tok = send(tok, data32_s, u32:0xDEADBEEF);
+        let tok = send(tok, data32_s, u32:0xBEEFCAFE);
+        let tok = send(tok, data32_s, u32:0xCAFEDEAD);
+
+        let (tok, received_data) = recv(tok, data48_r);
+        assert_eq(received_data, u48:0xCAFE_DEAD_BEEF);
+        let (tok, received_data) = recv(tok, data48_r);
+        assert_eq(received_data, u48:0xCAFE_DEAD_BEEF);
+
+        send(tok, terminator, true);
+    }
 }