docs/dev/events.pod

   1 # Copyright (C) 2001-2006, Parrot Foundation.
   2 # $Id$
   3
   4 =head1 NAME
   5
   6 docs/dev/events.pod - Design Notes for Events
   7
   8 =head1 VERSION
   9
  10 This document describes the current state, which might not be the final
  11 implementation.
  12
  13 =head1 Overview
  14
  15 Parrot has to deal with asynchronous events (from timers, signals, async IO,
  16 notifications, and so on). This document describes the current implementation.
  17
  18 =head1 Prelims
  19
  20 As there is currently no good test if a threading library is included at link
  21 time, its assumed, that platforms having B<PARROT_HAS_HEADER_PTHREAD> link
  22 against B<libpthread>.
  23
  24 =head1 DESCRIPTION
  25
  26 On construction of the first interpreter (the one with no
  27 B<parent_interpreter>) two threads are started: The B<event_thread>, which
  28 manages the static global B<event_queue> and the B<io_thread> which is
  29 responsible for signal and IO related events.
  30
  31 =head2 Events
  32
  33 Events can be either timed (they are due after some elapsed time) or untimed.
  34 For the former there is one API call: B<Parrot_new_timer_event>
  35
  36 =head2 The B<event_thread>
  37
  38 The B<event_thread> holds the B<event_queue> mutex first. When there is no
  39 event entry in the B<event_queue>, the B<event_thread> waits on the event
  40 condition until an event arrives. When there is an event with a timed entry, a
  41 timed wait is performed. (Waiting on the condition releases the mutex, so that
  42 other threads can insert events into the B<event_queue>.)
  43
  44 When an event arrives (or the timeout was reached) the B<event_thread> pops off
  45 all events and places the queue entries into the interpreter's B<task_queue>.
  46 This also enables event checking in the interpreter's run-core.
  47
  48 When the popped off entry is a timed event and has a repeat interval, the entry
  49 is duplicated and reinserted with the interval added to the current time.
  50
  51 =head2 B<Signals>
  52
  53 All signals that should be handled inside Parrot are blocked in all threads and
  54 only enabled in the B<io_thread>. The signal handler functions just sets an
  55 atomic flag, that this signal arrived and returns. This finally interrupts the
  56 select(2) loop in the B<io_thread>.
  57
  58 =head2 The B<io_thread>
  59
  60 The B<io_thread> sleeps in a select(2) loop, which is interrupted when either a
  61 signal arrives or when one of the file descriptors has a ready condition.
  62 Additionally the file descriptor set contains the reader end of an internal
  63 pipe, which is used by other threads to communicate with the B<io_thread>.
  64
  65 Signal events like SIGINT are broadcasted to all running interpreters, which
  66 then throw an appropriate exception.
  67
  68 =head2 The interpreter event checking code
  69
  70 We cannot interrupt the interpreter at arbitrary points and run some different
  71 code (e.g. a PASM subroutine handling timer events). So when an event is put
  72 into the interpreter's B<task_queue> the opcode dispatch table for the
  73 interpreter is changed.
  74
  75 Plain function cores get a function table with all entries filled with the
  76 B<check_events__> opcode. This opcode pops off and finally handles the event.
  77 The same scheme works for the CGOTO core, where the address table is replaced.
  78 The switched core does an explicit check if events are to be handled.
  79
  80 Prederefed and especially the CGP core don't have an opcode dispatch table that
  81 is checked during running the opcodes. When an event is scheduled, the event
  82 handler replaces backward branches in the opcode image with the
  83 B<check_events__> opcode.
  84
  85 After all events are popped off and handled, the opcode dispatch table is
  86 restored to its original, and the B<check_events__> reexecutes the same
  87 instruction again, which is now the real one and thus normal execution flow
  88 continues.
  89
  90 This scheme has zero overhead in the absence of scheduled events for all cores
  91 except switched.
  92
  93 =head1 Missing
  94
  95 =over 4
  96
  97 =item Synchronous event API
  98
  99 Sync events could be placed directly into the interpreter's task queue.
 100
 101 =item Async IO
 102
 103 That depends probably on the underlying OS, i.e. if it does async IO or we have
 104 to do it.
 105
 106 =item Event priorities
 107
 108 =item A lot more
 109
 110 =back
 111
 112 =head1 Author
 113
 114 Leopold Toetsch C<lt@toetsch.at>
 115
 116 =cut
 117
 118 # vim: expandtab shiftwidth=2 tw=70:
 119