ChangeLogTag:Mon Aug 30 16:48:34 UTC 2010 Steve Huston <shuston@riverace.com>

4 files changed, 47 insertions, 10 deletions

diff --git a/ChangeLog b/ChangeLog
index e8e7db181e0..c54d1e38b93 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+Mon Aug 30 16:48:34 UTC 2010  Steve Huston  <shuston@riverace.com>
+
+        * ace/FIFO.h:
+        * ace/FIFO_Recv.h:
+        * ace/FIFO_Send.h: Clarified initialization and open behavior.
+
 Fri Aug 27 19:17:11 UTC 2010  Steve Huston  <shuston@riverace.com>
 
         * ace/ACE.cpp (handle_ready, handle_timed_complete,
diff --git a/ace/FIFO.h b/ace/FIFO.h
index 3866b0e4eb8..9dc5e7feb92 100644
--- a/ace/FIFO.h
+++ b/ace/FIFO.h
@@ -32,15 +32,24 @@ ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  * @brief Abstract base class for UNIX FIFOs
  *
  * UNIX FIFOs are also known Named Pipes, which are totally
- * unrelated to Win32 Named Pipes.  If you want to use a local
- * IPC mechanism that will be portable to both UNIX and Win32,
- * take a look at the <ACE_SPIPE_*> classes.
+ * unrelated to Windows Named Pipes.  If you want to use a local
+ * IPC mechanism that will be portable to both UNIX and Windows,
+ * take a look at the ACE_Pipe or ACE_SPIPE_Stream classes.
  */
 class ACE_Export ACE_FIFO : public ACE_IPC_SAP
 {
 public:
-  /// Open up the named pipe on the <rendezvous> in accordance with the
-  /// flags.
+  /**
+   * Open up the named pipe (FIFO) on the @a rendezvous point in accordance
+   * with the @a flags.
+   *
+   * If @a flags contains @c O_CREAT open() will attempt to call mkfifo()
+   * to create the FIFO before opening it. In this case, this method
+   * will not fail simply because the fifo already exists.
+   *
+   * @retval 0 for success
+   * @retval -1 for error; errno contains the error code.
+   */
   int open (const ACE_TCHAR *rendezvous, int flags, mode_t perms,
             LPSECURITY_ATTRIBUTES sa = 0);
 
@@ -61,14 +70,19 @@ public:
   ACE_ALLOC_HOOK_DECLARE;
 
 protected:
-  // = Make these protected to ensure that the class is "abstract."
+  /**
+   * Protected constructors ensure this class cannot be used directly.
+   * User code must use ACE_FIFO_Send and/or ACE_FIFO_Recv.
+   */
+  //@{
   /// Default constructor.
   ACE_FIFO (void);
 
-  /// Open up the named pipe on the <rendezvous> in accordance with the
+  /// Open up the named pipe on the @a rendezvous in accordance with the
   /// flags.
   ACE_FIFO (const ACE_TCHAR *rendezvous, int flags, mode_t perms,
             LPSECURITY_ATTRIBUTES sa = 0);
+  //@}
 
 private:
   /// Rendezvous point in the file system.
diff --git a/ace/FIFO_Recv.h b/ace/FIFO_Recv.h
index fa18cf291a5..232d3840825 100644
--- a/ace/FIFO_Recv.h
+++ b/ace/FIFO_Recv.h
@@ -36,7 +36,17 @@ ACE_BEGIN_VERSIONED_NAMESPACE_DECL
 class ACE_Export ACE_FIFO_Recv : public ACE_FIFO
 {
 public:
-  // = Initialization methods.
+  /// @name Initialization methods.
+  ///
+  /// Note that @c ACE_NONBLOCK will be added to any @a flags value passed.
+  /// This causes the open to succeed even if no writer has yet opened the
+  /// fifo. There is no way to disable this behavior.
+  ///
+  /// @arg persistent  Means "open fifo for writing, as well as
+  /// reading."  This ensures that the fifo never gets EOF, even if there
+  /// aren't any writers at the moment!
+  //@{
+
   /// Default constructor.
   ACE_FIFO_Recv (void);
 
@@ -53,8 +63,9 @@ public:
             mode_t perms = ACE_DEFAULT_FILE_PERMS,
             int persistent = 1,
             LPSECURITY_ATTRIBUTES sa = 0);
+  //@}
 
-  /// Close down the named pipe.
+  /// Close down the fifo.
   int close (void);
 
   /// Recv @a buf of up to @a len bytes.
diff --git a/ace/FIFO_Send.h b/ace/FIFO_Send.h
index 51a14508114..ae1576bd4f2 100644
--- a/ace/FIFO_Send.h
+++ b/ace/FIFO_Send.h
@@ -35,7 +35,12 @@ ACE_BEGIN_VERSIONED_NAMESPACE_DECL
 class ACE_Export ACE_FIFO_Send : public ACE_FIFO
 {
 public:
-  // = Initialization methods.
+  /// @name Initialization methods.
+  ///
+  /// Note that @c O_WRONLY will be added to any @a flags value passed.
+  /// Default behavior is to block until a receiver also opens the fifo.
+  /// To use non-blocking behavior include ACE_NONBLOCK in @a flags.
+  //@{
   /// Default constructor.
   ACE_FIFO_Send (void);
 
@@ -50,6 +55,7 @@ public:
             int flags = O_WRONLY,
             mode_t perms = ACE_DEFAULT_FILE_PERMS,
             LPSECURITY_ATTRIBUTES sa = 0);
+  //@}
 
   /// Send @a buf of up to @a len bytes.
   ssize_t send (const void *buf, size_t len);