Skip to content
Browse files

Make a new README.

  • Loading branch information...
1 parent a5a773c commit e94b67c6a0289acdb8a8b4d922cfbf275de396ec @rcaputo committed Mar 26, 2011
Showing with 933 additions and 894 deletions.
  1. +29 −894 README
  2. +904 −0 README.old
View
923 README
@@ -1,904 +1,39 @@
-vim: ts=2 sw=2 noexpandtab
+This is a long-term project to write a comprehensive, book-like manual
+for POE. It's inspired in part by similar manuals for projects such
+as Moose::Manual. Some files are part of an attempt to write the "POE
+Book" that people have asked for.
-To Do:
+If cash motivates you, the Enlightened Perl Organisation has offered a
+£450 grant to complete this documentation. For more information, see
+http://www.enlightenedperl.org/grants/grants001.html
- Develop a rough outline with the order we want to present things.
+ Devin Austin was working on this grant, but he seems to have got
+ busy with other things. Please contact the project if you're
+ interested in taking over the grant work.
-Topics:
+To help, this repository recently aggregated external POE
+documentation, proto-documentation ideas, and links to additional
+resources.
-Intro To POE Braindump.
------------------------
+The project's scope and roadmap is evolving in TODO.otl, which is a
+plain-text outline that may be viewed and changed in any editor.
-1. Who?
- Who uses POE now?
- Yahoo!
- poe.perl.org lists others
- (Need to update poe.perl.org's list... it's been several months.)
- Who should be using POE?
- Everyone! :)
- A lot of the "what" details cover this.
- Who built POE?
- Rocco Caputo
- Plus a dozen or two named contributors.
- Plus dozens of contributors only named in the changelogs.
- (Need to pull their names out and list them.)
- (Also see Acme::CPANAuthors::POE.)
- Who are the community?
- #poe on irc.perl.org, freenode, efnet, oftc
- poe@perl.org mailing list
- Interwoven throughout the Perl community.
- http://www.flickr.com/photos/franck_/3877930818/sizes/l/
- etc.
+ The outline is actually in a format supported by Vim Outline.
+ http://sites.google.com/site/vimoutlinerinfo/ version 0.3.4 or later
+ might help. However, the project is looking for an outline format
+ supported by more editors. Let us know if such a thing exists.
-2. What?
- What kinds of things does POE do?
- Co-processing.
- Cooperative, event driven co-processing using sessions rather than threads.
- Workers.
- Dispatch work on multiple CPUs or machines, using a central controller.
- Multi- and simultaneous processing.
- Cooperative, if I/O wait is your bottleneck.
- Differences between POE and other forms of concurrency.
- POE multiplexes I/O and related things.
- Single processor.
- Single memory space.
- Can coordinate multiple processes and threads.
- Kind of erlang-like in that regard.
- Not as tightly bound to the idea as erlang.
- What can I do with POE?
- Network clients and servers.
- Watchdogs.
- Process managers.
- Device interfaces.
- Process simulations.
- (Page through CPAN POE components & the cookbook for ideas.)
- What should/shouldn't be done with POE?
- If I/O wait is your bottleneck, then POE will help a lot.
- If I/O bandwidth is your bottleneck, only hardware will help.
- Or altering your protocols to be more compact.
- Consider compressing data on the wire.
- Although this burns more CPU, and could make CPU your bottleneck.
- If CPU is your bottleneck, then POE won't help so much.
- But it can be used to coordinate multiple threads or processes.
- If disk wait is your bottleneck, POE could help.
- Although POE might help even more with IO::AIO.
- Hardware is another option.
- Distribute the work across many drives, a la Hadoop.
- POE can help coordinate this as well.
- If RAM is your bottleneck...
- Add more!
- Shrink your data structures.
- Delegate to disk, although this may make disk your bottleneck.
+Licensing
-3. Where?
- Where should I put POE?
- The usual cpan -i stuff.
- Relocatable.
- Untar it anywhere, and begin testing it there.
- Great for regression testing and evaluation.
- Does it play well with others, or does it want to run alone?
- 13 event loops supported as of this writing.
- run_one_timeslice() allows it to be driven by external loops.
- Examples of stand-alone POE apps.
- (Aren't they all?)
- Using POE to delegate tasks that need long-running processes and workers.
+ A quick `grep -A4 -i copyright *` shows that most materials have no
+ explicit copyright. The materials that are copyright, are done so
+ from 2001-2011 under "the same terms as Perl itself".
-4. When?
- When should I use POE?
- (See "what" section.)
- When do I start looking at my app and saying "this needs POE!"?
- When it's waiting for external input a lot.
- When it needs to wait for external input from more than one source.
- When it needs to manage multiple timers.
- When it needs concurrency but multiple CPUs aren't really an issue.
- (Those are simplistic, but they're a start.)
- When does an app need POE?
- When it starts doing processing on its own that could be better and more efficiently handled by a dedicated process or app?
- (Kinda redundant question, but maybe I don't understand the nuances?)
-
-5. Why?
- Why should I use POE?
- What advantages does it give me over Coro, Erlang, etc.?
- Speed?
- Size?
- Maturity?
- Good architecture?
-
-6. How?
- How do I actually use POE?
- (See most of the rest of this document.)
- Examples of the aforementioned points, with scenarios.
-
-===== Tutorial =====
-
-Intro to POE.
-
- What it is (1-2 paragraphs).
- - practical applications in web
- 0. show how POE provides the event driven/actors paradigm. Try to provide that "aha" push.
- 1. a web app (shined up paste app),
- 2. a bot
- 3. an app interfacing with a Catalyst App (ThumbIt perhaps?),
-
- What it does (1-2 paragraphs).
- - what its role would be in these situations
- 1. perform as a web framework
- 2. a scalable and multi-process bot for doing x y and z (probably most useful would be an infobot for irc, or a web scraper)
- 3. a job queue and worker application to delegate image resizing to
-
-Hello, World 1
-
- Count to 10 (Hello, world!)
- Explain what's going on.
- Use all verbose, explicit constructs.
- Explain that this is longer than it needs to be.
-
-
-Hello, World 2
-
- Replace the verbose bits with shortcuts.
- Explain where things went, and why we did it that way.
-
-Hello, Worlds
-
- Count to 10 concurrently.
- Multiple sessions.
- Explain how POE's concurrency works.
-
-...
-
-Gradually build upon these with 'branches' involving aforementioned scenarios
-
-===== OLDER BRAINDUMP FOLLOW =====
-
-Basic concepts.
-
- Initial example and notes:
- anatomy of a program - hello.perl
- looping - looping.perl
-
- Ideas:
- different session types - inline handlers
- different session types - object handlers
- different session types - class handlers
-
- wrapping sessions in object interfaces
-
- event handlers in more detail (event parameters)
- Kernel and session as concepts
-
- alarms
- multitasking within a session
- multitasking with multiple sessions
- message passing between sessions
- complex request and response between sessions
- managing request state while performing large tasks
- replacing IO::Select (note 1)
- handling signals
- sessions
- the kernel
- different types of event handler (inline, object, class/package)
- anonymous vs. named inline handlers
- repeating alarms
- debugging - TRACE_FOO and ASSERT_FOO
- parent/child session interaction
- ... what else?
-
-User interfaces:
-
- Ideas:
- Wheel::ReadLine
- Wheel::Curses
- Wheel::ReadWrite on STDIN/STDOUT
- Term::Visual
- Tk
- Gtk
- Gtk2
- ... what else?
-
-Wheels, filters, drivers.
-
- Ideas:
- wheels in general
- drivers in general
- filters in general
- how they fit together
- graceful POE::Wheel::ReadWrite shutdown
- shutdown flag
- creating a "flushed" state on the fly
- directing FlushedEvent to a shutdown handler
- complex flow control in POE::Wheel::ReadWrite
- using filters outside POE
- using drivers outside POE
-
- POE::Wheel::SocketFactory (note 1)
- POE::Wheel::ReadWrite (note 1)
- POE::Wheel::ReadLine
- POE::Wheel::FollowTail
- POE::Wheel::Curses
- POE::Wheel::ListenAccept
- POE::Wheel::Run - one process per session
- POE::Wheel::Run - many processes per session
- POE::Wheel::SocketFactory
- POE::Filter::Block
- POE::Filter::Grep
- POE::Filter::HTTPD
- POE::Filter::Line
- POE::Filter::Map
- POE::Filter::RecordBlock
- POE::Filter::Reference
- POE::Filter::Stackable
- POE::Filter::Stream
- POE::Driver::SysRW
- ... what else?
-
-High-level networking:
-
- Ideas:
- UDP sockets
- UNIX sockets
- FIFOs
-
-IRC programming:
-
- Ideas:
- Logging to IRC (Randal Schwartz)
- Bot debugging techniques
- Graceful bot shutdown
- Graceful bot reconnecting
- Simple IRC bots
- IRC plugins
- Letting POE::Component::IRC track state
-
-IPC
-
- Ideas:
- poe server, poe client, low-level via POE::Filter::Reference
- poe server, poe client, POE::Component::IKC
- poe server, light client, via POE::Filter::Reference
- poe server, light client, POE::Component::IKC's light client
-
-Process management:
-
- Ideas:
- POE::Wheel::Run
- POE::Component::Generic
- Managing multiple forked workers (dynamic)
- Managing multiple forked workers (static pool)
- Managig child processes that require ttys
-
-System administration:
-
- Ideas:
- POE::Component::Client::Ping
- POE::Component::SNMP?
- Gathering banners from multiple hosts/services.
- Following logs - POE::Wheel::FollowTail
- Following snort logs - POE::Filter::Snort
-
-Extending event flow control:
-
- Ideas:
- Broadcast groups
- Combining services (telnet chat + web service) ???
- Dynamically creating events from input
- Changing events emitted by wheels
- POE::NFA
- Changing event handlers on the fly
-
-Database interaction:
-
- Ideas:
- DBIAgent
- EasyDBI
- etc.
-
-Device interfaces:
-
- Ideas:
- Serial ports
-
-Networking tools:
-
- Ideas:
- TCP forwarder: client <-> this <-> server (components)
- TCP forwarder: client <-> this <-> server (wheels)
- client1 <-> server1 <-events-> server2 <-> client2
-
-Multiuser servers:
-
- Ideas:
- Chat server
- Chat client with Term::Visual
-
-Asynchronous DNS:
-
- Ideas:
- POE::Component::Client::DNS - log file resolving
-
-Fanciful applicotions
-
- Ideas:
- Neural networks
- Quantum computing
- Filter::Template tricks
- Curses based media player
-
-Web programming:
-
- Ideas:
- Web client (POE::Component::Client::HTTP)
- Simple web server with POE::Filter::HTTPD
- Complex web server with POE::Component::Server::HTTP
- Complex web server with POE::Component::Server::SimpleHTTP
- Complex web server with POE::Component::Server::HTTPServer?
- A pre-forking web server
- Web server for large media files
- A web proxy with streaming support
- Handling CGI requests
-
------
-
-Notes:
-
-1. Some articles will be adapted from the "evolution of a server"
-tutorial. The idea is to break the entire tutorial into separate
-examples and discussions, then re-create the original tutorial by
-stringing them together.
-
------
-
-Random notes pulled from various places. Not anywhere near complete,
-but it's a lot of ideas to extract and place in the above article
-buckets.
-
-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.
-
----
-
-POE - A Perl Object Environment, or Perl Objects for Events.
-
-Introduction - What POE Is
-
- Perl Object Environment
- Originally the core of a larger project.
- Originally about 1/10 its current size.
- A lot of conveniences added over time.
- At its heart, POE is an event loop.
-
-Event loops
-
- Watchers and handlers.
- Queue and dispatcher.
-
-POE's event loop
-
- Kernel (event queue, watcher methods, watchers, dispatcher).
- Session (dispatcher adapter, task concept, handlers).
-
-POE's events
-
- Just lists of data, provided by various places.
- Kernel includes itself, event name, sender.
- Sessions include themselves, their private data spaces, and other things.
- Watchers include their own fields.
- Programs also include data.
-
-POE's Kernel
-
- POE::Queue::Array (enqueue, dequeue)
- POE::Kernel (post, select_read, alarm_set)
- POE::Loop::Select (others)
- POE::Resource::Filehandles
- POE::Resource::Alarms
-
- POE::Session (invoke)
-
-POE's Sessions
-
- invoke()
- handler lookup
- handler invocation
- handlers call Kernel methods to affect new changes
-
-Sessions as "threads".
-
- Sessions are instances of POE::Session (or subclasses).
- Each session's stuff (data, watchers, events, etc.) is kept apart from stuff of the others.
- POE::Kernel knows which sessions call it.
-
- These rules codify the boundaries between session contexts. POE is
- still just Perl, though. There are no shotguns to enforce those
- boundaries, but the idea that they're there is strong enough to keep
- most developers from crossing them.
-
-Sessions as interfaces.
-
- Sessions can act as message-based interfaces.
- Calls and return values can be propagated by events.
- POE::Component::SubWrapper.
-
-Sessions as adapters.
-
- Session classes customize event dispatch.
- POE::NFA
- POE::Session::MessageBased
- POE::Session::MultiDispatch
- etc.
-
-Event handlers (syntax, examples).
-
- Inline (syntax, examples)
- Object methods (method name = event name, and method != event)
- Class methods (same as objects, but use class names)
- Can mix and match styles, but the last definition wins any conflict.
-
-Hello, World! program.
-
-Event handler parameters.
-
- Event fields are members of @_.
- POE::Session exports constants for field positions within @_.
- KERNEL, SESSION, HEAP, ARG0
- etc.
- ARG0 is always towards the end of @_.
- my @stuff = @\_\[ARG0..$#_\].
-
-Enqueuing events.
-
- yield()
- post()
- call()
-
- Destinations are very flexible.
- call() is an immediate call, bypassing the queue. Returns values.
-
-Hello, World! with events passed around.
-
-Tod do is to be.
-
- Sessions stop when they run out of work to do.
- Events count as work.
- Most event watchers do, as well.
- Signals also count, although they didn't until recently.
- Aliases are special, and will be covered later.
-
-Cooperation
-
- Each do_count() iteration is triggered by a "count" event.
- The "count" events take turns in the queue.
- A session can juggle multiple events. Only one is handled at a time.
- POE::Kernel can juggle multiple sessions.
-
-Aliases.
-
- Allow sessions to be addressed by symbolic names.
- Each may only refer to a single session.
- Although a session can go by many aliases.
- Are useful for message passing.
- Only count as work when something can generate events.
-
-Alias examples.
-
- alias_set()
- alias_remove()
- alias_resolve()
- alias_list()
-
-Using aliases.
-
- Example and discussion.
-
-Parents and children.
-
- A session is the parent of the sessions it creates.
- POE::Kernel is the ancestor of all sessions.
- Child sessions count as work for their parents.
- POE notifies sessions when their parents or children come or go.
-
-Parent notification
-
- _parent tells a session its parent session has changed.
- Parameters: ARG0 = old parent; ARG1 = new parent
-
-Child notification
-
- _child tells a session that a child's state has changed.
- It's not related to SIGCHLD, although it performs a similar purpose.
- Parameters: ARG0 is the state transition; ARG1 is the child session
- reference; ARG2 is the child's _start or _stop value.
-
-Worker manager example
-
-Parent and child events matrix
-
- EVENT - ARG0 - ARG1 - ARG2
- _parent - old parent - new parent - N/A
- _child - "gain" or "lose" - child session - _stop return value
- _child - "create" - child session - _start return value
-
-Watching the clock
-
- Timers are event watchers.
- They watch for a certain wall clock time.
- They watch for elapsed time.
- They do not repeat.
- POE's queue is kept in due-time order.
- Events created with yield() or post() are due for "now".
-
-Kinds of timers
-
- Two ways to watch time:
- Absolute timers (alarms)
- Relative timers (delays)
-
- Two ways to track the watcher:
- Event name
- Unique IDs
-
- All just ways to manipulate future events.
-
-Named timers
- Keyed by event name
- Only one timer per name (alarm(), delay()), per session.
- Unless you add extras (alarm_add(), delay_add()).
- Clearing by name clears ALL timers with the same name.
- Within the current session, of course.
-
-Identified timers
- Can be set, cleared, or adjusted by ID.
- Duplicate timer names are not a problem.
- Unless you use a named timer function.
-
-Uncooperative timer example
- (uses sleep)
-
-Cooperative timer example
- (uses delay)
-
- delay() posts the event, which is scheduled to be delivered in the
- future. It returns right away. The event will linger in the queue
- until it becomes due.
-
-Timer methods matrix
-
- ... alarms - delays
- named - (functions) - (functions)
- identified - (functions) - (functions)
- either/both - alarm_remove_all() - N/A
-
-I/O watchers
-
- Select-like
- Input, output, and exceptional (out-of-band) input
- Start, stop, pause, and resume.
- They condition filehandles.
- They do NOT perform I/O.
-
-I/O watchers example(s)
-
-I/O methods matrix
- etc.
-
-Signal watchers
-
- Watch for OS signals or internal ones.
- Internal signals are created by the program itself.
- No processes are killed in their making.
- Keep sessions alive.
- Safe perl signals not needed with SIGCHLD.
-
-Signal types
-
- All signals are not created equal.
- Benign: Information only.
- IO, WINCH, INFO, CHLD, PIPE, etc.
- Terminal. Stop sessions unless handled.
- QUIT, INT, TERM, HUP, "IDLE"
- Non-maskable. Always stop sessions.
- "ZOMBIE", "UIDESTROY"
-
-Signal dispatch
-
- Signals sent to a session are also dispatched to its children
- If any of those sessions handles a signal, then it's handled for the
- whole tree.
- Signaling POE::Kernel signals the entire program.
-
-Signal watcher example.
-
-Signal watcher method matrix.
-
-Signal event arguments.
-
-Kernel shutdown.
-
- Kernel runs until all sessions stop.
- It sends everyone a SIGIDLE, if only aliased sessions remait.
- It sends SIGZOMBIE if SIGIDLE didn't help.
- run() returns when the last session stops.
-
-Wheels
-
- Objects that encapsulate common watcher and event handler patterns.
- They are not managed by POE.
- They create and destroy watchers and handlers.
-
-Filters and drivers
-
- Filters translate data formats for wheels
- But they don't understand high-level protocols
- POE::Filter::Line is assumed.
- Drivers perform file I/O.
- But there's only one: POE::Driver::SysRW
- POE::Driver::SysRW is the default
-
-Session and wheels interaction
-
-Wheel interaction with drivers and filters
-
-POE::Wheel::FollowTail
-
- Watches the end of a file
- Doesn't block the rest of the program
- Can be used to watch many log files
- May be used with AIM/Yahoo/ICQ/IRC components for reporting
-
-Wheel::FollowTail example
-
-POE::Wheel::Run
-
- Runs programs and interacts with them via standard I/O
- Can use pipes, pseudo terminals, or a mix
- Can change the child's user, priority
- Can close the child's STDIN
- Can send signals to the child program
-
-POE::Wheel::Run example
-
-POE::Wheel::SocketFactory
-
- Creates sockets. That's it. Does NOT read or write.
- Client mode: builds one connection.
- Server mode: Listens, and builds one socket per connection.
- Supports most of the Berkeley sockets API.
- Can create UNIX sockets.
- Supports UDP, but why bother?
-
-POE::Wheel::SocketFactory example
-
-Throttling connections
-
- pause_accept()
- resume_accept()
-
-Session initialization
-
- create() args parameter
- create() hash parameter
- closures
-
-POE::Wheel::ReadWrite
-
- Performs buffered, non-blocking I/O on streams
- Does NOT create filehandles
- Not really appropriate for datagram I/O
- Although people have used it that way
-
-POE::Wheel::ReadWrite example
-
-Separate I/O for input and output
-
- Can use separate InputHandle and OutputHandle
- Instead of just Handle
- Can use separate InputFilter and OutputFilter
- Instead of just Filter
-
-Water marks
-
- Tell when a driver's put() buffer fills up.
- Indicates an imminent emptiness in the put() buffer.
- put() returns true if the driver is overfull.
- LowMark and LowEvent indicate when it's ok to send again.
- FlushedEvent tells when output buffer is empty.
-
-Water marks example
-
-Changing watermarks on the fly
-
- set_high_mark()
- set_low_mark()
-
-FlushedEvent example
-
-Other flow control
-
- pause_input()
- resume_input()
- shutdown_input()
- shutdown_output()
-
-Querying buffers
-
- get_driver_out_octets()
- get_driver_out_messages()
-
-Switching filters on the fly
-
- Changes data formats in mid-stream.
- For example, HTTP streams
- For example, SMTP sessions
-
-Switching filters example
-
-Switching events
-
- Changes the events a wheel generates
- Re-routes wheel information to new code
- Useful for stateful things, like protocols
-
-Switching events example
-
-POE guts---
-
-POE::Loop
-POE::Queue
-POE::Resource
-POE::API
-POE::NFA in detail
-Dozens of components on the CPAN
-
-Writing a filter
-
- Variable-length records, length-prepended
- Filters are plain Perl objects.
- Stream and processed data passed by list reference.
- Filter switching requires access to buffered stream data
- use bytes;
-
-Examples of new() and put()
-Examples of get_one_start() and get_pending()
-Examples of get_one()
-
-Postbacks
-
- Create callbacks that post POE events
- Created for graphical toolkits
- Keep their sessions alive until destroyed
-
- Callbacks (like postbacks, but synchronous)
-
-Graphical toolkits
-
- POE detects other event loops and uses them internally.
- Tk, Gtk, Gtk2, Event, IO::Poll, WxWindows, possibly others.
- Can support anything that provides I/O watchers and timeouts.
-
-Tk + POE
-
- Use Tk before using POE::Kernel
- POE APIs work the same
- POE::Loop::Tk uses native Tk facilities
- Postbacks translate Tk callbacks into events
- POE exports Tk's main window as \$poe_main_window.
-
- Once written, an interface-neutral POE component is portable to
- various event loops with no modification. Your application can be
- ported to graphical or textual user interfaces by adding new
- interface code.
-
- Tk's event loop doesn't run without at least one widget. POE
- creates a main window for the application and uses it as the handle
- into Tk's event loop. The window is exported so developers can use
- it.
-
-Tk + POE example
-
-Session IDs
-
- Unique session identifiers
- Originally created for component developers
- \$session->ID (numeric)
- \$kernel->ID (non-numeric uuid)
- \$kernel->ID_id_to_session(session id)
- \$kernel->ID_session_to_id(session ref)
-
-Extra references
-
- One session can keep itself or another active arbitrarily.
- Often used with message passing.
- Also used in postbacks and callbacks.
-
-Extra references examples
-
-Extra references API matrix
-
-Self-modification
-
- Add, remove, or replace handlers at runtime
- First implemented for Wheel classes
- Named events let this work smoothly
-
- POE::Wheel classes use these facilities to add their handlers to
- sessions that create them, then later remove those handlers at
- DESTROY time.
-
- Yes, POE::Wheel classes build upon the basic POE libraries covered
- here. It's easy to create new ones, or replace them entirely with
- something you might like better. Whatever you create will coexist
- with wheels because they all use the same low-level libraries.
-
-Self-modification example
-
-Self-modification API matrix
-
- Explain state() name.
-
-Session options
-
- Options change a session's behavior.
- Set at create time with "options" parameter.
- Set at runtime with \$session->option()
- Watch events with the "trace" option.
- Catch duplicate states with "debug".
- Catch unknown events with "default".
-
-Library helpers
-
- \$poe_kernel - exported by POE::Kernel
- get_active_session()
- \$session->get_heap()
-
-Components
-
- High level modules, often nearly complete programs
- Facades hiding one or more sessions
- There's more than one way to interface it.
-
-TCP components
-
- Abstract common TCP patterns
- Use callbacks instead of status events
- Touch \$_[HEAP] (usually forbidden)
- Client and Server work mostly the same.
- Use and expose wheels.
-
-POE::Component::Client::TCP example
-
-POE::Component::Server::TCP example
-
-(... worthy components here ...)
+ For compatibility, all future contributions must be made under the
+ For compatibility, all new contributions must also be made under the
+ same terms as Perl 5. The final product will be distributed with
+ Dist::Zilla, using 'license = Perl_5'.
+Thank you for reading. I hope you'll help.
+-- Rocco Caputo
View
904 README.old
@@ -0,0 +1,904 @@
+vim: ts=2 sw=2 noexpandtab
+
+To Do:
+
+ Develop a rough outline with the order we want to present things.
+
+Topics:
+
+Intro To POE Braindump.
+-----------------------
+
+1. Who?
+ Who uses POE now?
+ Yahoo!
+ poe.perl.org lists others
+ (Need to update poe.perl.org's list... it's been several months.)
+ Who should be using POE?
+ Everyone! :)
+ A lot of the "what" details cover this.
+ Who built POE?
+ Rocco Caputo
+ Plus a dozen or two named contributors.
+ Plus dozens of contributors only named in the changelogs.
+ (Need to pull their names out and list them.)
+ (Also see Acme::CPANAuthors::POE.)
+ Who are the community?
+ #poe on irc.perl.org, freenode, efnet, oftc
+ poe@perl.org mailing list
+ Interwoven throughout the Perl community.
+ http://www.flickr.com/photos/franck_/3877930818/sizes/l/
+ etc.
+
+2. What?
+ What kinds of things does POE do?
+ Co-processing.
+ Cooperative, event driven co-processing using sessions rather than threads.
+ Workers.
+ Dispatch work on multiple CPUs or machines, using a central controller.
+ Multi- and simultaneous processing.
+ Cooperative, if I/O wait is your bottleneck.
+ Differences between POE and other forms of concurrency.
+ POE multiplexes I/O and related things.
+ Single processor.
+ Single memory space.
+ Can coordinate multiple processes and threads.
+ Kind of erlang-like in that regard.
+ Not as tightly bound to the idea as erlang.
+ What can I do with POE?
+ Network clients and servers.
+ Watchdogs.
+ Process managers.
+ Device interfaces.
+ Process simulations.
+ (Page through CPAN POE components & the cookbook for ideas.)
+ What should/shouldn't be done with POE?
+ If I/O wait is your bottleneck, then POE will help a lot.
+ If I/O bandwidth is your bottleneck, only hardware will help.
+ Or altering your protocols to be more compact.
+ Consider compressing data on the wire.
+ Although this burns more CPU, and could make CPU your bottleneck.
+ If CPU is your bottleneck, then POE won't help so much.
+ But it can be used to coordinate multiple threads or processes.
+ If disk wait is your bottleneck, POE could help.
+ Although POE might help even more with IO::AIO.
+ Hardware is another option.
+ Distribute the work across many drives, a la Hadoop.
+ POE can help coordinate this as well.
+ If RAM is your bottleneck...
+ Add more!
+ Shrink your data structures.
+ Delegate to disk, although this may make disk your bottleneck.
+
+3. Where?
+ Where should I put POE?
+ The usual cpan -i stuff.
+ Relocatable.
+ Untar it anywhere, and begin testing it there.
+ Great for regression testing and evaluation.
+ Does it play well with others, or does it want to run alone?
+ 13 event loops supported as of this writing.
+ run_one_timeslice() allows it to be driven by external loops.
+ Examples of stand-alone POE apps.
+ (Aren't they all?)
+ Using POE to delegate tasks that need long-running processes and workers.
+
+4. When?
+ When should I use POE?
+ (See "what" section.)
+ When do I start looking at my app and saying "this needs POE!"?
+ When it's waiting for external input a lot.
+ When it needs to wait for external input from more than one source.
+ When it needs to manage multiple timers.
+ When it needs concurrency but multiple CPUs aren't really an issue.
+ (Those are simplistic, but they're a start.)
+ When does an app need POE?
+ When it starts doing processing on its own that could be better and more efficiently handled by a dedicated process or app?
+ (Kinda redundant question, but maybe I don't understand the nuances?)
+
+5. Why?
+ Why should I use POE?
+ What advantages does it give me over Coro, Erlang, etc.?
+ Speed?
+ Size?
+ Maturity?
+ Good architecture?
+
+6. How?
+ How do I actually use POE?
+ (See most of the rest of this document.)
+ Examples of the aforementioned points, with scenarios.
+
+===== Tutorial =====
+
+Intro to POE.
+
+ What it is (1-2 paragraphs).
+ - practical applications in web
+ 0. show how POE provides the event driven/actors paradigm. Try to provide that "aha" push.
+ 1. a web app (shined up paste app),
+ 2. a bot
+ 3. an app interfacing with a Catalyst App (ThumbIt perhaps?),
+
+ What it does (1-2 paragraphs).
+ - what its role would be in these situations
+ 1. perform as a web framework
+ 2. a scalable and multi-process bot for doing x y and z (probably most useful would be an infobot for irc, or a web scraper)
+ 3. a job queue and worker application to delegate image resizing to
+
+Hello, World 1
+
+ Count to 10 (Hello, world!)
+ Explain what's going on.
+ Use all verbose, explicit constructs.
+ Explain that this is longer than it needs to be.
+
+
+Hello, World 2
+
+ Replace the verbose bits with shortcuts.
+ Explain where things went, and why we did it that way.
+
+Hello, Worlds
+
+ Count to 10 concurrently.
+ Multiple sessions.
+ Explain how POE's concurrency works.
+
+...
+
+Gradually build upon these with 'branches' involving aforementioned scenarios
+
+===== OLDER BRAINDUMP FOLLOW =====
+
+Basic concepts.
+
+ Initial example and notes:
+ anatomy of a program - hello.perl
+ looping - looping.perl
+
+ Ideas:
+ different session types - inline handlers
+ different session types - object handlers
+ different session types - class handlers
+
+ wrapping sessions in object interfaces
+
+ event handlers in more detail (event parameters)
+ Kernel and session as concepts
+
+ alarms
+ multitasking within a session
+ multitasking with multiple sessions
+ message passing between sessions
+ complex request and response between sessions
+ managing request state while performing large tasks
+ replacing IO::Select (note 1)
+ handling signals
+ sessions
+ the kernel
+ different types of event handler (inline, object, class/package)
+ anonymous vs. named inline handlers
+ repeating alarms
+ debugging - TRACE_FOO and ASSERT_FOO
+ parent/child session interaction
+ ... what else?
+
+User interfaces:
+
+ Ideas:
+ Wheel::ReadLine
+ Wheel::Curses
+ Wheel::ReadWrite on STDIN/STDOUT
+ Term::Visual
+ Tk
+ Gtk
+ Gtk2
+ ... what else?
+
+Wheels, filters, drivers.
+
+ Ideas:
+ wheels in general
+ drivers in general
+ filters in general
+ how they fit together
+ graceful POE::Wheel::ReadWrite shutdown
+ shutdown flag
+ creating a "flushed" state on the fly
+ directing FlushedEvent to a shutdown handler
+ complex flow control in POE::Wheel::ReadWrite
+ using filters outside POE
+ using drivers outside POE
+
+ POE::Wheel::SocketFactory (note 1)
+ POE::Wheel::ReadWrite (note 1)
+ POE::Wheel::ReadLine
+ POE::Wheel::FollowTail
+ POE::Wheel::Curses
+ POE::Wheel::ListenAccept
+ POE::Wheel::Run - one process per session
+ POE::Wheel::Run - many processes per session
+ POE::Wheel::SocketFactory
+ POE::Filter::Block
+ POE::Filter::Grep
+ POE::Filter::HTTPD
+ POE::Filter::Line
+ POE::Filter::Map
+ POE::Filter::RecordBlock
+ POE::Filter::Reference
+ POE::Filter::Stackable
+ POE::Filter::Stream
+ POE::Driver::SysRW
+ ... what else?
+
+High-level networking:
+
+ Ideas:
+ UDP sockets
+ UNIX sockets
+ FIFOs
+
+IRC programming:
+
+ Ideas:
+ Logging to IRC (Randal Schwartz)
+ Bot debugging techniques
+ Graceful bot shutdown
+ Graceful bot reconnecting
+ Simple IRC bots
+ IRC plugins
+ Letting POE::Component::IRC track state
+
+IPC
+
+ Ideas:
+ poe server, poe client, low-level via POE::Filter::Reference
+ poe server, poe client, POE::Component::IKC
+ poe server, light client, via POE::Filter::Reference
+ poe server, light client, POE::Component::IKC's light client
+
+Process management:
+
+ Ideas:
+ POE::Wheel::Run
+ POE::Component::Generic
+ Managing multiple forked workers (dynamic)
+ Managing multiple forked workers (static pool)
+ Managig child processes that require ttys
+
+System administration:
+
+ Ideas:
+ POE::Component::Client::Ping
+ POE::Component::SNMP?
+ Gathering banners from multiple hosts/services.
+ Following logs - POE::Wheel::FollowTail
+ Following snort logs - POE::Filter::Snort
+
+Extending event flow control:
+
+ Ideas:
+ Broadcast groups
+ Combining services (telnet chat + web service) ???
+ Dynamically creating events from input
+ Changing events emitted by wheels
+ POE::NFA
+ Changing event handlers on the fly
+
+Database interaction:
+
+ Ideas:
+ DBIAgent
+ EasyDBI
+ etc.
+
+Device interfaces:
+
+ Ideas:
+ Serial ports
+
+Networking tools:
+
+ Ideas:
+ TCP forwarder: client <-> this <-> server (components)
+ TCP forwarder: client <-> this <-> server (wheels)
+ client1 <-> server1 <-events-> server2 <-> client2
+
+Multiuser servers:
+
+ Ideas:
+ Chat server
+ Chat client with Term::Visual
+
+Asynchronous DNS:
+
+ Ideas:
+ POE::Component::Client::DNS - log file resolving
+
+Fanciful applicotions
+
+ Ideas:
+ Neural networks
+ Quantum computing
+ Filter::Template tricks
+ Curses based media player
+
+Web programming:
+
+ Ideas:
+ Web client (POE::Component::Client::HTTP)
+ Simple web server with POE::Filter::HTTPD
+ Complex web server with POE::Component::Server::HTTP
+ Complex web server with POE::Component::Server::SimpleHTTP
+ Complex web server with POE::Component::Server::HTTPServer?
+ A pre-forking web server
+ Web server for large media files
+ A web proxy with streaming support
+ Handling CGI requests
+
+-----
+
+Notes:
+
+1. Some articles will be adapted from the "evolution of a server"
+tutorial. The idea is to break the entire tutorial into separate
+examples and discussions, then re-create the original tutorial by
+stringing them together.
+
+-----
+
+Random notes pulled from various places. Not anywhere near complete,
+but it's a lot of ideas to extract and place in the above article
+buckets.
+
+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.
+
+---
+
+POE - A Perl Object Environment, or Perl Objects for Events.
+
+Introduction - What POE Is
+
+ Perl Object Environment
+ Originally the core of a larger project.
+ Originally about 1/10 its current size.
+ A lot of conveniences added over time.
+ At its heart, POE is an event loop.
+
+Event loops
+
+ Watchers and handlers.
+ Queue and dispatcher.
+
+POE's event loop
+
+ Kernel (event queue, watcher methods, watchers, dispatcher).
+ Session (dispatcher adapter, task concept, handlers).
+
+POE's events
+
+ Just lists of data, provided by various places.
+ Kernel includes itself, event name, sender.
+ Sessions include themselves, their private data spaces, and other things.
+ Watchers include their own fields.
+ Programs also include data.
+
+POE's Kernel
+
+ POE::Queue::Array (enqueue, dequeue)
+ POE::Kernel (post, select_read, alarm_set)
+ POE::Loop::Select (others)
+ POE::Resource::Filehandles
+ POE::Resource::Alarms
+
+ POE::Session (invoke)
+
+POE's Sessions
+
+ invoke()
+ handler lookup
+ handler invocation
+ handlers call Kernel methods to affect new changes
+
+Sessions as "threads".
+
+ Sessions are instances of POE::Session (or subclasses).
+ Each session's stuff (data, watchers, events, etc.) is kept apart from stuff of the others.
+ POE::Kernel knows which sessions call it.
+
+ These rules codify the boundaries between session contexts. POE is
+ still just Perl, though. There are no shotguns to enforce those
+ boundaries, but the idea that they're there is strong enough to keep
+ most developers from crossing them.
+
+Sessions as interfaces.
+
+ Sessions can act as message-based interfaces.
+ Calls and return values can be propagated by events.
+ POE::Component::SubWrapper.
+
+Sessions as adapters.
+
+ Session classes customize event dispatch.
+ POE::NFA
+ POE::Session::MessageBased
+ POE::Session::MultiDispatch
+ etc.
+
+Event handlers (syntax, examples).
+
+ Inline (syntax, examples)
+ Object methods (method name = event name, and method != event)
+ Class methods (same as objects, but use class names)
+ Can mix and match styles, but the last definition wins any conflict.
+
+Hello, World! program.
+
+Event handler parameters.
+
+ Event fields are members of @_.
+ POE::Session exports constants for field positions within @_.
+ KERNEL, SESSION, HEAP, ARG0
+ etc.
+ ARG0 is always towards the end of @_.
+ my @stuff = @\_\[ARG0..$#_\].
+
+Enqueuing events.
+
+ yield()
+ post()
+ call()
+
+ Destinations are very flexible.
+ call() is an immediate call, bypassing the queue. Returns values.
+
+Hello, World! with events passed around.
+
+Tod do is to be.
+
+ Sessions stop when they run out of work to do.
+ Events count as work.
+ Most event watchers do, as well.
+ Signals also count, although they didn't until recently.
+ Aliases are special, and will be covered later.
+
+Cooperation
+
+ Each do_count() iteration is triggered by a "count" event.
+ The "count" events take turns in the queue.
+ A session can juggle multiple events. Only one is handled at a time.
+ POE::Kernel can juggle multiple sessions.
+
+Aliases.
+
+ Allow sessions to be addressed by symbolic names.
+ Each may only refer to a single session.
+ Although a session can go by many aliases.
+ Are useful for message passing.
+ Only count as work when something can generate events.
+
+Alias examples.
+
+ alias_set()
+ alias_remove()
+ alias_resolve()
+ alias_list()
+
+Using aliases.
+
+ Example and discussion.
+
+Parents and children.
+
+ A session is the parent of the sessions it creates.
+ POE::Kernel is the ancestor of all sessions.
+ Child sessions count as work for their parents.
+ POE notifies sessions when their parents or children come or go.
+
+Parent notification
+
+ _parent tells a session its parent session has changed.
+ Parameters: ARG0 = old parent; ARG1 = new parent
+
+Child notification
+
+ _child tells a session that a child's state has changed.
+ It's not related to SIGCHLD, although it performs a similar purpose.
+ Parameters: ARG0 is the state transition; ARG1 is the child session
+ reference; ARG2 is the child's _start or _stop value.
+
+Worker manager example
+
+Parent and child events matrix
+
+ EVENT - ARG0 - ARG1 - ARG2
+ _parent - old parent - new parent - N/A
+ _child - "gain" or "lose" - child session - _stop return value
+ _child - "create" - child session - _start return value
+
+Watching the clock
+
+ Timers are event watchers.
+ They watch for a certain wall clock time.
+ They watch for elapsed time.
+ They do not repeat.
+ POE's queue is kept in due-time order.
+ Events created with yield() or post() are due for "now".
+
+Kinds of timers
+
+ Two ways to watch time:
+ Absolute timers (alarms)
+ Relative timers (delays)
+
+ Two ways to track the watcher:
+ Event name
+ Unique IDs
+
+ All just ways to manipulate future events.
+
+Named timers
+ Keyed by event name
+ Only one timer per name (alarm(), delay()), per session.
+ Unless you add extras (alarm_add(), delay_add()).
+ Clearing by name clears ALL timers with the same name.
+ Within the current session, of course.
+
+Identified timers
+ Can be set, cleared, or adjusted by ID.
+ Duplicate timer names are not a problem.
+ Unless you use a named timer function.
+
+Uncooperative timer example
+ (uses sleep)
+
+Cooperative timer example
+ (uses delay)
+
+ delay() posts the event, which is scheduled to be delivered in the
+ future. It returns right away. The event will linger in the queue
+ until it becomes due.
+
+Timer methods matrix
+
+ ... alarms - delays
+ named - (functions) - (functions)
+ identified - (functions) - (functions)
+ either/both - alarm_remove_all() - N/A
+
+I/O watchers
+
+ Select-like
+ Input, output, and exceptional (out-of-band) input
+ Start, stop, pause, and resume.
+ They condition filehandles.
+ They do NOT perform I/O.
+
+I/O watchers example(s)
+
+I/O methods matrix
+ etc.
+
+Signal watchers
+
+ Watch for OS signals or internal ones.
+ Internal signals are created by the program itself.
+ No processes are killed in their making.
+ Keep sessions alive.
+ Safe perl signals not needed with SIGCHLD.
+
+Signal types
+
+ All signals are not created equal.
+ Benign: Information only.
+ IO, WINCH, INFO, CHLD, PIPE, etc.
+ Terminal. Stop sessions unless handled.
+ QUIT, INT, TERM, HUP, "IDLE"
+ Non-maskable. Always stop sessions.
+ "ZOMBIE", "UIDESTROY"
+
+Signal dispatch
+
+ Signals sent to a session are also dispatched to its children
+ If any of those sessions handles a signal, then it's handled for the
+ whole tree.
+ Signaling POE::Kernel signals the entire program.
+
+Signal watcher example.
+
+Signal watcher method matrix.
+
+Signal event arguments.
+
+Kernel shutdown.
+
+ Kernel runs until all sessions stop.
+ It sends everyone a SIGIDLE, if only aliased sessions remait.
+ It sends SIGZOMBIE if SIGIDLE didn't help.
+ run() returns when the last session stops.
+
+Wheels
+
+ Objects that encapsulate common watcher and event handler patterns.
+ They are not managed by POE.
+ They create and destroy watchers and handlers.
+
+Filters and drivers
+
+ Filters translate data formats for wheels
+ But they don't understand high-level protocols
+ POE::Filter::Line is assumed.
+ Drivers perform file I/O.
+ But there's only one: POE::Driver::SysRW
+ POE::Driver::SysRW is the default
+
+Session and wheels interaction
+
+Wheel interaction with drivers and filters
+
+POE::Wheel::FollowTail
+
+ Watches the end of a file
+ Doesn't block the rest of the program
+ Can be used to watch many log files
+ May be used with AIM/Yahoo/ICQ/IRC components for reporting
+
+Wheel::FollowTail example
+
+POE::Wheel::Run
+
+ Runs programs and interacts with them via standard I/O
+ Can use pipes, pseudo terminals, or a mix
+ Can change the child's user, priority
+ Can close the child's STDIN
+ Can send signals to the child program
+
+POE::Wheel::Run example
+
+POE::Wheel::SocketFactory
+
+ Creates sockets. That's it. Does NOT read or write.
+ Client mode: builds one connection.
+ Server mode: Listens, and builds one socket per connection.
+ Supports most of the Berkeley sockets API.
+ Can create UNIX sockets.
+ Supports UDP, but why bother?
+
+POE::Wheel::SocketFactory example
+
+Throttling connections
+
+ pause_accept()
+ resume_accept()
+
+Session initialization
+
+ create() args parameter
+ create() hash parameter
+ closures
+
+POE::Wheel::ReadWrite
+
+ Performs buffered, non-blocking I/O on streams
+ Does NOT create filehandles
+ Not really appropriate for datagram I/O
+ Although people have used it that way
+
+POE::Wheel::ReadWrite example
+
+Separate I/O for input and output
+
+ Can use separate InputHandle and OutputHandle
+ Instead of just Handle
+ Can use separate InputFilter and OutputFilter
+ Instead of just Filter
+
+Water marks
+
+ Tell when a driver's put() buffer fills up.
+ Indicates an imminent emptiness in the put() buffer.
+ put() returns true if the driver is overfull.
+ LowMark and LowEvent indicate when it's ok to send again.
+ FlushedEvent tells when output buffer is empty.
+
+Water marks example
+
+Changing watermarks on the fly
+
+ set_high_mark()
+ set_low_mark()
+
+FlushedEvent example
+
+Other flow control
+
+ pause_input()
+ resume_input()
+ shutdown_input()
+ shutdown_output()
+
+Querying buffers
+
+ get_driver_out_octets()
+ get_driver_out_messages()
+
+Switching filters on the fly
+
+ Changes data formats in mid-stream.
+ For example, HTTP streams
+ For example, SMTP sessions
+
+Switching filters example
+
+Switching events
+
+ Changes the events a wheel generates
+ Re-routes wheel information to new code
+ Useful for stateful things, like protocols
+
+Switching events example
+
+POE guts---
+
+POE::Loop
+POE::Queue
+POE::Resource
+POE::API
+POE::NFA in detail
+Dozens of components on the CPAN
+
+Writing a filter
+
+ Variable-length records, length-prepended
+ Filters are plain Perl objects.
+ Stream and processed data passed by list reference.
+ Filter switching requires access to buffered stream data
+ use bytes;
+
+Examples of new() and put()
+Examples of get_one_start() and get_pending()
+Examples of get_one()
+
+Postbacks
+
+ Create callbacks that post POE events
+ Created for graphical toolkits
+ Keep their sessions alive until destroyed
+
+ Callbacks (like postbacks, but synchronous)
+
+Graphical toolkits
+
+ POE detects other event loops and uses them internally.
+ Tk, Gtk, Gtk2, Event, IO::Poll, WxWindows, possibly others.
+ Can support anything that provides I/O watchers and timeouts.
+
+Tk + POE
+
+ Use Tk before using POE::Kernel
+ POE APIs work the same
+ POE::Loop::Tk uses native Tk facilities
+ Postbacks translate Tk callbacks into events
+ POE exports Tk's main window as \$poe_main_window.
+
+ Once written, an interface-neutral POE component is portable to
+ various event loops with no modification. Your application can be
+ ported to graphical or textual user interfaces by adding new
+ interface code.
+
+ Tk's event loop doesn't run without at least one widget. POE
+ creates a main window for the application and uses it as the handle
+ into Tk's event loop. The window is exported so developers can use
+ it.
+
+Tk + POE example
+
+Session IDs
+
+ Unique session identifiers
+ Originally created for component developers
+ \$session->ID (numeric)
+ \$kernel->ID (non-numeric uuid)
+ \$kernel->ID_id_to_session(session id)
+ \$kernel->ID_session_to_id(session ref)
+
+Extra references
+
+ One session can keep itself or another active arbitrarily.
+ Often used with message passing.
+ Also used in postbacks and callbacks.
+
+Extra references examples
+
+Extra references API matrix
+
+Self-modification
+
+ Add, remove, or replace handlers at runtime
+ First implemented for Wheel classes
+ Named events let this work smoothly
+
+ POE::Wheel classes use these facilities to add their handlers to
+ sessions that create them, then later remove those handlers at
+ DESTROY time.
+
+ Yes, POE::Wheel classes build upon the basic POE libraries covered
+ here. It's easy to create new ones, or replace them entirely with
+ something you might like better. Whatever you create will coexist
+ with wheels because they all use the same low-level libraries.
+
+Self-modification example
+
+Self-modification API matrix
+
+ Explain state() name.
+
+Session options
+
+ Options change a session's behavior.
+ Set at create time with "options" parameter.
+ Set at runtime with \$session->option()
+ Watch events with the "trace" option.
+ Catch duplicate states with "debug".
+ Catch unknown events with "default".
+
+Library helpers
+
+ \$poe_kernel - exported by POE::Kernel
+ get_active_session()
+ \$session->get_heap()
+
+Components
+
+ High level modules, often nearly complete programs
+ Facades hiding one or more sessions
+ There's more than one way to interface it.
+
+TCP components
+
+ Abstract common TCP patterns
+ Use callbacks instead of status events
+ Touch \$_[HEAP] (usually forbidden)
+ Client and Server work mostly the same.
+ Use and expose wheels.
+
+POE::Component::Client::TCP example
+
+POE::Component::Server::TCP example
+
+(... worthy components here ...)
+
+

0 comments on commit e94b67c

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