senf/Scheduler/Mainpage.dox

   1 // $Id$
   2 //
   3 // Copyright (C) 2007
   4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
   5 //
   6 // The contents of this file are subject to the Fraunhofer FOKUS Public License
   7 // Version 1.0 (the "License"); you may not use this file except in compliance
   8 // with the License. You may obtain a copy of the License at
   9 // http://senf.berlios.de/license.html
  10 //
  11 // The Fraunhofer FOKUS Public License Version 1.0 is based on,
  12 // but modifies the Mozilla Public License Version 1.1.
  13 // See the full license text for the amendments.
  14 //
  15 // Software distributed under the License is distributed on an "AS IS" basis,
  16 // WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  17 // for the specific language governing rights and limitations under the License.
  18 //
  19 // The Original Code is Fraunhofer FOKUS code.
  20 //
  21 // The Initial Developer of the Original Code is Fraunhofer-Gesellschaft e.V.
  22 // (registered association), Hansastraße 27 c, 80686 Munich, Germany.
  23 //
  24 // Contributor(s):
  25 //   Stefan Bund <g0dil@berlios.de>
  26
  27
  28 /** \mainpage The SENF Scheduler Library
  29
  30     The %Scheduler Library provides a single-threaded application event-loop multiplexing multiple
  31     event sources.
  32
  33     \autotoc
  34
  35     \section scheduler_scheduler The Scheduler
  36     \seechapter \ref senf::scheduler
  37
  38     The %scheduler provides a single threaded event dispatch architecture with reliable task
  39     queueing using FIFO scheduling. The %scheduler provides event handling for
  40
  41     \li File descriptors
  42     \li Timers
  43     \li UNIX signals
  44
  45     \section scheduler_clockservice The ClockService
  46     \seechapter senf::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     \section scheduler_helpers Miscellaneous helpers
  53
  54     To ease the use of the Scheduler there are some additional helpers managing callbacks and
  55     registrations.
  56
  57     \li senf::ReadHelper reads data from an arbitrary file descritor until a use specified condition
  58         is met (e.g. number of chars read or a specific character sequence is found in the input).
  59     \li senf::WriteHelper writes data to an arbitrary file descriptor until all provided data has
  60         been written.
  61
  62     \section scheduler_i Implementation
  63     \seechapter \ref scheduler_implementation
  64
  65     senf::Scheduler is only a wrapper around the real implementation. The real implementation is now
  66     based on a modular dispatcher architecture
  67
  68  */
  69
  70 /** \page scheduler_implementation The Scheduler Implementation
  71
  72     The implentation architecture now is based on a set of dispatchers, one for each type of
  73     event.
  74
  75     \autotoc
  76
  77     \section scheduler_i_overview Overview
  78
  79     The %scheduler utilizes the following components
  80
  81     \li There is a dispatcher for each event type. This dispatcher manages the event specific
  82         registration and unregistration. The dispatcher is owns the event (and task) objects.
  83
  84     \li Every registered event is represented by an event specific event class instance.
  85
  86     \li The Dispatcher ultimately registeres with the senf::scheduler::detail::FdManager. Since the
  87         event-loop is based on epoll() (it could easily be changed to be based on select() or
  88         poll()), all events must ultimately be represented by some type of file descriptor (not
  89         necessarily a \e different file descriptor for each event).
  90
  91     \li The Dispatcher registeres all callbacks as tasks with the runner
  92         (senf::scheduler::detail::FIFORunner).
  93
  94     \li The senf::scheduler::detail::FdManager uses senf::scheduler::detail::Poller to access the
  95         low-level epoll() API.
  96
  97     All these classes are singletons.
  98
  99
 100     \section scheduler_i_dispatchers Dispatchers
 101
 102     There is a dispatcher for each event type
 103
 104     \li senf::scheduler::detail::FdDispatcher manages poll-able file descriptors. This does \e not
 105         include real files.
 106     \li senf::scheduler::detail::FileDispatcher manages disk files
 107     \li senf::scheduler::detail::TimerDispatcher manages timers
 108     \li senf::scheduler::detail::SignalDispatcher manages UNIX signals
 109
 110     Each dispatcher has a specific API and the integration into the main-loop is not standardized
 111     for performance reasons.
 112
 113     The Dispatcher does not own the event instances, instead those instances are owned by the
 114     respective object creating the event. The implementation uses boost::intrusive containeres to
 115     manage the events. This makes the Scheduler itself be completely devoid of dynamic memory
 116     allocations.
 117
 118
 119     \section scheduler_i_mainloop The main loop
 120
 121     The application mainloop senf::scheduler::process() is constructed by calling the correct
 122     members of all these classes repeatedly in the correct order:
 123
 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: