ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent/lib/AnyEvent/Impl/POE.pm
(Generate patch)

Comparing AnyEvent/lib/AnyEvent/Impl/POE.pm (file contents):
Revision 1.9 by root, Fri Apr 25 02:40:44 2008 UTC vs.
Revision 1.10 by root, Fri Apr 25 04:34:30 2008 UTC

… …
107 107
108=item Documentation Quality 108=item Documentation Quality
109 109
110At the time of this writing, POE was in its tenth year. Still, its 110At the time of this writing, POE was in its tenth year. Still, its
111documentation is extremely lacking, making it impossible to implement 111documentation is extremely lacking, making it impossible to implement
112stuff as trivial as AnyEvent watchers without havign to resort to 112stuff as trivial as AnyEvent watchers without having to resort to
113undocumented behaviour or features. 113undocumented behaviour or features.
114 114
115For example, the POE::Kernel manpage has nice occurances of the word TODO 115For example, the POE::Kernel manpage has nice occurances of the word TODO
116with an explanation of whats missing. Some other gems: 116with an explanation of whats missing. In general, the POE manpages are
117littered with comments like "section not yet written".
118
119Some other gems:
117 120
118 This allows many object methods to also be package methods. 121 This allows many object methods to also be package methods.
119 122
120This is nice, but since it doesn't document I<which> methods these are, 123This is nice, but since it doesn't document I<which> methods these are,
121this is utterly useless information. 124this is utterly useless information.
122 125
123 Terminal signals will kill sessions if they are not handled by a 126 Terminal signals will kill sessions if they are not handled by a
124 "sig_handled"() call. The OS signals that usually kill or dump a 127 "sig_handled"() call. The OS signals that usually kill or dump a
125 process are con‐ sidered terminal in POE, but they never trigger a 128 process are considered terminal in POE, but they never trigger a
126 coredump. These are: HUP, INT, QUIT and TERM. 129 coredump. These are: HUP, INT, QUIT and TERM.
127 130
128Although AnyEvent calls sig_handled, removing it has no apparent effects 131Although AnyEvent calls C<sig_handled>, removing it has no apparent
129on POE handling SIGINT. 132effects on POE handling SIGINT.
130 133
131 Furthermore, since the Kernel keeps track of everything sessions do, it 134 Furthermore, since the Kernel keeps track of everything sessions do, it
132 knows when a session has run out of tasks to perform. 135 knows when a session has run out of tasks to perform.
133 136
134This is impossible - how does the kernel now that a session is no longer 137This is impossible - how does the kernel now that a session is no longer
135watching for some (external) event (e.g. by some other session)? It 138watching for some (external) event (e.g. by some other session)? It
136cannot, and therefore this is wrong. 139cannot, and therefore this is wrong - but you would be hard pressed to
140find out how to work around this and tell the kernel manually about such
141events.
137 142
138It gets worse, though - the notion of "task" or "resource", although used 143It gets worse, though - the notion of "task" or "resource", although used
139throughout the documentation, is not defined in a usable way. For example, 144throughout the documentation, is not defined in a usable way. For example,
140waiting for a timeout is considered to be a task, waiting for a signal is 145waiting for a timeout is considered to be a task, waiting for a signal is
146not (a session that only waits for a signal is considered finished and
141not. The user is left guessing when waiting for an event counts as task 147gets removed). The user is left guessing when waiting for an event counts
142and when not. 148as task and when not.
143 149
144One could go on endlessly - ten years, no usable docs. 150One could go on endlessly - ten years, no usable documentation.
145 151
146It is likely that differences between documentation, or the one or two 152It is likely that differences between documentation, or the one or two
147things I had to guess, cause unanticipated problems with the backend. 153things I had to guess, cause unanticipated problems with this adaptor.
148 154
149=item Bad API 155=item Bad API
150 156
151The POE API is extremely inconsistent - sometimes you have to pass a 157The POE API is extremely inconsistent - sometimes you have to pass a
152session argument, sometimes it gets ignored, sometimes a session-specific 158session argument, sometimes it gets ignored, sometimes a session-specific
153method must not use a session argument. 159method must not use a session argument.
154 160
161Error handling is sub-standard as well: even for programming mistakes,
162POE does not C<croak> but, in most cases, just sets C<$!> or simply does
163nothing at all, leading to fragile programs.
164
155Sometimes registering a handler uses "eventname, parameter" (timeouts), 165Sometimes registering a handler uses the "eventname, parameter" ordering
156sometimes it is "parameter, eventname" (signals). There is little 166(timeouts), sometimes it is "parameter, eventname" (signals). There is
157consistency. 167little consistency overall.
158 168
159=back 169=back
160 170
161On the good side, AnyEvent allows you to write your modules in a 100% 171On the good side, AnyEvent allows you to write your modules in a 100%
162POE-compatible way (bug-for-bug compatible even), without forcing your 172POE-compatible way (bug-for-bug compatible even), without forcing your

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines