Design/event_notes

   1
   2 Events
   3
   4 The low-level core of a Stem hub is an event-loop engine.  This
   5 engine provides support for the common events needed in a networking
   6 system, including reading and writing, socket connection and
   7 acceptance, and timers.  The Stem::Event system provides a high-level
   8 API to these services to the rest of the hub while it, in turn,
   9 relies on a lower-level event system which is currently Event.pm,
  10 which is available on CPAN.  This design isolates the actual event
  11 engine used from the cells which need its services.  There are plans
  12 to support other event engines including Perl/Tk, and creating one
  13 that runs on NT/Win2K.
  14
  15 Stem::Event uses the standard Stem callback style which requires
  16 parameters designating the object and method to call when an event
  17 has been triggered.  In typical Stem fashion, the method names have
  18 useful defaults so a Stem::Event call is made with very few
  19 parameters.
  20
  21 Read and write Stem events take a required object and filehandle as
  22 parameters, and an optional timeout value.  If the I/O is not
  23 completed before the timeout occurs, the timeout method is called
  24 instead of the normal I/O completion method.  The connect and accept
  25 events also require an object and the appropriate socket parameters.
  26 The connect event can take an optional timeout which behaves
  27 similarly to the read/write timeout.  A timer event can be created
  28 which will be triggered after a given delay and optionally repeated
  29 at a specified interval.  As you would expect in an event system,
  30 multiple instances of all these events can be active at the same
  31 time.
  32
  33 Most cells will never directly use the Stem::Event interface as there
  34 are higher level cells that perform commonly needed services for
  35 them.  These include Stem::AsynchIO, Stem::Socket, and Stem::Cron.
  36 However, this does not stop any cell from directly calling these if
  37 it needs finer control over its events.
  38