Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

holy crap. i'm committing to poed.... anyway, wrap the text in this f…

…ile to 72 chars and move the head3's to item blocks so older perls can read this properly
  • Loading branch information...
commit b7e776c64447ff4e634aa03bf9c1531413a26191 1 parent 1f6f97f
sungo sungo authored

Showing 1 changed file with 95 additions and 26 deletions. Show diff stats Hide diff stats

  1. +95 26 poeintro.pod
121 poeintro.pod
Source Rendered
@@ -18,7 +18,12 @@ $Date$
18 18
19 19 =head2 What is POE?
20 20
21   -POE is a giant ball of kinetic energy and Computer Science buzzwords wrapped in a very strange and wonderful culture. POE is a MUD engine gone awry into some sort of wacked out Disney land of event driven network niftiness. POE is that which keeps many minds from wandering the streets in search of branes to eat. Ok. None of that means anything to anyone. Maybe I should start on a much simpler level, eh?
  21 +POE is a giant ball of kinetic energy and Computer Science buzzwords
  22 +wrapped in a very strange and wonderful culture. POE is a MUD engine
  23 +gone awry into some sort of wacked out Disney land of event driven
  24 +network niftiness. POE is that which keeps many minds from wandering the
  25 +streets in search of branes to eat. Ok. None of that means anything to
  26 +anyone. Maybe I should start on a much simpler level, eh?
22 27
23 28 POE is:
24 29
@@ -38,25 +43,42 @@ Will most likely run on most annoying web hosting services out there.
38 43
39 44 =item * a pseudothreading application kernel
40 45
41   -Huh? The short version is that perl programs can pretend to be threaded on a non-threaded perl with POE. POE is essentially a cooperative task scheduler at heart. Tasks are bundles of event handlers that look a lot like state machines. Several of these carefully constructed state machines can be running all at once.
  46 +Huh? The short version is that perl programs can pretend to be threaded
  47 +on a non-threaded perl with POE. POE is essentially a cooperative task
  48 +scheduler at heart. Tasks are bundles of event handlers that look a lot
  49 +like state machines. Several of these carefully constructed state
  50 +machines can be running all at once.
42 51
43 52 =item * an event loop
44 53
45   -POE's task scheduler is basically an event loop. (We'll be talking about event-driven systems here in a bit.) Various event loops usually don't play nice with each other. POE, however, is designed to play nicely with such event loops as Event.pm, GTK, or Tk.
  54 +POE's task scheduler is basically an event loop. (We'll be talking about
  55 +event-driven systems here in a bit.) Various event loops usually don't
  56 +play nice with each other. POE, however, is designed to play nicely with
  57 +such event loops as Event.pm, GTK, or Tk.
46 58
47   -To quote the author of POE: I<POE's methods are designed from the user's standpoint. More people will be using them than writing them, so they should be a lot easier to use than implement. This should reduce the authors' workload over time, since they'll be using POE more than writing it.>
  59 +To quote the author of POE: I<POE's methods are designed from the user's
  60 +standpoint. More people will be using them than writing them, so they
  61 +should be a lot easier to use than implement. This should reduce the
  62 +authors' workload over time, since they'll be using POE more than
  63 +writing it.>
48 64
49 65 =item * a network application framework
50 66
51   -POE lends itself quite well to network applications. Some folks would say this is what it's best at.
  67 +POE lends itself quite well to network applications. Some folks would
  68 +say this is what it's best at.
52 69
53 70 =item * a singlethreaded application architecture
54 71
55   -POE can track state for procedural code. In single-tasking programs, there's no real requirement for states to return right away. State transitions act more like C<goto> here.
  72 +POE can track state for procedural code. In single-tasking programs,
  73 +there's no real requirement for states to return right away. State
  74 +transitions act more like C<goto> here.
56 75
57 76 =item * a framework for portable high-level components
58 77
59   -POE can be used as a framework for portable high-level components. Components may be event-driven, class hierarchies, or simple functions. Many such components already exist and more are in development every day.
  78 +POE can be used as a framework for portable high-level components.
  79 +Components may be event-driven, class hierarchies, or simple functions.
  80 +Many such components already exist and more are in development every
  81 +day.
