Scheduler/Mainpage.dox

   1 // $Id$
   2 //
   3 // Copyright (C) 2007
   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 /** \mainpage The SENF Scheduler Library
  24
  25     The %Scheduler Library provides a single-threaded application event-loop multiplexing multiple
  26     event sources.
  27
  28     \autotoc
  29
  30     \section scheduler_scheduler The Scheduler
  31
  32     The Scheduler is based on the RAII principle: Every event is represented by a class
  33     instance. The event is registered in the constructor and removed by the destructor of that
  34     instance. This implementation automatically links the lifetime of an event with the lifetime of
  35     the object resposible for it's creation.
  36
  37     The Scheduler supports the following types of events::
  38
  39     \li File descriptors
  40     \li Timers
  41     \li UNIX signals
  42
  43     \see \ref senf::scheduler
  44
  45
  46     \section scheduler_clockservice The ClockService
  47
  48     To support precise event timing, the senf::ClockService class implements a reliable monotonous
  49     time source. It is based on the high precision POSIX clock and adds support for reliable
  50     conversion between an abstract clock type and absolute date/time
  51
  52     \see senf::ClockService
  53
  54
  55     \section scheduler_helpers Miscellaneous helpers
  56
  57     To ease the use of the Scheduler there are some additional helpers managing callbacks and
  58     registrations.
  59
  60     \li senf::ReadHelper reads data from an arbitrary file descritor until a use specified condition
  61         is met (e.g. number of chars read or a specific character sequence is found in the input).
  62     \li senf::WriteHelper writes data to an arbitrary file descriptor until all provided data has
  63         been written.
  64
  65
  66     \section scheduler_i Implementation
  67
  68     senf::Scheduler is only a wrapper around the real implementation. The real implementation is now
  69     based on a modular dispatcher architecture
  70
  71     \see \ref scheduler_implementation
  72  */
  73
  74 /** \page scheduler_implementation The Scheduler Implementation
  75
  76     The implentation architecture now is based on a set of dispatchers, one for each type of
  77     event.
  78
  79     \autotoc
  80
  81     \section scheduler_i_overview Overview
  82
  83     The %scheduler utilizes the following components
  84
  85     \li There is a dispatcher for each event type. This dispatcher manages the event specific
  86         registration and unregistration. The dispatcher is owns the event (and task) objects.
  87
  88     \li Every registered event is represented by an event specific event class instance.
  89
  90     \li The Dispatcher ultimately registeres with the senf::scheduler::detail::FdManager. Since the
  91         event-loop is based on epoll() (it could easily be changed to be based on select() or
  92         poll()), all events must ultimately be represented by some type of file descriptor (not
  93         necessarily a \e different file descriptor for each event).
  94
  95     \li The Dispatcher registeres all callbacks as tasks with the runner
  96         (senf::scheduler::detail::FIFORunner).
  97
  98     \li The senf::scheduler::detail::FdManager uses senf::scheduler::detail::Poller to access the
  99         low-level epoll() API.
 100
 101     All these classes are singletons.
 102
 103
 104     \section scheduler_i_dispatchers Dispatchers
 105
 106     There is a dispatcher for each event type
 107
 108     \li senf::scheduler::detail::FdDispatcher manages poll-able file descriptors. This does \e not
 109         include real files.
 110     \li senf::scheduler::detail::FileDispatcher manages disk files
 111     \li senf::scheduler::detail::TimerDispatcher manages timers
 112     \li senf::scheduler::detail::SignalDispatcher manages UNIX signals
 113
 114     Each dispatcher has a specific API and the integration into the main-loop is not standardized
 115     for performance reasons.
 116
 117     The Dispatcher does not own the event instances, instead those instances are owned by the
 118     respective object creating the event. The implementation uses boost::intrusive containeres to
 119     manage the events. This makes the Scheduler itself be completely devoid of dynamic memory
 120     allocations.
 121
 122
 123     \section scheduler_i_mainloop The main loop
 124
 125     The application mainloop senf::scheduler::process() is constructed by calling the correct
 126     members of all these classes repeatedly in the correct order:
 127
 128     \li First dispatchers are set up
 129     \li then the senf::scheduler::FdManager is called to wait for an event
 130     \li After cleaning up the dispatchers,
 131     \li the senf::scheduler::FIFORunner is called to executed all now runnable tasks.
 132  */
 133
 134 \f
 135 // Local Variables:
 136 // mode: c++
 137 // fill-column: 100
 138 // c-file-style: "senf"
 139 // indent-tabs-mode: nil
 140 // ispell-local-dictionary: "american"
 141 // mode: flyspell
 142 // mode: auto-fill
 143 // compile-command: "scons -U doc"
 144 // End: