ucw docs: Generic headers

[libucw.git] / ucw / doc / mainloop.txt

diff --git a/ucw/doc/mainloop.txt b/ucw/doc/mainloop.txt
index 916692ca189f26892b578c0dc4e230154dca2be4..6a196281edba0f8abe69cb30de28dbec09f8d028 100644 (file)
--- a/ucw/doc/mainloop.txt
+++ b/ucw/doc/mainloop.txt
@@ -1,18 +1,26 @@
 Mainloop
 ========
 
-Not every program is sequential. You may need an event driven program
-sometime, lets say a railway server. It has a connection to each
-station and train to know, where each one is, some things happen at
-given times, like train is scheduled to leave as station and so on.
+Not every program is strictly sequential. Sometimes, an event-driven
+model is much easier to grasp. A fine example of such a program could
+be a railway server. It has a separate connection to each station
+and also to each train, so that it knows where each of them is (and
+that neither a train nor a station have got missing). So it has to wait
+for events coming from these connections and handle them appropriately.
+It also processes other events that it has itself generated -- for
+example various timers telling that a train is scheduled to depart
+from some station.
 
-With the mainloop module you can write just the hooks and tell it to
-watch over a set of file descriptors, timers and running processes.
+The mainloop module takes care of the low-level part of event-driven
+programs: it calls the OS to monitor file activity, to interrupt
+the program at the right moment to serve a timer, and so on. The
+programmer only defines hooks that should be called to handle
+the events and calls mainloop functions to schedule them.
 
 // TODO Example?
 
 - <<conventions,Conventions>>
-- <<time,Time manipulation>>
+- <<time,Time and timers>>
 - <<file,Activity on file descriptors>>
 - <<hooks,Loop hooks>>
 - <<process,Child processes>>