ACE/ace/Pipe.h

   1 // -*- C++ -*-
   2
   3 //==========================================================================
   4 /**
   5  *  @file    Pipe.h
   6  *
   7  *  @author Douglas C. Schmidt <d.schmidt@vanderbilt.edu>
   8  */
   9 //==========================================================================
  10
  11 #ifndef ACE_PIPE_H
  12 #define ACE_PIPE_H
  13
  14 #include /**/ "ace/pre.h"
  15
  16 #include /**/ "ace/ACE_export.h"
  17
  18 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  19 # pragma once
  20 #endif /* ACE_LACKS_PRAGMA_ONCE */
  21
  22 #include "ace/Default_Constants.h"
  23
  24 #include "ace/OS_NS_sys_uio.h"
  25 #include "ace/OS_NS_unistd.h"
  26
  27 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  28
  29 // Forward decl.
  30 class ACE_Message_Block;
  31 class ACE_Time_Value;
  32
  33 /**
  34  * @class ACE_Pipe
  35  *
  36  * @brief Provides a portable bidirectional "pipe" abstraction.
  37  *
  38  * This class is designed to work with select()-based demuxers, such
  39  * as the ACE_Select_Reactor, which is why it uses sockets on Windows
  40  * rather than Win32 pipes (which aren't select()'able).
  41  */
  42 class ACE_Export ACE_Pipe
  43 {
  44 public:
  45   /// Default constructor (does nothing...).
  46   ACE_Pipe ();
  47
  48   /// Open the pipe and initialize the handles.
  49   ACE_Pipe (ACE_HANDLE handles[2]);
  50
  51   /// Initialize the ACE_Pipe from the @a read and @a write handles.
  52   ACE_Pipe (ACE_HANDLE read, ACE_HANDLE write);
  53
  54   /// Default dtor.  It doesn't close the handles for you.
  55   ~ACE_Pipe ();
  56
  57   /// Open the pipe and initialize the handles.
  58   int open (ACE_HANDLE handles[2]);
  59
  60   /// Open the pipe, setting the buffer size to the maximum.
  61   int open (int buffer_size = ACE_DEFAULT_MAX_SOCKET_BUFSIZ);
  62
  63   /// Close down the pipe HANDLEs;
  64   int close ();
  65   int close_read ();
  66   int close_write ();
  67
  68   // = Accessors.
  69
  70   /**
  71    * This is the "read" side of the pipe.  Note, however, that
  72    * processes can also write to this handle as well since pipes are
  73    * bi-directional.
  74    */
  75   ACE_HANDLE read_handle () const;
  76
  77   /**
  78    * This is the "write" side of the pipe.  Note, however, that
  79    * processes can also read to this handle as well since pipes are
  80    * bi-directional.
  81    */
  82   ACE_HANDLE write_handle () const;
  83
  84   /// Dump the state of the object.
  85   void dump () const;
  86
  87   /// send upto @a n bytes in @a buf.
  88   ssize_t send (const void *buf, size_t n) const;
  89
  90   /// Recv upto @a n bytes in @a buf.
  91   ssize_t recv (void *buf, size_t n) const;
  92
  93   /// Send n bytes, keep trying until n are sent.
  94   ssize_t send_n (const void *buf, size_t n) const;
  95
  96   /// Send all the @a message_blocks chained through their <next> and
  97   /// <cont> pointers.  This call uses the underlying OS gather-write
  98   /// operation to reduce the domain-crossing penalty.
  99   ssize_t send_n (const ACE_Message_Block *message_block,
 100                   const ACE_Time_Value *timeout = 0,
 101                   size_t *bytes_transferred = 0);
 102
 103   /// Recv n bytes, keep trying until n are received.
 104   ssize_t recv_n (void *buf, size_t n) const;
 105
 106   /// Send iovecs via <::writev>.
 107   ssize_t send (const iovec iov[], int n) const;
 108
 109   /// Recv iovecs via <::readv>.
 110   ssize_t recv (iovec iov[], int n) const;
 111
 112 #if !defined (ACE_LACKS_VA_FUNCTIONS)
 113   /**
 114    * Send N char *ptrs and int lengths.  Note that the char *'s
 115    * precede the ints (basically, an varargs version of writev).  The
 116    * count N is the *total* number of trailing arguments, *not* a
 117    * couple of the number of tuple pairs!
 118    */
 119   ssize_t send (size_t n, ...) const;
 120
 121   /**
 122    * This is an interface to ::readv, that doesn't use the struct
 123    * iovec explicitly.  The ... can be passed as an arbitrary number
 124    * of (char *ptr, int len) tuples.  However, the count N is the
 125    * *total* number of trailing arguments, *not* a count of the
 126    * number of tuple pairs!
 127    */
 128   ssize_t recv (size_t n, ...) const;
 129 #endif /* !ACE_LACKS_VA_FUNCTIONS */
 130
 131   /// Send @a n bytes via Win32 WriteFile using overlapped I/O.
 132   ssize_t send (const void *buf,
 133                 size_t n,
 134                 ACE_OVERLAPPED *overlapped) const;
 135
 136   /// Recv @a n bytes via Win32 ReadFile using overlapped I/O.
 137   ssize_t recv (void *buf,
 138                 size_t n,
 139                 ACE_OVERLAPPED *overlapped) const;
 140
 141   /// Send an <iovec> of size @a n to the file.
 142   ssize_t sendv (const iovec iov[],
 143                  int n) const;
 144
 145   /// Send an @c iovec of size @a n to the file.  Will block until all
 146   /// bytes are sent or an error occurs.
 147   ssize_t sendv_n (const iovec iov[],
 148                    int n) const;
 149
 150   /// Receive an @c iovec of size @a n to the file.
 151   ssize_t recvv_n (iovec iov[],
 152                    int n) const;
 153
 154 private:
 155   ACE_HANDLE handles_[2];
 156   int close_handle (int which);
 157 };
 158
 159 ACE_END_VERSIONED_NAMESPACE_DECL
 160
 161 #if defined (__ACE_INLINE__)
 162 #include "ace/Pipe.inl"
 163 #endif /* __ACE_INLINE__ */
 164
 165 #include /**/ "ace/post.h"
 166
 167 #endif /* ACE_PIPE_H */