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 FIFORunner::TaskInfo,
  80           public detail::FdSetBase,
  81           public FdManager::Event
  82     {
  83     public:
  84         ///////////////////////////////////////////////////////////////////////////
  85         // Types
  86
  87         typedef boost::function<void (int)> Callback;
  88
  89         enum Events {
  90             EV_READ = FdManager::EV_READ, EV_PRIO = FdManager::EV_PRIO, EV_WRITE = FdManager::EV_WRITE,
  91             EV_HUP = FdManager::EV_HUP, EV_ERR = FdManager::EV_ERR,
  92             EV_ALL = FdManager::EV_READ | FdManager::EV_WRITE | FdManager::EV_PRIO
  93         };
  94
  95         ///////////////////////////////////////////////////////////////////////////
  96         ///\name Structors and default members
  97         ///@{
  98
  99         template <class Handle>
 100         FdEvent(std::string const & name, Callback const & cb, Handle const & handle, int events,
 101                 bool initiallyEnabled = true);
 102                                         ///< Register a file descriptor event
 103                                         /**< Registers \a cb to be called when any of the \a events
 104                                              occurs on \a handle. If \a initiallyEnabled is set \c
 105                                              false, the callback will not be enabled
 106                                              automatically. Use enable() to do so.
 107                                              \param[in] name Descriptive event name (purely
 108                                                  informational)
 109                                              \param[in] cb Callback to call
 110                                              \param[in] handle Handle (file descriptor) to watch
 111                                              \param[in] events Events to watch for (see Events enum)
 112                                              \param[in] initiallyEnabled if set \c false, do not
 113                                                  enable callback automatically. */
 114         FdEvent(std::string const & name, Callback const & cb);
 115                                         ///< Create a file descriptor event
 116                                         /**< Creates a file descriptor event for callback \a cb. The
 117                                              event is initially disabled. Use the other members to
 118                                              set the missing parameters and enable the event.
 119                                              \param[in] name Descriptive event name (purely
 120                                                  informational)
 121                                              \param[in] cb Callback to call. This callback may \e
 122                                                  explicitly be set to \c 0 if the value cannot be
 123                                                  initialized. */
 124         ~FdEvent();
 125
 126         ///@}
 127         ///////////////////////////////////////////////////////////////////////////
 128
 129         void disable();                 ///< Disable event
 130         void enable();                  ///< Enable event
 131         bool enabled();                 ///< \c true if event enabled, \c false otherwise
 132
 133         FdEvent & action(Callback const & cb); ///< Change event callback
 134
 135         FdEvent & events(int events);   ///< Change event mask
 136         FdEvent & addEvents(int events); ///< Add additional events to event mask
 137         FdEvent & removeEvents(int events); ///< Remove events from event mask
 138         int events();                   ///< Current event mask
 139
 140         template <class Handle>
 141         FdEvent & handle(Handle const & handle); ///< Change event file handle
 142
 143         struct DuplicateEventRegistrationException : public Exception
 144         { DuplicateEventRegistrationException() : Exception("duplicate fd event registration") {} };
 145
 146     protected:
 147
 148     private:
 149         virtual void signal(int events);
 150         virtual void run();
 151
 152         Callback cb_;
 153         int fd_;
 154         bool pollable_;
 155         int events_;
 156         int signaledEvents_;
 157
 158         friend class detail::FdSetCompare;
 159         friend class detail::FindFd;
 160         friend class detail::FdDispatcher;
 161         friend class detail::FileDispatcher;
 162     };
 163
 164     int retrieve_filehandle(int fd);
 165
 166 }}
 167
 168 ///////////////////////////////hh.e////////////////////////////////////////
 169 #include "FdEvent.cci"
 170 #include "FdEvent.ct"
 171 #include "FdEvent.cti"
 172 #endif
 173
 174 \f
 175 // Local Variables:
 176 // mode: c++
 177 // fill-column: 100
 178 // comment-column: 40
 179 // c-file-style: "senf"
 180 // indent-tabs-mode: nil
 181 // ispell-local-dictionary: "american"
 182 // compile-command: "scons -u test"
 183 // End: