kernel: queue, fifo: Add peek_head/peek_tail accessors

As explained in the docstrings, a usecase behind these operations is
when other container objects are put in a fifo. The typical
processing iteration make take just some data from a container at
the head of fifo, with the container still being kept at the fifo,
unless it becomes empty, and only then it's removed. Similarly with
adding more data - first step may be to try to add more data to a
container at the tail of fifo, and only if it's full, add another
container to a fifo.

The specific usecase these operations are added for is network
subsystem processing, where net_buf's and net_pkt's are added
to fifo.

Signed-off-by: Paul Sokolovsky <[email protected]>

Author: pfalcon

include/kernel.h

@@ -1458,6 +1458,34 @@ static inline int k_queue_is_empty(struct k_queue *queue)
 	return (int)sys_slist_is_empty(&queue->data_q);
 }
 
+/**
+ * @brief Peek element at the head of queue.
+ *
+ * Return element from the head of queue without removing it.
+ *
+ * @param queue Address of the queue.
+ *
+ * @return Head element, or NULL if queue is empty.
+ */
+static inline void *k_queue_peek_head(struct k_queue *queue)
+{
+	return sys_slist_peek_head(&queue->data_q);
+}
+
+/**
+ * @brief Peek element at the tail of queue.
+ *
+ * Return element from the tail of queue without removing it.
+ *
+ * @param queue Address of the queue.
+ *
+ * @return Tail element, or NULL if queue is empty.
+ */
+static inline void *k_queue_peek_tail(struct k_queue *queue)
+{
+	return sys_slist_peek_tail(&queue->data_q);
+}
+
 /**
  * @brief Statically define and initialize a queue.
  *
@@ -1615,6 +1643,36 @@ struct k_fifo {
 #define k_fifo_is_empty(fifo) \
 	k_queue_is_empty((struct k_queue *) fifo)
 
+/**
+ * @brief Peek element at the head of fifo.
+ *
+ * Return element from the head of fifo without removing it. A usecase
+ * for this is if elements of the fifo are themselves containers. Then
+ * on each iteration of processing, a head container will be peeked,
+ * and some data processed out of it, and only if the container is empty,
+ * it will be completely remove from the fifo.
+ *
+ * @param fifo Address of the fifo.
+ *
+ * @return Head element, or NULL if the fifo is empty.
+ */
+#define k_fifo_peek_head(fifo) \
+	k_queue_peek_head((struct k_queue *) fifo)
+
+/**
+ * @brief Peek element at the tail of fifo.
+ *
+ * Return element from the tail of fifo (without removing it). A usecase
+ * for this is if elements of the fifo are themselves containers. Then
+ * it may be useful to add more data to the last container in fifo.
+ *
+ * @param fifo Address of the fifo.
+ *
+ * @return Tail element, or NULL if fifo is empty.
+ */
+#define k_fifo_peek_tail(fifo) \
+	k_queue_peek_tail((struct k_queue *) fifo)
+
 /**
  * @brief Statically define and initialize a fifo.
  *