POE::Wheel(3pm)

1POE::Wheel(3)         User Contributed Perl Documentation        POE::Wheel(3)
2
3
4

NAME

6       POE::Wheel - high-level protocol logic
7

SYNOPSIS

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

DESCRIPTION

13       Wheels are bundles of event handlers (states) which perform common
14       tasks.  Wheel::FollowTail, for example, contains I/O handlers for
15       watching a file as it grows and reading the new information when it
16       appears.
17
18       Unlike Components, Wheels do not stand alone.  Each wheel must be cre‐
19       ated by a session, and each belongs to their parent session until it's
20       destroyed.
21

COMMON PUBLIC WHEEL METHODS

23       These methods are the generic Wheel interface, and every filter must
24       implement them.
25
26       new LOTS_OF_STUFF
27         new() creates a new wheel, returning the wheels reference.  The new
28         wheel will continue to run for as long as it exists.  Every wheel has
29         a different purpose and requires different parameters, so
30         LOTS_OF_STUFF will vary from one to the next.
31
32       DESTROY
33         Perl calls DESTROY when the wheel's last reference is relinquished.
34         This triggers the wheel's destruction, which stops the wheel and
35         releases whatever resources it was managing.
36
37       event TYPE => EVENT_NAME, ...
38         event() changes the events that a wheel will emit.  Its parameters
39         are pairs of event TYPEs and the EVENT_NAMEs to emit when each type
40         of event occurs.
41
42         Event TYPEs differ for each wheel, and their manpages discuss them in
43         greater detail.  EVENT_NAMEs may be undef, in which case a wheel will
44         stop emitting an event for that TYPE.
45
46         This example changes the events to emit on new input and when output
47         is flushed.  It stops the wheel from emitting events when errors
48         occur.
49
50           $wheel->event( InputEvent   => 'new_input_event',
51                          ErrorEvent   => undef,
52                          FlushedEvent => 'new_flushed_event',
53                        );
54

I/O WHEEL COMMON METHODS

56       These methods are common to I/O wheels.  Some I/O wheels are read-only
57       and will not have a put() method.
58
59       put LIST
60         put() sends a LIST of one or more records to the wheel for transmit‐
61         ting.  Each thing in the LIST is serialized by the wheel's Filter,
62         and then buffered in the wheel's Driver until it can be flushed to
63         its filehandle.
64

STATIC FUNCTIONS

66       These functions keep global information about all wheels.  They should
67       be called as normal functions:
68
69         &POE::Wheel::function( ... );
70
71       allocate_wheel_id
72         This is not a class method.  Call it as: POE::Wheel::allo‐
73         cate_wheel_id().
74
75         allocate_wheel_id() allocates a unique identifier for a wheel.
76         Wheels pass these identifiers back to sessions in their events so
77         that sessions with several wheels can match events back to other
78         information.
79
80         POE::Wheel keeps track of allocated IDs to avoid collisions.  It's
81         important to free an ID when it's not in use, or they will consume
82         memory unnecessarily.
83
84       free_wheel_id WHEEL_ID
85         This is not a class method.  Call it as:
86         POE::Wheel::free_wheel_id($id).
87
88         Deallocates a wheel identifier so it may be reused later.  This often
89         is called from a wheel's destructor.
90

BUGS

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

AUTHORS & COPYRIGHTS

99       Please see POE for more information about authors and contributors.
100
101
102
103perl v5.8.8                       2006-09-01                     POE::Wheel(3)