Author: allison
Date: Mon Oct 15 21:02:33 2007
New Revision: 22108
Modified:
trunk/docs/pdds/draft/pdd24_events.pod
Log:
[pdd] Added opcodes and event types to events PDD, and largely rewrote signals
section.
Modified: trunk/docs/pdds/draft/pdd24_events.pod
==============================================================================
--- trunk/docs/pdds/draft/pdd24_events.pod (original)
+++ trunk/docs/pdds/draft/pdd24_events.pod Mon Oct 15 21:02:33 2007
@@ -53,8 +53,10 @@
an event, the concurrency scheduler compares the type of the event to the type
of the event handler and selects the closest match. An exact type match is
always highest ranked, then a parent type, and finally a general handler
-designed to handle all types. (A parent type may be something like a category
-"key press" as a parent type to "key 'a' press".)
+designed to handle all types. In addition to the type of an event, an event
+handler may check the data attribute of an event and decide whether to accept
+or decline that event based on its data. (For example, a "key press" may
+contain a data attribute value specifying that it's a "key 'a' press".)
In the simple case, the concurrency scheduler runs within the single
interpreter thread. In more complex cases (particularly on multi-processor
@@ -125,16 +127,22 @@
=over 4
-=item get_string(STRING *)
+=item get_string
+
+ STRING * get_string()
Returns a simple string name for the event, suitable for printing in error
messages.
-=item get_pmc(PMC *)
+=item get_pmc
+
+ PMC * get_pmc()
Returns the data attribute of the event, or PMCNULL if the event has no data.
-=item isa(INTVAL *, STRING *)
+=item isa
+
+ INTVAL isa(STRING *)
Returns true or false if the event is of the type passed in the string
parameter, or has a parent of that type.
@@ -190,18 +198,24 @@
=over 4
-=item init_pmc(PMC *)
+=item init_pmc
+
+ void init_pmc(PMC *)
Initializes the PMC, either with a single sub object for the core code, or with
a hash object containing arguments for the code object, type, priority
threshold, and interpreter object for the handler.
-=item set_string(STRING *)
+=item set_string
+
+ void set_string(STRING *)
Set the type of event this handler responds to. {{NOTE: These basic attribute
setting operations could be set_attr_str and get_attr_str instead.}}
-=item set_integer_native(INTVAL)
+=item set_integer_native
+
+ set_integer_native(INTVAL)
Set the minimum threshhold of priority.
@@ -209,7 +223,9 @@
Set the interpreter object for this event handler.
-=item invoke (opcode_t *, void*)
+=item invoke
+
+ opcode_t * invoke(void *)
Invoke the event handler.
@@ -229,59 +245,101 @@
Creates a new event or event handler.
+=item schedule
+
+ $P0 = new 'Event'
+ # set attributes
+ schedule $P0
+
+Register an event with the concurrency scheduler. If the concurrency scheduler
+for this interpreter (thread/clustered instance) is linked to another "primary"
+concurrency scheduler, this will pass along the event to the primary. All
+details about the event (its type, whether it's fatal or non-fatal, whether
+it's a timer, etc) are stored within the event PMC.
+
+=item addhandler
+
+ $P0 = new 'EventHandler'
+ # set attributes
+ addhandler $P0
+
+Register an event handler with the concurrency scheduler. If the concurrency
+scheduler for this interpreter (thread/clustered instance) is linked to another
+"primary" concurrency scheduler, this will pass along the event handler to the
+primary.
+
=back
=head2 Event Type Hierarchy
Parrot defines a core set of event types. Users may also define their own event
-types.
+types. An event type of 'allevents' is effectively the parent of all event
+types, and will respond to any event in the task list that isn't handled by
+other event handlers in a final way.
+
+ allevents
+
+ ioevent
+ packetsent
+ packetreceived
+ fileopened
+ fileclosed
+ readcomplete
+
+ keyevent
+ keydown
+ keypress
+ keyup
+
+ mouseevent
+ click
+ doubleclick
+ mousedown
+ mouseup
+ mousemove
+ mouseenter
+ mouseleave
+
+ windowevent
+ blur
+ focus
+ resize
+ scroll
+ textselect
+
+ signal
+ alarm
+ interrupt
+ childdie
=head2 Signals
-Signals are a special form of event, based on the Unix signal mechanism.
-Parrot presents them as mildly special, as a remnant of Perl's Unix
-heritage, but under the hood they're not treated any differently from
-any other event.
-
-The Unix signaling mechanism is something of a mash, having been
-extended and worked on over the years by a small legion of undergrad
-programmers. At this point, signals can be divided into two
-categories, those that are fatal, and those that aren't.
-
-Fatal signals are things like
-SIGKILL, which unconditionally kills a process, or SIGSEGV, which
-indicates that the process has tried to access memory that isn't part
-of your process. There's no good way for Parrot to catch these
-signals, so they remain fatal and will kill your process. On some
-systems it's possible to catch some of the fatal signals, but
-Parrot code itself operates at too high a level for a user program to
-do anything with them--they must be handled with special-purpose code
-written in C or some other low-level language. Parrot itself may
-catch them in special circumstances for its own use, but that's an
-implementation detail that isn't exposed to a user program.
-
-Non-fatal signals are things like SIGCHLD, indicating that a
-child process has died, or SIGINT, indicating that the user
-has hit C<^C> on the keyboard. Parrot turns these signals into events
-and puts them in the event queue. Your program's event handler for the
-signal will be called as soon as Parrot gets to the event in the queue,
-and your code can do what it needs to with it.
-
-SIGALRM, the timer expiration signal, is treated specially by
-Parrot. Generated by an expiring alarm() system call, this signal is
-normally used to provide timeouts for system calls that would
-otherwise block forever, which is very useful. The big downside to
-this is that on most systems there can only be one outstanding
-alarm() request, and while you can get around this somewhat with the
-setitimer call (which allows up to three pending alarms) it's still
-quite limited.
-
-Since Parrot's IO system is fully asynchronous and never blocks--even
-what looks like a blocking request still drains the event queue--the
-alarm signal isn't needed for this. Parrot instead grabs SIGALRM for
-its own use, and provides a fully generic timer system which allows
-any number of timer events, each with their own callback functions
-and private data, to be outstanding.
+Signals are a special form of event. Parrot presents them as mildly special, as
+a remnant of Perl's Unix heritage, but under the hood they're not treated any
+differently from events generated by other sources.
+
+Signals can be divided into two categories, those handled by the operating
+system, and those passed on to the process.
+
+OS-handled signals are things like SIGKILL, which kills a process, or SIGSEGV,
+which indicates that the process has tried to access memory that isn't part of
+your process. Because these signals are handled before they reach the process,
+there's no way for Parrot to catch them.
+
+Signals Parrot can handle include things like SIGCHLD, indicating that a child
+process has died, or SIGINT, indicating that the user has hit C<^C> on the
+keyboard, or SIGALRM, the timer expiration signal. Parrot turns these signals
+into events and puts them in the event task list, and will be processed and
+dispatched to an event handler in order of priority and age just like other
+events.
+
+=head2 Timers
+
+A timer is a special kind of event with a time delay. A timer can act as any
+builtin or custom event type. Timers can be be flagged as repeating. Parrot
+provides builtin timers for greater portability. Some platforms provide their
+own implementations of timers, which may be used when performance on a
+particular platform is more important than portability.
=head1 ATTACHMENTS
@@ -297,6 +355,10 @@
http://www.seas.upenn.edu/~lipeng/homepage/unify.html
+
http://developer.apple.com/documentation/Carbon/Conceptual/Carbon_Event_Manager/Concept/chapter_2_section_2.html
+
+ http://www.quirksmode.org/js/events_compinfo.html
+
=cut
__END__
