| 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 |
|