senf/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_SENF_Scheduler_FdEvent_
  27 #define HH_SENF_Scheduler_FdEvent_ 1
  28
  29 // Custom includes
  30 #include <senf/boost_intrusive/iset_hook.hpp>
  31 #include <senf/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 FdEvent instance should be created within the
  79         same scope or on a scope below where the callback is defined (e.g. if the callback is a
  80         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
 142         FdEvent & action(Callback const & cb); ///< Change event callback
 143
 144         FdEvent & events(int events);   ///< Change event mask
 145         FdEvent & addEvents(int events); ///< Add additional events to event mask
 146         FdEvent & removeEvents(int events); ///< Remove events from event mask
 147         int events();                   ///< Current event mask
 148
 149         template <class Handle>
 150         FdEvent & handle(Handle const & handle); ///< Change event file handle
 151
 152         struct DuplicateEventRegistrationException : public Exception
 153         { DuplicateEventRegistrationException() : Exception("duplicate fd event registration") {} };
 154
 155     protected:
 156
 157     private:
 158         virtual void signal(int events);
 159         virtual void v_run();
 160         virtual char const * v_type() const;
 161         virtual std::string v_info() const;
 162
 163         Callback cb_;
 164         int fd_;
 165         bool pollable_;
 166         int events_;
 167         int signaledEvents_;
 168
 169         friend class detail::FdSetCompare;
 170         friend class detail::FindFd;
 171         friend class detail::FdDispatcher;
 172         friend class detail::FileDispatcher;
 173     };
 174
 175     /** \brief Get file descriptor from handle object
 176
 177         This function will query the \a handle for it's file descriptor. The real implementation
 178         must be provided by a freestanding function \c retrieve_filehandle(Handle const & h) within
 179         the namespace of \a Handle.
 180      */
 181     template <class Handle>
 182     int get_descriptor(Handle const & handle);
 183 }}
 184
 185 ///////////////////////////////hh.e////////////////////////////////////////
 186 #include "FdEvent.cci"
 187 #include "FdEvent.ct"
 188 #include "FdEvent.cti"
 189 #endif
 190
 191 \f
 192 // Local Variables:
 193 // mode: c++
 194 // fill-column: 100
 195 // comment-column: 40
 196 // c-file-style: "senf"
 197 // indent-tabs-mode: nil
 198 // ispell-local-dictionary: "american"
 199 // compile-command: "scons -u test"
 200 // End: