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 main interface is the senf::Scheduler class. This provides support for several types of
41 \section scheduler_clockservice The ClockService
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
47 \see senf::ClockService
50 \section scheduler_helpers Miscellaneous helpers
52 To ease the use of the Scheduler there are some additional helpers managing callbacks and
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
59 \li senf::SchedulerBinding is an RAII class which manages the registration of a file descriptor
61 \li senf::SchedulerTimer is an RAII class which manages a timer registration.
64 \section scheduler_i Implementation
66 senf::Scheduler is only a wrapper around the real implementation. The real implementation is now
67 based on a modular dispatcher architecture
69 \see \ref scheduler_implementation
72 /** \page scheduler_implementation The Scheduler Implementation
74 The implentation architecture now is based on a set of dispatchers, one for each type of
79 \section scheduler_i_overview Overview
81 The %scheduler utilizes the following components
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.
86 \li Every registered event is represented by an event specific event class instance.
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).
93 \li The Dispatcher registeres all callbacks as tasks with the runner
94 (senf::scheduler::FIFORunner).
96 \li The senf::scheduler::FdManager uses senf::scheduler::Poller to access the low-level epoll()
99 All these classes are \e not singletons. They are all instantiatied by the senf::Scheduler
103 \section scheduler_i_dispatchers Dispatchers
105 There is one dispatcher for each event type
107 \li senf::scheduler::FdDispatcher manages poll-able file descriptors. This does \e not include
109 \li senf::scheduler::FileDispatcher manages disk files
110 \li senf::scheduler::TimerDispatcher manages timers
111 \li senf::scheduler::SignalDispatcher manages UNIX signals
113 At the moment, each dispatcher has a specific API and the integration into the main-loop is not
114 standardized for performance reasons.
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.
120 \section scheduler_i_mainloop The main loop
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.
134 // c-file-style: "senf"
135 // indent-tabs-mode: nil
136 // ispell-local-dictionary: "american"
139 // compile-command: "scons -U doc"