Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Migrate proto-documentation from the wiki.

  • Loading branch information...
commit 968d404f48d138208964d55db35f81b3300f7905 1 parent edd79cc
@rcaputo authored
View
8 AUTHORS
@@ -1,3 +1,9 @@
-Name - CPAN ID (if applicable)
+This project is going to be an amalgam of several incomplete attempts
+to create a POE manual and/or book. Wherever possible, authors past
+and present will be credited here.
+Devin Austin - DHOSS
Rocco Caputo - RCAPUTO
+
+If you've been forgotten, please remind someone above, ask for a
+commit bit, or send a pull request.
View
6 notes.beginners → beginners-guide.wiki
@@ -1,4 +1,8 @@
-http://poe.perl.org/?POE_Documentation/Beginners_Guide
+A copy of http://poe.perl.org/?POE_Documentation/Beginners_Guide
+The wiki-hosted document has 17 Delicious bookmarks at the time of
+this writing, implying it's valuable to people where it is.
+
+---
What everyone needs to know about POE.
View
89 design-patterns.wiki
@@ -0,0 +1,89 @@
+Formerly http://poe.perl.org/?Design_Patterns
+
+---
+
+Design patterns. The phrase conjures all sorts of visions. Some
+people cringe, either because "design patterns" is overused or
+misused. Others understand the utility of documented design elements
+and are eager to read on. I hope everybody will at least take a brief
+look before closing the book---or worse, not opening it because they
+don't like the cover.
+
+== Components ==
+
+POE lends itself to asynchronous processes. This tendency brings
+about asynchronous components. Asynchrony means that command and
+response interfaces are loosely coupled, if at all, so this section is
+further decomposed into command and response interfaces.
+
+=== Command Interfaces ===
+
+[[/Command Message]]
+
+The component accepts commands in the form of asynchronous messages.
+One or more other sessions post these to the component, which then
+processes them.
+
+[[/Proxy Object]]
+
+Components can be hidden behind proxy objects. In this case, the code
+to perform actions looks like simple method calls. The main
+difference is that the methods may return an immediate result, the
+status of a pending result, or nothing particularly useful.
+
+Proxy object methods hide post() calls that send messages to some
+underlying session. They may also provide glue between normal code
+and POE.
+
+Proxy objects may be singletons, in which case every instance is a
+reference to the same object. They may also be dynamic, each holding
+some state outside the component's internal session.
+
+In their simplest form, proxy objects may be considered syntactic
+sugar for message services, since they are often thin wrappers for
+them.
+
+=== Response Interfaces ===
+
+[[/Callback]]
+
+Part of a command includes one of
+
+* a code reference
+* an object reference and/or method name
+* a package name and/or method name
+
+which the component then invokes with the response.
+
+[[/Response Message]]
+
+The response message has several mix-and-match aspects.
+
+The sender may be one of
+
+* the SENDER of the command message
+* specified in the command message
+
+The response message type may be one of
+
+* predefined by the component
+* specified in the command message
+
+The sender and response may together be defined by
+
+* a postback included in the command message
+
+but this is not portable across process boundaries.
+
+=== Tracking Commands and Responses ===
+
+Components that perform asynchronous activities need to save commands
+and send back appropriate responses.
+
+[[ToDo]]: This section will outline ways to do that when someone gets
+time to extend it.
+
+<!--
+" vim: syntax=wiki
+-->
+
View
33 documentation-design.wiki
@@ -0,0 +1,33 @@
+Formerly
+
+---
+
+I thought it might be helpful to come up with a coherent design for
+POE documentation, get some feedback, and then start rewriting (as
+well as sending armed gorillas after anyone who writes module docs
+which don't stick to the design.)
+
+Some of this has already been discussed a level up, but rather than
+totally refactor that I want to focus on design and then refactor
+both.
+
+= Design goals =
+* [[/Accuracy]]
+* Clarity
+* Terseness
+* Forward reference reduction
+* Sane linkage
+* Simple multi-formatting
+
+= Documentation types =
+* Intro/tutorial
+* Overview
+* Cookbook
+* Reference
+* Module
+
+What I want is general spec covering the goals for each type (i.e.
+thirty <i>short, concise</i> wiki pages, plus a few introductory pages
+like this one. I am just going to bull ahead with this, and
+(eventually) hit the mailing list(s) to try to get people in here to
+comment.
View
375 lecture-2001-11-15.wiki
@@ -0,0 +1,375 @@
+Formerly http://poe.perl.org/?Lecture_2001-11-05
+
+---
+
+This is a long, rambling, unfocused lecture Rocco gave on IRC, back in
+early November 2001. It's cleaned up a bit.
+
+ROCCO:
+
+Once upon a time I wanted to make a mud. And I'd been coding in perl
+for a couple years, and it was friendly and stuff. But it didn't
+multitask. Threads were considered impossible, even, so I decided to
+write my own. (cue music and dream effects)
+
+I had written some select() code before... file_add, file_del, and a
+select() wrapper. I still have it somewhere. I'd also taken a few
+early stabs at something like POE, but they all had severe
+limitations. The last proto-POE system I released is called Serv.
+It's still on the web somewhere.
+
+Around 1996 I figured I could simulate threads with event driven state
+machines. My epiphany is in the p5p archives. [ToDo] Include a link.
+
+I had also written a similar event driven thing in C++, wrapped around
+the MBBS core serial drivers.
+
+That's the background context/backstory for POE::Kernel and
+POE::Session. One is the event loop, and the other is the tasks that
+it runs.
+
+POE::Kernel, at its heart, is yet another select loop. That's what it
+started as, anyway. It even used IO::Select to begin with.
+
+There are functions for managing select vectors (select_read,
+select_write, select_expedite, and the rest).. and the basic alarm and
+delay functions for affecting select()'s timeout. There is also a
+list of events in time order. That was about all pre-0.01 did, if I
+recall correctly.
+
+The idea of Session came from Serv, but Serv sucked because a session
+could only have one filehandle. You couldn't write things like
+proxies without creating two interlocked sessions, one for each end of
+the pipe. When I realized that, I decided to kill Serv :)
+
+So POE's core is basically the same as it started. It's a list of
+events in time order, and a select() loop to watch for the next event
+time and whatever filehandles are being monitored.
+
+The select() timeout is essentially
+
+
+<perl>$queue[0]->[TIME] - time();
+</perl>
+
+
+MHORAM:
+
+So are you interested in building a MUD, or just an engine?
+
+ROCCO:
+
+Still interested in the MUD, but the engine takes all my time now. :/
+
+That's really all the core is, deep down. Built around it is a big
+nasty knot of data that keeps reference counts for each session. When
+a session watches a filehandle, say
+
+
+<perl>$kernel->select_read(\*STDIN, 'console_input') </perl>
+
+
+that knot of data tracks which session is watching what filehandles in
+which modes (and which events to emit when select(2) says the handle's
+ready).
+
+When a session posts an event, it's entered into the time-ordered list
+of events at the proper place. That happens to be time(), so every
+call to post() enqueues its event after all the preceding ones.
+
+When an alarm or delay is posted, it's entered at whatever time is
+requested.
+
+And that knot of data tracks how many events are in the queue for each
+session, so that Kernel doesn't accidentally discard a session before
+it's received everything. To be sure, all those counts get
+decremented as events are pulled out.
+
+A lot of the data knot is cross-references. Reverse lookups and
+stuff. For example, there's a hash that translates an alarm's ID into
+its due time, so that it can be found in the queue by a binary search
+instead of a linear one. Most people don't need to know that, though.
+
+Aliases are just a hash of symbolic names and the session references
+they stand for. And the knot of data keeps a count of aliases for
+each session so the Kernel doesn't accidentally discard a session
+that's listening for events.
+
+Let's see... filehandles, alarms, aliases, posted events. yield() is
+just a "macro" for post to the same session. delay() is just a
+"macro" for an alarm at time() + $delay. select($handle, $read_event,
+$write_event, $expedite_event) is a "macro" for select_read +
+select_write + select_expedite together.
+
+POE is built up like that. New stuff is built off the basic things
+that came before.
+
+Kernel invokes $session->_invoke_state(...), and that code figures out
+where the event should go.
+
+That brings up the largest of Philip Gwyn's current frustrations with
+POE. The Kernel has no idea of Session capabilities because they're
+not its problem.
+
+JOS:
+
+Can you elaborate on that?
+
+ROCCO:
+
+Ok. When an event needs to be handled, the Kernel just passes it to a
+session's _invoke_state() and considers it done. "Here, $session,
+have an event". That's the extent of its responsibility.
+
+Session's _invoke_state() looks up the code to handle each event its
+given and calls it. It's also responsible for calling a _default
+handler if the right bit of code isn't available.
+
+JOS:
+
+Ok, _invoke_state() gets it and hands it off. Nothing else?
+
+ROCCO:
+
+Well... a lot of little other things, actually, before and after the
+handoff. They mostly relate to the knot of data the Kernel maintains.
+
+OE::NFA is a kind of Session with some extra logic. It still gets
+events through _invoke_state(). Instead of one handler for each
+event, though, it maintains an internal state and gives events to the
+handler in that state.
+
+So there could be twelve different "got_input" handlers, one for each
+state in a protocol. Kernel has no idea this is going on.
+
+Back to the Kernel side of the handoff.
+
+JOS:
+
+(Tries to shape a mental image of the flow.)
+
+ROCCO:
+
+
+<perl> while (@queue) {
+ my $event = shift @queue;
+ $event->[SESSION]
+ ->_invoke_state($event->[NAME], $event->[ARGS], and some other stuff);
+}
+</perl>
+
+
+JOS:
+
+Ok, it just handles them one by one.
+
+ROCCO:
+
+Yeah. No threads, you know.
+
+That's POE's dispatch loop in a very smoothed-over nutshell.
+
+MHORAM:
+
+Someone should draw up a diagram.
+
+JOS:
+
+"This is how POE works in one simple image."
+(Shows Mhoram a picture of a magic wand.)
+
+Rocco, this sounds pretty logical so far, but you haven't discussed
+much deeper magic here yet. =)
+
+ROCCO:
+
+What kind of deep magic? Wheels, maybe?
+
+JOS:
+
+Among others...
+
+ROCCO:
+
+POE didn't have wheels to begin with. I think maybe it had them by
+0.01, but this was after going around with Arthur about things for
+weeks.
+
+(This will come back around to other kernel magic in a bit.)
+
+I had already written some test servers, and they all had pretty much
+the same socket/listen/accept/sysread/syswrite logic. As nice as
+stuff was, typing the same code each time was getting to be tiresome.
+Wheel came from that.
+
+I added a Kernel function that exposed Session's event handler
+define/remove code so you can say:
+
+
+<perl>$kernel->state(event => \&new_handler);
+</perl>
+
+
+to add a new handler for "event" and
+
+
+<perl>$kernel->state(event => undef);
+</perl>
+
+
+to remove it. I took the states from my sample programs (see
+samples/selects.perl for example) and wrapped them in objects that
+create and destroy states on the fly.
+
+That way there's some extra start/stop overhead, but they should run
+as fast as your own event handlers. Runtime performance usually wins
+over create/destroy performance when I'm making design decisions.
+
+Filter and Driver are some abstractions so that the same Wheel doesn't need to be rewritten for each basic protocol.
+
+I think i'm starting to get unfocused. Questions?
+
+JOS:
+
+So how does Preprocessor fit in all this? (seeing you advised that it
+is the FIRST thing I read to understand POE better)
+
+ROCCO:
+
+Kernel.pm is full of preprocessor macros.
+
+
+<perl>la la la { %do_this_mysterious_thing % } la la la
+</perl>
+
+
+If you're not familiar with the syntax and where to look stuff up,
+it'll make reading the source harder. Like trying to read perl's
+source without knowing what the macros do.
+
+JOS:
+
+I'm not... the preprocessor looks kinda spooky to me.
+
+ROCCO:
+
+Macros are like inlined subs, but the Preprocessor uses a source
+filter to actually rewrite a program before it's compiled.
+
+
+<perl>macro numeric_max(<one>, <two>) {(((<one>) > (<two>)) ? (<one>) : (<two>))}
+ print "not "
+ unless {
+ %numeric_max NUM_ONE, NUM_TWO %} == 2;
+
+</perl>
+
+
+The print() statement is being rewritten read:
+
+
+<perl>print "not " unless (((1) > (2)) ? (1) : (2)) == 2;
+</perl>
+
+
+JOS:
+
+num_one and num_two being translated to 1 and 2?
+
+ROCCO:
+
+Yes, enum is like C's enum. It creates a list of things in numeric
+order without having to define them.
+
+JOS:
+
+Can I see in Preprocessor.pm HOW it does that?
+
+ROCCO:
+
+You can see it if you look hard, but the idea's to get comfortable
+enough reading code that uses it. Kernel uses it a lot
+
+There's more magic in the Kernel. There's some housekeeping and
+knot-management before and after $session->_invoke_state() is called.
+
+_start and _stop events, for example. Before the $session gets a
+_start event, the dispatcher creates a record for it. And after
+$session gets a _stop event, the dispatcher destroys that record. (a
+record in the "knot of data")
+
+That's also why _stop is so fatal and a session can't do anything
+after receiving one. Part of session destruction (after _stop is
+dispatched) is explicitly going through the session's record and
+removing things it didn't clean up.
+
+If there are any filehandles still being watched, they're removed.
+Alarms are turned off. Events are removed from the queue. Aliases
+are forgotten... those sorts of things.
+
+That's why poe usually doesn't leak memory. It's very strict about
+reference counting.
+
+Child sessions.
+
+At one point I had been focusing on the similarities between Sessions
+and system processes. More to the point, I had been trying to write
+thrash.perl, which is a server and a bunch of clients in the same
+program.
+
+I needed a convenient way to keep track of how many clients were
+running so that new ones could be started if there were too few. One
+session acts as a manager, creating new sessions as old ones go away.
+
+That's where parent/child relationships come from. Or if it's not,
+it's a convenient scapegoat.
+
+When momma session creates a new baby session, the Kernel remembers
+which created the other. Both the parent and child have entries in
+their records pointing to the other. The parent gets a _child event,
+and the child gets a _parent event. Those events are side effects of
+_start. They never go into the queue, in fact.
+
+Likewise, _stop also generates _parent and _child events, but
+signifying a child's stoppage.
+
+POE::Kernel, by the way, is the momma session of them all. And since
+signals are dispatched to child sessions, sending a signal to the
+Kernel broadcasts them everywhere.
+
+
+<perl>
+ # send SIGQUIT to everything without using kill()
+ $kernel->signal($kernel, 'QUIT');
+</perl>
+
+
+JOS:
+
+I vaguely remember there being some issues with trapping signals on
+Windows... Ctrl-C wouldn't kill?
+
+ROCCO:
+
+You could make a signal socket that reads a line and rebroadcasts it
+as a signal.
+
+
+<perl>sub got_socket_input {
+ $_[KERNEL]->signal($_[KERNEL], $_[ARG0]);
+}
+</perl>
+
+
+Now you just need a kill program to connect to the socket and send a
+signal name. :)
+
+Anyway, the _parent and _child events also have side effects. They
+update session structures's parent and child pointers.
+
+JOS:
+
+Ah, I think this will do nicely for a first lecture. It's around
+bedtime, and I have some things to look over.
+
+(END)
View
1,396 poe-book.wiki
@@ -0,0 +1,1396 @@
+Formerly http://poe.perl.org/action/edit?id=Poe_Book_Outline
+
+---
+
+= Programming in the Perl Object Environment =
+
+This is not a complete outline. While I've already begun writing, this outline is largely broken (Mostly between the third and sixth chapters), as its in mid-rework. I just wanted to see how it looked in the POE wiki's otl parser. If look at this and think I am missing or will miss something important, please let me know. (mailto:tag@cpan.org)
+
+<!--
+" vim: syntax=otl
+-->
+
+<H1><H1><outline-head>
+</H1></H1>
+
+= =
+<H1><H1>
+</H1></H1>
+
+= =
+<H1><H1>Perl Object Environment
+</H1></H1>
+
+= =
+<H1>The introduction to this chapter should provide various information
+</H1>
+
+<H1>reguaring what POE does. A simple over view of how it runs, and a
+</H1>
+
+<H1>bit of information on how to use it.
+</H1>
+
+<H1><H2>Why use POE?
+</H2></H1>
+
+= =
+<H1><H3>Its effective
+</H3></H1>
+
+= =
+<H1>POE Is much more efficient and effective than forking or
+</H1>
+
+<H1>multithreading.
+</H1>
+
+<H1><H3>Its efficient
+</H3></H1>
+
+= =
+<H1>Efficiency is often overlooked in favor of spending large amounts
+</H1>
+
+<H1>of money on scaling server clusters in order to handle load and
+</H1>
+
+<H1>decrease development time simultaniously. This is a fallacy, and
+</H1>
+
+<H1>aside from that, POE can scale in ways nothing else can.
+</H1>
+
+<H1><H3>Its cooperative
+</H3></H1>
+
+= =
+<H1>Because POE doesn't thread or fork, data is easier to manage.
+</H1>
+
+<H1>Multithreading requires a very difficult to maintain combination of
+</H1>
+
+<H1>locks on all shared data to avoid corruption. Forking doesn't
+</H1>
+
+<H1>allow sharing of data after the new process is created, other than
+</H1>
+
+<H1>via signals, alarms or pipes. This makes POE more powerful, and
+</H1>
+
+<H1>easier to maintain.
+</H1>
+
+<H1><H2>What POE does
+</H2></H1>
+
+= =
+<H1><H3>What POE was meant to be
+</H3></H1>
+
+= =
+<H1>POE was designed to be an object environment. It is, but its not
+</H1>
+
+<H1>quite how it was original invisioned. Here we will cover just a
+</H1>
+
+<H1>snippet of POE History.
+</H1>
+
+<H1><H3>What POE is today
+</H3></H1>
+
+= =
+<H1>POE has become alot more than the Object/Event multitasking
+</H1>
+
+<H1>environment it was intended to be. But in the same its alot less.
+</H1>
+
+<H1>We're going to talk a little about the new directions POE is
+</H1>
+
+<H1>taking as a flexable, extendable framework for scalable, event
+</H1>
+
+<H1>based applications.
+</H1>
+
+<H1><H3>What POE can and should do
+</H3></H1>
+
+= =
+<H1>Here we're going to just give an overview of what POE is capable
+</H1>
+
+<H1>of, large multitasking environments, distributed applications,
+</H1>
+
+<H1>extremely efficient usage of processing time, deligation of
+</H1>
+
+<H1>resources.
+</H1>
+
+<H1><H3>What POE can't and shouldn't do
+</H3></H1>
+
+= =
+<H1>POE has some limitations...but not many.
+</H1>
+
+<H1><H5>+ Note
+</H5></H1>
+
+= =
+<H1>I'm actually considering pulling this out and maybe
+</H1>
+
+<H1>summarizing the above subsection to be more along the
+</H1>
+
+<H1>lines of "What POE can do for you". As this is sort of
+</H1>
+
+<H1>covered below, in "Problems POE Creates"
+</H1>
+
+<H1><H2>Problems POE Solves
+</H2></H1>
+
+= =
+<H1><H3>Effective use of processing time
+</H3></H1>
+
+= =
+<H1>POE deligates process time, giving events a chance to be performed
+</H1>
+
+<H1>in order of priority, and from their in FIFO sequence.
+</H1>
+
+<H1><H3>Time slicing
+</H3></H1>
+
+= =
+<H1>We'll touch base with the concept of time slicing that makes most
+</H1>
+
+<H1>multitasking systems work.
+</H1>
+
+<H1><H3>Wait without limits
+</H3></H1>
+
+= =
+<H1>Its quite easy to get a program to wait for input or wait for
+</H1>
+
+<H1>another process to exit. But POE will wait for anything and
+</H1>
+
+<H1>everything at once, and then prioritize timed events in addition
+</H1>
+
+<H1>to this.
+</H1>
+
+<H1><H2>Problems POE Creates
+</H2></H1>
+
+= =
+<H1><H3>Limitations in program design
+</H3></H1>
+
+= =
+<H1>Not all modules work well with POE, we will discuss this, and other things
+</H1>
+
+<H1><H3>Nonblocking requirement
+</H3></H1>
+
+= =
+<H1>Its quite easy to stop a POE program from running. However you
+</H1>
+
+<H1>have to think about this in order to keep a POE program running,
+</H1>
+
+<H1>and in order to keep it running effectively. Its all to simple
+</H1>
+
+<H1>for a bad program design to make POE less responsive. We'll
+</H1>
+
+<H1>discuss this in this subsection.
+</H1>
+
+<H1><H3>There's always an answer
+</H3></H1>
+
+= =
+<H1>Pretty much every problem presented by the induction of POE into
+</H1>
+
+<H1>your programs design can be solved by a work around or other that
+</H1>
+
+<H1>has been added to POE to solve this problem.
+</H1>
+
+<H1><H1>Power Operating Environment
+</H1></H1>
+
+= =
+<H1>Here we will introduce various POE concepts and walk the reader through
+</H1>
+
+<H1>the writing of thier first POE program.
+</H1>
+
+<H1><H2>POE Sessions
+</H2></H1>
+
+= =
+<H1><H3>Explaination of Sessions
+</H3></H1>
+
+= =
+<H1>We'll provide a breif overview of what Sessions are, and what they
+</H1>
+
+<H1>are for. We will dip lightly into how they work, but try not to
+</H1>
+
+<H1>burry the reader in advanced concepts.
+</H1>
+
+<H1><H4>Inline States
+</H4></H1>
+
+= =
+<H1>We'll introduce inline states, which are the pinnacle of POE
+</H1>
+
+<H1>programming. We'll explain how they work and what they do, and
+</H1>
+
+<H1>what they get.
+</H1>
+
+<H1><H4>Session Heaps
+</H4></H1>
+
+= =
+<H1>This section should detail how the heaps work, why the heaps
+</H1>
+
+<H1>are provided, and how you can access them.
+</H1>
+
+<H1><H3>Creating a Session
+</H3></H1>
+
+= =
+<H1>Its time to introduce the create method. I'm opting to leave
+</H1>
+
+<H1>'new' out of the book entirely, since it is never needed it is
+</H1>
+
+<H1>only occasionally useful and I would like to see less code use it.
+</H1>
+
+<H1><H5>+ Note
+</H5></H1>
+
+= =
+<H1>That is assuming Rocco agrees.
+</H1>
+
+<H1><H4>State Arguments
+</H4></H1>
+
+= =
+<H1>We'll introduce the large number of arguements each session
+</H1>
+
+<H1>reiceves, as well as why POE is implimented this way.
+</H1>
+
+<H1><H4>Constants - a real psuedo hash
+</H4></H1>
+
+= =
+<H1>In this section we'll explain the constants which are exported
+</H1>
+
+<H1>by the POE Session module, and how this greatly increases the
+</H1>
+
+<H1>efficiency of inline states over a hash reference or argument
+</H1>
+
+<H1>hashes.
+</H1>
+
+<H1><H2>Introducing the POE Kernel
+</H2></H1>
+
+= =
+<H1><H3>What it does
+</H3></H1>
+
+= =
+<H1>The POE Kernel is the center of POE, respectively. In this
+</H1>
+
+<H1>section we will provide a little introduction to how the POE
+</H1>
+
+<H1>Kernel works, so our reader can understand a little of whats going
+</H1>
+
+<H1>on.
+</H1>
+
+<H1><H3>How it works
+</H3></H1>
+
+= =
+<H1>The POE Kernel watches signals, filehandles, and prepairs alarms
+</H1>
+
+<H1>all at once. Here we will bring how this happens to light.
+</H1>
+
+<H1><H3>Using the Kernel
+</H3></H1>
+
+= =
+<H1>We'll explain how to use the POE Kernel, in short. We wont really
+</H1>
+
+<H1>go into great detail about its other features, we'll bring this in
+</H1>
+
+<H1>later.
+</H1>
+
+<H1><H4>->run
+</H4></H1>
+
+= =
+<H1><H4>->post
+</H4></H1>
+
+= =
+<H1><H4>->yield
+</H4></H1>
+
+= =
+<H1><H5>+ Note
+</H5></H1>
+
+= =
+<H1>Just the basics at first.
+</H1>
+
+<H1><H2>Interaction between Kernel and Session
+</H2></H1>
+
+= =
+<H1>In this section we'll illustrate how the POE Kernel interacts with
+</H1>
+
+<H1>its Sessions. Hopefully this will bring into light when a task
+</H1>
+
+<H1>deserves its own Session, as well as explain some of the design
+</H1>
+
+<H1>decisions of POE in general.
+</H1>
+
+<H1><H3>Special States
+</H3></H1>
+
+= =
+<H1>POE Sessions treat states with a few specific names in a special
+</H1>
+
+<H1>way. In this section, we will introduce these states and thier
+</H1>
+
+<H1>workings. We will also explain why the reader should know about
+</H1>
+
+<H1>atleast some of them from the begining. (Namely _start).
+</H1>
+
+<H1><H4>_start
+</H4></H1>
+
+= =
+<H1><H4>_stop
+</H4></H1>
+
+= =
+<H1><H4>_child
+</H4></H1>
+
+= =
+<H1><H4>_parent
+</H4></H1>
+
+= =
+<H1><H4>_default
+</H4></H1>
+
+= =
+<H1><H4>_signal
+</H4></H1>
+
+= =
+<H1><H3>Event Routing
+</H3></H1>
+
+= =
+<H1>We will also describe POE's event routing, both the low level
+</H1>
+
+<H1>event routing performed by the POE Kernel and the high level event
+</H1>
+
+<H1>routing which should be performed by most Components. Sure
+</H1>
+
+<H1>references to the chapter on Components, somewhere around the
+</H1>
+
+<H1>section which goes over writing your own components, for more
+</H1>
+
+<H1>information on why higher level event routing should be used.
+</H1>
+
+<H1><H1>Perl Overdrive Engine
+</H1></H1>
+
+= =
+<H1>Sooner than later we needed to bring this up, so this section will be
+</H1>
+
+<H1>dedicated to the POE Wheel. This chapter will introduce the concept of the
+</H1>
+
+<H1>Wheel. What its intentions are, and what the expected behavior of a Wheel
+</H1>
+
+<H1>is.
+</H1>
+
+<H1><H2>Nonblocking IO
+</H2></H1>
+
+= =
+<H1>This section will describe how POE's Wheels interact with the Kernel
+</H1>
+
+<H1>to perform nonblocking IO on a higher level.
+</H1>
+
+<H1><H2>Different Wheels for different environments
+</H2></H1>
+
+= =
+<H1>Like different tires for different terrain.
+</H1>
+
+<H1><H3>ReadWrite Wheel
+</H3></H1>
+
+= =
+<H1>We must first illustrate the ReadWrite, possibly the most common,
+</H1>
+
+<H1>POE Wheel.
+</H1>
+
+<H1><H3>SocketFactory Wheel
+</H3></H1>
+
+= =
+<H1>And then SocketFactory Wheel and how to use it with the ReadWrite
+</H1>
+
+<H1>wheel to do create sockets in a completely POE friendly manner.
+</H1>
+
+<H1><H3>ListenAccept Wheel
+</H3></H1>
+
+= =
+<H1>Then while we're on topic the ListenAccept Wheel, and how you can
+</H1>
+
+<H1>use it to work with Net:: and other modules which create thier own
+</H1>
+
+<H1>sockets in a non-POE-friendly manner.
+</H1>
+
+<H1><H3>FollowTail Wheel
+</H3></H1>
+
+= =
+<H1>A brief description of the FollowTail Wheel and maybe a multiple
+</H1>
+
+<H1>log chaser example.
+</H1>
+
+<H1><H3>Curses Wheel
+</H3></H1>
+
+= =
+<H1>The Curses Wheel and an example of how to use it to do simple
+</H1>
+
+<H1>nonblocking keyboard input.
+</H1>
+
+<H1><H3>Run Wheel
+</H3></H1>
+
+= =
+<H1>Then last but not least the Run Wheel. We'll provide an example of
+</H1>
+
+<H1>how it can be used to do inter-process communication with a
+</H1>
+
+<H1>programs children in a nonblocking form, while your program does
+</H1>
+
+<H1>other things.
+</H1>
+
+<H1><H2>POE Filters
+</H2></H1>
+
+= =
+<H1>This would be a good time to go over POE Filters and what thier
+</H1>
+
+<H1>purpose is. And then go over the various filters.
+</H1>
+
+<H1><H3>Line Filter
+</H3></H1>
+
+= =
+<H1>The line filter, the most common and often default should be
+</H1>
+
+<H1>first.
+</H1>
+
+<H1><H3>Block Filter
+</H3></H1>
+
+= =
+<H1>The block filter, and how it can be used for binary networking
+</H1>
+
+<H1>protocols.
+</H1>
+
+<H1><H3>Reference Filter
+</H3></H1>
+
+= =
+<H1>The reference filter and probably here, while we're on references,
+</H1>
+
+<H1>we'll refer them to the the section on Application Servers and
+</H1>
+
+<H1>IKC.
+</H1>
+
+<H1><H3>Grep Filter
+</H3></H1>
+
+= =
+<H1>The clever and ultimately flexable Grep filter
+</H1>
+
+<H1><H3>Map filter
+</H3></H1>
+
+= =
+<H1>The map filter and how it lets them get all down and dirty with
+</H1>
+
+<H1>thier data.
+</H1>
+
+<H1><H3>Stackable Filter
+</H3></H1>
+
+= =
+<H1>And then how to use several filters togeather, using the stackable
+</H1>
+
+<H1>filter.
+</H1>
+
+<H1><H1>POE Components
+</H1></H1>
+
+= =
+<H1>Now that we have the details out of the way, the reader should be familiar
+</H1>
+
+<H1>with enough POE to write a Component or two.
+</H1>
+
+<H1><H2>Component Oriented Programming
+</H2></H1>
+
+= =
+<H1>But first we must introduce the concept of the component.
+</H1>
+
+<H1><H2>Component Designs
+</H2></H1>
+
+= =
+<H1>And why component based designs work for the programmer.
+</H1>
+
+<H1><H3>Message Based Components
+</H3></H1>
+
+= =
+<H1>We should describe message based copmonents and how thier event
+</H1>
+
+<H1>callbacks let you work seemlessly with another session who's
+</H1>
+
+<H1>output you have to wait for.
+</H1>
+
+<H1><H3>Session Based Components
+</H3></H1>
+
+= =
+<H1>As well as Session based components that allow you to build your
+</H1>
+
+<H1>entire application around them.
+</H1>
+
+<H1><H2>Writing your own components
+</H2></H1>
+
+= =
+<H1>It will describe how you can easily go about writing your own
+</H1>
+
+<H1>components.
+</H1>
+
+<H1><H3>Writing components from scratch.
+</H3></H1>
+
+= =
+<H1>How small an simple a component can be, and yet how much it can
+</H1>
+
+<H1>break up your design and make it easier to manage.
+</H1>
+
+<H1><H3>Writing components using components.
+</H3></H1>
+
+= =
+<H1>As well as how you would use other components to write things like
+</H1>
+
+<H1>protocol specific daemons that build stand alone applications
+</H1>
+
+<H1>using POE. Clients will be covered too of course.
+</H1>
+
+<H1><H3>Component Conventions
+</H3></H1>
+
+= =
+<H1>Things people should consider when designing thier components,
+</H1>
+
+<H1>such as inline state naming, high level event routing, how to go
+</H1>
+
+<H1>about exporting constants and adding features to the array given
+</H1>
+
+<H1>to states. Also interface considerations, and what ever else may
+</H1>
+
+<H1>come up between now and writing this section..'
+</H1>
+
+<H1><H1>User interfaces and POE
+</H1></H1>
+
+= =
+<H1>Now we will talk about using POE For user interfaces. We will go over how
+</H1>
+
+<H1>we replace other event loops with POE loops, and how to do it with or
+</H1>
+
+<H1>without an alternative POE Loop.
+</H1>
+
+<H1><H2>POE and Tk
+</H2></H1>
+
+= =
+<H1>We'll talk about POE and Tk and how POE's custom Tk loop has been
+</H1>
+
+<H1>designed to work seemlessly with Tk.
+</H1>
+
+<H1><H2>POE and Gtk
+</H2></H1>
+
+= =
+<H1>We'll also talk about the Gtk event loop and how POE replaces it, as
+</H1>
+
+<H1>well as how its signal and other handlers communicate.
+</H1>
+
+<H1><H2>POE and Qt
+</H2></H1>
+
+= =
+<H1>Maybe by then there will be some Qt to cover, as that event loop
+</H1>
+
+<H1>hasn't been addressed yet.
+</H1>
+
+<H1><H2>POE and Curses
+</H2></H1>
+
+= =
+<H1>And then we'll talk about the down and dirty, using POE for Good old
+</H1>
+
+<H1>Curses interfaces.
+</H1>
+
+<H1><H3>POE and the Curses UI Toolkit
+</H3></H1>
+
+= =
+<H1>Someplace we might wish to mention the Curses UI Toolkit
+</H1>
+
+<H1>adaptation.
+</H1>
+
+<H1><H3>The Term Visual interface
+</H3></H1>
+
+= =
+<H1>We also should make mention of the very nice Term Visual
+</H1>
+
+<H1>interface.
+</H1>
+
+<H1><H2>POE and the xyz UI
+</H2></H1>
+
+= =
+<H1>As well as more information on how to make POE work with any old user
+</H1>
+
+<H1>interface. How to go about circumventing foreign event loops to make
+</H1>
+
+<H1>them use POE, as well as how to make POE use other event loops (also
+</H1>
+
+<H1>when you can, when you should, and when you shouldn't take that
+</H1>
+
+<H1>approach).
+</H1>
+
+<H1><H1>Programming Over Easy
+</H1></H1>
+
+= =
+<H1>Now would be a good time to make a trip back into Networking to describe
+</H1>
+
+<H1>it in possibly a little more detail, since our reader probably by now
+</H1>
+
+<H1>wants to either make a client, a daemon, or never ever hear of POE again.
+</H1>
+
+<H1>Hopefully not the latter :)
+</H1>
+
+<H1><H2>Moving from IO::Select
+</H2></H1>
+
+= =
+<H1>We'll describe how to migrate IO::Select applications.
+</H1>
+
+<H1><H2>Moving from Net::SomeModule
+</H2></H1>
+
+= =
+<H1>And we'll describe how to work with Net::SomeModule, as well as a few
+</H1>
+
+<H1>of the components which can easily replace Net::SomeModule.
+</H1>
+
+<H1><H2>Using POE for TCP
+</H2></H1>
+
+= =
+<H1>And we'll talk about TCP, for Clients and Servers. Using POE's
+</H1>
+
+<H1>ReadWrite and SocketFactory wheel's, and daemonizing
+</H1>
+
+<H1><H3>POE Clients
+</H3></H1>
+
+= =
+<H1><H3>POE Daemons
+</H3></H1>
+
+= =
+<H1><H3>Using TCP Components
+</H3></H1>
+
+= =
+<H1>And we'll discuss the components that make thier lives easier. As
+</H1>
+
+<H1>well as the components which make thier lives a little harder to
+</H1>
+
+<H1>achieve a slightly different ultimate goal.
+</H1>
+
+<H1><H4>Client Components
+</H4></H1>
+
+= =
+<H1>Client Components
+</H1>
+
+<H1><H4>Daemon Components
+</H4></H1>
+
+= =
+<H1>And Daemon Components.
+</H1>
+
+<H1><H2>Using POE for UDP
+</H2></H1>
+
+= =
+<H1>And then we'll take a short trip into the land of UDP and POE.
+</H1>
+
+<H1><H2>Using POE for DNS
+</H2></H1>
+
+= =
+<H1>But by this time, they're going to want to know about the DNS Client
+</H1>
+
+<H1>Component, which should allow them to utilize some of their recently
+</H1>
+
+<H1>aquired message based communication knowledge.
+</H1>
+
+<H1><H1>Advanced Concepts
+</H1></H1>
+
+= =
+<H1><H2>NFA
+</H2></H1>
+
+= =
+<H1>Then we should describe the NFA State Machine. I will have to learn a
+</H1>
+
+<H1>little bit more about it myself before I can write about it, I'm still
+</H1>
+
+<H1>kind of in awe :)
+</H1>
+
+<H1><H1>Proliferation Of Events
+</H1></H1>
+
+= =
+<H1>The introduction to this chapter will begin with explanations of what
+</H1>
+
+<H1>distributing tasks is all about. Why we do it, why we often dont, and why
+</H1>
+
+<H1>POE does a good job of this.
+</H1>
+
+<H1><H2>Application Servers
+</H2></H1>
+
+= =
+<H1>Then we'll explain how to design application servers in POE.
+</H1>
+
+<H1><H2>InterKernel Communication
+</H2></H1>
+
+= =
+<H1>Using InterKernel Communication, and the IKC Components.
+</H1>
+
+<H1><H3>The IKC Server
+</H3></H1>
+
+= =
+<H1>We'll explain how the IKC Server works to seemelessly accept
+</H1>
+
+<H1>instructions as through they came from inside the current Kernel.
+</H1>
+
+<H1><H3>The IKC Client
+</H3></H1>
+
+= =
+<H1>And how the IKC Client works with the IKC Server to give
+</H1>
+
+<H1>instructions to other Kernels.
+</H1>
+
+<H1><H3>The IKC Responder
+</H3></H1>
+
+= =
+<H1>As well as How the responder can be used to generate responses
+</H1>
+
+<H1>seemlessly like message based POE Components.
+</H1>
+
+<H1><H3>Serialization
+</H3></H1>
+
+= =
+<H1>And how you can use whatever Serialization you want to transfer
+</H1>
+
+<H1>the data, including something like YAML or Data::Dumper which are
+</H1>
+
+<H1>a bit more legible for logging/debugging. And a small overview of
+</H1>
+
+<H1>various available Serialization modules and languages.
+</H1>
+
+<H1><H5>+ Note
+</H5></H1>
+
+= =
+<H1>Surely we will make references here back to Filter-Reference
+</H1>
+
+<H1>mentioned earlier in the book
+</H1>
+
+<H1><H3>Non POE Clients
+</H3></H1>
+
+= =
+<H1>We'll demonstrate how to use Non POE clients in places where its
+</H1>
+
+<H1>not appropriate to use a POE client, but it is appropriate to
+</H1>
+
+<H1>distribute your application. I think the example we should use is
+</H1>
+
+<H1>a mod_perl application that must scale, we'll make POE distribute
+</H1>
+
+<H1>all the work while the mod_perl program works as simply an outlet
+</H1>
+
+<H1>for communicating with the browsers.
+</H1>
+
+<H1><H2>Job Servers
+</H2></H1>
+
+= =
+<H1>We'll explain the more about much more Simple job servers which dont
+</H1>
+
+<H1>use inter-kernel communication, but are implimented with more of a
+</H1>
+
+<H1>simple TCP protocol for enqueuing jobs and returning thier
+</H1>
+
+<H1>information.
+</H1>
+
+<H1><H1>POE's Private Parts
+</H1></H1>
+
+= =
+<H1>And now we'll actually dig into the internals and more obscure parts of
+</H1>
+
+<H1>POE. The point is the same as the recent abstractions, to make POE Easier
+</H1>
+
+<H1>to extend. The goal is to document the Kernel abstractions promoting that
+</H1>
+
+<H1>pretty much any problem concievable can be solved without actually
+</H1>
+
+<H1>fiddling with the POE Kernel.
+</H1>
+
+<H1><H2>POE's Loops
+</H2></H1>
+
+= =
+<H1>Such as the methods which are passed on to the POE Loops.
+</H1>
+
+<H1><H3>Loop Contexts
+</H3></H1>
+
+= =
+<H1>It will describe how POE Selects which Loop to use. This should be
+</H1>
+
+<H1>useful information for anyone who wants to write an additional POE
+</H1>
+
+<H1>Loop to impliment something which doesn't currently exist.
+</H1>
+
+<H1><H5>+ Note
+</H5></H1>
+
+= =
+<H1>Presumably by this time POE's new Loop Loading will be
+</H1>
+
+<H1>working properly.
+</H1>
+
+<H1><H3>Various POE Loops
+</H3></H1>
+
+= =
+<H1>It will also describe a number of alternative POE Loops that
+</H1>
+
+<H1>already exist, and why they exist. Surely this section will have
+</H1>
+
+<H1>plenty of references to the User Interface chapter.
+</H1>
+
+<H1><H2>POE Drivers
+</H2></H1>
+
+= =
+<H1>In this section we'll be describing the more low level POE friendly IO
+</H1>
+
+<H1>than most people would really ever use...the SysRW Driver, which is
+</H1>
+
+<H1>used by most POE Wheels.
+</H1>
+
+<H1><H2>POE Queues
+</H2></H1>
+
+= =
+<H1>We'll describe POE's Array Queue, and its FIFO organization of
+</H1>
+
+<H1>similarly prioritized items.
+</H1>
+
+<H1><H2>POE API
+</H2></H1>
+
+= =
+<H1>We'll describe the new POE::API interface in short, and its new found
+</H1>
+
+<H1>ability to provide third party APIs into POE, without altering the
+</H1>
+
+<H1>Kernel itself.
+</H1>
+
+<H1><H2>POE Resource
+</H2></H1>
+
+= =
+<H1>And how it can interact with the new Resource abstractions, as well as
+</H1>
+
+<H1>illustrate some of the current Resource abstractions available.
+</H1>
+
+<H1><H3>Resource Aliases
+</H3></H1>
+
+= =
+<H1>Such as the managing of Session Aliases.
+</H1>
+
+<H1><H3>Resource Events
+</H3></H1>
+
+= =
+<H1>We'll describe how abstracting the Event handling from the POE
+</H1>
+
+<H1>Kernel simplifies its tasks
+</H1>
+
+<H1><H3>Resource FileHandles
+</H3></H1>
+
+= =
+<H1>And all the other stuff that has no public interface.
+</H1>
+
+<H1><H1>Appendix
+</H1></H1>
+
+= =
+<H1><H2>Quick Reference
+</H2></H1>
+
+= =
+<H1><H3>Kernel
+</H3></H1>
+
+= =
+<H1><H4>Methods
+</H4></H1>
+
+= =
+<H1><H4>Exports
+</H4></H1>
+
+= =
+<H1><H4>Debugging
+</H4></H1>
+
+= =
+<H1><H3>Session
+</H3></H1>
+
+= =
+<H1><H4>Methods
+</H4></H1>
+
+= =
+<H1><H4>Constructor Options
+</H4></H1>
+
+= =
+<H1><H4>Event Fields
+</H4></H1>
+
+= =
+<H1><H4>Predefined Event Names
+</H4></H1>
+
+= =
+<H1><H3>Loop
+</H3></H1>
+
+= =
+<H1><H3>API
+</H3></H1>
+
+= =
+<H1><H3>Resource
+</H3></H1>
+
+= =
+<H1><H3>Components
+</H3></H1>
+
+= =
+<H1>Established and stable POE components, brief listing
+</H1>
+
+<H1><H4>POE::Component::IRC
+</H4></H1>
+
+= =
+<H1>IRC Client Component
+</H1>
+
+<H1><H4>POE::Component::SNMP
+</H4></H1>
+
+= =
+<H1>SNMP Client Component
+</H1>
+
+<H1><H4>POE::Component::Client::HTTP
+</H4></H1>
+
+= =
+<H1>Flexable and fast HTTP and HTTPs Client Component.
+</H1>
+
+<H1><H4>POE::Component::Server::HTTP
+</H4></H1>
+
+= =
+<H1>POE Micro WebServer.
+</H1>
+
+<H1><H4>POE::Component::Client::POP3
+</H4></H1>
+
+= =
+<H1>Pop3 Client
+</H1>
+
+<H1><H4>POE::Component::Client::Ping
+</H4></H1>
+
+= =
+<H1>Ping Client
+</H1>
+
+<H1><H4>POE::Component::Pcap
+</H4></H1>
+
+= =
+<H1>libpcap Interface
+</H1>
+
+<H1><H4>POE::Component::Client::TCP
+</H4></H1>
+
+= =
+<H1>Simplified TCP Client
+</H1>
+
+<H1><H4>POE::Component::Server::TCP
+</H4></H1>
+
+= =
+<H1>Simplified TCP Server
+</H1>
+
+<H1><H4>POE::Component::Client::DNS
+</H4></H1>
+
+= =
+<H1>A simple and effective DNS Client
+</H1>
+
+<H1><H4>POE::Component::LaDBI
+</H4></H1>
+
+= =
+<H1>Nonblocking DBI Access
+</H1>
+
+<H1><H4>POE::Component::IKC
+</H4></H1>
+
+= =
+<H1>InterKernel Communication Components
+</H1>
+
+<H1><H5>POE::Component::IKC::Client
+</H5></H1>
+
+= =
+<H1>The Client
+</H1>
+
+<H1><H5>POE::Component::IKC::Server
+</H5></H1>
+
+= =
+<H1>The Server
+</H1>
+
+<H1><H5>POE::Component::IKC::Responder
+</H5></H1>
+
+= =
+<H1>State Handling
+</H1>
+
+<H1><H5>POE::Component::IKC::Specifier
+</H5></H1>
+
+= =
+<H1>Event Specifier
+</H1>
+
+<H1><H5>POE::Component::IKC::Freezer
+</H5></H1>
+
+= =
+<H1>Pure Perl Sterilization
+</H1>
+
+<H1><H1></outline></H1>
+
+</H1>
+
View
180 programming-poe.wiki
@@ -0,0 +1,180 @@
+Formerly http://poe.perl.org/action/edit?id=Programming_POE
+
+---
+
+= Programming POE =
+
+Ah, a book. Who'd have thunk it.
+
+Authors: [[Rocco]], [[Sungo]], DrForr
+
+The outline we're working with looks something like this (as with all
+things, it won't look anything like this in the end game. suck it up):
+
+== [[/Introduction to POE]] ==
+
+* What is POE?
+** Why should I use it?
+** Where do I find it?
+** When and how was it developed?
+* General Concepts
+** Events
+** States
+** Sessions
+** Heaps
+* POErl
+** Basic Rules
+** Session Creation
+** State Parameters
+** Methods
+*** post
+*** yield
+*** delay
+
+== POE ==
+
+* Overview
+** POE's event loop is flexible enough to handle GUIs like Tk and Gtk, and network events all at the same time.
+** Events in POE interact with Components.
+** Components can be network servers like IRC or HTTPD
+** Components can spawn their own children, much like how Apache handles connections.
+* Low-Level layers
+** Sessions are like processes on your typical O/S.
+** Just like processes, Sessions are non-blocking, which means that they're always ready to accept input.
+** Of course, processes are no use unless they can accept input and produce output.
+** Wheels take on this challenge. Wheels can deal with file handles, like Wheel::ReadWrite, or network events like Wheel::SocketFactory.
+* Components
+** An Event can be a webserver access. POE::Component::Client::HTTPD can manage that.
+** A webserver has to return something to the user, so, assuming we have a class called "Game", stick some text into a webpage and return it.
+* Wheel
+* Session (process)
+* Filters and the Driver
+** Filters take data from a source (socket, filehandle, and other Filters.
+** They take the incoming data and buffer, block and/or transform it in some manner.
+** Driver::SysRW
+* Kernel
+
+== [[/Advanced POE]] ==
+
+* Component Internals
+** Anatomy of a component
+** A sample component.
+* Inside Filters
+** Anatomy of a filter.
+*** Filters take an input handle and store the data collected somewhere.
+** A sample filter.
+*** The Block Filter collects N bytes of data
+*** And the Filter posts an event to send the post-processed data out.
+*** We'll simply separate the string into integers, identifiers, and everything else.
+*** Using the Block filter as a sample, we'll accumulate text into a buffer.
+*** Instead of returning the entire buffer
+**** If there's a number at the start of the buffer, send that back.
+**** If there's an identifier at the start, send that back.
+**** Couldn't find anything to process, so just return the first character.
+* Network protocol modules
+** HTTP
+*** Sample app: metavoyeur. I have a command-line interface to fifteen or so search voyeurs. It polls them periodically and generates combined popularity numbers. it may be too big to present, though.
+*** Micrometavoyeur: a scaled down version.
+** IRC
+** Others (Just as important, but web applications will likely get the most time and attention)
+*** DNS
+*** ping
+*** PCap
+* General purpose components
+** Components don't need to be I/O bound.
+*** JobQueue
+** Text and Speech
+*** Text parsing
+**** RSS
+**** Tokenize
+**** Speech synthesis and recognition
+**** POE::Component::Festival - Speech generation
+**** POE::Component::SPX - Speech Recognition
+** IKC
+*** Kernels can communicate with one another.
+** Uncategorized Stuff
+*** Notes:
+**** The introductory section might cover projects using POE. Lots of sexy stuff is going on.
+**** This uncategorized section is just free-association outside the main outline. I'll weed through stuff here and put the useful bits into the outline above.
+**** I could be on the bad kind of crack. Someone tell me some sense before I go nuts on this. :)
+**** Don't eat the brown acid! --[[coral]]
+
+== Uncategorized Topics ==
+
+These topics are from the original outline. They should be integrated
+into the book or swept under a carpet.
+
+* How events are dispatched.
+** The precedence order of dispatched events.
+** Synchronous vs. asynchronous events.
+*** post() vs. call()
+*** Why not to use call()
+*** When call() is necessary.
+** Signal propagation from the operating system to your code.
+*** Signals are bad, but this is useful information.
+
+* Extending sessions with wheels.
+** How wheels work.
+*** Anatomy of a wheel.
+*** They plug into sessions.
+*** They add states into sessions, like viral DNA in an unsuspecting cell.
+*** They take their tentacles back out when destroyed.
+*** They cannot be given to another session!
+*** Nice place for a diagram: wheels, filters, and drivers.
+*** Design flaws, and a future without them?
+** How to write a wheel.
+*** Parts of a wheel.
+
+* Extending sessions with interfaces.
+** Interfaces are just boilerplate sets of states.
+** Interfaces are defined in session constructors.
+** So far nobody has ever used them.
+
+* Extending wheels with filters.
+** How filters work.
+** How to write a new filter.
+** Jeff has practically finished this session.
+
+* Extending programs with components.
+** What components are.
+** Component interfaces.
+*** Event driven: request and response messages. Wallowing in the POE-ness of it all.
+*** Function interface with callbacks. Hiding POE behind an innocent looking function library.
+*** Object interface with callbacks. Hiding POE behind a suspicious looking set of objects.
+
+* Customizing event dispatch with new sessions.
+** How sessions work inside. What goes on in there?
+*** Route events to handlers.
+*** They do the _default thing, not Kernel.
+*** NFA vs. Session.
+*** Sessions own resources, but Kernel does that for us. Sessions are basically keys into the Kernel's data structures.
+** How sessions don't work. What's wrong with them?
+*** Can't tell which events a session supports without the session's cooperation. That's called "encapsulation", and it's a feature.
+*** A new kind of session could publish its event handler names, etc.
+** Design and build a new session from scratch.
+*** Something useful, fun, and not too big. Ch'yeah!
+
+* Supporting new event loops. Event substrates.
+** Deep guts magic.
+** Requires a firm grasp of POE::Preprocessor.
+** How to roll a new event substrate.
+*** Dear gods, no!
+
+* Macros
+** Templates for Perl source code.
+** const
+** enum
+** macro
+** conditional compilation (deprecated?)
+** What happens when const/enum names clash with other source code.
+*** Hint: It's bad.
+
+* *nix vs Win32 environment (kz15)
+** fork() implementations
+** Wheels and filters
+** Creating standalone executables in Win32
+*** Hint: sub RUNNING_IN_HELL () { $^O eq 'MSWin32' }
+
+[[Rocco]] adds here: Creating standalone executables in Win32 has been
+documented (and tested with perl2exe) in POE 0.21. See the notes
+towards the end of the POE::Preprocessor perldoc/man page.
View
83 style-concepts.wiki
@@ -0,0 +1,83 @@
+Formerly http://poe.perl.org/action/edit?id=POE_Documentation/Style_Concepts
+
+---
+
+== Combined Concept ==
+
+This section discusses how things interact in POE.
+
+=== Kernel and Sessions ===
+
+The kernel's largest job is watching resources. Not only does it
+check the resources for new events, but it also tracks their uses. It
+does this itself, rather than relying on Perl reference counting,
+because it was written prior to Perl's weak references, and it's still
+in use by Perl versions as old as 5.004.
+
+The kernel tracks resources by the sessions that watch them. It
+maintains each resource's reference count, cleaning them up and
+releasing their memory when they are no longer in use. That is, it
+will do this if programs don't keep extra resource references. Again,
+weak references would help here, but they don't exist in all the
+places where POE is useful.
+
+Sessions are resources themselves, and a session created within
+another becomes a child of its creator. The kernel tracks these
+relationships for the purpose of job control-- especially the ability
+for one session to manage a pool of several others-- and signal
+propagation within a program.
+
+=== Sessions and Wheels ===
+
+While writing sample programs and test cases for POE's early
+development, the same sorts of algorithms came up again and again.
+The most common routines involved I/O, either at the socket
+establishment level or for buffered reading and writing on open files.
+
+These recurring routines are often filehandle watcher callbacks or
+supporting states. Rewriting them had become tiresome almost as soon
+as POE was released, so it was decided to make modular units out of
+them. Wheels were invented, replacing the ones being re-created with
+every program.
+
+Wheels were invented to encapsulate these bundles of redundant states
+and provide the glue logic to insert them into sessions. They are
+state machine fragments that plug themselves into sessions at creation
+time, giving their owners new capabilities.
+
+Wheels are not resources, and POE's kernel will not keep track of
+them. It's therefore important that sessions hold onto their wheel
+references for as long as they're needed. Wheels may be given
+resources to manage; in this case, the resource is watched internally
+by the wheel, and destroying it will cascade cleanup to the resource
+itself. Wheels are implemented so that any circular references are
+broken at destruction time, ensuring complete destruction and memory
+reuse.
+
+Wheels bind themselves tightly to the sessions that create them.
+While it's possible to pass wheel references amongst sessions, their
+states will remain in the sessions that created them.
+
+Wheels often deal with resources on behalf of their sessions, finally
+passing back events when something truly notable occurs. On the other
+hand, sessions usually invoke wheel features through direct method
+calls.
+
+=== I/O Wheels, Drivers, and Filters ===
+
+Many I/O wheels use drivers and filters to abstract away the gory
+details of raw file I/O and the specifics of low-level data parsing
+and marshalling. This division allows the I/O wheels themselves to
+focus on the logic necessary to perform a task.
+
+The ReadWrite wheel, for example, performs simple reading and writing.
+It can adapt to the natures of several different file types by virtue
+of using different filters. It can perform HTTP server transactions
+by using Filter::HTTPD; it can read and write lines by using
+Filter::Line; or it can use some other filter, either currently
+available or written in the future.
+
+
+This style guide is copyright 2001-2002 by Rocco Caputo. All rights
+reserved. This guide is free text and may be distributed and/or
+modified under the same terms as Perl itself.
View
28 style-general.wiki
@@ -0,0 +1,28 @@
+Formerly http://poe.perl.org/action/edit?id=POE_Documentation/Style_General
+
+---
+
+== The Elements of Style ==
+
+This section discusses typographical and syntactical conventions used
+throughout POE's documentation.
+
+=== Capitalization (c12n) ===
+
+People expect ``kernel'' to mean the operating system's, not POE's.
+Session also has a meaning in Unix, and while there's a little overlap
+between that meaning and POE's, it's different and similar enough at
+the same time to be confusing.
+
+Capitalize the names of POE classes to distinguish them from operating
+system constructs. Preface them with ``POE's'' now and again to keep
+the reader oriented.
+
+
+This style guide is copyright 2001-2002 by Rocco Caputo. All rights
+reserved. This guide is free text and may be distributed and/or
+modified under the same terms as Perl itself.
+
+<!--
+" vim: syntax=wiki
+-->
View
319 notes.glossary → style-glossary.wiki
@@ -1,58 +1,63 @@
-Glossary
+Formerly http://poe.perl.org/action/edit?id=POE_Documentation/Style_Glossary
-POE docs throw around lots of odd words and phrases. It's confusing to
-the reader when they're used inconsistently, so documentation authors
-should have a good grasp of what they mean.
+---
-Woe unto anyone-- especially Rocco-- who uses these terms incorrectly.
+== Glossary ==
+
+POE docs throw around lots of odd words and phrases. It's confusing
+to the reader when they're used inconsistently, so documentation
+authors should have a good grasp of what they mean.
+
+Woe unto anyone-- especially [[Rocco]]-- who uses these terms
+incorrectly.
Actually, this might make a great starting point for the POE
-documentation itself. It covers a lot of concepts in broad strokes,
+documentation itself. It covers a lot of concepts in broad strokes,
and it could link to more detailed discussion of things.
-alarm
+=== alarm ===
A timer that dispatches an event at an absolute time.
see: delay, dispatch, event, timer
-asynchronous
+=== asynchronous ===
-Happening at a different time. Literally, not coinciding in time.
+Happening at a different time. Literally, not coinciding in time.
Handlers for queued events run asynchronously; that is, they are
invoked after the current event has been handled.
see: dispatch, event, synchronous
-call
+=== call ===
To immediately invoke an event handler, passing the event to it
directly instead of posting it through the queue.
see: dispatch, immediate event
-callback
+=== callback ===
A code reference that is passed to a library so that it may be called
-when something has occurred. The library calls the main program back,
+when something has occurred. The library calls the main program back,
rather than returning something.
Callbacks are useful in event driven programs since they often provide
-a form of concurrency. The main program can continue on, eventually
+a form of concurrency. The main program can continue on, eventually
receiving notification via callback that some background task has
finished.
see: event driven program, postback
-client session
+=== client session ===
-A session that requests a service from another session. Clients are
+A session that requests a service from another session. Clients are
often custom code; servers are usually pre-written or reusable
components.
see: component, server session, session
-component
+=== component ===
A module or library containing one or more POE sessions.
@@ -60,83 +65,83 @@ Components can be divided into three types, based on their interfaces:
servlets, libraries, and hybrids.
"Servlet" components set up stand-alone sessions that interact with
-the rest of the program through events. Client sessions post requests
+the rest of the program through events. Client sessions post requests
at servelets, and the servlets post responses back.
Library components present a more traditional call and callback
-interface. Programs call functions within the component that in turn
-interact with its underlying session. Events occurring within the
-session are passed back to the program through callbacks. It's
-possible to completely hide POE this way.
+interface. Programs call functions within the component that in turn
+interact with its underlying session. Events occurring within the
+session are passed back to the program through callbacks. It's possible to
+completely hide POE this way.
-Hybrid components provide some mix of the other two interfaces. To
+Hybrid components provide some mix of the other two interfaces. To
date, nobody has written a hybrid component.
see: callback, nfa session, session
-cooperative multitasking
+=== cooperative multitasking ===
A form of multitasking where the programs themselves decide when to
-end their timeslices and allow other programs the chance to run. POE
+end their timeslices and allow other programs the chance to run. POE
uses cooperative multitasking.
Cooperative multitasking can be dangerous because a single thread or
-process can hold a timeslice indefinitely. It can also be more
+process can hold a timeslice indefinitely. It can also be more
efficient: The system spends less time switching between threads, so
it has more opportunity to run the code within them.
see: pre-emptive multitasking, timeslice
-custom event
+=== custom event ===
An event generated by a program, as opposed to a standard event that
POE generates itself.
see: event, standard event
-delay
+=== delay ===
A timer that dispatches an event after an interval of time has
elapsed.
see: alarm, dispatch, event, timer
-dispatch
+=== dispatch ===
To call an event handler using the event's fields as parameters.
Each event is dispatched when it arrive at the head of the Kernel's
-event queue. Dispatching an event clears the way for the next one, and
-so on, until the queue empties. Event handlers and resource watchers
-may post new events into the queue.
+event queue. Dispatching an event clears the way for the next one,
+and so on, until the queue empties. Event handlers and resource
+watchers may post new events into the queue.
see: event, event fields, event handler, event handler parameters,
event queue, immediate event, kernel, post, queued event
-driver
+=== driver ===
A member of the Wheels I/O abstraction that performs low-level raw I/O
-with a filehandle. A driver's sole purpose is to hide the specific
+with a filehandle. A driver's sole purpose is to hide the specific
guts of some form of file I/O.
Drivers both send and receive, but it's not necessary to use them in
-both directions. Drivers' sending sides may maintain write buffers, so
-sending data to a wheel often means it is queued and written later.
+both directions. Drivers' sending sides may maintain write buffers,
+so sending data to a wheel often means it is queued and written later.
Drivers buffer data to be sent, while filters buffer received data
until it can be converted.
-Drivers don't depend on any other part of POE. They can be used by
+Drivers don't depend on any other part of POE. They can be used by
themselves in other programs.
see: filter, raw data, record, wheel, Sessions and Wheels
-event
+=== event ===
A message that notifies a session when something has happened.
Events often convey information about resources that have become
-active. They're are also used for other things, including
+active. They're are also used for other things, including
self-notification, yielding timeslices to other sessions, and
inter-session communication.
@@ -146,33 +151,33 @@ parameters.
see: dispatch, event fields, event handler, event handler parameters,
immediate event, kernel, queued event, resource
-event driven programming
+=== event driven programming ===
Programs that react to events as they occur rather than performing
-tasks in a linear fashion. Events are the impetus which drives these
+tasks in a linear fashion. Events are the impetus which drives these
programs instead of some pre-set procedure.
-User interfaces are classical event driven programs. They can't know
+User interfaces are classical event driven programs. They can't know
what their users will do next, so they must wait for events to happen
-and handle them when they do. Shells, for example, wait for user
+and handle them when they do. Shells, for example, wait for user
events (commands) and then invoke their handlers (usually programs).
Event driven programs often seem inside-out because their main loops
-are part of the event management library. Programs are usually bunches
-of event handlers and a tiny initialization stub. This reverses the
-roles of program and library: the library calls the program to perform
-tasks. While this may seem awkward, it is elegant and concise when
-properly applied.
+are part of the event management library. Programs are usually
+bunches of event handlers and a tiny initialization stub. This
+reverses the roles of program and library: the library calls the
+program to perform tasks. While this may seem awkward, it is elegant
+and concise when properly applied.
see: event, event handler, resource
-event fields
+=== event fields ===
-The elements of an event that describe it. They are passed as
+The elements of an event that describe it. They are passed as
parameters to each event's handler function.
The Kernel manages fields like the event's name, the session it was
-sent to, and the session that sent it. The session manages its own
+sent to, and the session that sent it. The session manages its own
fields, including its heap and the object or package the handler
belongs to.
@@ -181,16 +186,16 @@ Many events include other type specific fields.
see: dispatch, event, event handler parameters, heap, immediate event,
kernel, queued event, resource
-event handler
+=== event handler ===
Code that is called when an event is dispatched.
-Event handlers are atomic. Only one handler can run at a time in any
-given thread. Perl's threads are still experimental, so POE does not
-use them. For now, this means that a program can only run one event
+Event handlers are atomic. Only one handler can run at a time in any
+given thread. Perl's threads are still experimental, so POE does not
+use them. For now, this means that a program can only run one event
handler at a time.
-Event handlers receive their events as parameters. Part of each event
+Event handlers receive their events as parameters. Part of each event
includes its runtime context, so the same code can handle events in
several sessions without becoming confused.
@@ -200,129 +205,129 @@ created.
see: dispatch, event, event fields, event handler parameters, kernel,
nfa session, session, state, state machine, thread
-event handler parameters
+=== event handler parameters ===
-The parameters given to an event handler. These correspond to the
+The parameters given to an event handler. These correspond to the
event's different fields.
see: dispatch, event, event fields, heap, immediate event, queued
event, resource, runstate
-event loop
+=== event loop ===
-A program's main control loop. This loop contains an event queue, an
+A program's main control loop. This loop contains an event queue, an
event dispatcher, and one or more ways to create new events.
see: event queue, dispatch, main loop, resource, resource watcher
-event queue
+=== event queue ===
An ordered list of pending events, managed by POE's kernel on behalf
-of every session. It ensures that each event is dispatched in its
+of every session. It ensures that each event is dispatched in its
proper turn.
Immediate events are dispatched right away, bypassing the queue.
see: dispatch, event, event handler, immediate event, queued event
-event substrate
+=== event substrate ===
-A lower-level event loop that POE uses internally. Since it's
+A lower-level event loop that POE uses internally. Since it's
difficult to have multiple event loops in a single program, POE is
-written so it can use others instead of its own select() loop. This
-allows POE to support Tk, Gtk, IO::Poll, and Event. Adding support for
-a new event system is as easy (?) as writing a substrate that
+written so it can use others instead of its own select() loop. This
+allows POE to support Tk, Gtk, IO::Poll, and Event. Adding support
+for a new event system is as easy (?) as writing a substrate that
implements a small set of basic features.
see: event loop, event queue, main loop
-filter
+=== filter ===
A member of the Wheels I/O abstraction that translates data between
-raw streams and logical records. A filter's sole purpose is to hide
+raw streams and logical records. A filter's sole purpose is to hide
the specific guts of some low-level protocol.
-Filters are bidirectional. Their sending sides translate complete
-logical records into streams. Their receiving sides buffer streamed
+Filters are bidirectional. Their sending sides translate complete
+logical records into streams. Their receiving sides buffer streamed
data, framing it into logical records as complete ones arrive.
Filters buffer received data until it can be converted, while drivers
buffer data to be sent.
-Filters don't depend on any other part of POE. They can be used by
+Filters don't depend on any other part of POE. They can be used by
themselves in other programs.
see: driver, raw data, record, wheel, Sessions and Wheels
-heap
+=== heap ===
A session's unique storage area.
Every event handler receives a parameter that gives it access to the
-current session's heap. They may use this to store or access
+current session's heap. They may use this to store or access
persistent data between events.
see: dispatch, event fields, event handler parameters, runstate,
session
-immediate event
+=== immediate event ===
An event that is dispatched immediately, bypassing the kernel's queue.
Immediate events are mainly used to dispatch events that must be
-handled right away. I/O resource watchers are the most notable sources
-of immediate events. I/O resources must be serviced immediately,
-otherwise their watchers would generate streams of redundant events to
-signal their continued readiness.
+handled right away. I/O resource watchers are the most notable
+sources of immediate events. I/O resources must be serviced
+immediately, otherwise their watchers would generate streams of
+redundant events to signal their continued readiness.
Sessions that dispatch immediate events must wait for the handler to
-complete. This gives the caller access to a handler's return value,
+complete. This gives the caller access to a handler's return value,
which is sometimes useful.
-It can be tricky to mix immediate I/O events with queued ones. A
+It can be tricky to mix immediate I/O events with queued ones. A
convenient way to prevent I/O from generating responses out of turn is
-to always respond through queued events. Queuing the responses this
+to always respond through queued events. Queuing the responses this
way ensures that they arrive at clients in the same order they
occurred.
see: dispatch, event, queued event, time-critical resource, watcher
-I/O resource
+=== I/O resource ===
-A resource that performs I/O. A filehandle.
+A resource that performs I/O. A filehandle.
see: resource
-kernel
+=== kernel ===
POE's event queue, dispatcher, main loop, resource manager, and core
resource watcher library.
The kernel does just about everything, including taking care of many
-tedious little housekeeping tasks. The kernel spends most of its time
+tedious little housekeeping tasks. The kernel spends most of its time
dispatching events and reference couting resources.
see: dispatch, event, immediate event, nfa session, queued event,
resource, session
-main loop
+=== main loop ===
-A program's outermost control loop. The main loop usually contains a
+A program's outermost control loop. The main loop usually contains a
program's event dispatcher and resource watching code.
see: event loop, event queue, dispatch, resource, resource watcher
-nfa session
+=== nfa session ===
A session that runs a nondeterministic finite automaton, or NFA.
NFAs are state machines that doesn't necessarily know which states
-follow each other when they starts. Rather, they decide the next state
-to go into based on runtime conditions.