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