POE's Cookbook is a collection of illustrative examples for doing things (wonderful and mundane) with POE. It was started in the spirit of the [Perl Cookbook].

This cookbook is meant to be comprehensive, but it can't be without your help. Please add suggestions to the end, or feel free to create your own examples. If you wrote a component you'd like to see here, add an example.

Unless otherwise stated, the code in these recipes is distributed under the same terms as POE itself. POE, in turn, is distributed under the same terms as Perl. A copy of Perl's license is available in the README file that comes with its source.

Application/Job Servers

/Application Servers 2:
A simple application server based on POE::Component::IKC, and a client using its ClientLite library. ClientLite provides lightweight clients, such as CGI programs, access to powerful POE-based back-ends.
/Application Servers:
An application server and client. They interact using POE::Filter::Reference, which transparently serializes Perl data on the sending side and reconstitutes it at the receiver.
/Job Server:
A simple job server. It supports multiple clients running jobs simultaneously. Each job's output is sent back to its client. It's just shy of 100 lines, including whitespace and comments.
/Inter Kernel Communique:
A simple demonstration using POE::Component::IKC::Client to remotely call a Session published with POE::Component::IKC::Server and printing the result.


/Chat Server:
A very simple chat server. It implements a pattern where multiple TCP clients broadcast messages amongst themselves.
/DNS Lookups:
Using POE::Component::Client::DNS to resolve a large number of domains in parallel.
/Graceful Wheel Shutdown:
It's often necessary to shut down a wheel while it still has pending output. This recipe shows how that's done. It fixes the common symptom of programs that never send a final message.
/Pinging Multiple Hosts:
POE::Component::Client::Ping lets programs monitor the statuses of several hosts at once.
/TCP Clients:
How to write simple TCP clients that run simultaneously. This recipe includes a naive parallel service scanner. It will print the greeting banners of various daemons.
/TCP SSL Client:
How to write simple SSL TCP clients that run simultaneously. This recipe includes a naive parallel service scanner. It will print the greeting banners of various daemons.
/TCP Forwarding:
An odd sort of TCP bridge. Two servers listen on different ports. The clients of one server send information feeds, which are broadcast to the clients of the other server.
/TCP Port Redirection With Components:
A single-service TCP port redirector using POE::Component::Server- and Client::TCP.
/TCP Simple Client-Server with Filter::Reference:
A very very simple client server that uses POE::Component:Server::TCP and POE::Component::Client. The client passes an array containing two numbers and the server return the sum. All using the POE::Filter::Reference filter.
/TCP Port Redirection:
The classic TCP port redirector. It accepts client connections on some ports and bounces them to servers at other locations. It might make a serviceable if simplistic firewall hopper.
/TCP Servers:
Multiple examples of a simple line-based echo service. Examples are shown using high-, medium-, and low-level POE libraries.
/UDP Multicast Sockets:
Multicast sockets are just as easy as vanilla UDP, but with a little more setup.
/UDP Sockets:
POE doesn't provide medium- and high-level facilities for UDP sockets beacuse datagrams are much simpler to work with than connections. Here's a rot13 server and a client that echoes back whatever it receives.
/UNIX Clients:
This recipe uses POE::Wheel::SocketFactory and POE::Wheel::ReadLine to implement a UNIX socket client with local input editing. JamesCOU wrote it to work with the UNIX servers recipe elsewhere in this cookbook.
/UNIX Servers:
This recipe uses SocketFactory to create a UNIX socket server. The server simply echoes back whatever is sent to it.

IRC Programming

/IRC Logfile Tailing:
Tailing one or more logfiles into an IRC channel (with throttling)
/IRC Bot Debugging:
A note about tracing the effects of POE::Component::IRC commands.
/IRC Bot Disconnecting:
Shutting down an IRC bot can be quick and messy, or slow and graceful.
/IRC Bot Reconnecting:
The Internet tends to be flaky, especially near IRC servers. Reliable bots should accept this and work around it robustly. This recipe shows one way to reconnect when necessary.
/IRC Bots:
A very simple IRC bot written with POE::Component::IRC.
/IRC Plugins:
Some templates for creating POE::Component::IRC plugins.
/IRC A Simple Client:
A simple IRC client written using POE::Component::IRC and POE::Wheel::ReadLine

Process Management

/Child Component:
This example demonstrates usage of POE::Component::Child, a simplified interface for creating and managing child processes.
/Child Processes 2:
How to spawn a child process to perform an asynchronous or long-running task without blocking the rest of the main program.
/Child Processes 3:
How to manage a large number of long, slow tasks in child processes. It is a multi-process extension of /Child Processes 2. It also shows POE::Filter::Reference used without the rest of POE.
/Child Processes 4:
Another example of using POE::Filter::Reference in conjunction with POE::Wheel::Run.
/Child Processes:
A simple way to parse output from a full-screen program, and to assign complex macro functions to keystrokes. It uses POE::Wheel::Run and ptys.
/Child Processes Nested:
Sets up a child process using POE::Wheel::Run, sets up a second Kernel and Session inside and talks bi-directionally with the child using POE::Filter::Reference.

