Peek functionality

.gitignore

@@ -8,6 +8,7 @@
 .tox
 .vscode
 env/
+.venv/
 venv/
 error.csv
 log.csv

docs/com/user_guide.rst

@@ -108,7 +108,7 @@ An actor waiting for a message uses the receive procedure
 
 This procedure returns immediately if there are pending message(s) in the receiver's inbox or blocks until the first
 message arrives. The returned message contains the oldest incoming message and its information can be retrieved using
-``pop`` functions. The code below will verify that the message has the expected content using the VUnit
+``pop`` and ``peek`` functions. The code below will verify that the message has the expected content using the VUnit
 :ref:`check_equal <equality_check>` procedure.
 
 .. code-block:: vhdl
@@ -117,7 +117,18 @@ message arrives. The returned message contains the oldest incoming message and i
   my_integer := pop(msg);
   check_equal(my_integer, 17);
 
-Just like ``push`` there are both ``pop`` functions and more verbose aliases on the form ``pop_<type>``.
+Just like ``push`` there are:
+- ``pop`` functions and more verbose aliases on the form ``pop_<type>``,
+- ``peek`` functions and more verbose aliases on the form ``peek_<type>``.
+
+Note that the ``peek`` functions returns the element at the front the message. It does not deletes the element in the message. Therefore, you can peek any number of time, it will return the exact same element.
+
+.. code-block:: vhdl
+
+  push_integer(msg, 17)
+  check_equal(peek_integer(msg), 17);
+  check_equal(peek_integer(msg), 17);
+  check_equal(peek_integer(msg), 17);
 
 Objects are always popped from the message in the same order they were pushed into the message and once all objects
 have been popped the message is empty. If you want to keep a message for later you can make a copy before popping.
@@ -738,7 +749,7 @@ value will be replaced with ``-``.
 Note that ``com`` has limited knowledge of the contents of a message. All data pushed into a message is encoded
 and is basically handled as a sequence of bytes without any overhead for type information. ``com`` doesn't
 know if four bytes represents an integer, four characters or something else. The interpretation of
-these bytes takes place when the user pops data using a type specific pop function. The exception is the message
+these bytes takes place when the user pops/peeks data using a type specific pop/peek function. The exception is the message
 type for which the type overhead is included to provide better debugging. Higher levels of debug information,
 for example that a message represents a read request to a specific address is something that the verification
 component using ``com`` provides.

vunit/com/codec_datatype_template.py

@@ -39,12 +39,16 @@ class DatatypeCodecTemplate(object):
     variable result : out $type);
   alias decode_$type is decode[string, positive, $type];
   procedure push(queue : queue_t; value : $type);
+  impure function peek(queue : queue_t) return $type;
   impure function pop(queue : queue_t) return $type;
   alias push_$type is push[queue_t, $type];
+  alias peek_$type is peek[queue_t return $type];
   alias pop_$type is pop[queue_t return $type];
   procedure push(msg : msg_t; value : $type);
+  impure function peek(msg : msg_t) return $type;
   impure function pop(msg : msg_t) return $type;
   alias push_$type is push[msg_t, $type];