60 82
61 83 =back
62 84
@@ -66,57 +88,104 @@ POE can be used as a framework for portable high-level components. Components ma
66 88
67 89 =item * ease of use
68 90
69   -POE is very easy to use once one understands the concepts behind the system. Its modularity and flexibility allow for code and concept reuse. This ease of use translates into ease of maintenence, a much sought after commodity.
  91 +POE is very easy to use once one understands the concepts behind the
  92 +system. Its modularity and flexibility allow for code and concept reuse.
  93 +This ease of use translates into ease of maintenence, a much sought
  94 +after commodity.
70 95
71 96 =item * portability
72 97
73   -POE runs almost everywhere on any decent perl. Perl 5.004_05 and up all run POE (tho earlier perl's may sacrifice some of newer features due to strangeness in that perl). POE runs on NT, believe it or not. There are even rumors of it running on Mac OS Classic. MAC OS X is also supported.
  98 +POE runs almost everywhere on any decent perl. Perl 5.004_05 and up all
  99 +run POE (tho earlier perl's may sacrifice some of newer features due to
  100 +strangeness in that perl). POE runs on NT, believe it or not. There are
  101 +even rumors of it running on Mac OS Classic. MAC OS X is also supported.
74 102
75 103 =item * rapid development
76 104
77   -Thanks to POE's ease of use, the concept-to-code cycle is very rapid. To make things even better, Richard Soderberg (coral) and Rocco Caputo (dngor) have been working on a system by which flow charts can be run as POE programs. Isn't that scary? The other really scary thing is how often pseudocode works well as a first pass POE program. Tiny states can be written to encapsulate algorithms and then tied together with a Session.
  105 +Thanks to POE's ease of use, the concept-to-code cycle is very rapid.
  106 +To make things even better, Richard Soderberg (coral) and Rocco Caputo
  107 +(dngor) have been working on a system by which flow charts can be run as
  108 +POE programs. Isn't that scary? The other really scary thing is how
  109 +often pseudocode works well as a first pass POE program. Tiny states
  110 +can be written to encapsulate algorithms and then tied together with a
  111 +Session.
78 112
79 113 =item * shininess
80 114
81   -POE won Best New Module at TPC3 in 1999. Mark Jason Dominus called POE I<the last really interesting Perl development> (speaking about the Perl5 universe). While not quite strewn across billboards, POE suffers from a huge and fanatical underground following, almost a revolution some days.
  115 +POE won Best New Module at TPC3 in 1999. Mark Jason Dominus called POE
  116 +I<the last really interesting Perl development> (speaking about the
  117 +Perl5 universe). While not quite strewn across billboards, POE suffers
  118 +from a huge and fanatical underground following, almost a revolution
  119 +some days.
82 120
83 121 =back
84 122
85 123 =head2 General Concepts
86 124
87   -POE is a completely new way of looking at perl for most folks. It destroys the minds of the feeble and empowers the minds of the great. There is a sense in which POE is like learning a new programming language. Say goodbye to Kansas, Dorothy, because here we go...
  125 +POE is a completely new way of looking at perl for most folks. It
  126 +destroys the minds of the feeble and empowers the minds of the great.
  127 +There is a sense in which POE is like learning a new programming
  128 +language. Say goodbye to Kansas, Dorothy, because here we go...
88 129
89   -=head3 Events
  130 +=over 4
  131 +
  132 +=item * Events
90 133
91   -POE is event driven. Wait. What does that mean? To draw a somewhat relevant analogy... For most geeks, life is event driven. Most of the day is spent waiting for something interesting to happen.
  134 +POE is event driven. Wait. What does that mean? To draw a somewhat
  135 +relevant analogy... For most geeks, life is event driven. Most of the
  136 +day is spent waiting for something interesting to happen.
92 137
93   -Ponder a friday evening. We're talking about a geek here so not much is going on. Just bad american tv. (is there any other kind of american tv?) Delivery Pizza arrives. This causes the geek to scramble for cash, pay the delivery man, and then hungrily devour pizza. When the pizza is gone, the geek resumes watching tv.
  138 +Ponder a friday evening. We're talking about a geek here so not much is
  139 +going on. Just bad american tv. (is there any other kind of american
  140 +tv?) Delivery Pizza arrives. This causes the geek to scramble for cash,
  141 +pay the delivery man, and then hungrily devour pizza. When the pizza is
  142 +gone, the geek resumes watching tv.
94 143
95   -The arrival of the pizza is an B<event>. This causes a Pizza Arrival B<state>, the collection of actions including paying for the pizza and eating it. When the Pizza Arrival state ends, the geek goes back to a passive wait state, waiting for the next event in his/her life.
  144 +The arrival of the pizza is an B<event>. This causes a Pizza Arrival
  145 +B<state>, the collection of actions including paying for the pizza and
  146 +eating it. When the Pizza Arrival state ends, the geek goes back to a
  147 +passive wait state, waiting for the next event in his/her life.
96 148
97   -POE spends most of its time waiting. Waiting for what? Well, for any number of things. Incoming socket connections, console input, and internal timers can all trigger events. POE::Wheel's also trigger events from various input sources.
  149 +POE spends most of its time waiting. Waiting for what? Well, for any
  150 +number of things. Incoming socket connections, console input, and
  151 +internal timers can all trigger events. POE::Wheel's also trigger
  152 +events from various input sources.
98 153
99   -=head3 States
  154 +=item * States
100 155
101   -States are a collection of actions which will be "fired" when an event happens. These can be customized for the given parameters of the event. For instance, it is not always appropriate to scream and run when the Pizza Delivery Person speaks. The Pizza Delivery Person may be an attractive member of the Appropriate Gender. In light of these parameters, an appropriate interface can be defined.
  156 +States are a collection of actions which will be "fired" when an event
  157 +happens. These can be customized for the given parameters of the event.
  158 +For instance, it is not always appropriate to scream and run when the
  159 +Pizza Delivery Person speaks. The Pizza Delivery Person may be an
  160 +attractive member of the Appropriate Gender. In light of these
  161 +parameters, an appropriate interface can be defined.
102 162
103   -POE states are plain ol' perl. Standard perl rules apply. Anything that can be in perl, can be done in a state.
  163 +POE states are plain ol' perl. Standard perl rules apply. Anything that
  164 +can be in perl, can be done in a state.
104 165
105   -=head3 Sessions
  166 +=item * Sessions
106 167
107   -A Session is a collection of event handlers that looks a lot like state machine. Several sessions can be running at one time. Each session is its own unique machine, though communication is possible between sessions.
  168 +A Session is a collection of event handlers that looks a lot like state
  169 +machine. Several sessions can be running at one time. Each session is
  170 +its own unique machine, though communication is possible between
  171 +sessions.
108 172
109   -=head3 The Heap
  173 +=item * The Heap
110 174
111   -Each session has a data storehouse called the C<heap>. The heap can be any data structure required. It is unique per session and persistent across events. This is a great place to store session data like tickets, user information, or whatever the program needs.
  175 +Each session has a data storehouse called the C<heap>. The heap can be
  176 +any data structure required. It is unique per session and persistent
  177 +across events. This is a great place to store session data like
  178 +tickets, user information, or whatever the program needs.
112 179
113 180
114 181
115 182 =head2 POErl (Syntax)
116 183
117   -Ok, now for the nitty gritty. This is a very high level introduction to POE syntax. Each of the following sections is tied to another man page which provides the super indepth view.
  184 +Ok, now for the nitty gritty. This is a very high level introduction to
  185 +POE syntax. Each of the following sections is tied to another man page
  186 +which provides the super indepth view.
118 187
119   -=head3 Session Creation (poesess)
  188 +=item * Session Creation (poesess)
120 189
121 190 POE::Session->create(
122 191 inline_states => {

0 comments on commit b7e776c

Please sign in to comment.
Something went wrong with that request. Please try again.