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