NAME

POE::Wheel - high-level protocol logic

SYNOPSIS

  $wheel = POE::Wheel::Something->new( ... );
  $wheel->put($some_logical_data_chunks);

DESCRIPTION

Wheels are bundles of event handlers (states) which perform common tasks. Wheel::FollowTail, for example, contains I/O handlers for watching a file as it grows and reading the new information when it appears.

Unlike Components, Wheels do not stand alone. Each wheel must be created by a session, and each belongs to their parent session until it's destroyed.

COMMON PUBLIC WHEEL METHODS

These methods are the generic Wheel interface, and every filter must implement them.

new LOTS_OF_STUFF

new() creates a new wheel, returning the wheels reference. The new wheel will continue to run for as long as it exists. Every wheel has a different purpose and requires different parameters, so LOTS_OF_STUFF will vary from one to the next.

DESTROY

Perl calls DESTROY when the wheel's last reference is relinquished. This triggers the wheel's destruction, which stops the wheel and releases whatever resources it was managing.

event TYPE => EVENT_NAME, ...

event() changes the events that a wheel will emit. Its parameters are pairs of event TYPEs and the EVENT_NAMEs to emit when each type of event occurs.

Event TYPEs differ for each wheel, and their manpages discuss them in greater detail. EVENT_NAMEs may be undef, in which case a wheel will stop emitting an event for that TYPE.

This example changes the events to emit on new input and when output is flushed. It stops the wheel from emitting events when errors occur.

  $wheel->event( InputEvent   => 'new_input_event',
                 ErrorEvent   => undef,
                 FlushedEvent => 'new_flushed_event',
               );

I/O WHEEL COMMON METHODS

These methods are common to I/O wheels. Some I/O wheels are read-only and will not have a put() method.

put LIST: put() sends a LIST of one or more records to the wheel for transmitting. Each thing in the LIST is serialized by the wheel's Filter, and then buffered in the wheel's Driver until it can be flushed to its filehandle.

STATIC FUNCTIONS

These functions keep global information about all wheels. They should be called as normal functions:

  &POE::Wheel::function( ... );

allocate_wheel_id: This is not a class method. Call it as: POE::Wheel::allocate_wheel_id().; allocate_wheel_id() allocates a unique identifier for a wheel. Wheels pass these identifiers back to sessions in their events so that sessions with several wheels can match events back to other information.; POE::Wheel keeps track of allocated IDs to avoid collisions. It's important to free an ID when it's not in use, or they will consume memory unnecessarily.
free_wheel_id WHEEL_ID: This is not a class method. Call it as: POE::Wheel::free_wheel_id($id).; Deallocates a wheel identifier so it may be reused later. This often is called from a wheel's destructor.

BUGS

It would be nice if wheels were more like proper Unix streams.

AUTHORS & COPYRIGHTS

Please see POE for more information about authors and contributors.

POE::Wheel - high-level protocol logic