[newlib-cygwin] Cygwin: fhandler_fifo.cc: add commentary

[newlib-cygwin] Cygwin: fhandler_fifo.cc: add commentary

[Ken Brown]

https://sourceware.org/git/gitweb.cgi?p=newlib-cygwin.git;h=279f230620d784c7df91dc5242f76427e706ded7

commit 279f230620d784c7df91dc5242f76427e706ded7
Author: Ken Brown <kbrown@cornell.edu>
Date:   Sat Feb 1 16:36:31 2020 -0500

    Cygwin: fhandler_fifo.cc: add commentary

Diff:
---
 winsup/cygwin/fhandler_fifo.cc | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/winsup/cygwin/fhandler_fifo.cc b/winsup/cygwin/fhandler_fifo.cc
index ef568f6..19cd0e5 100644
--- a/winsup/cygwin/fhandler_fifo.cc
+++ b/winsup/cygwin/fhandler_fifo.cc
@@ -22,6 +22,35 @@
 #include "ntdll.h"
 #include "cygwait.h"
 
+/*
+   Overview:
+
+     Currently a FIFO can be opened once for reading and multiple
+     times for writing.  Any attempt to open the FIFO a second time
+     for reading fails with EACCES (from STATUS_ACCESS_DENIED).
+
+     When a FIFO is opened for reading,
+     fhandler_fifo::create_pipe_instance is called to create the first
+     instance of a Windows named pipe server (Windows terminology).  A
+     "listen_client" thread is also started; it waits for pipe clients
+     (Windows terminology again) to connect.  This happens every time
+     a process opens the FIFO for writing.
+
+     The listen_client thread creates new instances of the pipe server
+     as needed, so that there is always an instance available for a
+     writer to connect to.
+
+     The reader maintains a list of "fifo_client_handlers", one for
+     each pipe instance.  A fifo_client_handler manages the connection
+     between the pipe instance and a writer connected to that pipe
+     instance.
+
+     TODO: Allow a FIFO to be opened multiple times for reading.
+     Maybe this could be done by using shared memory, so that all
+     readers could have access to the same list of writers.
+*/
+
+
 /* This is only to be used for writers.  When reading,
 STATUS_PIPE_EMPTY simply means there's no data to be read. */
 #define STATUS_PIPE_IS_CLOSED(status)	\