+  alias peek_$type is peek[msg_t return $type];
   alias pop_$type is pop[msg_t return $type];
 
 """

vunit/com/codec_vhdl_array_type.py

@@ -200,6 +200,11 @@ class ArrayCodecTemplate(DatatypeCodecTemplate):
     push_variable_string(queue, encode(value));
   end;
 
+  impure function peek(queue : queue_t) return $type is
+  begin
+    return decode(peek_variable_string(queue));
+  end;
+
   impure function pop(queue : queue_t) return $type is
   begin
     return decode(pop_variable_string(queue));
@@ -210,6 +215,11 @@ class ArrayCodecTemplate(DatatypeCodecTemplate):
     push(msg.data, value);
   end;
 
+  impure function peek(msg : msg_t) return $type is
+  begin
+    return peek(msg.data);
+  end;
+
   impure function pop(msg : msg_t) return $type is
   begin
     return pop(msg.data);
@@ -265,6 +275,11 @@ class ArrayCodecTemplate(DatatypeCodecTemplate):
     push_variable_string(queue, encode(value));
   end;
 
+  impure function peek(queue : queue_t) return $type is
+  begin
+    return decode(peek_variable_string(queue));
+  end;
+
   impure function pop(queue : queue_t) return $type is
   begin
     return decode(pop_variable_string(queue));
@@ -275,6 +290,11 @@ class ArrayCodecTemplate(DatatypeCodecTemplate):
     push(msg.data, value);
   end;
 
+  impure function peek(msg : msg_t) return $type is
+  begin
+    return peek(msg.data);
+  end;
+
   impure function pop(msg : msg_t) return $type is
   begin
     return pop(msg.data);
@@ -361,6 +381,11 @@ class ArrayCodecTemplate(DatatypeCodecTemplate):
     push_variable_string(queue, encode(value));
   end;
 
+  impure function peek(queue : queue_t) return $array_type is
+  begin
+    return decode(peek_variable_string(queue));
+  end;
+
   impure function pop(queue : queue_t) return $array_type is
   begin
     return decode(pop_variable_string(queue));
@@ -371,6 +396,11 @@ class ArrayCodecTemplate(DatatypeCodecTemplate):
     push(msg.data, value);
   end;
 
+  impure function peek(msg : msg_t) return $array_type is
+  begin
+    return peek(msg.data);
+  end;
+
   impure function pop(msg : msg_t) return $array_type is
   begin
     return pop(msg.data);
@@ -490,6 +520,11 @@ class ArrayCodecTemplate(DatatypeCodecTemplate):
     push_variable_string(queue, encode(value));
   end;
 
+  impure function peek(queue : queue_t) return $array_type is
+  begin
+    return decode(peek_variable_string(queue));
+  end;
+
   impure function pop(queue : queue_t) return $array_type is
   begin
     return decode(pop_variable_string(queue));
@@ -500,6 +535,11 @@ class ArrayCodecTemplate(DatatypeCodecTemplate):
     push(msg.data, value);
   end;
 
+  impure function peek(msg : msg_t) return $array_type is
+  begin
+    return peek(msg.data);
+  end;
+
   impure function pop(msg : msg_t) return $array_type is
   begin
     return pop(msg.data);

vunit/com/codec_vhdl_enumeration_type.py

@@ -85,6 +85,11 @@ class EnumerationCodecTemplate(DatatypeCodecTemplate):
     push_fix_string(queue, encode(value));
   end;
 
+  impure function peek(queue : queue_t) return $type is
+  begin
+    return decode(peek_fix_string(queue, 1));
+  end;
+
   impure function pop(queue : queue_t) return $type is
   begin
     return decode(pop_fix_string(queue, 1));
@@ -95,6 +100,11 @@ class EnumerationCodecTemplate(DatatypeCodecTemplate):
     push(msg.data, value);
   end;
 
+  impure function peek(msg : msg_t) return $type is
+  begin
+    return peek(msg.data);
+  end;
+
   impure function pop(msg : msg_t) return $type is
   begin
     return pop(msg.data);

vunit/com/codec_vhdl_record_type.py

@@ -99,6 +99,11 @@ class RecordCodecTemplate(DatatypeCodecTemplate):
     push_variable_string(queue, encode(value));
   end;
 
+  impure function peek(queue : queue_t) return $type is
+  begin
+    return decode(peek_variable_string(queue));
+  end;
+
   impure function pop(queue : queue_t) return $type is
   begin
     return decode(pop_variable_string(queue));
@@ -109,6 +114,11 @@ class RecordCodecTemplate(DatatypeCodecTemplate):
     push(msg.data, value);
   end;
 
+  impure function peek(msg : msg_t) return $type is
+  begin
+    return peek(msg.data);
+  end;
+
   impure function pop(msg : msg_t) return $type is
   begin
     return pop(msg.data);