Scheduler/FdEvent.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2008
   4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
   5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
   6 //     Stefan Bund <g0dil@berlios.de>
   7 //
   8 // This program is free software; you can redistribute it and/or modify
   9 // it under the terms of the GNU General Public License as published by
  10 // the Free Software Foundation; either version 2 of the License, or
  11 // (at your option) any later version.
  12 //
  13 // This program is distributed in the hope that it will be useful,
  14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 // GNU General Public License for more details.
  17 //
  18 // You should have received a copy of the GNU General Public License
  19 // along with this program; if not, write to the
  20 // Free Software Foundation, Inc.,
  21 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  22
  23 /** \file
  24     \brief FdDispatcher public header */
  25
  26 #ifndef HH_FdDispatcher_
  27 #define HH_FdDispatcher_ 1
  28
  29 // Custom includes
  30 #include "../boost/intrusive/iset_hook.hpp"
  31 #include "../Utils/Exception.hh"
  32 #include "FdManager.hh"
  33 #include "FIFORunner.hh"
  34
  35 //#include "FdEvent.mpp"
  36 ///////////////////////////////hh.p////////////////////////////////////////
  37
  38 namespace senf {
  39 namespace scheduler {
  40
  41     namespace detail {
  42         struct FdSetTag;
  43         typedef boost::intrusive::iset_base_hook<FdSetTag> FdSetBase;
  44         struct FdSetCompare;
  45         struct FindFd;
  46         class FdDispatcher;
  47         class FileDispatcher;
  48     }
  49
  50     /** \brief File descriptor event
  51
  52         The FdEvent class registers a file descriptor for read or write events.
  53
  54         There are a number of different event types supported for file descriptors. Those are
  55         specified using a bit mask. Possible events are
  56
  57         \li \c EV_READ: File descriptor is readable (or at EOF)
  58         \li \c EV_PRIO: There is out-of-band data available to be read on the file descriptor
  59         \li \c EV_WRITE: File descriptor is writable
  60
  61         The callback will be called with one additional argument. This argument is the event mask of
  62         type int. This mask will tell, which of the registered events are signaled. There are some
  63         additional flags which can be set when calling the handler callback:
  64
  65         \li \c EV_HUP: The other end has closed the connection
  66         \li \c EV_ERR: Transport error
  67
  68         Only a single handler may be registered for any combination of file descriptor and event
  69         otherwise a DuplicateEventRegistrationException is thrown.
  70
  71         The file descriptor is specified using an arbitrary handle type which supports the \c
  72         retrieve_filehandle() protocol: There must be a global function \c retrieve_filehandle
  73         callable with the handle type. This function must return the file descriptor associated with
  74         the handle. Implementations for integer numbers (explicit file descriptors) and senf socket
  75         handles are provided.
  76
  77         The FdEvent class is an implementation of the RAII idiom: The event will be automatically
  78         unregistered in the FdEvent destructor. The TimerEvent instance should be created
  79         within the same scope or on a scope below where the callback is defined (e.g. if the
  80         callback is a member function it should be defined as a class member).
  81      */
  82     class FdEvent
  83         : public detail::FIFORunner::TaskInfo,
  84           public detail::FdSetBase,
  85           public detail::FdManager::Event
  86     {
  87     public:
  88         ///////////////////////////////////////////////////////////////////////////
  89         // Types
  90
  91         typedef boost::function<void (int)> Callback;
  92
  93         enum Events {
  94             EV_NONE = 0                             ///< No event
  95           , EV_READ = detail::FdManager::EV_READ    ///< fd readable (or EOF)
  96           , EV_PRIO = detail::FdManager::EV_PRIO    ///< OOB data available for read
  97           , EV_WRITE = detail::FdManager::EV_WRITE  ///< fd writable
  98           , EV_HUP = detail::FdManager::EV_HUP      ///< remote end closed connection
  99           , EV_ERR = detail::FdManager::EV_ERR      ///< transport error
 100           , EV_ALL = (detail::FdManager::EV_READ
 101                       | detail::FdManager::EV_WRITE
 102                       | detail::FdManager::EV_PRIO) ///< register all events (read, prio and write)
 103         };
 104
 105         ///////////////////////////////////////////////////////////////////////////
 106         ///\name Structors and default members
 107         ///@{
 108
 109         template <class Handle>
 110         FdEvent(std::string const & name, Callback const & cb, Handle const & handle, int events,
 111                 bool initiallyEnabled = true);
 112                                         ///< Register a file descriptor event
 113                                         /**< Registers \a cb to be called when any of the \a events
 114                                              occurs on \a handle. If \a initiallyEnabled is set \c
 115                                              false, the callback will not be enabled
 116                                              automatically. Use enable() to do so.
 117                                              \param[in] name Descriptive event name (purely
 118                                                  informational)
 119                                              \param[in] cb Callback to call
 120                                              \param[in] handle Handle (file descriptor) to watch
 121                                              \param[in] events Events to watch for (see Events enum)
 122                                              \param[in] initiallyEnabled if set \c false, do not
 123                                                  enable callback automatically. */
 124         FdEvent(std::string const & name, Callback const & cb);
 125                                         ///< Create a file descriptor event
 126                                         /**< Creates a file descriptor event for callback \a cb. The
 127                                              event is initially disabled. Use the other members to
 128                                              set the missing parameters and enable the event.
 129                                              \param[in] name Descriptive event name (purely
 130                                                  informational)
 131                                              \param[in] cb Callback to call. This callback may \e
 132                                                  explicitly be set to \c 0 if the value cannot be
 133                                                  initialized. */
 134         ~FdEvent();
 135
 136         ///@}
 137         ///////////////////////////////////////////////////////////////////////////
 138
 139         void disable();                 ///< Disable event
 140         void enable();                  ///< Enable event
 141         bool enabled();                 ///< \c true if event enabled, \c false otherwise
 142
 143         FdEvent & action(Callback const & cb); ///< Change event callback
 144
 145         FdEvent & events(int events);   ///< Change event mask
 146         FdEvent & addEvents(int events); ///< Add additional events to event mask
 147         FdEvent & removeEvents(int events); ///< Remove events from event mask
 148         int events();                   ///< Current event mask
 149
 150         template <class Handle>
 151         FdEvent & handle(Handle const & handle); ///< Change event file handle
 152
 153         struct DuplicateEventRegistrationException : public Exception
 154         { DuplicateEventRegistrationException() : Exception("duplicate fd event registration") {} };
 155
 156     protected:
 157
 158     private:
 159         virtual void signal(int events);
 160         virtual void run();
 161
 162         Callback cb_;
 163         int fd_;
 164         bool pollable_;
 165         int events_;
 166         int signaledEvents_;
 167
 168         friend class detail::FdSetCompare;
 169         friend class detail::FindFd;
 170         friend class detail::FdDispatcher;
 171         friend class detail::FileDispatcher;
 172     };
 173
 174 }}
 175
 176 int retrieve_filehandle(int fd);
 177
 178 ///////////////////////////////hh.e////////////////////////////////////////
 179 #include "FdEvent.cci"
 180 #include "FdEvent.ct"
 181 #include "FdEvent.cti"
 182 #endif
 183
 184 \f
 185 // Local Variables:
 186 // mode: c++
 187 // fill-column: 100
 188 // comment-column: 40
 189 // c-file-style: "senf"
 190 // indent-tabs-mode: nil
 191 // ispell-local-dictionary: "american"
 192 // compile-command: "scons -u test"
 193 // End: