// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-namespace senf {
-
/** \mainpage The SENF Scheduler Library
- The Scheduler library provides a simple yet flexible abstraction of the standard asynchronous
- UNIX mainloop utilizing \c select or \c poll. The Scheduler library is based on the highly
- efficient (but linux specific) \c epoll() system call.
+ The %Scheduler Library provides a single-threaded application event-loop multiplexing multiple
+ event sources.
+
+ \autotoc
- The library provides
- \li the ClockService as a reliable high-resolution highly accurate monotonous time source
- \li a central \ref Scheduler %singleton and
- \li \ref ReadHelper and \ref WriteHelper templates to simplify common tasks.
+ \section scheduler_scheduler The Scheduler
+ \seechapter \ref senf::scheduler
- The Scheduler supports several types of scheduling activites:
- \li Arbitrary file descriptors (however, local disk file-handles are not guaranteed
- non-blocking)
+ The %scheduler provides a single threaded event dispatch architecture with reliable task
+ queueing using FIFO scheduling. The %scheduler provides event handling for
+
+ \li File descriptors
\li Timers
- \li UNIX Signals
+ \li UNIX signals
+
+ \section scheduler_clockservice The ClockService
+ \seechapter senf::ClockService
+
+ To support precise event timing, the senf::ClockService class implements a reliable monotonous
+ time source. It is based on the high precision POSIX clock and adds support for reliable
+ conversion between an abstract clock type and absolute date/time
+
+ \section scheduler_helpers Miscellaneous helpers
+
+ To ease the use of the Scheduler there are some additional helpers managing callbacks and
+ registrations.
+
+ \li senf::ReadHelper reads data from an arbitrary file descritor until a use specified condition
+ is met (e.g. number of chars read or a specific character sequence is found in the input).
+ \li senf::WriteHelper writes data to an arbitrary file descriptor until all provided data has
+ been written.
+
+ \section scheduler_i Implementation
+ \seechapter \ref scheduler_implementation
+
+ senf::Scheduler is only a wrapper around the real implementation. The real implementation is now
+ based on a modular dispatcher architecture
+
*/
-}
+/** \page scheduler_implementation The Scheduler Implementation
+
+ The implentation architecture now is based on a set of dispatchers, one for each type of
+ event.
+
+ \autotoc
+
+ \section scheduler_i_overview Overview
+
+ The %scheduler utilizes the following components
+
+ \li There is a dispatcher for each event type. This dispatcher manages the event specific
+ registration and unregistration. The dispatcher is owns the event (and task) objects.
+
+ \li Every registered event is represented by an event specific event class instance.
+
+ \li The Dispatcher ultimately registeres with the senf::scheduler::detail::FdManager. Since the
+ event-loop is based on epoll() (it could easily be changed to be based on select() or
+ poll()), all events must ultimately be represented by some type of file descriptor (not
+ necessarily a \e different file descriptor for each event).
+
+ \li The Dispatcher registeres all callbacks as tasks with the runner
+ (senf::scheduler::detail::FIFORunner).
+
+ \li The senf::scheduler::detail::FdManager uses senf::scheduler::detail::Poller to access the
+ low-level epoll() API.
+
+ All these classes are singletons.
+
+
+ \section scheduler_i_dispatchers Dispatchers
+
+ There is a dispatcher for each event type
+
+ \li senf::scheduler::detail::FdDispatcher manages poll-able file descriptors. This does \e not
+ include real files.
+ \li senf::scheduler::detail::FileDispatcher manages disk files
+ \li senf::scheduler::detail::TimerDispatcher manages timers
+ \li senf::scheduler::detail::SignalDispatcher manages UNIX signals
+
+ Each dispatcher has a specific API and the integration into the main-loop is not standardized
+ for performance reasons.
+
+ The Dispatcher does not own the event instances, instead those instances are owned by the
+ respective object creating the event. The implementation uses boost::intrusive containeres to
+ manage the events. This makes the Scheduler itself be completely devoid of dynamic memory
+ allocations.
+
+
+ \section scheduler_i_mainloop The main loop
+
+ The application mainloop senf::scheduler::process() is constructed by calling the correct
+ members of all these classes repeatedly in the correct order:
+
+ \li First dispatchers are set up
+ \li then the senf::scheduler::FdManager is called to wait for an event
+ \li After cleaning up the dispatchers,
+ \li the senf::scheduler::FIFORunner is called to executed all now runnable tasks.
+ */
\f
// Local Variables:
// ispell-local-dictionary: "american"
// mode: flyspell
// mode: auto-fill
+// compile-command: "scons -U doc"
// End: