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         The type of event is specified using an event mask. Possible events are
  55
  56         \li \c EV_READ: File descriptor is readable (or at EOF)
  57         \li \c EV_PRIO: There is out-of-band data available to be read on the file descriptor
  58         \li \c EV_WRITE: File descriptor is writable
  59
  60         These event flags can be or-ed together to form an event mask. The callback will be called
  61         with those flags set which are currently signaled. There are additional flags which may be
  62         set when calling the callback:
  63
  64         \li \c EV_HUP: The other end has closed the connection
  65         \li \c EV_ERR: Transport error
  66
  67         The file descriptor is specified using an arbitrary handle type which supports the \c
  68         retrieve_filehandle() protocol: There must be a global function \c retrieve_filehandle
  69         callable with the handle type. This function must return the file descriptor associated with
  70         the handle. Implementations for integer numbers (explicit file descriptors) and senf socket
  71         handles are provided.
  72
  73         The FdEvent class is an implementation of the RAII idiom: The event will be automatically
  74         unregistered in the FdEvent destructor. The TimerEvent instance should be created
  75         within the same scope or on a scope below where the callback is defined (e.g. if the
  76         callback is a member function it should be defined as a class member).
  77      */
  78     class FdEvent
  79         : public detail::FIFORunner::TaskInfo,
  80           public detail::FdSetBase,
  81           public detail::FdManager::Event
  82     {
  83     public:
  84         ///////////////////////////////////////////////////////////////////////////
  85         // Types
  86
  87         typedef boost::function<void (int)> Callback;
  88
  89         enum Events {
  90             EV_NONE = 0,
  91             EV_READ = detail::FdManager::EV_READ,
  92             EV_PRIO = detail::FdManager::EV_PRIO,
  93             EV_WRITE = detail::FdManager::EV_WRITE,
  94             EV_HUP = detail::FdManager::EV_HUP,
  95             EV_ERR = detail::FdManager::EV_ERR,
  96             EV_ALL = (detail::FdManager::EV_READ
  97                       | detail::FdManager::EV_WRITE
  98                       | detail::FdManager::EV_PRIO)
  99         };
 100
 101         ///////////////////////////////////////////////////////////////////////////
 102         ///\name Structors and default members
 103         ///@{
 104
 105         template <class Handle>
 106         FdEvent(std::string const & name, Callback const & cb, Handle const & handle, int events,
 107                 bool initiallyEnabled = true);
 108                                         ///< Register a file descriptor event
 109                                         /**< Registers \a cb to be called when any of the \a events
 110                                              occurs on \a handle. If \a initiallyEnabled is set \c
 111                                              false, the callback will not be enabled
 112                                              automatically. Use enable() to do so.
 113                                              \param[in] name Descriptive event name (purely
 114                                                  informational)
 115                                              \param[in] cb Callback to call
 116                                              \param[in] handle Handle (file descriptor) to watch
 117                                              \param[in] events Events to watch for (see Events enum)
 118                                              \param[in] initiallyEnabled if set \c false, do not
 119                                                  enable callback automatically. */
 120         FdEvent(std::string const & name, Callback const & cb);
 121                                         ///< Create a file descriptor event
 122                                         /**< Creates a file descriptor event for callback \a cb. The
 123                                              event is initially disabled. Use the other members to
 124                                              set the missing parameters and enable the event.
 125                                              \param[in] name Descriptive event name (purely
 126                                                  informational)
 127                                              \param[in] cb Callback to call. This callback may \e
 128                                                  explicitly be set to \c 0 if the value cannot be
 129                                                  initialized. */
 130         ~FdEvent();
 131
 132         ///@}
 133         ///////////////////////////////////////////////////////////////////////////
 134
 135         void disable();                 ///< Disable event
 136         void enable();                  ///< Enable event
 137         bool enabled();                 ///< \c true if event enabled, \c false otherwise
 138
 139         FdEvent & action(Callback const & cb); ///< Change event callback
 140
 141         FdEvent & events(int events);   ///< Change event mask
 142         FdEvent & addEvents(int events); ///< Add additional events to event mask
 143         FdEvent & removeEvents(int events); ///< Remove events from event mask
 144         int events();                   ///< Current event mask
 145
 146         template <class Handle>
 147         FdEvent & handle(Handle const & handle); ///< Change event file handle
 148
 149         struct DuplicateEventRegistrationException : public Exception
 150         { DuplicateEventRegistrationException() : Exception("duplicate fd event registration") {} };
 151
 152     protected:
 153
 154     private:
 155         virtual void signal(int events);
 156         virtual void run();
 157
 158         Callback cb_;
 159         int fd_;
 160         bool pollable_;
 161         int events_;
 162         int signaledEvents_;
 163
 164         friend class detail::FdSetCompare;
 165         friend class detail::FindFd;
 166         friend class detail::FdDispatcher;
 167         friend class detail::FileDispatcher;
 168     };
 169
 170     int retrieve_filehandle(int fd);
 171
 172 }}
 173
 174 ///////////////////////////////hh.e////////////////////////////////////////
 175 #include "FdEvent.cci"
 176 #include "FdEvent.ct"
 177 #include "FdEvent.cti"
 178 #endif
 179
 180 \f
 181 // Local Variables:
 182 // mode: c++
 183 // fill-column: 100
 184 // comment-column: 40
 185 // c-file-style: "senf"
 186 // indent-tabs-mode: nil
 187 // ispell-local-dictionary: "american"
 188 // compile-command: "scons -u test"
 189 // End: