"Fossies" - the Fresh Open Source Software Archive

Member "muscle/dataio/DataIO.h" (8 Jun 2019, 6922 Bytes) of package /linux/privat/muscle7.30.zip:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "DataIO.h" see the Fossies "Dox" file reference documentation.

    1 /* This file is Copyright 2000-2013 Meyer Sound Laboratories Inc.  See the included LICENSE.txt file for details. */
    2 
    3 #ifndef MuscleDataIO_h
    4 #define MuscleDataIO_h
    5 
    6 #include "support/NotCopyable.h"
    7 #include "util/Socket.h"
    8 #include "util/TimeUtilityFunctions.h"  // for MUSCLE_TIME_NEVER
    9 #include "util/CountedObject.h"
   10 
   11 namespace muscle {
   12  
   13 /** Abstract base class for any object that can perform basic data I/O operations.  */
   14 class DataIO : public RefCountable, private NotCopyable
   15 {
   16 public:
   17    /** Default Constructor */
   18    DataIO() {/* empty */}
   19 
   20    /** Virtual destructor, to keep C++ honest.  */
   21    virtual ~DataIO() {/* empty */}
   22 
   23    /** Tries to place (size) bytes of new data into (buffer).  Returns the
   24     *  actual number of bytes placed, or a negative value if there
   25     *  was an error.
   26     *  @param buffer Buffer to write the bytes into
   27     *  @param size Number of bytes in the buffer.
   28     *  @return Number of bytes read, or -1 on error.   
   29     */
   30    virtual int32 Read(void * buffer, uint32 size) = 0;
   31 
   32    /** Takes (size) bytes from (buffer) and pushes them in to the
   33     *  outgoing I/O stream.  Returns the actual number of bytes 
   34     *  read from (buffer) and pushed, or a negative value if there
   35     *  was an error.
   36     *  @param buffer Buffer to read the bytes from.
   37     *  @param size Number of bytes in the buffer.
   38     *  @return Number of bytes written, or -1 on error.        
   39     */
   40    virtual int32 Write(const void * buffer, uint32 size) = 0;
   41 
   42    /** 
   43     * Returns the max number of microseconds to allow
   44     * for an output stall, before presuming that the I/O is hosed.
   45     * Default implementation returns MUSCLE_TIME_NEVER, aka no limit.
   46     */
   47    virtual uint64 GetOutputStallLimit() const {return MUSCLE_TIME_NEVER;}
   48 
   49    /**
   50     * Flushes the output buffer, if possible.  For some implementations,
   51     * this is a no-op.  For others (e.g. TCPSocketDataIO) this can be
   52     * called to reduced latency of outgoing data blocks.
   53     */
   54    virtual void FlushOutput() = 0;
   55 
   56    /** 
   57     * Closes the connection.  After calling this method, the
   58     * DataIO object should not be used any more.
   59     */
   60    virtual void Shutdown() = 0;
   61 
   62    /**
   63     * This method should return a ConstSocketRef object containing a file descriptor 
   64     * that can be passed to the readSet argument of select(), so that select() can 
   65     * return when there is data available to be read from this DataIO (via Read()).
   66     *
   67     * If this DataIO cannot provide a socket that will notify select() about
   68     * data-ready-to-be-read, then this method should return GetNullSocket().
   69     *
   70     * Note that the only thing you are allowed to do with the returned ConstSocketRef
   71     * is pass it to a SocketMultiplexer to block on (or pass the underlying file descriptor
   72     * to select()/etc's readSet).  For all other operations, use the appropriate
   73     * methods in the DataIO interface instead.  If you attempt to do any other I/O operations
   74     * on Socket or its file descriptor directly, the results are undefined.
   75     */
   76    virtual const ConstSocketRef & GetReadSelectSocket() const = 0;
   77 
   78    /**
   79     * This method should return a ConstSocketRef object containing a file descriptor 
   80     * that can be passed to the writeSet argument of select(), so that select() can 
   81     * return when there is buffer space available to Write() to this DataIO.
   82     *
   83     * If this DataIO cannot provide a socket that will notify select() about
   84     * space-ready-to-be-written-to, then this method should return GetNullSocket().
   85     *
   86     * Note that the only thing you are allowed to do with the returned ConstSocketRef
   87     * is pass it to a SocketMultiplexer to block on (or pass the underlying file descriptor
   88     * to select()/etc's writeSet).  For all other operations, use the appropriate
   89     * methods in the DataIO interface instead.  If you attempt to do any other I/O operations
   90     * on Socket or its file descriptor directly, the results are undefined.
   91     */
   92    virtual const ConstSocketRef & GetWriteSelectSocket() const = 0;
   93 
   94    /**
   95     * Optional interface for returning information on when a given byte
   96     * returned by the previous Read() call was received.  Not implemented 
   97     * by default, and not implemented by any of the standard MUSCLE DataIO 
   98     * subclasses. (Used by an LCS dataIO class that needs precision timing)
   99     * @param whichByte Index of the byte in the previously returned 
  100     *                  read-buffer that you are interested in.
  101     * @param retStamp On success, this value is set to the timestamp
  102     *                 of the byte.
  103     * @return B_NO_ERROR if a timestamp was written into (retStamp),
  104     *                    otherwise B_ERROR.  Default implementation
  105     *                    always returns B_ERROR.
  106     */
  107    virtual status_t GetReadByteTimeStamp(int32 whichByte, uint64 & retStamp) const {(void) whichByte; (void) retStamp; return B_ERROR;}
  108 
  109    /**
  110     * Optional:  If your DataIO subclass is holding buffered data that it wants
  111     *            to output as soon as possible but hasn't been able to yet,
  112     *            then override this method to return true, and that will cause
  113     *            WriteBufferedOutput() to be called ASAP.  Default implementation
  114     *            always returns false.
  115     */
  116    virtual bool HasBufferedOutput() const {return false;}
  117 
  118    /**
  119     * Optional:  If this DataIO is holding any buffered output data, this method should 
  120     *            be implemented to Write() as much of that data as possible.  Default 
  121     *            implementation is a no-op.
  122     */
  123    virtual void WriteBufferedOutput() {/* empty */}
  124 
  125    /** Convenience method:  Calls Write() in a loop until the entire buffer is written, or
  126      * until an error occurs.  This method should only be used in conjunction with 
  127      * blocking I/O; it will not work reliably with non-blocking I/O.
  128      * @param buffer Pointer to the first byte of the buffer to write data from.
  129      * @param size Number of bytes to write
  130      * @return The number of bytes that were actually written.  On success,
  131      *         This will be equal to (size).  On failure, it will be a smaller value.
  132      */
  133    uint32 WriteFully(const void * buffer, uint32 size);
  134    
  135    /** Convenience method:  Calls Read() in a loop until the entire buffer is written, or
  136      * until an error occurs.  This method should only be used in conjunction with 
  137      * blocking I/O; it will not work reliably with non-blocking I/O.
  138      * @param buffer Pointer to the first byte of the buffer to place the read data into.
  139      * @param size Number of bytes to read
  140      * @return The number of bytes that were actually read.  On success,
  141      *         This will be equal to (size).  On failure, it will be a smaller value.
  142      */
  143    uint32 ReadFully(void * buffer, uint32 size);
  144 
  145 private:
  146    DECLARE_COUNTED_OBJECT(DataIO);
  147 };
  148 DECLARE_REFTYPES(DataIO);
  149 
  150 } // end namespace muscle
  151 
  152 #endif