| … | |
… | |
| 196 | |
196 | |
| 197 | Replace the current C<on_eof> callback (see the C<on_eof> constructor argument). |
197 | Replace the current C<on_eof> callback (see the C<on_eof> constructor argument). |
| 198 | |
198 | |
| 199 | =cut |
199 | =cut |
| 200 | |
200 | |
| 201 | ############################################################################# |
|
|
| 202 | |
|
|
| 203 | sub on_eof { |
201 | sub on_eof { |
| 204 | $_[0]{on_eof} = $_[1]; |
202 | $_[0]{on_eof} = $_[1]; |
| 205 | } |
203 | } |
|
|
204 | |
|
|
205 | ############################################################################# |
|
|
206 | |
|
|
207 | =back |
|
|
208 | |
|
|
209 | =head2 WRITE QUEUE |
|
|
210 | |
|
|
211 | AnyEvent::Handle manages two queues per handle, one for writing and one |
|
|
212 | for reading. |
|
|
213 | |
|
|
214 | The write queue is very simple: you can add data to its end, and |
|
|
215 | AnyEvent::Handle will automatically try to get rid of it for you. |
|
|
216 | |
|
|
217 | When data could be writtena nd the write buffer is shorter then the low |
|
|
218 | water mark, the C<on_drain> callback will be invoked. |
|
|
219 | |
|
|
220 | =over 4 |
| 206 | |
221 | |
| 207 | =item $handle->on_drain ($cb) |
222 | =item $handle->on_drain ($cb) |
| 208 | |
223 | |
| 209 | Sets the C<on_drain> callback or clears it (see the description of |
224 | Sets the C<on_drain> callback or clears it (see the description of |
| 210 | C<on_drain> in the constructor). |
225 | C<on_drain> in the constructor). |
| … | |
… | |
| 257 | $cb->($self); |
272 | $cb->($self); |
| 258 | }; |
273 | }; |
| 259 | } |
274 | } |
| 260 | |
275 | |
| 261 | ############################################################################# |
276 | ############################################################################# |
|
|
277 | |
|
|
278 | =back |
|
|
279 | |
|
|
280 | =head2 READ QUEUE |
|
|
281 | |
|
|
282 | AnyEvent::Handle manages two queues per handle, one for writing and one |
|
|
283 | for reading. |
|
|
284 | |
|
|
285 | The read queue is more complex than the write queue. It can be used in two |
|
|
286 | ways, the "simple" way, using only C<on_read> and the "complex" way, using |
|
|
287 | a queue. |
|
|
288 | |
|
|
289 | In the simple case, you just install an C<on_read> callback and whenever |
|
|
290 | new data arrives, it will be called. You can then remove some data (if |
|
|
291 | enough is there) from the read buffer (C<< $handle->rbuf >>) if you want |
|
|
292 | or not. |
|
|
293 | |
|
|
294 | In the more complex case, you want to queue multiple callbacks. In this |
|
|
295 | case, AnyEvent::Handle will call the first queued callback each time new |
|
|
296 | data arrives and removes it when it has done its job (see C<push_read>, |
|
|
297 | below). |
|
|
298 | |
|
|
299 | This way you can, for example, push three line-reads, followed by reading |
|
|
300 | a chunk of data, and AnyEvent::Handle will execute them in order. |
|
|
301 | |
|
|
302 | Example 1: EPP protocol parser. EPP sends 4 byte length info, followed by |
|
|
303 | the specified number of bytes which give an XML datagram. |
|
|
304 | |
|
|
305 | # in the default state, expect some header bytes |
|
|
306 | $handle->on_read (sub { |
|
|
307 | # some data is here, now queue the length-header-read (4 octets) |
|
|
308 | shift->unshift_read_chunk (4, sub { |
|
|
309 | # header arrived, decode |
|
|
310 | my $len = unpack "N", $_[1]; |
|
|
311 | |
|
|
312 | # now read the payload |
|
|
313 | shift->unshift_read_chunk ($len, sub { |
|
|
314 | my $xml = $_[1]; |
|
|
315 | # handle xml |
|
|
316 | }); |
|
|
317 | }); |
|
|
318 | }); |
|
|
319 | |
|
|
320 | Example 2: Implement a client for a protocol that replies either with |
|
|
321 | "OK" and another line or "ERROR" for one request, and 64 bytes for the |
|
|
322 | second request. Due tot he availability of a full queue, we can just |
|
|
323 | pipeline sending both requests and manipulate the queue as necessary in |
|
|
324 | the callbacks: |
|
|
325 | |
|
|
326 | # request one |
|
|
327 | $handle->push_write ("request 1\015\012"); |
|
|
328 | |
|
|
329 | # we expect "ERROR" or "OK" as response, so push a line read |
|
|
330 | $handle->push_read_line (sub { |
|
|
331 | # if we got an "OK", we have to _prepend_ another line, |
|
|
332 | # so it will be read before the second request reads its 64 bytes |
|
|
333 | # which are already in the queue when this callback is called |
|
|
334 | # we don't do this in case we got an error |
|
|
335 | if ($_[1] eq "OK") { |
|
|
336 | $_[0]->unshift_read_line (sub { |
|
|
337 | my $response = $_[1]; |
|
|
338 | ... |
|
|
339 | }); |
|
|
340 | } |
|
|
341 | }); |
|
|
342 | |
|
|
343 | # request two |
|
|
344 | $handle->push_write ("request 2\015\012"); |
|
|
345 | |
|
|
346 | # simply read 64 bytes, always |
|
|
347 | $handle->push_read_chunk (64, sub { |
|
|
348 | my $response = $_[1]; |
|
|
349 | ... |
|
|
350 | }); |
|
|
351 | |
|
|
352 | =over 4 |
| 262 | |
353 | |
| 263 | sub _drain_rbuf { |
354 | sub _drain_rbuf { |
| 264 | my ($self) = @_; |
355 | my ($self) = @_; |
| 265 | |
356 | |
| 266 | return if exists $self->{in_drain}; |
357 | return if exists $self->{in_drain}; |
