Debian Codegraph @

README

raw
1 NAME
2
3 IO::Stream - ease non-blocking I/O streams based on EV
4
5 VERSION
6
7 This document describes IO::Stream version v2.0.3
8
9 SYNOPSIS
10
11 use EV;
12 use IO::Stream;
13
14 IO::Stream->new({
15 host => 'google.com',
16 port => 80,
17 cb => \&client,
18 wait_for => SENT|EOF,
19 in_buf_limit=> 102400,
20 out_buf => "GET / HTTP/1.0\nHost: google.com\n\n",
21 });
22
23 $EV::DIED = sub { warn $@; EV::unloop };
24 EV::loop;
25
26 sub client {
27 my ($io, $e, $err) = @_;
28 if ($err) {
29 $io->close();
30 die $err;
31 }
32 if ($e & SENT) {
33 print "request sent, waiting for reply...\n";
34 }
35 if ($e & EOF) {
36 print "server reply:\n", $io->{in_buf};
37 $io->close();
38 EV::unloop; # ALL DONE
39 }
40 }
41
42 DESCRIPTION
43
44 Non-blocking event-based low-level I/O is hard to get right. Code
45 usually error-prone and complex... and it very similar in all
46 applications. Things become much worse when you need to alter I/O
47 stream in some way - use proxies, encryption, SSL, etc.
48
49 This module designed to give user ability to work with I/O streams on
50 higher level, using input/output buffers (just scalars) and high-level
51 events like CONNECTED, SENT or EOF. As same time it doesn't hide
52 low-level things, and user still able to work on low-level without any
53 limitations.
54
55 PLUGINS
56
57 Architecture of this module make it ease to write plugins, which will
58 alter I/O stream in any way - route it through proxies, encrypt, log,
59 etc.
60
61 Here are few available plugins, you may find more on CPAN:
62 IO::Stream::Crypt::RC4, IO::Stream::Proxy::HTTPS,
63 IO::Stream::MatrixSSL::Client, IO::Stream::MatrixSSL::Server.
64
65 If you interested in writing own plugin, check source for "skeleton"
66 plugins: IO::Stream::Noop and IO::Stream::NoopAlias.
67
68 EXPORTS
69
70 This modules doesn't export any functions/methods/variables, but it
71 exports a lot of constants. There two groups of constants: events and
72 errors (which can be imported using tags ':Event' and ':Error'). By
73 default all constants are exported.
74
75 Events:
76
77 RESOLVED CONNECTED IN OUT EOF SENT
78
79 Errors:
80
81 EINBUFLIMIT
82 ETORESOLVE ETOCONNECT ETOWRITE
83 EDNS EDNSNXDOMAIN EDNSNODATA
84 EREQINBUFLIMIT EREQINEOF
85
86 Errors are similar to $! - they're dualvars, having both textual and
87 numeric values.
88
89 NOTE: Since v2.0.0 ETORESOLVE, EDNSNXDOMAIN and EDNSNODATA are not used
90 anymore (EDNS is used instead), but they're still exported for
91 compatibility.
92
93 OVERVIEW
94
95 You can create IO::Stream object using any "stream" fh (file, TTY, UNIX
96 socket, TCP socket, pipe, FIFO). Or, if you need TCP socket, you can
97 create IO::Stream object using host+port instead of fh (in this case
98 IO::Stream will do non-blocking host resolving, create TCP socket and
99 do non-blocking connect).
100
101 After you created IO::Stream object, it will handle read/write on this
102 fh, and deliver only high-level events you asked for into your
103 callback, where you will be able to operate with in/out buffers instead
104 of doing sysread()/syswrite() manually.
105
106 There no limitations on what you can do with fh after you've created
107 IO::Stream object - you can even do sysread()/syswrite() (but there no
108 reasons for you to do this anymore).
109
110 IMPORTANT! When you want to close this fh, you MUST use $io->close()
111 method for closing fh instead of doing close($fh). This is because
112 IO::Stream doesn't require from you to keep object returned by new(),
113 and without call to $io->close() IO::Stream object will continue to
114 exists and may receive/generate some events, which is not what you
115 expect after closing fh. Also, if you keep object returned by
116 IO::Stream->new() somewhere in your variables, you should either undef
117 all such variables after you called $io->close(), or you should use
118 Scalar::Util::weaken() on these variables after storing IO::Stream
119 object. (The same is applicable for all plugin objects too.)
120
121 EVENTS
122
123 RESOLVED
124
125 If you created IO::Stream object using {host}+{port} instead of {fh},
126 this event will be generated after resolving {host}. Resolved IP
127 address will be stored in {ip}.
128
129 CONNECTED
130
131 If you created IO::Stream object using {host}+{port} instead of {fh},
132 this event will be generated after connecting socket to {ip}:{port}.
133
134 IN
135
136 Generated after each successful read. IO::Stream may execute several
137 sysread() at once before generating IN event for optimization. Read
138 data will be stored in {in_buf}, and {in_bytes} counter will be
139 incremented by amount of bytes read.
140
141 EOF
142
143 Generated only ONCE when EOF reached (sysread() return 0). Also will
144 set {is_eof} to true.
145
146 OUT
147
148 Generated when some data from {out_buf} was written. Written bytes
149 either removed from {out_buf} or just increment {out_pos} by amount
150 of bytes written (see documentation about these fields below for more
151 details). Also increment {out_bytes} counter by amount of bytes
152 written.
153
154 Here 'written' may be somewhat virtual, while {out_buf}/{out_pos}
155 changes, the real data still can be in plugin buffers (if you use
156 plugins) and real syswrite() may not be called yet. To detect when
157 all data is really written you should use SENT event, not OUT.
158
159 SENT
160
161 Generated when all data from {out_buf} was written. It's usual and
162 safe to call $io->close() on SENT event.
163
164 TIMEOUTS
165
166 IO::Stream has 30-second timeouts for connect and write, to timeout DNS
167 resolve it use default AnyEvent::DNS timeout. If you need to timeout
168 other operations, you have to create own timers using EV::timer().
169
170 Current version doesn't allow you to change these timeouts.
171
172 SERVER
173
174 If you need to run TCP/UNIX-server socket, then you should handle that
175 socket manually. But you can create IO::Stream object for accept()'ed
176 socket:
177
178 my ($host, $port) = ('0.0.0.0', 1234);
179 socket my $srv_sock, AF_INET, SOCK_STREAM, 0;
180 setsockopt $srv_sock, SOL_SOCKET, SO_REUSEADDR, 1;
181 bind $srv_sock, sockaddr_in($port, inet_aton($host));
182 listen $srv_sock, SOMAXCONN;
183 fcntl $srv_sock, F_SETFL, O_NONBLOCK;
184 $srv_w = EV::io($srv_sock, EV::READ, sub {
185 if (accept my $sock, $srv_sock) {
186 IO::Stream->new({
187 fh => $sock,
188 cb => \&server,
189 wait_for => IN,
190 });
191 }
192 elsif ($! != EAGAIN) {
193 die "accept: $!";
194 }
195 });
196
197 INTERFACE
198
199 IO::Stream provide only three public methods: new(), write() and
200 close(). new() will create new object, close() will destroy it and
201 write() must be called when you want to modify (or just modified)
202 output buffer.
203
204 All other operations are done using IO::Stream object fields - for
205 simplicity and performance reasons. Moreover, you can keep your own
206 data in it. There convention on field names, to avoid conflicts:
207
208 /^_/
209
210 Fields with names started with underscore are for internal use by
211 IO::Stream, you shouldn't touch them or create your own field with
212 such names.
213
214 /^[a-z]/
215
216 Fields with names started with lower-case letter are part of
217 IO::Stream public interface - you allowed to read/write these fields,
218 but you should not store incorrect values in these fields. Check
219 "PUBLIC FIELDS" below for description of available fields and their
220 format.
221
222 /^[A-Z]/
223
224 You can store your own data in IO::Stream object using field names
225 started with upper-case letter. IO::Stream will not touch these
226 fields.
227
228 When some event arise which you're waited for, your callback will be
229 called with 3 parameters: IO::Stream object, event mask, and error (if
230 any):
231
232 sub callback {
233 my ($io, $e, $err) = @_;
234 }
235
236 METHODS
237
238 new
239
240 IO::Stream->new( \%opt );
241
242 Create and return IO::Stream object. You may not keep returned object -
243 you will get it in your callback (in first parameter) when some
244 interesting for your event happens, and will exists until to call
245 method close(). See OVERVIEW for more details.
246
247 Fields of %opt become fields of created IO::Stream object. There only
248 few fields required, but you can set any other fields too, and can also
249 set your custom fields (with names starting from upper-case letter).
250
251 Only required fields in %opt are {cb} and either {fh} or {host}+{port}.
252 The {wait_for} field also highly recommended to set when creating
253 object.
254
255 If {out_buf} will be set, then new() will automatically call write()
256 after creating object.
257
258 IO::Stream->new({
259 fh => \*STDIN,
260 cb => \&console,
261 wait_for => IN,
262 });
263
264 write
265
266 $io->write();
267 $io->write($data);
268
269 Method write() MUST be called after any modifications of {out_buf}
270 field, to ensure data in {out_buf} will be written to {fh} as soon as
271 it will be possible.
272
273 If {fh} available for writing when calling write(), then it will write
274 (may be partially) {out_buf} and may immediately call your callback
275 function delivering OUT|SENT events there. So, if you call write() from
276 that callback (as it usually happens), keep in mind it may be called
277 again while executing write(), and object state may significantly
278 change (it even may be close()'d) after it return from write() into
279 your callback.
280
281 The write($data) is just a shortcut for:
282
283 $io->{out_buf} .= $data;
284 $io->write();
285
286 close
287
288 $io->close()
289
290 Method close() will close {fh} and destroy IO::Stream object. See
291 OVERVIEW for more details.
292
293 PUBLIC FIELDS
294
295 If field marked *RO* that mean field is read-only and shouldn't be
296 changed.
297
298 Some field have default values (shown after equal sign).
299
300 Some field modified on events.
301
302 cb
303
304 method ='IO'
305
306 User callback which will be called when some listed in {wait_for}
307 events arise or error happens.
308
309 Field {cb} should be either CODE ref or object or class name. In last
310 two cases method named {method} will be called. Field {method} should
311 be string.
312
313 wait_for
314
315 Bitmask of events interesting for user. Can be changed at any time.
316 For example:
317
318 $io->{wait_for} = RESOLVED|CONNECTED|IN|EOF|OUT|SENT;
319
320 When some data will be read from {fh}, {wait_for} must contain IN
321 and/or EOF, or error EREQINEOF will be generated. So, it's better to
322 always have IN and/or EOF in {wait_for}.
323
324 If {wait_for} contain EOF and doesn't contain IN then {in_buf_limit}
325 must be defined or error EREQINBUFLIMIT will be generated.
326
327 fh *RO*
328
329 File handle for doing I/O. It's either provided by user to new(), or
330 created by new() (when user provided {host}+{port} instead).
331
332 host *RO*
333
334 port *RO*
335
336 If user doesn't provide {fh} to new(), he should provide {host} and
337 {port} instead. This way new() will create new TCP socket in {fh} and
338 resolve {host} and connect this {fh} to resolved {ip} and {port}.
339 Both resolving and connecting happens in non-blocking way, and will
340 result in delivering RESOLVED and CONNECTED events into user callback
341 (if user {wait_for} these events).
342
343 in_buf_limit =undef
344
345 Used to avoid DoS attach when user doesn't handle IN events and want
346 his callback called only on EOF event. Must be defined if user have
347 EOF without IN in {wait_for}.
348
349 Any value >0 will defined amount of bytes which can be read into
350 {in_buf} before EOF happens. When size of {in_buf} become larger than
351 {in_buf_limit}, error EINBUFLIMIT will be delivered to user callback.
352 In this case user can either remove some data from {in_buf} to make
353 it smaller than {in_buf_limit} or increase {in_buf_limit}, and
354 continue reading data.
355
356 NOT RECOMMENDED! Value 0 will switch off DoS protection, so there
357 will be no limit on amount of data to read into {in_buf} until EOF
358 happens.
359
360 out_buf =q{} # modified on: OUT
361
362 out_pos =undef # modified on: OUT
363
364 Data from {out_buf} will be written to {fh}.
365
366 If {out_pos} not defined, then data will be written from beginning of
367 {out_buf}, and after successful write written bytes will be removed
368 from beginning of {out_buf}.
369
370 If {out_pos} defined, it should be >= 0. In this case data will be
371 written from {out_pos} position in {out_buf}, and after successful
372 write {out_pos} will be incremented by amount of bytes written.
373 {out_buf} will not be changed!
374
375 out_bytes =0 # modified on: OUT
376
377 Each successful write will increment {out_bytes} by amount of written
378 bytes. You can change {out_bytes} in any way, but it should always be
379 a number.
380
381 in_buf =q{} # modified on: IN
382
383 Each successful read will concatenate read bytes to {in_buf}. You can
384 change {in_buf} in any way, but it should always be a string.
385
386 in_bytes =0 # modified on: IN
387
388 Each successful read will increment {in_bytes} by amount of read
389 bytes. You can change {in_bytes} in any way, but it should always be
390 a number.
391
392 ip *RO* =undef # modified on: RESOLVED
393
394 When you call new() with {host}+{port} instead of {fh} then IP
395 address resolved from {host} will be stored in {ip}, and event
396 RESOLVED will be generated.
397
398 is_eof *RO* =undef # modified on: EOF
399
400 When EOF event happens {is_eof} will be set to true value. This allow
401 you to detect is EOF already happens at any time, even if you doesn't
402 have EOF in {wait_for}.
403
404 plugin *RO* ={}
405
406 Allow you to set list of plugins when creating object with new(), and
407 later access these plugins.
408
409 This field is somewhat special, because when you call new() you
410 should set plugin to ARRAY ref, but in IO::Stream object {plugin} is
411 HASH ref:
412
413 my $io = IO::Stream->new({
414 host => 'www.google.com',
415 port => 443,
416 cb => \&google,
417 wait_for => EOF,
418 in_buf_limit=> 102400,
419 out_buf => "GET / HTTP/1.0\nHost: www.google.com\n\n",
420 plugin => [ # <------ it's ARRAY, but looks like HASH
421 ssl => IO::Stream::MatrixSSL::Client->new(),
422 proxy => IO::Stream::Proxy::HTTPS->new({
423 host => 'my.proxy.com',
424 port => 3218,
425 user => 'me',
426 pass => 'my pass',
427 }),
428 ],
429 MyField1 => 'my data1',
430 MyField2 => \%mydata2,
431 });
432
433 # access the "proxy" plugin:
434 $io->{plugin}{proxy};
435
436 This is because when calling new() it's important to keep plugins in
437 order, but later it's easier to access them using names.
438
439 DIAGNOSTICS
440
441 Exceptions may be thrown only in new(). All other errors will be
442 delivered to user's callback in last parameter.
443
444 usage: IO::Stream->new({ cb=>, wait_for=>, [fh=>, | host=>, port=>,]
445 ... })
446
447 You called new() with wrong parameters.
448
449 socket: %s
450
451 fcntl: %s
452
453 Error happens while creating new socket. Usually this happens because
454 you run out of file descriptors.
455
456 can't get file descriptor
457
458 Failed to get fileno() for your fh. Either fh doesn't open, or this
459 fh type is not supported (directory handle), or fh is not file handle
460 at all.
461
462 can't create second object for same fh
463
464 You can't have more than one IO::Stream object for same fh.
465
466 IO::Stream keep all objects created by new() until $io->close() will
467 be called. Probably you've closed fh in some way without calling
468 $io->close(), then new fh was created with same file descriptor
469 number, and you've tried to create IO::Stream object using new fh.
470
471 SEE ALSO
472
473 AnyEvent::Handle
474
475 SUPPORT
476
477 Bugs / Feature Requests
478
479 Please report any bugs or feature requests through the issue tracker at
480 https://github.com/powerman/perl-IO-Stream/issues. You will be notified
481 automatically of any progress on your issue.
482
483 Source Code
484
485 This is open source software. The code repository is available for
486 public review and contribution under the terms of the license. Feel
487 free to fork the repository and submit pull requests.
488
489 https://github.com/powerman/perl-IO-Stream
490
491 git clone https://github.com/powerman/perl-IO-Stream.git
492
493 Resources
494
495 * MetaCPAN Search
496
497 https://metacpan.org/search?q=IO-Stream
498
499 * CPAN Ratings
500
501 http://cpanratings.perl.org/dist/IO-Stream
502
503 * AnnoCPAN: Annotated CPAN documentation
504
505 http://annocpan.org/dist/IO-Stream
506
507 * CPAN Testers Matrix
508
509 http://matrix.cpantesters.org/?dist=IO-Stream
510
511 * CPANTS: A CPAN Testing Service (Kwalitee)
512
513 http://cpants.cpanauthors.org/dist/IO-Stream
514
515 AUTHOR
516
517 Alex Efros <[email protected]>
518
519 COPYRIGHT AND LICENSE
520
521 This software is Copyright (c) 2008- by Alex Efros <[email protected]>.
522
523 This is free software, licensed under:
524
525 The MIT (X11) License
526