doc: Document pipe flush routines
Adds documentation for the two new flush routines:
k_pipe_buffer_flush()
k_pipe_flush()
Signed-off-by: Peter Mitsis <peter.mitsis@intel.com>
diff --git a/doc/reference/kernel/data_passing/pipes.rst b/doc/reference/kernel/data_passing/pipes.rst
index ddccdd0..593edfb 100644
--- a/doc/reference/kernel/data_passing/pipes.rst
+++ b/doc/reference/kernel/data_passing/pipes.rst
@@ -41,9 +41,21 @@
data is either copied from the pipe's ring buffer or directly from the
waiting sender(s).
+Data may also be **flushed** from a pipe by a thread. Flushing can be performed
+either on the entire pipe or on only its ring buffer. Flushing the entire pipe
+is equivalent to reading all the information in the ring buffer **and** waiting
+to be written into a giant temporary buffer which is then discarded. Flushing
+the ring buffer is equivalent to reading **only** the data in the ring buffer
+into a temporary buffer which is then discarded. Flushing the ring buffer does
+not guarantee that the ring buffer will stay empty; flushing it may allow a
+pended writer to fill the ring buffer.
+
+.. note::
+ Flushing does not in practice allocate or use additional buffers.
+
.. note::
The kernel does NOT allow for an ISR to send or receive data to/from a
- pipe even if it does not attempt to wait for space/data.
+ pipe or flush even if it does not attempt to wait for space/data.
Implementation
**************
@@ -152,9 +164,6 @@
}
}
-Suggested uses
-**************
-
Use a pipe to send streams of data between threads.
.. note::
@@ -162,6 +171,50 @@
it is often preferable to send pointers to large data items to avoid
copying the data.
+Flushing a Pipe's Buffer
+========================
+
+Data is flushed from the pipe's ring buffer by calling
+:c:func:`k_pipe_buffer_flush`.
+
+The following code builds on the examples above, and flushes the pipe's
+buffer.
+
+.. code-block:: c
+
+ void monitor_thread(void)
+ {
+ while (1) {
+ ...
+ /* Pipe buffer contains stale data. Flush it. */
+ k_pipe_buffer_flush(&my_pipe);
+ ...
+ }
+ }
+
+Flushing a Pipe
+===============
+
+All data in the pipe is flushed by calling :c:func:`k_pipe_flush`.
+
+The following code builds on the examples above, and flushes all the
+data in the pipe.
+
+Suggested uses
+**************
+
+.. code-block:: c
+
+ void monitor_thread(void)
+ {
+ while (1) {
+ ...
+ /* Critical error detected. Flush the entire pipe to reset it. */
+ k_pipe_flush(&my_pipe);
+ ...
+ }
+ }
+
Configuration Options
*********************
