4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
6 // Stefan Bund <g0dil@berlios.de>
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.
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.
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.
23 /** \mainpage The SENF Scheduler Library
25 The %Scheduler Library provides a single-threaded application event-loop multiplexing multiple
30 \section scheduler_scheduler The Scheduler
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.
37 The Scheduler supports the following types of events::
43 \see \ref senf::scheduler
46 \section scheduler_clockservice The ClockService
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
52 \see senf::ClockService
55 \section scheduler_helpers Miscellaneous helpers
57 To ease the use of the Scheduler there are some additional helpers managing callbacks and
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
66 \section scheduler_i Implementation
68 senf::Scheduler is only a wrapper around the real implementation. The real implementation is now
69 based on a modular dispatcher architecture
71 \see \ref scheduler_implementation
74 /** \page scheduler_implementation The Scheduler Implementation
76 The implentation architecture now is based on a set of dispatchers, one for each type of
81 \section scheduler_i_overview Overview
83 The %scheduler utilizes the following components
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.
88 \li Every registered event is represented by an event specific event class instance.
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).
95 \li The Dispatcher registeres all callbacks as tasks with the runner
96 (senf::scheduler::detail::FIFORunner).
98 \li The senf::scheduler::detail::FdManager uses senf::scheduler::detail::Poller to access the
99 low-level epoll() API.
101 All these classes are singletons.
104 \section scheduler_i_dispatchers Dispatchers
106 There is a dispatcher for each event type
108 \li senf::scheduler::detail::FdDispatcher manages poll-able file descriptors. This does \e not
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
114 Each dispatcher has a specific API and the integration into the main-loop is not standardized
115 for performance reasons.
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
123 \section scheduler_i_mainloop The main loop
125 The application mainloop senf::scheduler::process() is constructed by calling the correct
126 members of all these classes repeatedly in the correct order:
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.
138 // c-file-style: "senf"
139 // indent-tabs-mode: nil
140 // ispell-local-dictionary: "american"
143 // compile-command: "scons -U doc"