local-lib5/man/man3/Data::Stream::Bulk.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "Data::Stream::Bulk 3"
 127 .TH Data::Stream::Bulk 3 "2009-07-11" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 Data::Stream::Bulk \- N at a time iteration API
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 2
 137 \&        # get a bulk stream from somewere
 138 \&        my $s = Data::Stream::Bulk::Foo\->new( ... );
 139 \&
 140 \&        # can be used like this:
 141 \&        until ( $s\->is_done ) {
 142 \&                foreach my $item ( $s\->items ) {
 143 \&                        process($item);
 144 \&                }
 145 \&        }
 146 \&
 147 \&        # or like this:
 148 \&        while( my $block = $s\->next ) {
 149 \&                foreach my $item ( @$block ) {
 150 \&                        process($item);
 151 \&                }
 152 \&        }
 153 .Ve
 154 .SH "DESCRIPTION"
 155 .IX Header "DESCRIPTION"
 156 This module tries to find middle ground between one at a time and all at once
 157 processing of data sets.
 158 .PP
 159 The purpose of this module is to avoid the overhead of implementing an
 160 iterative api when this isn't necessary, without breaking forward
 161 compatibility in case that becomes necessary later on.
 162 .PP
 163 The \s-1API\s0 optimizes for when a data set typically fits in memory and is returned
 164 as an array, but the consumer cannot assume that the data set is bounded.
 165 .PP
 166 The \s-1API\s0 is destructive in order to minimize the chance that resultsets are
 167 leaked due to improper usage.
 168 .SH "API"
 169 .IX Header "API"
 170 .SS "Required Methods"
 171 .IX Subsection "Required Methods"
 172 The \s-1API\s0 requires two methods to be implemented:
 173 .IP "is_done" 4
 174 .IX Item "is_done"
 175 Should return true if the stream is exhausted.
 176 .Sp
 177 As long as this method returns a false value (not done) \f(CW\*(C`next\*(C'\fR could
 178 potentially return another block.
 179 .IP "next" 4
 180 .IX Item "next"
 181 Returns the next block.
 182 .Sp
 183 Note that \f(CW\*(C`next\*(C'\fR is not guaranteed to return an array reference, even if
 184 \&\f(CW\*(C`is_done\*(C'\fR returned false prior to calling it.
 185 .SS "Convenience Methods"
 186 .IX Subsection "Convenience Methods"
 187 .IP "items" 4
 188 .IX Item "items"
 189 This method calls \f(CW\*(C`next\*(C'\fR and dereferences the result if there are pending
 190 items.
 191 .IP "all" 4
 192 .IX Item "all"
 193 Force evaluation of the entire resultset.
 194 .Sp
 195 Note that for large data sets this might cause swap thrashing of various other
 196 undesired effects. Use with caution.
 197 .ie n .IP "cat @streams" 4
 198 .el .IP "cat \f(CW@streams\fR" 4
 199 .IX Item "cat @streams"
 200 Concatenates this stream with \f(CW@streams\fR, returning a single stream.
 201 .ie n .IP "list_cat @tail" 4
 202 .el .IP "list_cat \f(CW@tail\fR" 4
 203 .IX Item "list_cat @tail"
 204 Returns a possibly cleaned up list of streams.
 205 .Sp
 206 Used by \f(CW\*(C`cat\*(C'\fR.
 207 .Sp
 208 Overridden by Data::Stream::Bulk::Array, Data::Stream::Bulk::Cat and
 209 Data::Stream::Bulk::Nil to implement some simple short circuiting.
 210 .ie n .IP "filter $filter" 4
 211 .el .IP "filter \f(CW$filter\fR" 4
 212 .IX Item "filter $filter"
 213 Applies a per-block block filter to the stream.
 214 .Sp
 215 Returns a possibly new stream with the filtering layered.
 216 .Sp
 217 \&\f(CW$filter\fR is invoked once per block and should return an array reference to
 218 the filtered block.
 219 .IP "loaded" 4
 220 .IX Item "loaded"
 221 Should be overridden to return true if all the items are already realized (e.g.
 222 in the case of Data::Stream::Bulk::Array).
 223 .Sp
 224 Returns false by default.
 225 .Sp
 226 When true calling \f(CW\*(C`all\*(C'\fR is supposed to be safe (memory usage should be in the
 227 same order of magnitude as stream's own usage).
 228 .Sp
 229 This is typically useful when tranforming an array is easier than transorming a
 230 stream (e.g. optional duplicate filtering).
 231 .SH "CLASSES"
 232 .IX Header "CLASSES"
 233 .IP "Data::Stream::Bulk::Array" 4
 234 .IX Item "Data::Stream::Bulk::Array"
 235 This class is not a stream at all, but just one block. When the data set easily
 236 fits in memory this class can be used, while retaining forward compatibility
 237 with larger data sets.
 238 .IP "Data::Stream::Bulk::Callback" 4
 239 .IX Item "Data::Stream::Bulk::Callback"
 240 Callback driven iteration.
 241 .IP "Data::Stream::Bulk::DBI" 4
 242 .IX Item "Data::Stream::Bulk::DBI"
 243 Bulk fetching of data from \s-1DBI\s0 statement handles.
 244 .IP "Data::Stream::Bulk::DBIC" 4
 245 .IX Item "Data::Stream::Bulk::DBIC"
 246 DBIx::Class::ResultSet iteration.
 247 .IP "Data::Stream::Bulk::Nil" 4
 248 .IX Item "Data::Stream::Bulk::Nil"
 249 An empty result set.
 250 .IP "Data::Stream::Bulk::Cat" 4
 251 .IX Item "Data::Stream::Bulk::Cat"
 252 A concatenation of several streams.
 253 .IP "Data::Stream::Bulk::Filter" 4
 254 .IX Item "Data::Stream::Bulk::Filter"
 255 A filter wrapping a stream.
 256 .SH "SEE ALSO"
 257 .IX Header "SEE ALSO"
 258 HOP::Stream, Iterator, Class::Iterator etc for one by one iteration
 259 .PP
 260 \&\s-1DBI\s0, DBIx::Class::ResultSet
 261 .PP
 262 POE::Filter
 263 .PP
 264 Data::Page
 265 .PP
 266 Parallel::Iterator
 267 .PP
 268 <http://en.wikipedia.org/wiki/MapReduce>, \s-1LISP\s0, and all that other kool aid
 269 .SH "TODO"
 270 .IX Header "TODO"
 271 .IP "Sorted streams" 4
 272 .IX Item "Sorted streams"
 273 Add a hint for sorted streams (like \f(CW\*(C`loaded\*(C'\fR but as an attribute in the base
 274 role).
 275 .Sp
 276 Introduce a \f(CW\*(C`merge\*(C'\fR operation for merging of sorted streams.
 277 .Sp
 278 Optimize \f(CW\*(C`unique\*(C'\fR to make use of sorting hints for constant space uniquing.
 279 .IP "More utility functions" 4
 280 .IX Item "More utility functions"
 281 To assist in proccessing and creating streams.
 282 .IP "Coercion tables" 4
 283 .IX Item "Coercion tables"
 284 Moose::Util::TypeConstraints
 285 .SH "VERSION CONTROL"
 286 .IX Header "VERSION CONTROL"
 287 This module is maintained using git. You can get the latest version from
 288 <http://github.com/nothingmuch/data\-stream\-bulk/>.
 289 .SH "AUTHOR"
 290 .IX Header "AUTHOR"
 291 Yuval Kogman <nothingmuch@woobling.org>
 292 .SH "COPYRIGHT"
 293 .IX Header "COPYRIGHT"
 294 .Vb 3
 295 \&        Copyright (c) 2008 Yuval Kogman. All rights reserved
 296 \&        This program is free software; you can redistribute
 297 \&        it and/or modify it under the same terms as Perl itself.
 298 .Ve