NAME

       MCE::Relay - Extends Many-Core Engine with relay capabilities

VERSION

       This document describes MCE::Relay version 1.608

SYNOPSIS

          use MCE::Flow;

          my $file = shift || \*STDIN;

          ## Line Count #######################################

          mce_flow_f {
             use_slurpio => 1, init_relay => 0,
          },
          sub {
             my ($mce, $slurp_ref, $chunk_id) = @_;
             my $line_count = ($$slurp_ref =~ tr/\n//);

             ## Receive and pass on updated information.
             my $lines_read = MCE::relay { $_ += $line_count };

          }, $file;

          my $total_lines = MCE->relay_final;

          print {*STDERR} "$total_lines\n";

          ## Orderly Action ###################################

          mce_flow_f {
             use_slurpio => 1, init_relay => 0,
          },
          sub {
             my ($mce, $slurp_ref, $chunk_id) = @_;

             ## Exclusive access to STDOUT. Relays 0.
             MCE::relay { print $$slurp_ref };

          }, $file;

DESCRIPTION

       This module enables workers to receive and pass on information orderly with zero involvement by the
       manager process while running. The module is loaded automatically when init_relay is specified.

       All workers must participate when relaying data. Calling relay more than once is not recommended inside
       the block. Doing so will stall the application.

       Relaying is not met for passing big data. The last worker will likely stall if exceeding the buffer size
       for the socket. Not exceeding 8 KiB is safe across all platforms.

API DOCUMENTATION

       MCE->relay ( sub { code } )
       MCE::relay { code }
          Relay  is  enabled  by  specifying  the  init_relay option which takes a hash or array reference, or a
          scalar value. Relaying is orderly and driven by chunk_id when  processing  data,  otherwise  task_wid.
          Omitting the code block (e.g. MCE::relay) relays forward.

          Below, relaying multiple values via a HASH reference.

             use MCE::Flow max_workers => 4;

             mce_flow {
                init_relay => { p => 0, e => 0 },
             },
             sub {
                my $wid = MCE->wid;

                ## do work
                my $pass = $wid % 3;
                my $errs = $wid % 2;

                ## relay
                my %last_rpt = MCE::relay { $_->{p} += $pass; $_->{e} += $errs };

                MCE->print("$wid: passed $pass, errors $errs\n");

                return;
             };

             my %results = MCE->relay_final;

             print "   passed $results{p}, errors $results{e} final\n\n";

             -- Output

             1: passed 1, errors 1
             2: passed 2, errors 0
             3: passed 0, errors 1
             4: passed 1, errors 0
                passed 4, errors 2 final

          Or multiple values via an ARRAY reference.

             use MCE::Flow max_workers => 4;

             mce_flow {
                init_relay => [ 0, 0 ],
             },
             sub {
                my $wid = MCE->wid;

                ## do work
                my $pass = $wid % 3;
                my $errs = $wid % 2;

                ## relay
                my @last_rpt = MCE::relay { $_->[0] += $pass; $_->[1] += $errs };

                MCE->print("$wid: passed $pass, errors $errs\n");

                return;
             };

             my ($pass, $errs) = MCE->relay_final;

             print "   passed $pass, errors $errs final\n\n";

             -- Output

             1: passed 1, errors 1
             2: passed 2, errors 0
             3: passed 0, errors 1
             4: passed 1, errors 0
                passed 4, errors 2 final

          Or simply a scalar value.

             use MCE::Flow max_workers => 4;

             mce_flow {
                init_relay => 0,
             },
             sub {
                my $wid = MCE->wid;

                ## do work
                my $bytes_read = 1000 + ((MCE->wid % 3) * 3);

                ## relay
                my $last_offset = MCE::relay { $_ += $bytes_read };

                ## output
                MCE->print("$wid: $bytes_read\n");

                return;
             };

             my $total = MCE->relay_final;

             print "   $total size\n\n";

             -- Output

             1: 1003
             2: 1006
             3: 1000
             4: 1003
                4012 size

       MCE->relay_final ( void )
          Call  this method to obtain the final relay values after running. See included example findnull.pl for
          another use case.

             use MCE max_workers => 4;

             my $mce = MCE->new(
                init_relay => [ 0, 100 ],       ## initial values (two counters)

                user_func => sub {
                   my ($mce) = @_;

                   ## do work
                   my ($acc1, $acc2) = (10, 20);

                   ## relay to next worker
                   MCE::relay { $_->[0] += $acc1; $_->[1] += $acc2 };

                   return;
                }
             )->run;

             my ($cnt1, $cnt2) = $mce->relay_final;

             print "$cnt1 : $cnt2\n";

             -- Output

             40 : 180

       MCE->relay_recv ( void )
          The relay_recv method allows one to  perform  an  exclusive  action  prior  to  relaying.  Below,  the
          user_func  is  taken  from  the  cat.pl  example.  Relaying  is  chunk_id driven (or task_wid when not
          processing input), thus orderly.

             user_func => sub {
                my ($mce, $chunk_ref, $chunk_id) = @_;

                if ($n_flag) {
                   ## Relays the total lines read.

                   my $output = ''; my $line_count = ($$chunk_ref =~ tr/\n//);
                   my $lines_read = MCE::relay { $_ += $line_count };

                   open my $fh, '<', $chunk_ref;
                   $output .= sprintf "%6d\t%s", ++$lines_read, $_ while (<$fh>);
                   close $fh;

                   $output .= ":$chunk_id";
                   MCE->do('display_chunk', $output);
                }
                else {
                   ## The following is another way to have ordered output. Workers
                   ## write directly to STDOUT exclusively without any involvement
                   ## from the manager process. The statements between relay_recv
                   ## and relay run serially and most important orderly.

                   ## STDERR/OUT flush automatically inside worker threads and
                   ## processes. Disable buffering on file handles otherwise.

                   MCE->relay_recv;             ## my $val = MCE->relay_recv;
                                                ## relay simply forwards 0 below

                   print $$chunk_ref;           ## exclusive access to STDOUT
                                                ## important, flush immediately

                   MCE->relay;
                }

                return;
             }

INDEX

       MCE

AUTHOR

       Mario E. Roy, <marioeroy AT gmail DOT com>

perl v5.20.2                                       2015-04-10                                    MCE::Relay(3pm)