System Administration

Also see Process Management.

/Watching Logs:
How a single POE program can watch several log-like files extend. POE's FollowTail wheel acts like the "tail -f" utility, but it does not prevent a program from doing other things in the meantime.
/CVS Stress Testing:
Use POE to stress-test a CVS server for tuning.

System Interfaces

/Serial Ports:
A small line-based serial terminal.
/XBee Shell:
Paul Miller's XBee shell, reprinted from [his blog article] with permission.


/Asynchronous MySQL:
DBD::mysql has an asynchronous mode and exposes a file descriptor that POE can use to wait for results without blocking.
/Broadcasting Events:
Some designs require that an event be broadcast to several sessions. As usual, there is more than one way to do it.
/Combined Services:
We were bored and grafted the telnet chat server with a web server. The web interface shows a log of recent conversation in the telnet server. Both services run in the same process and thread, so sharing information between them is trivial. Both servers were implemented in under 120 lines of code.
/DBI Helper Processes:
Using POE::Component::DBIAgent to perform expensive queries in coprocesses.
/Distributing Events:
This recipe explains how to create dynamic events based on input. It's the POE equivalent of a "switch" statement of jump table. In this example, input for a pop3 daemon is turned into command events.
/Dynamic Loading:
billn describes his dynamic loader framework. He uses a small stub program that loads the rest of the system from a central database. The framework automatically deploys updates to running systems when changes are made in the database.
Event Handlers:
There are four major ways to define event handlers. These recipes show the same code written with /Anonymous Inline Subrefs, /Inline Subrefs, /Object Methods, and /Package Methods.
/Filters Stand Alone:
Yet another example illustrating the stand-alone use of POE::Filter classes. This feature allows thin clients to interact with thick POE services.
A simple method for turning long-running loops inside-out so they can multitask cooperatively.
/Multitasking Solutions:
Some interesting ways you can use POE to solve problems by multitasking.
/Neural Networks:
A cheezy, pointless neural network. While it's a fun example of the things POE can do, it wouldn't be practical to run large networks this way.
[/POE Preprocessor Tricks]?:
Using source code templates and substitutions to simplify code generation.
/Quantum Computing:
A travelling salesperson implementation that tests every possible solution in simulated constant time. This is another example that's more fun than practical.
/Recurring Alarms:
How to make alarms that periodically repeat, and why you might not want to use delay() to do it.
/State Validation:
How to make sure events will be handled. Typos are common in event names, and POE::Session just drops unknown events by default.
/Useful Things:
A collection of code bits that have proven useful to others in the past.
Waiting in procedural programs is often as easy as calling sleep(). Here's how to translate those delays into POE's delay() call.
/Creating Components an Intro:
As a noob to POE I could not find a lot of info regarding the creation of your own PoCo. This short tutorial shuld get you started.
MooseX::POE allows you to use Moose to define a POE Session using Object States

User Interfaces

/Console Input:
How to accept line-based console input using POE. Normally, one would use Term::ReadLine, but that blocks everything. Instead, this uses POE::Wheel::ReadLine.
/Gtk Interfaces:
POE supports different graphical interfaces. This recipe contains a very simple POE program with a Gtk interface.
/Gtk2 Interfaces:
POE also supports Gtk2. There are several recipes here.
/Music Player:
This recipe uses POE::Component::Player::Musicus to play any music file that has an XMMS plugin. It also uses POE::Wheel::Curses to provide a live full-terminal display.
/MPEG Player:
This recipe uses POE::Component::MPG123 to play mp3 files. It also uses POE::Wheel::Curses to provide a live full-terminal display.
/Tk Interfaces:
How to provide a Tk graphical interface to POE components and programs.


/CGI Requests:
POE's HTTP servers deal with HTTP::Request and HTTP::Response objects. Most people are familiar with CGI.pm instead. This recipe moves information from HTTP::Request to CGI.pm, and then from CGI.pm to HTTP::Response.
/Web Client:
Examples of simple web clients.
/Web Proxy:
A simple web proxy.
/Streaming Web Proxy:
A simple web proxy with streaming and transparent proxy support.
/Web Server With Components:
An even simpler web server, using POE::Component::Server::HTTP to handle virtually all of the HTTP mechanics.
/Web Server With Forking:
A pre-forking web server. Managing child processes makes this more complex than the others.
/Web Server:
A simple web server.
/SSL Web Server:
A simple SSL web server.
/Web Stream Server:
A simple web server that streams large content, such as multimedia.
/Web Sockets:
A simple streaming websocket client.


Here are some cookbook recipes we need, or that have been requested: