---

FileDescriptor.h

Go to the documentation of this file.

/* -*- c++ -*- */
#ifndef MPS_FileDescriptor_H
#define MPS_FileDescriptor_H

#include <sys/time.h>
#include <sys/types.h>
#include <unistd.h>

#ifdef __WIN32__
#include <winsock.h>
#endif

#include <ref.h>
#include <exception>
#include <string>
#include <vector>
#include <map>
#include <algorithm>

class FileDescriptor;
class FileDescriptorManager;

/**
 * Associates callbacks with events on a given Unix File Descriptor,
 * and provides an interface to Unix system calls dealing with file
 * descriptors. Works in association with a FileDescriptorManager. */
class FileDescriptor: public Referenceable {
public:
  //---------------------------------------------------------------------------
  /**
   * Thrown by methods on FileDescriptor and subclasses. Compatible
   * with std::exception. */
  class Exception: public std::exception {
  private:
    string message;     ///< Description of the error condition
    int savedErrno;     ///< Errno at the time of the error; zero if none available

  public:
    Exception(string const &msg, int _savedErrno = 0)
      : message(msg),
        savedErrno(_savedErrno)
    {}

    virtual char const *what() const { return message.c_str(); }        ///< Extract error msg
    int getErrno() const { return savedErrno; }                         ///< Extract saved errno
  };

  /**
   * Subclass of FileDescriptor::Exception for indicating end-of-file
   * conditions to callers. */
  class EndOfFile: public Exception {
  public:
    EndOfFile(string const &msg)
      : Exception(msg)
    {}
  };
  //---------------------------------------------------------------------------

  /**
   * Subclass this to provide callback-methods to be called by methods
   * on FileDescriptor and subclasses. */
  class Callback: public Referenceable {
  public:
    /**
     * All callbacks called by FileDescriptor methods must be of this
     * type. The single argument, desc, is the FileDescriptor that the
     * event occurred on. */
    typedef void (Callback::*Method)(ref<FileDescriptor> const &desc);
  };

private:
  ref<FileDescriptorManager> fdMgr;             ///< The FileDescriptorManager that manages this
  int fd;                                       ///< Unix fd we are wrapping
  char buf[1024];                               ///< Input buffer (output is unbuffered)
  int buflen;                                   ///< Number of bytes in the buffer
  int pos;                                      ///< Index of next byte to return

  /// Describes a particular bound callback
  struct callback_entry_t {
    ref<Callback> callback;                     ///< The callback itself
    Callback::Method callbackMethod;            ///< The method to invoke on the callback

    callback_entry_t()
      : callback(0),
        callbackMethod(0)
    {}
  };

  callback_entry_t readCallback;                ///< Callback for read-available
  callback_entry_t writeCallback;               ///< Callback for write-available

  /// Fill buffer with at least one byte. Returns true if okay, false if would block.
  bool fillBuffer();

  // Disallow copy ctor etc.
  FileDescriptor(FileDescriptor const &other);
  FileDescriptor const &operator=(FileDescriptor const &other);

  /**
   * Updates the fd_set objects in our FileDescriptorManager depending
   * on whether we are interested in read-available, write-available,
   * or both conditions. */
  void updateCallbacks();

protected:
  /**
   * Override, eg. for sockets on Linux, where you can use
   * ::send(... MSG_NOSIGNAL) etc., and for sockets on Win32 where you
   * have to use recv and send instead of read and write. Default
   * (superclass) behaviour is to use ::write and ::read. */
  //@{
  virtual int lowlevel_read(int handle, char *buf, int len);
  virtual int lowlevel_write(int handle, char const *buf, int len);
  virtual int lowlevel_close(int handle);
  //@}

public:
  /// This constructor wraps the passed in _fd in association with the passed in _fdMgr.
  FileDescriptor(ref<FileDescriptorManager> const &_fdMgr, int _fd);

  /// The file-descriptor is close()d on destruction.
  virtual ~FileDescriptor();

  bool isOpen() const { return (fd != -1); }    ///< true -> this fd is open.

  /// true -> some bytes are available for read *now*.
  bool inputReady() {
    fillBuffer();
    return isOpen() && (pos < buflen);
  }

  int getFd() const { return fd; }              ///< Access the file descriptor wrapped by this.
  ref<FileDescriptorManager> const &getFdMgr() const;   ///< Access our controlling fdMgr

  virtual void close();                         ///< Closes this fd.

  bool setNonBlocking(bool on);                 ///< true -> success

  //@{
  /// Installs a callback for read-available events.
  void setReadCallback(ref<Callback> const &cb, Callback::Method cbm);
  /// Installs a callback for write-available events.
  void setWriteCallback(ref<Callback> const &cb, Callback::Method cbm);

  /// Clear our read-available callback - we are no longer interested in those events
  void clearReadCallback();
  /// Clear our write-available callback - we are no longer interested in those events
  void clearWriteCallback();

  void fireReadCallback();      ///< Calls the read-callback; does not clear the callback
  void fireWriteCallback();     ///< Calls the write-callback; does not clear the callback
  //@}

  /**
   * Calls select() to wait for some event on this fd only; all others
   * are ignored.
   *
   * %%% (NOTE: should probably be protected rather than public; don't
   * %%% call it unless you're sure you know what you're doing - and
   * %%% let tonyg@kcbbs.gen.nz know if you *do* find a legitimate use
   * %%% for it!) */
  void block(bool forRead, bool forWrite);

  //@{
  /**
   * These process as many bytes as possible without blocking, and
   * return the number of bytes processed, unless 'complete' is set,
   * in which case they keep working until exactly len bytes have been
   * processed or an exception is met. */
  int read(char *inbuf, int len, bool complete = false);
  int write(char const *outbuf, int len, bool complete = false);
  //@}

  /// Read a single byte.
  bool read(int &ch) {
    if (!fillBuffer())
      return false;
    ch = buf[pos++];
    return true;
  }
};

/**
 * Manages a collection of FileDescriptors, using fd_sets and
 * select(). */
class FileDescriptorManager: public Referenceable {
private:
  typedef vector< ref<FileDescriptor> > descVec_t;      ///< Allow lookup of object from fd number

  descVec_t allFds;     ///< All FileDescriptor objects registered with this fdMgr
  int countRegistered;  ///< Count of registered FileDescriptor objects
  int maxFd;            ///< Maximum fd number of all registered FileDescriptors
  fd_set readFds;       ///< Set of fds interested in read-available events
  fd_set writeFds;      ///< Set of fds interested in write-available events

  //@{
  friend class FileDescriptor;
  /// Adds, updates or disables the entry for a given FileDescriptor.
  void update(ref<FileDescriptor> const &fd, bool forRead, bool forWrite);
  /// Removes the entry for a given FileDescriptor completely.
  void remove(int fdnum);
  //@}

public:
  FileDescriptorManager();

  void closeAll();              ///< Force close all FileDescriptors managed by this

  //@{
  int getMaxFd() const { return maxFd; }                ///< Returns the maximum FD managed
  void fillFdSet(fd_set *rfds, fd_set *wfds) const;     ///< Fills in all entries for managed fds
  void processFdSet(fd_set *rfds, fd_set *wfds);        ///< Runs work from a post-select() fdset
  //@}

  //@{
  /**
   * Wait for incoming work for up to the given timeout, or forever if
   * timeout is NULL.
   *
   * @return true for "work processed"; false for "timed out" */
  bool poll(struct timeval const *timeout);

  /// Repeatedly calls poll(NULL).
  void mainloop();
  //@}

  //@{
  /// Statistics.
  int getCountRegistered() const { return countRegistered; }
  //@}
};

#endif

---