NAME

IO::Plumbing::Bucket - catch (or pour in) data

SYNOPSIS

 use IO::Plumbing qw(plumb bucket);

 # catch stderr from that command!
 my $find = plumb("find", args=>[qw"/ -print0"],
                  stderr => bucket);

 # uses $var as a buffer
 my $var;
 my $bucket = bucket($var);

 # array-based buffer
 $bucket = bucket([]);

 # instead of letting the bucket catch everything, you can read from
 # it on its own.
 $bucket->getline;

 # array-based buffer

DESCRIPTION

Degenerate IO::Plumbing object that contains or collects data, depending on whether it is used as a target or a source of data.

Note that there are IPC issues with multiple target buckets that the first version of IO::Plumbing considers out of scope.

METHODS

collect_max( [ $value ] )

Specify the maximum size of data that will be collected in the output buffer before the filehandle is closed. Defaults to unlimited.

NOTES

PIPING LOTS INTO A BUCKET

IO::Plumbing::Bucket objects are the same for each time it is used in a pipeline, though it is possible to have multiple pipes emptying into one bucket.

For example, you can point the STDERR of a whole pipeline of processes into the same bucket; unless your pipelines start buffering (say, about 8kB written per scheduler context switch round) or some silly program starts doing buffered I/O on its STDERR (or making output in small sub-line chunks ;)), you'll always get unbroken reads from the things printed into it, so the lines won't be jumbled up.

Don't rely on this combining the output of many active writers at the same time very well though.

MULTIPLE BUCKETS

To collect from multiple buckets independently requires the use of a spigot. A spigot is considered an advanced tool used only by experienced plumbers and is not included in this first basic set of plumbings.

Alternatively you can probably use Coro or otherwise suitably arrange to multiprocess. But sorry, this isn't POE.

Or, write an IO::Plumbing sub-class with an IO::Select-like interface, that multiple objects can point themselves into, obviating the need for any buckets. But this interface isn't for that.

AUTHOR AND LICENCE

Copyright 2007, Sam Vilain. All Rights Reserved. This program is free software; you can use it and/or modify it under the same terms as Perl itself.